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：連携テスト用のテストアセットを作成します。

認証する

Indeedパートナーになると、Indeedが連携用のアプリを作成します。Partner Consoleにログインして、アプリとOAuth認証情報（クライアントID、クライアントシークレット、および3-legged OAuthの場合は認可コード）を確認します。認証情報をアクセストークンと交換し、API呼び出しを認証します。

Candidate Sync APIの各操作には、OAuthトークンが必要です。

Candidate Sync API操作のOAuthトークンタイプ

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

アクセストークンはATSに安全に保管し、ユーザー間で共有しないでください。Indeedは、お客様のシステムが求人の信頼できる情報源（source of truth）であると想定しています。あるユーザーが投稿した求人に対して別のユーザーのアクセストークンを使用すると、Indeed上で他のユーザーの求人へのアクセス権がそのユーザーに付与される可能性があります。

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

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

雇用主を登録する

Employer Registration APIを使用して雇用主を登録できます。

リクエスト – 雇用主を登録する

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

認証

employer.ats_candidate.syncスコープを持つ、雇用主を表す3-legged OAuthトークンで認証します。このトークンは、雇用主のIndeedアカウントとそのATSアカウントを関連付けます。Indeedの管理者またはオーナーが作成する必要があります。

registerEmployerがスコープ不足のエラーを返す場合、トークンが雇用主に関連付けられていない可能性があります。

雇用主を表す3-legged OAuthトークンをご覧ください。

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

registerEmployerの入力フィールド

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

レスポンス – 雇用主を登録する

レスポンスはEmployerRegistrationを返します。以降のCandidate Sync APIの呼び出しで使用するため、登録のidを保存してください。後からpartnerEmployerIdを使ってfindRegisteredEmployersで検索することもできます。

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

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

認証

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

2-legged OAuthトークンをご覧ください。

Retrieve Candidates APIは現在、Smart Sourcing由来のinterested candidatesに対応しています。今後のアップデートで新しいアセットタイプが追加される可能性があります。レスポンス内の想定外のアセットタイプは適切に処理してください。すべてのアセットが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の認可サーバーと直接認証します。

2-legged OAuthトークンをご覧ください。

注記

新しいアセットを取得するには、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の認可サーバーと直接認証します。

2-legged OAuthトークンをご覧ください。

要件

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

• 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エラーのトラブルシューティングをご覧ください。

 

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