Retrieve Candidates API guide

Get candidate information from Indeed for employers.

 

法的注意

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

API overview

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

Asset types

The Retrieve Candidates API returns these candidate asset types, which implement the AtsSyncCandidateSyncAsset interface:

• AtsSyncCandidateSyncInterestedCandidateAsset from Smart Sourcing.

  Includes this candidate information (AtsSyncCandidateSyncInterestedCandidate):

  AtsSyncCandidateSyncInterestedCandidate fields

  Field	Description
  name Type: String!	The candidate's full name.
  email Type: EmailAddress!	The candidate's email address.
  location Type: String	The candidate's location, if provided.
  resume Type: AtsSyncCandidateSyncInterestedCandidateResume	A presigned S3 URL to download the candidate's resume. See Download and upload objects with presigned URLs （新しいウィンドウで開きます）.

• AtsSyncCandidateSyncSmartScreeningUpdateAsset from Smart Screening updates.

  Smart Screening updates apply to the partner, not to one employer registration, so any Smart Screening job can produce application updates. Fetch results omit employerIdentifier and staging input omits metadata.employerIdentifier, so use the Indeed Apply ID to identify the application.

  Smart Sourcing requires employerIdentifier because it targets one employer registration.

  Includes this candidate information (AtsSyncCandidateSyncSmartScreeningUpdate):

  AtsSyncCandidateSyncSmartScreeningUpdate fields

  Field	Description
  applicationIdentifier Type: AtsSyncCandidateSyncScreeningApplicationIdentifier!	Application ID for the screening update. Select the Indeed Apply union member and read its indeedApply.indeedApplyId.
  smartFitScore Type: Float	The candidate's smart fit score, if available. Returns null if no score was staged.
  resume Type: AtsSyncCandidateSyncAssetFile!	The candidate's resume file. Use: resume { url name contentType } The download URL is a short-lived presigned URL. See Download and upload objects with presigned URLs （新しいウィンドウで開きます）.
  createdAt Type: DateTime!	When the screening update was created. Order updates by this timestamp.

These fetch operations can return both types:

• Get unacknowledged assets (fetchAssets)
• Get assets by time range (assetsByTimeRange)

Create test assets (stageAssets) accepts either asset type as input.

Best practices

Best practices

Best practice	Description
Handle interfaces and unions defensively	For the AtsSyncCandidateSyncAsset interface, use ... on Type inline fragments for known types and ignore unknown types. For the AtsSyncCandidateSyncScreeningApplicationIdentifier union, which includes AtsSyncCandidateSyncIndeedApplyApplicationIdentifier, check __typename and allow for new members later.
Apply updates in order	Order Smart Screening updates by AtsSyncCandidateSyncSmartScreeningUpdate.createdAt, which shows when the update happened. Do not order Smart Screening updates by AtsSyncCandidateSyncAssetMetadata.stagedAt, which shows when the asset became available. If you apply updates out of order, older data can overwrite newer data.

---

API steps

After you integrate with the Retrieve Candidates API, complete these steps to get candidate information from Indeed for employers:

---

1. 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 トークン で認証します。ユーザー操作は必要ありません。

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

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

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

---

2. 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 でもう一度取得します。

---

3. Get unacknowledged assets

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

fetchAssets returns assets from:

• Smart Sourcing outreach (AtsSyncCandidateSyncInterestedCandidateAsset)
• Smart Screening updates (AtsSyncCandidateSyncSmartScreeningUpdateAsset)

A single request can return a mix of both asset types. Indeed might add asset types, so handle types you do not recognize rather than assuming every asset is one of these two.

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

Smart Sourcing assets use employerIdentifier.

Smart Screening assets use applicationIdentifier.indeedApply.indeedApplyId.

Either the employerIdentifier or the indeedApplyId in the response matches the ID you sent when you created the registration. Use it to identify which employer receives the candidate.

Request — Get unacknowledged assets

This mutation returns a token, asset metadata, candidate details for interested candidates, and screening update details for Smart Screening 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 {
                files {
                  url
                  name
                  contentType
                }
              }
            }
            job {
              sourcedPostingId
            }
            tracking {
              recruiterEmail
            }
          }
        }
        ... on AtsSyncCandidateSyncSmartScreeningUpdateAsset {
          smartScreeningUpdate {
            smartFitScore
            createdAt
            applicationIdentifier {
              __typename
              ... on AtsSyncCandidateSyncIndeedApplyApplicationIdentifier {
                indeedApplyId
              }
            }
            resume {
              url
              name
              contentType
            }
          }
        }
      }
    }
  }
}

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 it 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, so wait the standard polling interval before you call again.

---

4. Get assets by time range

After you acknowledge assets, call assetsByTimeRange to fetch them again. Use this query to recover from data loss, and persist asset data in your own 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.

This query returns assets for a time range, including candidate details, Smart Screening updates, and pagination information:

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

Response — Get assets by time range

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

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

---

5. Create test assets

Call stageAssets to create test candidate assets in sandbox mode. Test assets behave like real ones, so you can retrieve them with fetchAssets to test your workflow.

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

Requirements

Before you stage test assets:

• For Smart Sourcing test assets, metadata.employerIdentifier must match the employerIdentifier of an employer registration that you created through registerEmployer.
• Smart Screening test assets do not use metadata.employerIdentifier.
• The sourcedPostingId must be a UUID, but does not need to match an existing job posting.
• Indeed removes test 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 test assets, check the stagedTest field on the metadata of each assets entry.

This mutation stages a Smart Sourcing candidate asset for an employer and returns the created asset IDs. Provide these required and optional fields:

stageAssets input fields to stage Smart Sourcing candidate asset for an employer

Field	Required	Type	Description
metadata	Yes	AtsSyncCandidateSyncAssetMetadataInput	Asset metadata.
contact	Yes	AtsSyncCandidateSyncInterestedCandidateContactInput	The candidate's contact information.
job	No	AtsSyncCandidateSyncInterestedCandidateContactJobInput	Job information for the contact.
tracking	No	AtsSyncCandidateSyncInterestedCandidateTrackingInput	Tracking information for attribution and reporting.

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

This mutation stages a Smart Screening update asset for an Indeed Apply application and returns the created asset IDs.

smartScreeningUpdate is one member of the oneOf AtsSyncCandidateSyncStageableAssetInput. Set exactly one asset type for each list entry.

Provide these required and optional fields:

stageAssets input fields to stage Smart Screening update asset

Field	Required	Type	Description
indeedApplyId	Yes	ID!	Indeed Apply ID for the application that was updated. applicationIdentifier is a oneOf, so set only indeedApply.
smartFitScore	No	Float	The candidate's smart fit score, if available. Omit this field to return null for the score.
createdAt	No	DateTime	The time when the screening update was created. Order updates by this timestamp. Defaults to the current time if omitted.

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

Screening does not use an includeResume flag. Screening updates always include a resume, so Indeed always attaches a fixed sample resume PDF.

---

6. Troubleshoot errors

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

For GraphQL errors, see Troubleshoot GraphQL errors.

---

GraphQL API reference

• registerEmployer — Registers an employer. Authenticate with a 3-legged OAuth token that represents an employer and the employer.ats_candidate.sync scope.
• 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.

 

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