Send Candidates API guide

Synchronize candidate applications with Indeed.

 

legal notice

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

Send Candidates API workflow

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

1. 1.
   Send Candidates API overview: Learn how the Send Candidates API syncs candidate applications with Indeed.
2. 2.
   Authenticate.
3. 3.
   Register employer: Register an employer, and return information about the registration.
4. 4.
   Initialize application and upload attachments: Stage an application version with Indeed, generate attachment upload URLs, and upload files to those URLs.
5. 5.
   Submit application: Submit an application version to Indeed. Versions are published asynchronously in submission order.
6. 6.
   Track application status: Track application status and processing errors.
7. 7.
   Delete application: Permanently remove an application and all its versions from Indeed.
8. 8.
   [Troubleshoot GraphQL errors](/integration-basics/graphql-at-indeed/troubleshoot-graphql-errors: Resolve GraphQL errors.

Send Candidates API references

• registerEmployer: Register an employer, and return information about the registration.
• application.initialize: Stage an application version with Indeed and generate URLs to upload attachments.
• application.submit: Submit an application.
• findStatuses: Track application status and processing errors.
• application.delete: Delete an application.

Send Candidates API overview

The Send Candidates API provides a complete workflow for submitting and tracking candidate applications. Submitting an application requires three steps: initialize, upload attachments, and submit.

Initializing stages an application version with Indeed and generates URLs to upload attachments. Each initialization creates a version with a unique applicationVersionId. After initialization, you have five minutes to upload attachments and submit.

The API organizes data in a hierarchy. The applicationIdentifier object contains these fields, which uniquely identify an application:

Application identity

Field	Required	Description
indeedRegistrationId	✅	Unique ID linking an Indeed employer to a partner employer. Provided during registration.
atsCandidateId	⬜	ID for a candidate profile associated with one or more ATS applications.
atsApplicationId	✅	Unique ID for the application in the ATS.
job.sourcedPostingId	✅	Job posting ID that createSourcedJobPostings returns.

This combination defines a single logical application. Each time you call initialize with the same applicationIdentifier, you create a new version of that application.

Every field, including optional ones, affects uniqueness. For example, an application with an atsCandidateId is different from one without it, even if all other fields match.

When you upload attachments:

• All attachments are scanned for viruses and harmful content. Unsafe files are removed.
• Total size of all attachments must not exceed 15 MB (15,728,640 bytes).
• Individual file size must not exceed 6 MB (6,291,456 bytes).
• Duplicate attachments are not allowed, based on MD5 hash.
• Include at most one RESUME and one COVER_LETTER attachment. Use OTHER_RESUME or OTHER_COVER_LETTER for additional files.
• All attachments must have a valid Base64-encoded MD5 checksum.

Answers to questions about protected demographic information (such as race, gender, age, or disability status) are not published to Indeed.

Deleting an application permanently removes it and all its versions from Indeed. You cannot reinitialize deleted applications.

Avoid concurrent mutations (initialize, submit, delete) on the same application. Running them too close together can cause race conditions, unexpected data states, and confusion about which version is published.

Authenticate

When you become an Indeed partner, Indeed sets up an app for your integration. Sign 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 and 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 sign 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!	✅	An ID you provide to uniquely identify the employer. You can register one partnerEmployerId with multiple Indeed accounts, but each Indeed account supports only one partnerEmployerId per ATS. If you use a different partnerEmployerId with the same Indeed account, Indeed updates the registration to the new atsName and partnerEmployerId.
atsName Type: String!	✅	The name you provide for the employer. Employers see this name on Indeed.

Response – Register employer

The API returns an EmployerRegistration. Store its id to use in later Candidate Sync API calls, or query findRegisteredEmployers with the partnerEmployerId to retrieve it.

Initialize application and upload attachments

Stage an application version with Indeed, generate attachment upload URLs, and upload files to those URLs.

Request – Initialize application

To initialize an application, call initialize. This operation stages an application version with Indeed and generates URLs to upload attachments.

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.

Set indeedRegistrationId to the EmployerRegistration.id that registerEmployer returns. The employer must enable the sendApplications feature.

See:

• indeedRegistrationId
• id
• registerEmployer
• EmployerRegistration
• sendApplications

The employer must have the sendApplications feature enabled.

Provide these input fields:

initialize mutation fields

Field	Required	Description
applicationIdentifier Type: AtsSyncCandidateSyncApplicationIdentifierInput!	✅	Unique ID for the application on Indeed.
applicant Type: AtsSyncCandidateSyncApplicantDetailsInput!	✅	Complete applicant details.
questionsAndAnswers Type: [AtsSyncCandidateSyncApplicationQuestionAndAnswerInput!]!	⬜	Screener questions and applicant answers, each as a plain text string.
disposition Type: AtsSyncCandidateSyncApplicationDispositionInput!	✅	Current application disposition status. See Indeed Standard Disposition Statuses for status mapping examples.
applicationLink Type: WebUrl!	✅	Direct link to the application in your system.
candidateLink Type: WebUrl	⬜	Direct link to the candidate profile in your system.

mutation InitializeApplication($input:
  InitializeAtsSyncCandidateSyncApplicationInput!) {
  atsSyncCandidateSync {
    application {
      initialize(input: $input) {
        applicationVersionId
        attachments {
          fileType
          fileName
          contentType
          contentLength
          fileChecksum {
            checksum
          }
          url
        }
      }
    }
  }
}

Response – Initialize application

Initialize application response fields

Field	Description
applicationVersionId Type: ID!	New application version, used when submitting.
attachments Type: [AtsSyncCandidateSyncApplicationAttachment!]!	Uploads file data for each attached file.

For each attachment returned in the initialize response, upload the file data with a PUT request to url. Include these headers matching the applicant.attachments values from the initialize mutation:

Upload attachments

Header	Value source	Description
Content-Type	contentType	Original media type of the file attachment.
Content-Length	contentLength	File size in bytes.
Content-MD5	fileChecksum.checksum	MD5 hash. Base64-encode the checksum as the Content-MD5 header value.

Submit application

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.

Submit an application version to Indeed. Versions are published asynchronously in submission order.

Set indeedRegistrationId to the EmployerRegistration.id returned by registerEmployer. The employer must enable the sendApplications feature.

See:

• indeedRegistrationId
• id
• registerEmployer
• EmployerRegistration
• sendApplications

Request – Submit application

To submit an application, call the application.submit mutation.

Provide these input fields:

submit mutation fields

Field	Required	Description
indeedRegistrationId Type: ID!	✅	Links to the Indeed employer account.
applicationVersionId Type: ID!	✅	Version ID that application.initialize returns.

mutation SubmitApplication($input: SubmitAtsSyncCandidateSyncApplicationInput!) {
  atsSyncCandidateSync {
    application {
      submit(input: $input) {
        applicationVersionId
      }
    }
  }
}

Response – Submit application

submit response fields

Field	Description
applicationVersionId Type: ID!	Same as the input value. Log for audit purposes if needed.

Call submit within five minutes of initialization. Upload all file attachments before you submit. Indeed still processes applications with missing attachments, but findStatuses returns a FILE_NOT_UPLOADED error. You can submit an application even if a file attachment fails to process. Indeed processes applications asynchronously and preserves submission order.

Track application status

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.

After submission, query application version status to check processing and identify errors.

Request – Find application status

To query application version status with pagination, call findStatuses.

Use this query to track publishing progress after submission and check bulk status with version history.

findStatuses filters

Field	Filters by
indeedRegistrationIds Type: ID!	Employers.
applications Type: [AtsSyncCandidateSyncApplicationIdentifierInput!]!	Application IDs.
applicationVersionIds Type: [ID!]!	Application versions.
applicationVersionStatusTypes Type: [AtsSyncCandidateSyncApplicationVersionStatusTypeInput!]!	Statuses.

query FindApplicationStatuses($input:
  AtsSyncCandidateSyncApplicationFindStatusesInput!$first: Int $after:
  String $last: Int $before: String) {
  atsSyncCandidateSync {
    application {
      findStatuses(input: $input first: $first after: $after last:
        $last before: $before) {
        applicationVersionStatuses {
          applicationVersionId
          applicationIdentifier {
            indeedRegistrationId
            atsCandidateId
            atsApplicationId
            job {
              sourcedPostingId
            }
          }
          status
          processingStatus
          errors
        }
        pageInfo {
          hasNextPage
          hasPreviousPage
          startCursor
          endCursor
        }
      }
    }
  }
}

Delete application

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.

Permanently remove an application and all its versions from Indeed.

Set indeedRegistrationId to the EmployerRegistration.id returned by registerEmployer. The employer must enable the sendApplications feature.

See:

• indeedRegistrationId
• id
• registerEmployer
• EmployerRegistration
• sendApplications

Request – Delete application

To delete an application, call the application.delete mutation.

This operation is permanent. Indeed removes all application versions. You cannot recreate versions or create new versions after deletion.

delete mutation fields

Field	Required	Description
applicationIdentifier Type: AtsSyncCandidateSyncApplicationIdentifierInput!	✅	Unique ID for the application.
deletedAt Type: DateTime!	✅	Timestamp when the application was deleted.

mutation DeleteApplication($input: DeleteAtsSyncCandidateSyncApplicationInput!) {
  atsSyncCandidateSync {
    application {
      delete(input: $input) {
        applicationVersionId
      }
    }
  }
}

Response – Delete application

delete response fields

Field	Description
applicationVersionId Type: ID!	Unique ID for this deletion. References the final version of the deleted application.

 

Was this page helpful?