Retrieve Candidates APIガイド

雇用主向けに Indeed から候補者情報を取得します。

 

法的注意

By using this API and its documentation and building an integration, you agree to the Additional API Terms and Guidelines.

雇用主向けに Indeed から候補者情報を取得するには、Retrieve Candidates API を呼び出します。

Retrieve Candidates API のワークフロー

Retrieve Candidates API と連携すると、次の操作を呼び出せます。

1. 1.
   認証する。
2. 2.
   雇用主を登録する: 雇用主を登録し、登録に関する情報を返します。
3. 3.
   未確認のアセットを取得する: 未確認のアセットを、ステージングされた順に古いものから新しいものへ取得します。
4. 4.
   時間範囲でアセットを取得する: 時間範囲で確認済みのアセットを取得します。
5. 5.
   テストアセットを作成する: 連携テスト用のテストアセットを作成します。
6. 6.
   GraphQL エラーをトラブルシューティングする: GraphQL エラーを解決します。

Retrieve Candidates API リファレンス

• registerEmployer: 雇用主を登録し、登録に関する情報を返します。
• fetchAssets: 未確認のアセットを、ステージングされた順に古いものから新しいものへ取得します。
• assetsByTimeRange: 時間範囲で確認済みのアセットを取得します。
• stageAssets: 連携テスト用のテストアセットを作成します。

認証する

When you become an Indeed partner, Indeed sets up an app for your integration. Sign in to Partner Console to view your app and OAuth credentials (client ID, secret, and authorization code for 3-legged OAuth). Exchange credentials for an access token to authenticate API calls.

Candidate Sync API の各オペレーションには OAuth トークンが必要です。

Candidate Sync API オペレーションの OAuth トークン種別

API とオペレーション	OAuth トークン種別
Employer Registration API 雇用主を登録する	雇用主を表す 3-legged OAuth トークン を使用し、employer.ats_candidate.sync スコープで認証します。このトークンは雇用主の Indeed アカウントと ATS アカウントを関連付けます。Indeed の管理者またはオーナーが作成する必要があります。registerEmployer がスコープ不足のエラーを返す場合、このトークンが雇用主に関連付けられていない可能性があります。
Employer Registration API 登録情報を更新する 登録情報を一覧表示する 雇用主の登録を解除する Send Candidates API 応募を初期化し、添付ファイルをアップロードする 応募を送信する 応募ステータスを追跡する 応募を削除する Retrieve Candidates API 未確認のアセットを取得する 時間範囲でアセットを取得する テストアセットを作成する	2-legged OAuth トークン. で認証します。アプリケーションは、ユーザー操作なしで Indeed の認可サーバーに直接認証します。

アクセストークンは ATS 内に安全に保存し、ユーザー間で共有しないでください。Indeed は、お客様のシステムが求人の信頼できる情報源であることを前提としています。あるユーザーが投稿した求人に別のユーザーのアクセストークンを使うと、Indeed 上でそのユーザーに別のユーザーの求人へのアクセスを付与する可能性があります。

アクセストークンを取得したら、クエリまたはミューテーションにこのトークンを含めます。最新の求人ステータスを確認するたびにユーザーへサインインを求めることがないよう、アクセストークンは有効期限が切れる前に更新することを推奨します。

Indeed と連携して API を呼び出す と スコープをご覧ください。

雇用主を登録する

Employer Registration API では、雇用主を登録できます。

リクエスト – Register employer

雇用主を登録し、登録情報を返すには、registerEmployer を呼び出します。

雇用主を表す 3-legged OAuth トークン を使用し、employer.ats_candidate.sync スコープで認証します。このトークンは雇用主の Indeed アカウントと ATS アカウントを関連付けます。Indeed の管理者またはオーナーが作成する必要があります。registerEmployer がスコープ不足のエラーを返す場合、このトークンが雇用主に関連付けられていない可能性があります。

RegisterEmployerInput では、次の入力フィールドを指定します。

registerEmployer の入力フィールド

フィールド	必須	説明
partnerEmployerId 型：ID!	✅	雇用主を一意に識別するために指定する ID です。 1 つの partnerEmployerId を複数の Indeed アカウントに登録できますが、各 Indeed アカウントでは、ATS ごとに 1 つの partnerEmployerId のみを使用できます。同じ Indeed アカウントで別の partnerEmployerId を使用すると、Indeed は登録を新しい atsName と partnerEmployerId に更新します。
atsName 型：String!	✅	雇用主に対して指定する名称です。Indeed 上では、この名称が雇用主に表示されます。

レスポンス – Register employer

API は EmployerRegistration を返します。後続の Candidate Sync API 呼び出しで使用するために id を保存するか、partnerEmployerId を指定して findRegisteredEmployers でもう一度取得します。

未確認のアセットを取得する

fetchAssets を呼び出して、未確認のアセットをステージングされた順に古いものから新しいものへ取得します。

2-legged OAuth トークン. で認証します。アプリケーションは、ユーザー操作なしで Indeed の認可サーバーに直接認証します。

Retrieve Candidates API は現在、Smart Sourcing からの関心を示した候補者に対応しています。今後の更新で新しいアセットタイプが追加されることがあります。レスポンス内の想定外のアセットタイプは適切に処理してください。すべてのアセットが AtsSyncCandidateSyncInterestedCandidateAsset であるとは限りません。

返される employerIdentifier は、登録を作成したときに Indeed に送信した ID と一致します。これを使用して、どの雇用主が候補者を受け取るかを識別します。

リクエスト – 未確認のアセットを取得する

このミューテーションは、未確認のアセットを取得します。

未確認のアセットを取得します。

mutation FetchAssets($input: FetchAssetsAtsSyncCandidateSyncInput) {
  atsSyncCandidateSync {
    fetchAssets(input: $input) {
      token
      assets {
        id
        metadata {
          stagedAt
          stagedTest
          employerIdentifier
          completeSourceAttribution {
            enumKey
            name
          }
        }
        ...on AtsSyncCandidateSyncInterestedCandidateAsset {
          contact {
            candidate {
              email
              location
              name
              phone
              resume {
                pdf {
                  name
                  url
                }
              }
            }
            job {
              sourcedPostingId
            }
            tracking {
              recruiterEmail
            }
          }
        }
      }
    }
  }
}

次の入力フィールドを指定します。

fetchAssets の入力フィールド

フィールド	タイプ	説明
limit	Int!	返すアセットの最大数です。
token	String	前回の fetchAssets 呼び出しで取得したトークンです。このトークンを渡すと、バッチが確認済みとしてマークされ、再び取得されなくなります。

レスポンス – 未確認のアセットを取得する

API は FetchAssetsAtsSyncCandidateSyncPayload レスポンスオブジェクトを返します。このオブジェクトには次のフィールドが含まれます。

fetchAssets のレスポンスフィールド

フィールド	タイプ	説明
assets	[AtsSyncCandidateSyncAsset]!	次に利用可能な AtsSyncCandidateSyncAsset オブジェクトです。
token	String	このバッチの確認応答トークンです。次回の fetchAssets 呼び出しに含めると、受信を確認し、次のバッチをリクエストできます。null または空の場合は、すべてのアセットが配信済みです。再度呼び出す前に、標準のポーリング間隔だけ待機してください。

時間範囲でアセットを取得する

アセットを確認した後、assetsByTimeRange を呼び出して Indeed から再取得できます。データ損失から復旧するには、このクエリを使用してください。アセットデータは、自社のデータストアに保持してください。ページネーションのベストプラクティスについては、GraphQL Cursor Connections Specification をご覧ください。

2-legged OAuth トークン. で認証します。アプリケーションは、ユーザー操作なしで Indeed の認可サーバーに直接認証します。

新しいアセットを取得するには、fetchAssets を使用します。

リクエスト – 時間範囲でアセットを取得する

開始日または終了日を省略すると、クエリはデフォルトで最も古い確認日と最も新しい確認日を使用します。

時間範囲で確認済みのアセットを取得します。

query AssetsByTimeRange($input: AtsSyncCandidateSyncAssetsByTimeRangeInput!,
  $after: String) {
  atsSyncCandidateSync {
    assetsByTimeRange(input: $input, after: $after) {
      assets {
        id
        metadata {
          employerIdentifier
          stagedAt
          stagedTest
          completeSourceAttribution {
            enumKey
            name
          }
        } 
        ... on AtsSyncCandidateSyncInterestedCandidateAsset {
          contact {
            candidate {
              email
              location
              name
              phone
              resume {
                pdf {
                  name
                  url
                }
              }
            }
            job {
              sourcedPostingId
            }
            tracking {
              recruiterEmail
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

レスポンス – 時間範囲でアセットを取得する

assetsByTimeRange は fetchAssets と同じアセットデータを返しますが、確認済みのアセットのみを返します。レスポンス – 未確認のアセットを取得する をご覧ください。

モックアセットは 14 日後に期限切れとなり、その後は assetsByTimeRange のレスポンスに表示されなくなります。テストアセットを作成する をご覧ください。

テストアセットを作成する

サンドボックスモードでテスト候補者アセットを作成するには、stageAssets を呼び出します。テストアセットは実際の候補者アセットと同じように機能します。fetchAssets を使用して取得し、ワークフローをテストしてください。

2-legged OAuth トークン. で認証します。アプリケーションは、ユーザー操作なしで Indeed の認可サーバーに直接認証します。

要件

テストアセットをステージングする前に、次の要件を確認してください。

• employerIdentifier は、registerEmployer を通じて作成した雇用主登録の employerIdentifier と一致する必要があります。
• sourcedPostingId は UUID である必要がありますが、既存の求人掲載に対応している必要はありません。
• モックアセットデータは、ステージングから 14 日後に自動的に削除されます。

リクエスト – テストアセットを作成する

テストアセットを作成するには、次の手順を実行します。

1. 名前、メールアドレス、電話番号、所在地などのテスト候補者の詳細を指定して、stageAssets を呼び出します。

   テスト用の履歴書を含めるには、includeResume を true に設定します。

   API は、ステージングした各アセットの一意の ID を返します。

2. ステージングした候補者を取得するには、fetchAssets を呼び出します。

3. 連携で候補者データが処理されることを確認します。

   モックアセットは、assets の metadata にある stageTest フィールドを使用して識別します。

連携テスト用のテスト候補者アセットを作成します。

mutation {
  atsSyncCandidateSync {
    stageAssets(input: {
      assets: [{
        smartSourcingContact: {
          metadata: {
            employerIdentifier: "employer-123"
          }
          contact: {
            candidate: {
              name: "Jane Smith"
              email: "jsmith@example.com"
              location: "Syracuse, New York 13209"
              phone: "+10001112223"
              includeResume: true
            }
            job: {
              sourcedPostingId: "e29aaba8-2cef-447f-a1e0-bcb7ec3fa730"
            }
            tracking: {
              recruiterEmail: "recruiter@example.com"
            }
          }
        }
      }]
    }) {
      ids
    }
  }
}

エラーをトラブルシューティングする

GraphQL にアクセスする前に発生する可能性がある OAuth エラーのトラブルシューティングについては、OAuth エラーをトラブルシューティングする をご覧ください。

GraphQL エラーのトラブルシューティングについては、GraphQL エラーをトラブルシューティングする をご覧ください。

 

このページは役に立ちましたか？