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 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. 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""
        }
    ],
}