PATCH/ employees

This API is used to update data for an existing Guardian employee. This request is often used to transfer an employee within the organization (i.e. change parameters such as locationId), or update changes to the employee’s biographical information or employment status (e.g. termination or re-hire).

For re-hired employees, this API is used to insert a new electronic I-9 in the employee’s record. Send the createI9 parameter to add a new I-9 and activate dashboard tracking of the re-hired employee. For remote employees who require an authorized representative to act on behalf of the company to complete Section 2, send the parameter createRemoteHireI9 instead. This will create an I-9 record and place the employee in the remote processing workflow. Note, the use of createLogin and sendLoginEmail parameters is not necessary in this case as an email is sent automatically when the createRemoteHireI9 parameter is used. Use the sendLoginEmail and createLogin only in instances when the employee is to complete Section 1 at home/ahead of the start date, but will be meeting with a Guardian user to complete the I-9 process. These parameters issue a system generated email containing Guardian credentials.

Please note that re-hire and termination dates can be included in this request. When used with this request the employee’s current period of employment is updated. As a result, the change could have unintended consequences if made concurrently or out of order (e.g. if the re-hired employee has not been terminated in Guardian and a new startDate is submitted then the previous date will be overwritten). For this reason, we recommend using the employments/POST endpoint to send new re-hire and termination dates, or employments/PATCH endpoint to correct existing employment record dates.

For additional parameter information access the employees data model section to review field information.

Method

PATCH

Resource Information

Requires authentication? YES
Request formats JSON
Response formats JSON

Parameters

Parameter Label Description Type Max Length Required
id Guardian system generated unique key int N/A
firstName First Name Employee’s first name string 40 Yes
lastName Last Name Employee’s last name string 40 Yes
middleName Middle Name Employee’s middle name string 25 No
socialSecurityNumber Social Security # Employee’s social security number string 11 No
dateOfBirth Date of Birth Employee’s birthdate date string N/A No
startDate Date Hired Employee’s hire date date string N/A No
profileId Employee ID Employee’s company-issued identification string 30 No
otherName Maiden Name Employee’s maiden name string 40 No
jobTitle Title Employee’s title string 80 No
emailAddress E-Mail Employee’s email address string 80 No
locationId Job Location Employee’s assigned worksite location’s system ID int N/A Yes
legalEntity Current Business Unit Employee’s assigned legal entity’s system ID int N/A No
terminatedDate Date Terminated Employee’s termination date date string N/A No
languagePreference Preferred Language Employee’s preferred language (used to present onscreen help text). Send a 1 value to indicate ‘English’ and 2 to indicate ‘Spanish’ int N/A No
custom1 NA Optional Organization-defined custom field string 255 No
custom2 NA Optional Organization-defined custom field string 255 No
custom3 NA Optional Organization-defined custom field string 255 No
custom4 NA Optional Organization-defined custom field string 255 No
custom5 NA Optional Organization-defined custom field string 255 No
custom6 NA Optional Organization-defined custom field string 255 No
custom7 NA Optional Organization-defined custom field string 255 No
custom8 NA Optional Organization-defined custom field string 255 No
notificationEmail1 Address 1 Optional organization-defined email notification recipient string 255 No
notificationEmail2 Address 2 Optional organization-defined email notification recipient string 255 No
addressStreet Line 1 Physical street address string 80 No
addressStreet2 Line 2 Physical street address string 80 No
addressApartment Apt # Apartment number string 80 No
addressCity City City address string 50 No
addressState State State address string 20 No
addressCountry Country Country address string 50 No
addressZip Zip Zip code address string 10 No
workNumber Work Phone Work phone number string 20 No
workExtension Ext Work phone extension number string 10 No
homeNumber Home Phone Home phone number string 20 No
homeExtension Ext Home phone extension number string 10 No
cellNumber Cell Phone Cell phone number string 20 No
cellExtension Ext Cell phone extension number string 10 No
createLogin Create Login Indicates if a login should be created for the employee. Specify “true” to create a login for the employee. boolean No
sendLoginEmail Send Login Email Indicates if email about login info should be sent to employee. Specify “true” to trigger a welcome email to the employee. boolean No
createI9 Create I-9 This action creates an electronic I-9 (non-remote processing) within the employee record and assumes a Guardian user will complete Section 2. Send a ‘yes’ value to insert a new I-9 record. Send a ‘if allowed’ to allow the system to determine if an I-9 can be created for the employee. 7 string No
createRemotehireI9 Create Remote Hire I-9 This action creates an electronic I-9 within the employee record and activates the remote processing workflow in which the employee will complete the I-9 with an authorized representative acting on behalf of the company. It is not necessary to use the sendLoginEmail or createLogin parameters for this workflow. Send a ‘yes’ value to insert a new I-9 record. Send a ‘if allowed’ to allow the system to determine if an I-9 can be created for the employee. 7 string No

Example

Request Example

PATCH https://sandbox.perfectcompliance.com/v1/employees/<employee_id>

{
    "addressCity": "Atlanta",
    "firstName": "Jenny",
    "lastName": "Smith-Jones"
}

Response Example

{
    "id": 2690279,
    "startDate": "2013-06-09",
    "addressState": "GA",
    "terminatedDate": null,
    "workNumber": null,
    "cellExtension": "",
    "dateOfBirth": "04/02/1990",
    "locationId": 1,
    "otherName": "",
    "languagePreference": 1,
    "addressCountry": "",
    "homeNumber": null,
    "legalEntity": 412,
    "addressStreet": "400 17th Street",
    "jobTitle": "",
    "notificationEmail2": null,
    "notificationEmail1": null,
    "socialSecurityNumber": "111-222-333",
    "emailAddress": "",
    "cellNumber": null,
    "fullName": "Smith, Jennifer P",
    "addressCity": "Atlanta",
    "firstName": "Jenny",
    "lastName": "Smith-Jones",
    "workExtension": "",
    "homeExtension": "",
    "middleName": "P",
    "addressStreet2": "",
    "profileId": "test",
    "addressApartment": "#1238",
    "addressZip": "30309",
    "custom8": null,
    "custom4": null,
    "custom5": null,
    "custom6": null,
    "custom7": null,
    "custom1": null,
    "custom2": null,
    "custom3": null,
    "links": [
        {
            "href": "/v1/employees/269027/",
            "rel": "self"
        },
        {
            "href": "/v1/employees/269027/i9s",
            "rel": "i9s"
        }
    ]
}