POST/ employees
This API is used to create a new employee within Guardian, and is often used to add new hires to the system. Though not required globally, parameters used in the organization’s hierarchical structure must be included in the request and include pre-existing values.
If the employee is to complete Section 1 at home, use the sendLoginEmail and createLogin parameters to issue a system generated email containing Guardian credentials.
For remote employees who require an authorized representative to act on behalf of the company to complete Section 2, the parameter createRemoteHireI9 should be sent. This will create an I-9 record and place the employee in the remote processing workflow. The use of createLogin and sendLoginEmail parameters is not necessary in this case as an email will be sent automatically when the createRemoteHireI9 parameter is used.
While not required, the createI9 parameter can be sent to add an electronic I-9 (non-remote processing) to the employee’s record. This parameter is sent when the organization desires to track a pending I-9 rather than an employee without an I-9.
Re-hiring of employees (i.e. those employees who already exist in Guardian) is managed through the employees/PATCH endpoint.
Method
POST
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 | 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. 1 | 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. 1 | string | No |
1: The field value is case sensitive. Sending a ‘Yes’ value instead of ‘yes’ value will result in an error. I-9 records may be created when specific conditions are met. Specifically, an employee may not have an open I-9 or unresolved E-Verify record. If the employee is in a state in which a new I-9 record cannot be added an a ‘yes’ value is sent, then the row will result in an error. Using the ‘if allowed’ option allows the row to be accepted regardless of the state of the employee record. A new I-9 record will be added if the conditions of the employee record allow addition. Note: the createI9 and createRemotehireI9 are mutually exclusive. You should send a value for only one or the other field. Sending a value for each field for an individual employee will result in an error.
Example
Request Example
POST https://<server>/v1/employees
{
""startDate"": ""2017-12-31"",
""addressState"": ""AZ"",
""dateOfBirth"": ""1990-01-15"",
""locationId"": “203258”,
""languagePreference"": 1,
""addressStreet"": ""400 17th Street"",
""jobTitle"": ""Manager"",
""socialSecurityNumber"": ""*******1111"",
""emailAddress"": ""jennifer@email.com"",
""addressCity"": ""Phoenix"",
""firstName"": ""Jennifer"",
""lastName"": ""Smith"",
""profileId"": ""B0123456"",
""addressApartment"": ""#1238"",
""addressZip"": ""85012""
}
{
""startDate"": ""2017-12-31"",
""addressState"": “AZ”,
""custom8"": """",
""integrationClientSystem"": null,
""custom4"": """",
""custom5"": """",
""custom6"": """",
""custom7"": """",
""custom1"": """",
""custom2"": """",
""custom3"": """",
""terminatedDate"": null,
""integrationClientProcess"": null,
""socialSecurityNumber"": “*******1111”,
""integrationHrUrl"": null,
""i9FormSection1Link"": ""https://<server>/4DCGI/WEB_Log_Login/EMP/I48AOX5C4PSSFKYQ/RMLNM"",
""id"": 2985804,
""workNumber"": null,
""cellExtension"": """",
""locationId"": 203258,
""IntegrationTransactionId"": null,
""otherName"": """",
""languagePreference"": “1”,
""employeeReturnUrl"": null,
""addressCountry"": null,
""dateOfBirth"": “01/15/1990”,
""integrationRequestId"": null,
""legalEntity"": null,
""addressStreet"": “400 7th Street”,
""homeNumber"": null,
""jobTitle"": ""Manager"",
""notificationEmail2"": """",
""notificationEmail1"": """",
""emailAddress"": “jennifer@email.com”,
""cellNumber"": null,
""fullName"": ""Smith, Jennifer"",
""addressCity"": “Phoenix”,
""firstName"": ""Jennifer"",
""lastName"": ""Smith"",
""workExtension"": """",
""integrationCandidateId"": null,
""homeExtension"": """",
""integrationServiceId"": null,
""middleName"": """",
""addressStreet2"": null,
""integrationReportUrl"": null,
""profileId"": ""B0123456"",
""addressApartment"": null,
""addressZip"": “85012”,
""links"": [
{
""href"": ""/v1/employees"",
""rel"": ""self""
},
{
""href"": ""/v1/employees?page=1"",
""rel"": ""first""
},
{
""href"": ""/v1/employees?page=0"",
""rel"": ""last""
},
{
""href"": ""/v1/employees?page=0"",
""rel"": ""next""
},
{
""href"": ""/v1/employees?page=0"",
""rel"": ""previous""
}
],
}