Retrieve Candidates API guide

Get candidate information from Indeed for employers.

 

法的注意

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

Call the Retrieve Candidates API to get candidate information from Indeed for employers.

Retrieve Candidates API workflow

After you integrate with the Retrieve Candidates API, you can call these operations:

1. 1.
   Authenticate.
2. 2.
   Register employer: Register an employer and return information about the registration.
3. 3.
   Get unacknowledged assets: Get unacknowledged assets in the order you staged them, from oldest to newest.
4. 4.
   Get assets by time range: Get acknowledged assets in a time range.
5. 5.
   Create test assets: Create test assets for integration testing.
6. 6.
   Troubleshoot GraphQL errors: Resolve GraphQL errors.

Retrieve Candidates API reference

• registerEmployer: Registers an employer and returns information about the registration.
• fetchAssets: Returns unacknowledged assets in the order you staged them, from oldest to newest.
• assetsByTimeRange: Returns acknowledged assets in a time range.
• stageAssets: Creates test assets for integration testing.

Authenticate

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 を呼び出す と スコープをご覧ください。

Register employer

Use the Employer Registration API to register an employer.

リクエスト – 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 でもう一度取得します。

Get unacknowledged assets

Call fetchAssets to get unacknowledged assets in the order you staged them, from oldest to newest.

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

The Retrieve Candidates API currently supports interested candidates from Smart Sourcing. Indeed might add more asset types later, so handle unexpected types in the response. Not every asset is an AtsSyncCandidateSyncInterestedCandidateAsset.

The employerIdentifier in the response matches the ID that you sent to Indeed when you created the registration. Use it to identify which employer receives the candidate.

Request – Get unacknowledged assets

This mutation gets unacknowledged assets.

Get unacknowledged assets:

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

Provide these input fields:

fetchAssets input fields

Field	Type	Description
limit	Int!	Maximum number of assets to return.
token	String	Token from a previous fetchAssets call. Passing this token acknowledges the batch and prevents you from retrieving it again.

Response – Get unacknowledged assets

The API returns a FetchAssetsAtsSyncCandidateSyncPayload object with these fields:

fetchAssets response fields

Field	Type	Description
assets	[AtsSyncCandidateSyncAsset]!	Next available AtsSyncCandidateSyncAsset objects.
token	String	Acknowledgment token for this batch. Pass the token in the next fetchAssets call to acknowledge receipt and request the next batch. If the token is null or empty, Indeed has delivered all assets. Wait the standard polling interval before you call again.

Get assets by time range

After you acknowledge assets, call assetsByTimeRange to fetch them again from Indeed. Use this query to recover from data loss. Persist asset data in your data store. For pagination best practices, see the GraphQL Cursor Connections Specification.

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

To retrieve new assets, use fetchAssets.

Request – Get assets by time range

If you omit a start or end date, the query uses the earliest and latest acknowledgment dates as defaults.

Gets acknowledged assets in a time range.

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

Response – Get assets by time range

assetsByTimeRange returns the same asset data as fetchAssets, but only for acknowledged assets. See Response – Get unacknowledged assets.

Mock assets expire after 14 days and stop appearing in assetsByTimeRange responses. See Create test assets.

Create test assets

Call stageAssets to create test candidate assets in sandbox mode. Test assets behave like real candidate assets. Use fetchAssets to retrieve them and test your workflow.

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

Requirements

Before you stage test assets:

• The employerIdentifier must match the employerIdentifier of an employer registration that you created through registerEmployer.
• The sourcedPostingId must be a UUID, but does not need to match an existing job posting.
• Indeed removes mock asset data 14 days after you stage it.

Request – Create test assets

To create test assets:

1. Call stageAssets with test candidate details such as name, email, phone, and location.

   To include a test resume, set includeResume to true.

   The API returns a unique ID for each staged asset.

2. Call fetchAssets to retrieve the staged candidates.

3. Verify that your integration processes the candidate data.

   To identify mock assets, check the stageTest field on the metadata of each assets entry.

Creates test candidate assets for integration testing:

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

Troubleshoot errors

For OAuth errors that occur before you reach GraphQL, see Troubleshoot OAuth errors.

For GraphQL errors, see Troubleshoot GraphQL errors.

 

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