Retrieve Candidates API guide

Get candidate information from Indeed for employers.

 

legal notice

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 they were staged, from oldest to newest.
4. 4.
   Get assets by time range: Get acknowledged assets by 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: Register an employer, and return information about the registration.
• fetchAssets: Get unacknowledged assets in the order they were staged, from oldest to newest.
• assetsByTimeRange: Get acknowledged assets by time range.
• stageAssets: Create test assets for integration testing.

Authenticate

When you become an Indeed partner, Indeed sets up an app for your integration. Log 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.

Each Candidate Sync API operation requires an OAuth token:

OAuth token types for Candidate Sync API operations

API / operations	OAuth token type
Employer Registration API Register an employer	Authentication Authenticate with a 3-legged OAuth token that represents an employer with the employer.ats_candidate.sync scope. This token links the employer's Indeed account to their ATS account. An Indeed administrator or owner must create it. If registerEmployer returns a missing scope error, the token might not be associated with an employer. See 3-legged OAuth token that represents an employer.
Employer Registration API Update a registration List registrations Deregister an employer Send Candidates API Initialize application and upload attachments Submit application Track application status Delete application Retrieve Candidates API Get unacknowledged assets Get assets by time range Create test assets	Authentication Authenticate with a 2‑legged OAuth token. Your application authenticates directly with Indeed's authorization server without user interaction. See 2‑legged OAuth token.

Securely store access tokens in your ATS, and don't share them between users. Indeed trusts that your system is the source of truth for a job. If you use a user's access token for a job that another user posted, Indeed might grant that user access to the other user's job on Indeed.

After you get an access token, include this token in the query or mutation. Indeed recommends that you refresh your access tokens before they expire to avoid asking users to log in every time they need to view updated job statuses.

See Integrate with Indeed and call APIs and Scopes.

Register employer

The Employer Registration API enables you to register an employer.

Request – Register employer

To register an employer and return registration information, call registerEmployer.

Authentication

Authenticate with a 3-legged OAuth token that represents an employer with the employer.ats_candidate.sync scope. This token links the employer's Indeed account to their ATS account. An Indeed administrator or owner must create it.

If registerEmployer returns a missing scope error, the token might not be associated with an employer.

See 3-legged OAuth token that represents an employer.

Provide these input fields:

registerEmployer input fields

Field	Required	Description
partnerEmployerId Type: ID!	✅	Partner-provided ID that uniquely identifies the employer. You can register one partnerEmployerId with multiple Indeed accounts, but each Indeed account supports only one partnerEmployerId per ATS. Using a different partnerEmployerId with the same Indeed account updates the registration to the specified atsName and partnerEmployerId.
atsName Type: String!	✅	Partner-provided name the employer uses. Employers on Indeed see this name.

Response – Register employer

The response returns EmployerRegistration. Save the registration id for subsequent Candidate Sync API calls, or look it up later with findRegisteredEmployers by partnerEmployerId.

Get unacknowledged assets

Call fetchAssets to get unacknowledged assets in the order they were staged, from oldest to newest.

Authentication

Authenticate with a 2‑legged OAuth token. Your application authenticates directly with Indeed's authorization server without user interaction.

See 2‑legged OAuth token.

The Retrieve Candidates API currently supports interested candidates from Smart Sourcing. New asset types might be added in future updates — handle unexpected asset types in the response gracefully. Not every asset is an AtsSyncCandidateSyncInterestedCandidateAsset.

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

Request – Get unacknowledged assets

The 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 marks the batch as acknowledged and prevents it from being retrieved again.

Response – Get unacknowledged assets

The API returns the FetchAssetsAtsSyncCandidateSyncPayload response object, which contains these fields:

fetchAssets response fields

Field	Type	Description
assets	[AtsSyncCandidateSyncAsset]!	Next available AtsSyncCandidateSyncAsset objects.
token	String	Acknowledgment token for this batch. Include it in the next fetchAssets call to acknowledge receipt and request the next batch. If null or empty, all assets have been delivered — wait the standard polling interval before calling again.

Get assets by time range

After acknowledging assets, call assetsByTimeRange to re-retrieve them from Indeed. Use this query to recover from data loss. Persist asset data in your own data store. See the GraphQL Cursor Connections Specification for pagination best practices.

Authentication

Authenticate with a 2‑legged OAuth token. Your application authenticates directly with Indeed's authorization server without user interaction.

See 2‑legged OAuth token.

note

To retrieve new assets, use fetchAssets.

Request – Get assets by time range

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

Gets acknowledged assets by 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 returns acknowledged assets. See Response – Get unacknowledged assets.

Mock assets expire after 14 days and no longer appear in assetsByTimeRange responses. See Create test assets.

Create test assets

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

Authentication

Authenticate with a 2‑legged OAuth token. Your application authenticates directly with Indeed's authorization server without user interaction.

See 2‑legged OAuth token.

Requirements

Before staging test assets:

• The employerIdentifier must match the employerIdentifier of an employer registration created through registerEmployer.
• The sourcedPostingId must be a UUID, but does not need to correspond to an existing job posting.
• Mock asset data is automatically removed 14 days after staging.

Request – Create test assets

To create test assets:

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

   To include a test resume, set includeResume to true.

   The API returns unique IDs for each staged asset.

2. To retrieve the staged candidates, call fetchAssets.

3. Verify that your integration processes the candidate data.

   Identify mock assets using the stageTest field on the assets metadata.

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

To troubleshoot OAuth errors that can occur before you access GraphQL, see Troubleshoot OAuth errors.

To troubleshoot GraphQL errors, see Troubleshoot GraphQL errors.

 

Was this page helpful?