HR REST API

Zurich API 참조

Release

zurich

ft:locale

ko-KR

ft:publication_title

Zurich API 참조

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

HR REST API

릴리스 버전: Zurich

업데이트 날짜 2025년 07월 31일

소요 시간: 8분

HR REST API는 미국에서 일하거나 거주하는 직원에 대한 정보를 반환하는 엔드포인트를 제공합니다.

이 API에 액세스하려면 sn_hr_core.usa_employee_only 역할과 Human Resources Scoped App: Core(com_sn_hr_core) 플러그인이 활성화되어 있어야 합니다.

HR REST - GET /get_usa_employee_profile

미국에 있는 직원의 직원 프로파일 정보를 반환합니다.

반환되는 정보는 다음 중 하나일 수 있습니다.

지정된 직원 ID에 대한 직원 프로파일 정보입니다.
지정된 날짜 또는 그 이후에 추가되었거나 정보가 업데이트된 직원에 대한 정보입니다.

주:

직원은 이 엔드포인트가 반환 결과에 포함되도록 직장 또는 본국을 미국으로 지정해야 합니다.

또한 엔드포인트는 다음 매개변수를 통합 CIC Plus 애플리케이션으로 전송합니다(설명은 반환 섹션 참조).

직원 식별자
이름
중간 이름
성
이메일
직장 주소
워크시티
작업 상태
작업 우편 번호
작업 국가
집 주소
홈시티
홈 상태
집우편 번호
국가(집)
생년월일
하이어데이트

URL 형식

기본 URL: /api/sn_hr_core/hr_rest_api/get_usa_employee_profile

지원되는 요청 매개변수

표 1. 경로 매개변수
이름	설명
없음

표 2. 쿼리 매개변수
매개변수	설명
employee_identifier	직원의 고유 식별자입니다. 호출 시스템은 이 값을 생성하며 해당 시스템과 일치하는 형식이 될 수 있습니다. 이 값을 가져오려면 먼저 매개 변수를 사용하여 끝점을 updated_after 호출합니다. 주: 이 매개 변수는 매개 변수와 함께 사용할 수 없습니다 updated_after . 이 매개변수는 고유한 직원을 정의하는 반면 updated_after , 지정된 날짜 이후에 작성/업데이트된 직원 그룹을 반환합니다. 데이터 유형: 문자열
sysparm_limit	반환할 최대 기록 수입니다. 이 기록 수를 초과하는 요청의 경우 sysparm_offset 매개변수를 사용하여 기록 검색을 페이지 매김합니다. 데이터 유형: 숫자 기본값: 1000
sysparm_offset	기록 검색을 시작할 시작 기록 인덱스입니다. 이 값을 사용하여 기록 검색을 페이지 매김합니다. 이 기능을 사용하면 기록 수와 관계없이 관리 가능한 작은 청크로 모든 기록을 검색할 수 있습니다. 예를 들어 이 엔드포인트를 처음 호출할 때 sysparm_offset이 "0"으로 설정됩니다. 사용 가능한 모든 기록을 간단히 살펴보려면 모든 기록이 끝날 때까지 `sysparm_offset=sysparm_offset+sysparm_limit`를 사용합니다.
updated_after	반환할 직원 데이터를 결정하는 데 사용할 날짜입니다. 인스턴스에 추가되었거나 이 날짜 또는 그 이후에 정보가 업데이트된 모든 미국 기반 직원(직장 또는 가정)이 반환 결과에 포함됩니다. 주: 이 매개 변수는 매개 변수와 함께 사용할 수 없습니다 employee_identifier . 데이터 유형: 문자열 형식: YYYY-MM-DD HH:MM:SS 또는 YYYY-MM-DD(시간은 00:00:00으로 기본 설정됨)

표 3. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
없음

헤더

다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

표 4. 요청 헤더
헤더	설명
수용	응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다. 기본값: application/json

표 5. 응답 헤더
헤더	설명
다음 페이지	후속 호출에서 가져올 추가 데이터가 있는지 여부를 나타내는 플래그입니다. 예를 들어 검색 조건과 일치하는 직원 기록이 총 120개이고 sysparm_limit 100 Next-Page 으로 설정된 경우 는 true입니다. 사용할 수 Next-Page 있는 추가 결과가 없으면 false입니다. 유효한 값은 다음과 같습니다. true: 추가 데이터를 사용할 수 있습니다. 다음 데이터 청크를 얻으려면 다른 호출을 수행해야 합니다. false: 추가 데이터가 없습니다.

상태 코드

다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

표 6. 상태 코드
상태 코드	설명
200	성공입니다. 요청이 성공적으로 처리되었습니다.
401	승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
404	찾을 수 없습니다. 요청한 항목을 찾을 수 없습니다.
500	내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

응답 본문 매개변수(JSON 또는 XML)


요소	설명
생년월일	직원의 생년월일입니다. 데이터 유형: 문자열
회사	회사 이름입니다. 데이터 유형: 문자열
이메일	직원의 이메일 주소입니다. 데이터 유형: 문자열
직원 식별자	고유 직원 식별자입니다. 데이터 유형: 문자열
이름	직원의 이름입니다. 데이터 유형: 문자열
하이어데이트	직원이 고용된 날짜입니다. 데이터 유형: 문자열
성	직원의 성입니다. 데이터 유형: 문자열
중간 이름	직원의 중간 이름입니다. 데이터 유형: 문자열
재고용	나중에 사용할 수 있습니다. 데이터 유형: 문자열
거주지주소	직원의 집 주소입니다. 데이터 유형: 문자열
레지던스 시티	직원의 거주지 구/군/시입니다. 데이터 유형: 문자열
거주지 국가	직원의 모국입니다. 데이터 유형: 문자열
거주지우편 번호	직원의 집 우편 번호입니다. 데이터 유형: 문자열
거주 상태	직원의 고향 주입니다. 데이터 유형: 문자열
접미사	직원의 접미사(예: Mr., Mrs. 또는 Dr.) 데이터 유형: 문자열
직장 주소	직원의 직장 주소입니다. 데이터 유형: 문자열
워크시티	직원의 직장 도시 데이터 유형: 문자열
작업 국가	직원의 직장 국가입니다. 데이터 유형: 문자열
작업 우편 번호	직원의 직장 우편 번호입니다. 데이터 유형: 문자열
작업 상태	직원의 작업 상태입니다. 데이터 유형: 문자열

특정 직원의 정보에 대한 샘플 cURL 요청

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": ""
 }
]}

2019년 5월 18일 이후에 추가/업데이트된 직원 목록에 대한 샘플 cURL 요청

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": ""
  }
]}