HR REST API

ワシントンDC API リファレンス

Release

washingtondc

ft:locale

ja-JP

ft:publication_title

ワシントンDC API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

HR REST API

リリースバージョン: Washingtondc

更新日 2024年02月01日

読む9読むのに数分

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 アプリケーションに次のパラメーターを送信します (詳細については「返される内容」セクションを参照してください)。

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

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. 応答ヘッダー
ヘッダー	説明
Next-Page	後続の呼び出しで取得する追加データがあるかどうかを示すフラグ。たとえば、検索条件に一致する従業員レコードが合計 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)


要素	説明
BirthDate	従業員の生年月日。データタイプ：文字列
Company	会社名。データタイプ：文字列
Email	従業員のメールアドレス。データタイプ：文字列
EmployeeIdentifier	従業員の一意の識別子。データタイプ：文字列
FirstName	従業員の名。データタイプ：文字列
HireDate	従業員が雇用された日付。データタイプ：文字列
LastName	従業員の姓。データタイプ：文字列
MiddleName	従業員のミドルネーム。データタイプ：文字列
ReHire	将来の使用のため。データタイプ：文字列
ResidenceAddress	従業員の自宅の番地。データタイプ：文字列
ResidenceCity	従業員の自宅の市区町村。データタイプ：文字列
ResidenceCountry	従業員の自宅の国。データタイプ：文字列
ResidencePostalCode	従業員の自宅の郵便番号。データタイプ：文字列
ResidenceState	従業員の自宅の都道府県。データタイプ：文字列
サフィックス	従業員のサフィックス (Mr.、Mrs.、Dr. など) データタイプ：文字列
WorkAddress	従業員の勤務先の番地。データタイプ：文字列
WorkCity	従業員の勤務先の市区町村データタイプ：文字列
WorkCountry	従業員の勤務先の国。データタイプ：文字列
WorkPostalCode	従業員の勤務先の郵便番号。データタイプ：文字列
WorkState	従業員の勤務先の都道府県。データタイプ：文字列

特定の従業員の情報のサンプル 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": ""
  }
]}