POST/ 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.
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 | N/A | No |
| startDate | Date Hired | Employee’s hire date | date | 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 | 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 | 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 | |
| rehire | Rehire | Indicates if the employee is a rehire and the startDate being sent is for a new period of employment. Specify “yes” and send this parameter in conjunction with the startDate parameter to add a new employment record for the employee. Use of this parameter assumes the employee was previously terminated in Guardian. | string | N/A | No |
Example
Request Example
PATCH https://<server>/v1/employees/<id>
{
""addressCity"": ""Atlanta"",
""firstName"": ""Jenny"",
""lastName"": ""Smith-Jones""
}Response Example
{
""startDate"": ""2017-12-15"",
""addressState"": “GA”,
""custom8"": """",
""integrationClientSystem"": null,
""custom4"": """",
""custom5"": """",
""custom6"": """",
""custom7"": """",
""custom1"": ""123456"",
""custom2"": """",
""custom3"": """",
""terminatedDate"": null,
""integrationClientProcess"": null,
""socialSecurityNumber"": null,
""integrationHrUrl"": null,
""i9FormSection1Link"": ""https://<server>/4DCGI/WEB_Log_Login/EMP/QDVHI0YX2G6TJYRJ/RMLNM"",
""id"": 2985804,
""workNumber"": null,
""cellExtension"": """",
""locationId"": 203258,
""IntegrationTransactionId"": null,
""otherName"": ""N/A"",
""languagePreference"": null,
""employeeReturnUrl"": null,
""addressCountry"": null,
""dateOfBirth"": ""1977-03-17"",
""integrationRequestId"": null,
""legalEntity"": 2646,
""addressStreet"": “1234 Elm St”,
""homeNumber"": null,
""jobTitle"": """",
""notificationEmail2"": """",
""notificationEmail1"": """",
""emailAddress"": null,
""cellNumber"": null,
""fullName"": ""Smith-Jones, Jenny"",
""addressCity"": “Atlanta”,
""firstName"": ""Jenny"",
""lastName"": ""Smith-Jones"",
""workExtension"": """",
""integrationCandidateId"": null,
""homeExtension"": """",
""integrationServiceId"": null,
""middleName"": """",
""addressStreet2"": null,
""integrationReportUrl"": null,
""profileId"": """",
""addressApartment"": null,
""addressZip"": null,
""links"": [
{
""href"": ""/v1/employees/2985804"",
""rel"": ""self""
}
]
}