GET/ employees

This API returns a collection of employees existing within Guardian. Optional page_size and page parameters can be passed in order to limit the results. Results include the employee’s Guardian ID which can be used in a subsequent GET request to obtain additional details related to the employee. For additional parameter information access the employees data model section to review field information.

A maximum of 50 employees are returned in the response. The ‘links’ section of the response includes paging information. Use this information to obtain additional collections of employee records, e.g. GET https://<server>/v1/employees?page=2.


Method

GET


Resource Information

Requires authentication? YES
Response formats JSON

Parameters

Parameter Required Description
page No specifies the page number from where you want to begin accessing records

Filtering

The fields in the table below can be used in the query string of a GET request, for example:
GET https://<server>/v1/employees?firstName=John
Currently, it is only possible to query for exact values (no wildcards or partial matches); however, the query criteria is case-insensitive.

Parameter Type Description
custom1 string Optional Organization-defined custom field
custom2 string Optional Organization-defined custom field
custom3 string Optional Organization-defined custom field
custom4 string Optional Organization-defined custom field
custom5 string Optional Organization-defined custom field
custom6 string Optional Organization-defined custom field
custom7 string Optional Organization-defined custom field
custom8 string Optional Organization-defined custom field
dateOfBirth date string Employee’s birthdate
emailAddress string Employee’s email address
firstName string Employee’s first name
jobTitle string Employee’s title
languagePreference int Employee’s preferred language (used to present onscreen help text). Send a 1 value to indicate ‘English’ and 2 to indicate ‘Spanish’
lastName string Employee’s last name
legalEntity int Employee’s assigned legal entity’s system ID
locationId int Employee’s assigned worksite location’s system ID
middleName string Employee’s middle name
otherName string Employee’s maiden name
profileId string Employee’s company-issued identification
socialSecurityNumber string Employee’s social security number, formatted as ###-##-####

Example

Get All Request Example

GET https://<server>/v1/employees

Response Example

{
 ""searchResult"": [
 {
 ""id"": 269027,
 ""i9Status"": ""Approved"",
 ""i9Expiration"": ""2015-11-30"",
 ""firstName"": ""Jennifer"",
 ""lastName"": ""Smith"",
 ""socialSecurityNumber"": ""*******0657"",
 ""profileId"": ""12345""
 },
 {
 ""id"": 242339,
 ""i9Status"": """",
 ""i9Expiration"": """",
 ""firstName"": ""Roger"",
 ""lastName"": ""Wilco"",
 ""socialSecurityNumber"": ""*******2222"",
 ""profileId"": ""67898""
 },
 {
 ""id"": 269117,
 ""i9Status"": ""Signed Sec 1"",
 ""i9Expiration"": ""null"",
 ""firstName"": ""Mark"",
 ""lastName"": ""Davis"",
 ""socialSecurityNumber"": ""*******3333"",
 ""profileId"": ""232434""
 },
 {
 ""id"": 270109,
 ""i9Status"": ""Approved"",
 ""i9Expiration"": ""null"",
 ""firstName"": ""John"",
 ""lastName"": ""Smith"",
 ""socialSecurityNumber"": ""444-44-444"",
 ""profileId"": ""2345435""
 },
 {
 ""id"": 242204,
 ""i9Status"": ""Approved"",
 ""i9Expiration"": ""2012-10-01"",
 ""firstName"": ""David"",
 ""lastName"": ""Dubois"",
 ""socialSecurityNumber"": ""*******5555"",
 ""profileId"": ""23432545""
 }
 ],
 ""links"": [
 {
 ""href"": ""/v1/employees/"",
 ""rel"": ""self""
 },
 {
 ""href"": ""/v1/employees/?page=1"",
 ""rel"": ""first""
 },
 {
 ""href"": ""/v1/employees/?page=5"",
 ""rel"": ""last""
 },
 {
 ""href"": ""/v1/employees/?page=2"",
 ""rel"": ""next""
 },
 {
 ""href"": ""/v1/employees/?page=5"",
 ""rel"": ""previous""
 }
 ]
}

Single Record Request by system ID Example
GET https://<server>/v1/employees/<id>

 

{
 ""startDate"": ""2016-11-05"",
 ""addressState"": null,
 ""custom8"": null,
 ""links"": [
 {
 ""href"": ""/v1/employees/2767042"",
 ""rel"": ""self""
 },
 {
 ""href"": ""/v1/employees/2767042i9s"",
 ""rel"": ""i9s""
 }
 ],
 ""integrationClientSystem"": null,
 ""custom4"": null,
 ""custom5"": null,
 ""custom6"": null,
 ""custom7"": null,
 ""custom1"": ""123456"",
 ""custom2"": ""0"",
 ""custom3"": null,
 ""terminatedDate"": null,
 ""integrationClientProcess"": null,
 ""i9FormSection2Link"": ""https://dweb.perfectcompliance.com/4DCGI/WEB_Log_Login/COM/E4DAMYPEQ4RW7QMB"",
 ""socialSecurityNumber"": ""*******5884"",
 ""integrationHrUrl"": null,
 ""id"": 2767042,
 ""workNumber"": null,
 ""cellExtension"": """",
 ""locationId"": 201244,
 ""IntegrationTransactionId"": null,
 ""otherName"": ""N/A"",
 ""languagePreference"": 1,
 ""employeeReturnUrl"": null,
 ""addressCountry"": null,
 ""dateOfBirth"": ""1978-08-01"",
 ""integrationRequestId"": null,
 ""legalEntity"": null,
 ""addressStreet"": null,
 ""homeNumber"": null,
 ""jobTitle"": null,
 ""notificationEmail2"": null,
 ""notificationEmail1"": null,
 ""emailAddress"": null,
 ""cellNumber"": null,
 ""fullName"": ""Jones, Judy"",
 ""addressCity"": null,
 ""firstName"": ""Judy"",
 ""lastName"": ""Jones"",
 ""workExtension"": """",
 ""integrationCandidateId"": null,
 ""homeExtension"": """",
 ""integrationServiceId"": null,
 ""middleName"": """",
 ""addressStreet2"": null,
 ""integrationReportUrl"": null,
 ""profileId"": null,
 ""addressApartment"": null,
 ""addressZip"": null
}

 

Single Record Request by Query String
GET https://<server>/v1/employees?profileId=b122338


{
 ""searchResult"": [{
 ""i9Status"": ""Signed Sec 1"",
 ""i9Expiration"": null,
 ""firstName"": ""Steve"",
 ""lastName"": ""Hobss"",
 ""socialSecurityNumber"": ""*******2311"",
 ""profileId"": ""b122338"",
 ""id"": 2985804
 }],
 ""links"": [{
 ""href"": ""/v1/employees"",
 ""rel"": ""self""
 },
 {
 ""href"": ""/v1/employees?page=1"",
 ""rel"": ""first""
 },
 {
 ""href"": ""/v1/employees?page=1"",
 ""rel"": ""last""
 },
 {
 ""href"": ""/v1/employees?page=1"",
 ""rel"": ""next""
 },
 {
 ""href"": ""/v1/employees?page=1"",
 ""rel"": ""previous""
 }]
}


I-9 Status Values

The status of the employee’s primary I-9 is included in the GET response when sending a GET request for a specific employee based on a query string like the example above (e.g. GET https:///v1/employees?profileId=b122338).

Available i9Status Values:

Value Description
Not Started Employee record has no I-9
Started I-9 record exists in employee record, but Sec 1 remains unsigned
Signed Sec 1 Section 1 is signed
Signed Sec 2 Both Section 1 and 2 are signed
Completed The I-9 has been marked Completed
Approved The I-9 has been marked Approved
Parked The I-9 may not have been completed and has been locked from further processing