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 formatsJSON
Response formatsJSON


 

Parameters

ParameterLabelDescriptionTypeMax LengthRequired
id Guardian system generated unique keyintN/A 
firstNameFirst NameEmployee’s first namestring40Yes
lastNameLast NameEmployee’s last namestring40Yes
middleNameMiddle NameEmployee’s middle namestring25No
socialSecurityNumberSocial Security #Employee’s social security numberstring11No
dateOfBirthDate of BirthEmployee’s birthdatedate stringN/ANo
startDateDate HiredEmployee’s hire datedate stringN/ANo
profileIdEmployee IDEmployee’s company-issued identificationstring30No
otherNameMaiden NameEmployee’s maiden namestring40No
jobTitleTitleEmployee’s titlestring80No
emailAddressE-MailEmployee’s email addressstring80No
locationIdJob LocationEmployee’s assigned worksite location’s system IDintN/AYes
legalEntityCurrent Business UnitEmployee’s assigned legal entity’s system IDintN/ANo
terminatedDateDate TerminatedEmployee’s termination datedate stringN/ANo
languagePreferencePreferred LanguageEmployee’s preferred language (used to present onscreen help text). Send a 1 value to indicate ‘English’ and 2 to indicate ‘Spanish’intN/ANo
custom1NAOptional Organization-defined custom fieldstring255No
custom2NAOptional Organization-defined custom fieldstring255No
custom3NAOptional Organization-defined custom fieldstring255No
custom4NAOptional Organization-defined custom fieldstring255No
custom5NAOptional Organization-defined custom fieldstring255No
custom6NAOptional Organization-defined custom fieldstring255No
custom7NAOptional Organization-defined custom fieldstring255No
custom8NAOptional Organization-defined custom fieldstring255No
notificationEmail1Address 1Optional organization-defined email notification recipientstring255No
notificationEmail2Address 2Optional organization-defined email notification recipientstring255No
addressStreetLine 1Physical street addressstring80No
addressStreet2Line 2Physical street addressstring80No
addressApartmentApt #Apartment numberstring80No
addressCityCityCity addressstring50No
addressStateStateState addressstring20No
addressCountryCountryCountry addressstring50No
addressZipZipZip code addressstring10No
workNumberWork PhoneWork phone numberstring20No
workExtensionExtWork phone extension numberstring10No
homeNumberHome PhoneHome phone numberstring20No
homeExtensionExtHome phone extension numberstring10No
cellNumberCell PhoneCell phone numberstring20No
cellExtensionExtCell phone extension numberstring10No
createLoginCreate LoginIndicates if a login should be created for the employee. Specify “true” to create a login for the employee.boolean No
sendLoginEmailSend Login EmailIndicates if email about login info should be sent to employee. Specify “true” to trigger a welcome email to the employee.boolean No
createI9Create I-9This 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. 1string No
createRemotehireI9Create Remote Hire I-9This 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. 1string 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"": ""011-22-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"": “011-22-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""
        }
    ],
}