Skip to content
REST API reference › API reference › API implementation and reference
Release: Australia · Updated: 2026-03-12 · Official documentation · View source

HR REST API

The HR REST API provides endpoints that return information about employees that work or live in the United States.

To access this API you must have the sn_hr_core.usa_employee_only role and the Human Resources Scoped App: Core (com_sn_hr_core) plugin activated.

Parent Topic:REST API reference

HR REST - GET /get_usa_employee_profile

Returns employee profile information for employees based in the United States.

The returned information can be either:

  • Employee profile information for a specified employee ID.
  • Information for employees that have been added, or whose information has been updated, on or after a specified date.

Note: Employees must either have their work or home country specified as the United States for this endpoint to include them in the return results.

In addition, the endpoint sends the following parameters to the integrated CIC Plus application (see the Returns section for descriptions):

  • EmployeeIdentifier
  • FirstName
  • MiddleName
  • LastName
  • Email
  • WorkAddress
  • WorkCity
  • WorkState
  • WorkPostalCode
  • WorkCountry
  • HomeAddress
  • HomeCity
  • HomeState
  • HomePostalCode
  • HomeCountry
  • BirthDate
  • HireDate

URL format

Default URL: /api/sn_hr_core/hr_rest_api/get_usa_employee_profile

Supported request parameters

NameDescription
None 
ParameterDescription
employee\_identifier

Unique identifier of an employee. The calling system generates this value and can be in whatever format is consistent with their system. To obtain this value, first call the endpoint using the updated_after parameter.Note: This parameter is mutually exclusive with the updated_after parameter. This parameter defines a unique employee, whereas updated_after returns a group of employees created/updated after a specified date.

Data type: String

sysparm\_limit

Maximum number of records to return. For requests that exceed this number of records, use the sysparm_offset parameter to paginate record retrieval. Data type: Number

Default: 1000

sysparm\_offsetStarting record index for which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. For example, the first time you call this endpoint, sysparm_offset is set to "0". To simply page through all available records, use sysparm_offset=sysparm_offset+sysparm_limit, until you reach the end of all records.
updated\_after

Date to use to determine the employee data to return. All United States-based employees (work or home) that were added to your instance, or whose information was updated on or after this date, are included in the return results.Note: This parameter is mutually exclusive with the employee_identifier parameter.

Data type: String

Format: YYYY-MM-DD HH:MM:SS or YYYY-MM-DD (time defaults to 00:00:00)

NameDescription
None 

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

HeaderDescription
AcceptData format of the response body. Supported types: application/json or application/xml. Default: application/json
HeaderDescription
Next-Page

Flag that indicates whether there is additional data to obtain in a subsequent call. For example, if there are a total of 120 employee records that match the search criteria, and sysparm_limit is set to 100, then Next-Page is true. If no additional results are available, Next-Page is false.Valid values:

  • true: Additional data is available, another call must be made to obtain the next chunk of data.
  • false: No additional data.

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Status codeDescription
200Successful. The request was successfully processed.
401Unauthorized. The user credentials are incorrect or have not been passed.
404Not found. The requested item wasn't found.
500Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

ElementDescription
BirthDateEmployee's birth date.Data type: String
CompanyCompany name.Data type: String
EmailEmployee's email address.Data type: String
EmployeeIdentifierUnique employee identifier.Data type: String
FirstNameEmployee's first name.Data type: String
HireDateDate on which the employee was hired.Data type: String
LastNameEmployee's last name.Data type: String
MiddleNameEmployee's middle name.Data type: String
ReHireFor future use.Data type: String
ResidenceAddressEmployee's home street address.Data type: String
ResidenceCityEmployee's home city.Data type: String
ResidenceCountryEmployee's home country.Data type: String
ResidencePostalCodeEmployee's home zip code.Data type: String
ResidenceStateEmployee's home state.Data type: String
SuffixEmployee's suffix, such as Mr., Mrs., or Dr.Data type: String
WorkAddressEmployee's work street address.Data type: String
WorkCityEmployee's work cityData type: String
WorkCountryEmployee's work country.Data type: String
WorkPostalCodeEmployee's work zip code.Data type: String
WorkStateEmployee's work state.Data type: String

Sample cURL request for a specific employee's information

curl -X GET "https://instance.servicenow.com/api/sn_hr_core/V1/hr_rest_api/get_usa_employee_profile?employee_identifier=231"
-H "accept: application/json" \
-u "username":"password"

{"result": [
 {
  "EmployeeIdentifier": "231",
  "FirstName": "Harold",
  "MiddleName": "William",
  "LastName": "Lewis",
  "Suffix": "Mr.",
  "Email": "Howard.Lewis@example.com",
  "BirthDate": "",
  "HireDate": "2021-02-18",
  "Company": "ServiceNow Inc",
  "ResidenceAddress": "",
  "ResidenceCity": "SD",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "2617 South Robinson Avenue, Oklahoma City",
  "WorkCity": "Oklahoma",
  "WorkState": "OK",
  "WorkPostalCode": "73109",
  "WorkCountry": "USA",
  "ReHire": ""
 }
]}

Sample cURL request for a list of employees added/updated on or after 05/18/2019

curl -X GET "https://instance.servicenow.com/api/sn_hr_core/V1/hr_rest_api/get_usa_employee_profile?update_after=2019-05-18"
-H "accept: application/json" \
-u "username":"password"

{"result": [
 {
  "EmployeeIdentifier": "2345",
  "FirstName": "Cheryl",
  "MiddleName": "Lynn",
  "LastName": "Smith",
  "Suffix": "Mrs.",
  "Email": "Cheryl.Smith@example.com",
  "BirthDate": "",
  "HireDate": "2019-06-18",
  "Company": "ServiceNow Inc",
  "ResidenceAddress": "",
  "ResidenceCity": "SD",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "2617 South Robinson Avenue, Oklahoma City",
  "WorkCity": "Oklahoma",
  "WorkState": "OK",
  "WorkPostalCode": "73109",
  "WorkCountry": "USA",
  "ReHire": ""
  },
  {
  "EmployeeIdentifier": "1111",
  "FirstName": "Thomas",
  "MiddleName": "",
  "LastName": "Doe",
  "Suffix": "Mr.",
  "Email": "Thomas.Doe@example.com",
  "BirthDate": "1978-05-22",
  "HireDate": "2019-08-14",
  "Company": "",
  "ResidenceAddress": "",
  "ResidenceCity": "San Jose",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "13308 Midland Road, Poway",
  "WorkCity": "Poway",
  "WorkState": "CA",
  "WorkPostalCode": "",
  "WorkCountry": "USA",
  "ReHire": ""
  }
]}