Retrieve Candidates API ガイド

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

 

法的注意

このAPIとそのドキュメントを使用して連携を構築すると、APIに関する追加の利用規約およびガイドラインに同意したことになります。

Retrieve Candidates API を呼び出して、雇用主向けに 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 雇用主を登録する	雇用主を表す 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 を呼び出す と スコープをご覧ください。

アセットタイプ

Retrieve Candidates API は、AtsSyncCandidateSyncAsset インターフェースを実装する次の候補者アセットタイプを返します。

• Smart Sourcing からの AtsSyncCandidateSyncInterestedCandidateAsset。

  次の候補者情報（AtsSyncCandidateSyncInterestedCandidate）を含みます。

  AtsSyncCandidateSyncInterestedCandidate のフィールド

  フィールド	説明
  name Type: String!	候補者の氏名です。
  email Type: EmailAddress!	候補者のメールアドレスです。
  location Type: String	指定されている場合、候補者の所在地です。
  resume Type: AtsSyncCandidateSyncInterestedCandidateResume	候補者の履歴書をダウンロードするための署名付き S3 URL です。Download and upload objects with presigned URLs をご覧ください。

• Smart Screening の更新からの AtsSyncCandidateSyncSmartScreeningUpdateAsset。

  Smart Screening の更新は、1 つの雇用主登録ではなく、パートナーに適用されます。Smart Screening の求人は、応募の更新を生成できます。取得結果には employerIdentifier は含まれません。ステージング入力には metadata.employerIdentifier は含まれません。

  応募を識別するには、Indeed Apply ID を使用します。

  Smart Sourcing は 1 つの雇用主登録を対象とするため、employerIdentifier が必要です。

  AtsSyncCandidateSyncSmartScreeningUpdateAsset には、次の候補者情報（AtsSyncCandidateSyncSmartScreeningUpdate）が含まれます。

  AtsSyncCandidateSyncSmartScreeningUpdate のフィールド

  フィールド	説明
  applicationIdentifier Type: AtsSyncCandidateSyncScreeningApplicationIdentifier!	スクリーニング更新の応募 ID です。このフィールドはユニオンです。indeedApply.indeedApplyId を設定します。
  smartFitScore Type: Float	利用できる場合、候補者のスマートフィットスコアです。スコアをステージングしていない場合は null を返します。
  resume Type: AtsSyncCandidateSyncAssetFile!	候補者の履歴書ファイルです。次を使用します。 resume { url, name, contentType } ダウンロード URL は短時間のみ有効な署名付き URL です。Download and upload objects with presigned URLs をご覧ください。
  createdAt Type: DateTime!	スクリーニング更新が作成された時刻です。更新はこのタイムスタンプで順序付けします。

これらの取得操作は、両方のタイプを返す場合があります。

• 未確認のアセットを取得する（fetchAssets）
• 時間範囲でアセットを取得する（assetsByTimeRange）

テストアセットを作成する（stageAssets） は、テストアセットを作成するときに、どちらのアセットタイプも入力として受け入れます。

ベストプラクティス

ベストプラクティス

ベストプラクティス	説明
インターフェースとユニオンを防御的に処理する	AtsSyncCandidateSyncAsset インターフェース では、既知のタイプに対して ... on Type のインラインフラグメントを使用し、未知のタイプは無視してください。 AtsSyncCandidateSyncIndeedApplyApplicationIdentifier を含む AtsSyncCandidateSyncScreeningApplicationIdentifier ユニオン では、__typename を確認し、今後新しいメンバーが追加されても処理できるようにしてください。
更新を順番どおりに適用する	Smart Screening の更新は、更新が発生した時刻を示す AtsSyncCandidateSyncSmartScreeningUpdate.createdAt で順序付けします。 アセットが利用可能になった時刻を示す AtsSyncCandidateSyncAssetMetadata.stagedAt では順序付けしないでください。 順序どおりに適用しないと、古いデータで新しいデータを上書きする可能性があります。

雇用主を登録する

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 を呼び出して、ステージングした順に、古いものから新しいものへ未確認のアセットを取得します。

fetchAssets は、次の関心を示した候補者をサポートします。

• Smart Sourcing のアウトリーチ（AtsSyncCandidateSyncInterestedCandidateAsset）
• Smart Screening の更新（AtsSyncCandidateSyncSmartScreeningUpdateAsset）

パートナーは、1 回のリクエストで両方のアセットタイプが混在したレスポンスを受け取る場合があります。

Indeed はアセットタイプを追加する場合があるため、レスポンス内の想定外のアセットタイプも処理してください。すべてのアセットが AtsSyncCandidateSyncInterestedCandidateAsset または AtsSyncCandidateSyncSmartScreeningUpdateAsset とは限りません。

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

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

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

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

このクエリは、未確認の Candidate Sync アセットを取得し、トークン、アセットメタデータ、関心を示した候補者の詳細、および Smart Screening アセットのスクリーニング更新の詳細を返します。

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 {
                files {
                  url
                  name
                  contentType
                }
              }
            }
            job {
              sourcedPostingId
            }
            tracking {
              recruiterEmail
            }
          }
        }
        ... on AtsSyncCandidateSyncSmartScreeningUpdateAsset {
          smartScreeningUpdate {
            smartFitScore
            createdAt
            applicationIdentifier {
              __typename
              ... on AtsSyncCandidateSyncIndeedApplyApplicationIdentifier {
                indeedApplyId
              }
            }
            resume {
              url
              name
              contentType
            }
          }
        }
      }
    }
  }
}

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

fetchAssets の入力フィールド

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

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

API は、次のフィールドを含む FetchAssetsAtsSyncCandidateSyncPayload オブジェクトを返します。

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

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

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

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

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

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

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

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

時間範囲の Candidate Sync アセットを取得し、候補者の詳細、Smart Screening の更新、およびページネーション情報を返します。

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 {
                files {
                  url
                  name
                  contentType
                }
              }
            }
            job {
              sourcedPostingId
            }
            tracking {
              recruiterEmail
            }
          }
        }
        ... on AtsSyncCandidateSyncSmartScreeningUpdateAsset {
          smartScreeningUpdate {
            smartFitScore
            createdAt
            applicationIdentifier {
              __typename
              ... on AtsSyncCandidateSyncIndeedApplyApplicationIdentifier {
                indeedApplyId
              }
            }
            resume {
              url
              name
              contentType
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

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

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

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

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

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

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

要件

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

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

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

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

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

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

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

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

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

   モックアセットを識別するには、各 assets エントリの metadata にある stageTest フィールドを確認します。

雇用主向けの Smart Sourcing 候補者アセットをステージングし、作成したアセット ID を返します。

次の必須フィールドと任意フィールドを指定します。

雇用主向けの Smart Sourcing 候補者アセットをステージングするための stageAssets 入力フィールド

フィールド	必須	タイプ	説明
metadata	はい	AtsSyncCandidateSyncAssetMetadataInput	アセットメタデータです。
contact	はい	AtsSyncCandidateSyncInterestedCandidateContactInput	候補者の連絡先情報です。
job	いいえ	AtsSyncCandidateSyncInterestedCandidateContactJobInput	連絡先の求人情報です。
tracking	いいえ	AtsSyncCandidateSyncInterestedCandidateTrackingInput	アトリビューションとレポート作成のためのトラッキング情報です。

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
    }
  }
}

Indeed エントリー応募向けの Smart Screening 更新アセットをステージングし、作成したアセット ID を返します。

次の必須フィールドと任意フィールドを指定します。

smartScreeningUpdate は、oneOf AtsSyncCandidateSyncStageableAssetInput の 1 つのメンバーです。各リストエントリに対して、アセットタイプは 1 つだけ設定します。

Smart Screening 更新アセットをステージングするための stageAssets 入力フィールド

フィールド	必須	タイプ	説明
indeedApplyId	はい	ID!	更新された応募の Indeed Apply ID です。applicationIdentifier は oneOf なので、indeedApply のみを設定します。
smartFitScore	いいえ	Float	利用できる場合、候補者のスマートフィットスコアです。スコアを null で返すには、このフィールドを省略します。
createdAt	いいえ	DateTime	スクリーニング更新が作成された時刻です。更新はこのタイムスタンプで順序付けします。省略した場合は現在時刻がデフォルトになります。

mutation {
  atsSyncCandidateSync {
    stageAssets(input: {
      assets: [{
        smartScreeningUpdate: {
          applicationIdentifier: {
            indeedApply: {
              indeedApplyId: "example-indeed-apply-id"
            }
          }
          smartFitScore: 0.87
          createdAt: "2026-06-22T12:00:00Z"
        }
      }]
    }) {
      ids
    }
  }
}

スクリーニングでは includeResume フラグを使用しません。スクリーニング更新には常に履歴書が含まれるため、固定のサンプル履歴書 PDF が常に添付されます。

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

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

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

 

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