HR REST API

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 03월 12일
  • 소요 시간: 12분

    • 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.

    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.
    주:
    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

    표 1. Path parameters
    Name Description
    None
    표 2. Query parameters
    Parameter Description
    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.
    주:
    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_offset Starting 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.
    주:
    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)
    표 3. Request body parameters (XML or JSON)
    Name Description
    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.

    표 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    표 5. Response headers
    Header Description
    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.

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

    Response body parameters (JSON or XML)

    Element Description
    BirthDate Employee's birth date.

    Data type: String
    Company Company name.

    Data type: String
    Email Employee's email address.

    Data type: String
    EmployeeIdentifier Unique employee identifier.

    Data type: String
    FirstName Employee's first name.

    Data type: String
    HireDate Date on which the employee was hired.

    Data type: String
    LastName Employee's last name.

    Data type: String
    MiddleName Employee's middle name.

    Data type: String
    ReHire For future use.

    Data type: String
    ResidenceAddress Employee's home street address.

    Data type: String
    ResidenceCity Employee's home city.

    Data type: String
    ResidenceCountry Employee's home country.

    Data type: String
    ResidencePostalCode Employee's home zip code.

    Data type: String
    ResidenceState Employee's home state.

    Data type: String
    Suffix Employee's suffix, such as Mr., Mrs., or Dr.

    Data type: String
    WorkAddress Employee's work street address.

    Data type: String
    WorkCity Employee's work city

    Data type: String
    WorkCountry Employee's work country.

    Data type: String
    WorkPostalCode Employee's work zip code.

    Data type: String
    WorkState Employee'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": ""
  }
]}