候補者検索API
CCWの候補者検索APIは、1つ以上のCCW申請書に対して提出された候補者に関するデータを照会するために使用されます。 候補者の姓名、ステータス、(有期契約作業員として)確認される資格などの検索条件を、CCW候補者検索APIを介して要求できます。 特定の検索条件に一致する候補者データが返されます。
CCW候補者検索APIにアクセスするための基本URLは次のとおりです。 https ://<instance>/api/candidates/search
CCW APIの認証とPOSTリクエストの送信方法については、CCW APIの概要を参照してください。 リクエストには、次の要素を含める必要があります。
申請ヘッダー
要求ヘッダーは認証に必要です。 詳細については、CCWのAPI概要文書のリクエストヘッダーセクションを参照してください。
リクエスト本文
メタとデータオブジェクトの両方をAPIリクエスト本文で渡す必要があります。
メタデータセクションは、より速いパフォーマンスを確保するために、返される結果の数を定義します。 次を含みます。
制限: 単一のAPIリクエストで返される結果の最大数を1から50の間で定義(ページ上の結果数)
制限の値が空または50より大きい場合、デフォルトで50件の結果に設定されます
制限の値が1未満の場合にエラーを返します
オフセット: リクエストを開始するレコードを定義します。たとえば、limit=30、offset=51は、レコード51から始まる次の30レコードを返します。
オフセットの値が空の場合、デフォルトで0に設定されます
オフセットの値が0未満の場合にエラーを返します。
データセクションには、要求される1つ以上の特定のルックアップパラメータが含まれています(少なくとも1つの空でないパラメータを送信する必要があります)。
次の表に、候補者検索APIリクエスト本文内で渡すことができるすべてのデータパラメーターを定義しています。
Attribute | データタイプ | 必須ですか? | 一意? | 値 | 説明 |
|---|---|---|---|---|---|
limit | 数字 | なし | なし | 1~50 | API呼び出しごとに返されるレコードの数 |
offset | 数字 | なし | なし | any | 結果を開始する特定のレコード番号 |
ID | 数字 | なし | はい | any | CCWにおける候補者の一意のID。 候補者が申請書に対して提出される際に生成されます。 (確認APIに使用)。 |
数字 | string(100) | なし | はい | any | 候補者にCCWで割り当てられた一意の数字。 フォーマット: <Client prefix>- CS -<sequence-number> |
first_name | string(100) | なし | なし | any | 候補者の名 |
last_name | string(100) | なし | なし | any | 候補者の姓 |
string(400) | なし | はい | any | 候補者のメールアドレス | |
ステータス | string(50) | なし | なし | CCWの有効なステータスの1つ | 以下の有効な候補者ステータステーブルを参照してください。 |
ccw_id | string(8) | なし | はい | any | CCW ID |
external_reference_number | string(200) | なし | なし | any | 候補者に関連付けられた一意のID |
requisition_number | string(100) | なし | なし | any | 候補者に関連付けられた申請番号 |
hiring_manager_first_name | string(100) | なし | なし | any | 採用マネージャーの名 |
hiring_manager_last_name | string (100) | なし | なし | any | 採用マネージャーの姓 |
onboarding_eligibility_met | 数字 | なし | なし | 0、1 | 0=対象、1=非対象 |
confirmation_eligibility_met | boolean | なし | なし | true/falseまたはyes/noまたは1/0またはY/NまたはT/F | 候補者に承認された作業指示があり、オンボーディングの資格基準が満たされているかどうかを示します |
supplier_name | string(200) | なし | なし | any | サプライヤー名 |
start_date | 日付 | なし | なし | any | アクティブな作業指示の開始日、YYYY-MM-DD形式(ISO 8601標準フォーマット) |
end_date | date | なし | なし | any | アクティブな作業指示の終了日、YYYY-MM-DD形式 |
リクエスト例
POST /api/candidates/search HOST: <CCW FQDN> Authorization: Bearer <token> Accept: "application/json" Correlation-Id: Z098Jth56Nkio343YY1vXt { "meta":{ "limit":"number", "offset":"number" } "data":{ "id":"number", "number":"string", "first_name":"string", "last_name":"string", "email":"string", "ccw_id":"number", "status":"string", "external_reference_number":"string", "requisition_number":"string", "hiring_manager_first_name":"string", "hiring_manager_last_name":"string", "onboarding_eligibility_met":"string", "confirmation_eligibility_met":"string", "supplier_name":"string" } }APIレスポンス
APIリクエスト本文で送信されたすべての検索パラメータに一致する候補が返されます。 次の表に、成功したAPIリクエストに対するCCWからの応答に候補者とともに含まれる可能性のあるすべてのパラメーターを定義しています。
Attribute | 要求本文オブジェクト | データタイプ | Description |
|---|---|---|---|
total_count | meta | 数字 | 検索条件に一致したレコードの数 |
has_more | meta | boolean | TrueまたはFalse検索条件を満たす候補が他にもあるかどうかを示します |
ID | データ | 数字 | CCWにおける候補者の一意のID。 候補者が申請書に対して提出される際に生成されます。 (確認APIに使用)。 |
数字 | データ | string(100) | 候補者にCCWで割り当てられた一意の数字。 フォーマット: <Client prefix>- CS -<sequence-number> |
first_name | データ | string(100) | 候補者の名 |
last_name | データ | string(100) | 候補者の姓 |
データ | string(400) | 候補者のメールアドレス | |
status | データ | string(50) | 以下の有効な候補者ステータステーブルを参照してください。 |
ccw_id | データ | string(8) | CCW ID |
cw_number | データ | string(100) | 候補者に割り当てられたCW番号 |
external_reference_number | データ | string(200) | 候補者に関連付けられた一意のID |
hiring_manager_first_name | データ | string(100) | 採用マネージャーの名 |
hiring_manager_last_name | データ | string(100) | 採用マネージャーの姓 |
hiring_manager_user_name | データ | string(512) | 採用マネージャーのユーザー名 |
hiring_manager_email | データ | string(100) | 採用マネージャーのメールアドレス |
engagement_type | data | string(400) | 臨時/ベンダー |
employment_type | data | string(200) | 雇用形態(W2、1099など) |
submitted_date | データ | date | 候補者が申請書に提出された日付、YYYY-MM-DDT24HHMMSSZ形式。 |
shortlisted | data | boolean | 候補者が最終候補者リストに追加されたかどうかを示します |
work_email | data | string(400) | 候補者に割り当てられた業務用メールアドレス |
date_available | データ | date | 候補者が勤務可能な日付、YYYY-MM-DDT24HHMMSSZ形式。 |
submitted_to_other_requisitions | data | boolean | 候補者が他の申請書に提出されたかどうかを示します |
onboarding_status | data | string(設定値) | 「事前提出-完了」、「オンボーディング-再開」、「オンボーディング-一時停止」、「オンボーディング-完了」、「オンボーディング-キャンセル」、「開始済み」、「進行中」 |
onboarding_eligibility_met | data | boolean | 0=対象、1=非対象 |
confirmation_eligibility_met | data | boolean | 候補者に承認された作業指示があり、オンボーディングの資格基準が満たされているかどうかを示します |
ID | data.supplier | 数字 | CCWでサプライヤーに割り当てられた一意のID |
名前 | data.supplier | string(400) | サプライヤー名 |
数字 | data.supplier | string(400) | CCWでサプライヤーに割り当てられた一意の数字 |
first_name | data.supplier.contact | string(100) | サプライヤー担当者の名 |
last_name | data.supplier.contact | string (100) | サプライヤー担当者の姓 |
data.supplier.contact | string(400) | サプライヤー担当者のメールアドレス | |
ID | data.requisition | 数字 | CCWで申請書に割り当てられた一意のID |
数字 | data.requisition | string(100) | CCWで申請書に割り当てられた一意の数字 |
タイプ | data.requisition | string(200) | 依頼タイプ(例:特定された候補者、通常) |
job_code | data.requisition | string(500) | 申請書ジョブコード |
job_title | data.requisition | string(400) | 申請書ジョブタイトル |
work_location_code | data.requisition | string(1000) | 申請書作業ロケーションコード |
work_location_name | data.requisition | string(40) | 申請書作業ロケーション名 |
type_of_service | data.requisition | string(200) | 作業のタイプ |
rate_type | data.requisition | string (100) | レートタイプ |
ID | data.work_orders | 数字 | CCWで作業指示に割り当てられた一意のID |
数字 | data.work_orders | string(200) | CCWで作業注文に割り当てられた一意の数字 |
active | data.work_orders | boolean | 作業指示が有効かどうかを示します |
contract_start_date | data.work_orders | 日付 | 作業指示の開始日、YYYY-MM-DDT24HHMMSSZ形式 |
contract_end_date | data.work_orders | 日付 | 作業指示の終了日、YYYY-MM-DDT24HHMMSSZ形式 |
ID | data.statement_of_works | 数字 | CCWでSOW (作業明細書)に割り当てられた一意のID |
数字 | data.statement_of_works | string (100) | CCWでSOW (作業明細書)に割り当てられた一意の数字 |
ID | data.sows.task_order | 数字 | CCWでタスク発注に割り当てられた一意のID |
数字 | data.sows.task_order | string(100) | CCWでタスク発注に割り当てられた一意のID |
レスポンスの例
以下は、少なくとも1人の候補者が検索条件に一致した、成功したレスポンスの例です。
total_count: APIリクエストの検索条件に一致した候補者の総数
has_more: trueまたはfalse。レスポンスに含まれる候補者に加えて、検索条件に一致する候補者が他にもいるかどうかを示します
{ "meta": { "total_count": 1, "has_more": false }, "data": [{ "candidate":{ "id":622757, "number":"CCW_CS_13897", "first_name":"Cedric", "last_name":"Daniels", "email":"cedric.daniels@coupa.com", "ccw_id":"23230203", "supplier":{ "id":526, "name":"Test Supplier.Inc", "number":"483735", "contact": { "first_name":"Lester", "last_name":"Freeman", "email":"lester.freeman@supplierssample.com" } }, "requisition":{ "id":"174011", "number":"RS-REQ-27130", "type":"Create Requisition", "job_code":"", "job_title":"Clerical", "work_location_code":"04872", "work_location_name":"04872-Craftsman CA", "type_of_service":"Clerical/Professional", "rate_type":"Per Hour" }, "hiring_manager_user_name": "100DuChloe1.DuCollins1.1@coupadev.com", "hiring_manager_first_name": "DuCollins1.1", "hiring_manager_last_name": "100DuChloe1", "hiring_manager_email": "100DuChloe1.DuCollins1.1@coupadev.com", "engagement_type": "Regular", "employment_type": "1099", "status": "wo-accepted", "submitted_date": "2020-07-28T14:36:22Z", "cw_number": "RS-CW-059713", "number": "RS-CS-0060176", "short_listed": false, "work_email": "", "date_available": null, "submitted_to_other_requirements": false, "onboarding_status": "initiated", "onboarding_eligibility_met": 1, "confirmation_eligibility_met": false, "statement_of_works": [], "work_orders":[ { "id":224583, "number":"RS-WO-059860", "active":"true", "contract_start_date":"2020-07-01T04:00:00Z", "contract_end_date":"2020-12-31T05:00:00Z" "external_reference_number": "" } ] } ], "meta": { "total_count": 1, "has_more": false } }以下は、検索条件を満たす候補者がいない場合のレスポンスの例です。
{ "meta": { "total_count": 0, "has_more": false }, "data":[] }有効な候補者ステータス
CCWの候補者APIへのリクエストで渡すことができる有効な候補者ステータス値は次のとおりです。
ステータス名 | ステータスコード |
|---|---|
候補者が承認された | candidate-approved |
候補者面接中 | candidate-interviewing |
候補者が不参加 | candidate-no-show |
候補者が却下された | candidate-rejected |
承認のために候補者を再度キューに入れた | candidate-requeue-approval |
候補者が取り下げられた | candidate-withdrawn |
送信しない | candidate-do-not-submit |
オンボーディング開始済み | candidate-onboarding-started |
OTHを受理済み | oth-accepted |
OTHを延長済み | oth-extended |
OTHを発行済み | oth-issued |
OTHの却下がロックされた | oth-rejected-locked |
OTHを却下済み | oth-rejected |
OTHを取り下げ済み | oth-withdrawn |
再提出が申請された | re-submit-requested |
承認申請を送信済み | submitted-for-approvals |
マネージャーに送信済み | submitted-to-manager |
プログラム管理者に送信済み | submitted-to-program-admin |
WOを受理済み | wo-accepted |
WOをキャンセル済み | wo-cancelled |
WOを発行済み | wo-issued |
WOを却下済み | wo-rejected |
エラーコード
APIリクエストが失敗した場合、レスポンスには次のいずれかのエラーコードが含まれます。
HTTPステータスコード | エラーコード | エラーサブコード | エラーメッセージ |
|---|---|---|---|
400 | E4000000 | E4000001 | 不正なリクエストです。 必須のHTTPヘッダーが1つ以上欠落しています |
400 | E4000000 | E4000003 | 入力本文が予想されるスキーマと一致しません |
400 | E4000000 | E4000004 | 無効な{field name}値 |
400 | E4000000 | E4000005 | {field name}は{max}文字以内にする必要があります |
401 | E4010000 | E4010001 | 認証に失敗しました. コンシューマー向けアプリに関連付けられている認証情報を確認してください |
401 | E4010000 | E4010002 | 認証に失敗しました. アクセストークンが無効または期限切れです |
403 | E4030000 | E4030001 | アクセス権がありません. ユーザーにはアクションを実行する権限がありません |
403 | E4030000 | E4030002 | アクセス権がありません. 無効な範囲です |
403 | E4030000 | E4030003 | アクセス権がありません. APIユーザーが無効です。 ユーザーがアクティブで、APIユーザーとして設定されていることを確認してください |
404 | E4040000 | E4040001 | 見つかりません |
405 | E4050000 | E4050001 | メソッドがサポートされていません。 サービスはリクエストされたHTTPメソッドをサポートしていません |
500 | E5000000 | E5000001 | システムまたはアプリケーションエラーが発生しました。Coupa CW管理者にお問い合わせください |