Disposition Sync API Guide

Send job application disposition data to Indeed.

Disposition Sync API Reference

See also the Disposition Sync API Reference.

Back to top

Before you start

Note: While our integration documentation is publicly available as a reference to understand and plan your integration with Indeed, it is intended to be implemented only by ATS partners who have signed a Master Services Agreement with Indeed.

Use the client credentials flow (2-legged OAuth) to get a client ID and secret for your application, which you exchange for an access token. Use this token for authentication when you call the Disposition Sync API. The token expires after one hour.

Back to top

Disposition Sync API glossary

Disposition Sync API glossary table
Term Description
application tracking system See ATS.
ATS

Application tracking system. Employers use an ATS to:

  • Track candidates for their open positions.
  • Manage their overall hiring process.
ATS application key An ATS-assigned unique, publicly shareable ID for an application.
disposition data

Any kind of update that happens to an application in your ATS.

Updates can include actions that a recruiter or hiring manager takes after a candidate applies. For example:

  • The ATS receives a new application
  • A candidate is:
    • contacted
    • interviewed
    • offered a position
    • rejected
    • hired
Indeed Apply ID

An Indeed-assigned unique ID for Indeed Apply jobs.

Used to reference the candidate and the job.

Indeed tracking token

See Ittk.
Ittk

Indeed tracking token. An Indeed-assigned unique ID.

Used to reference the employer, candidate, job, and more.
GraphQL

An open-source data query and manipulation language for APIs and a query runtime engine. GraphQL enables clients to use declarative data fetching to specify exactly which data they need from an API.

Learn more at GraphQL | A query language for your API.

Back to top

Disposition Sync API overview

Use the Disposition Sync API to send disposition data for Indeed Apply and non-Indeed Apply jobs to Indeed.

Disposition Sync API integration is required to submit disposition data to Indeed.

Mutations

Use the following Disposition Sync API mutations to send disposition data to Indeed:

Disposition Sync API mutations table
Mutation Description Application ID
sendIndeedApplyDispositions

Sends disposition data for Indeed Apply jobs.

Indeed Apply ID
sendITTKDispositions

Sends disposition data for non-Indeed Apply jobs.

Indeed tracking token (Ittk)

sendDispositions

Sends disposition data for non-Indeed Apply jobs.

Job ID and job seeker ID

Integration phases

Integration with the Disposition Sync API occurs in two phases:

Disposition Sync API integration phases table
Phase Description
1 Review

When you use the Disposition Sync API to send disposition data to Indeed, Indeed stores the data in the sandbox database.

Indeed reviews the data to ensure that the integration works as expected and the disposition status mapping is accurate.
2 Production

When you use the Disposition Sync API to send disposition data to Indeed, Indeed stores the data in the production database.

Integration guidelines

To integrate the Disposition Sync API, follow these guidelines:

  • For all Indeed-sourced applications, Indeed requires that you send ATS disposition data to Indeed.

    Indeed requires at least one disposition data sent with the NEW status, which corresponds to when the ATS received the application.

  • To use the Disposition Sync API to submit disposition data to Indeed, map each status through which the applications transition to the Indeed standard disposition status that best represents it.

    For information about the Indeed standard definition of disposition status, or hiring stages, see the following table.

  • Use the Disposition Sync API to send all disposition statuses through which applications transition. Indeed encourages you to send the disposition data each time a change occurs in your system.

    Alternatively, you can send disposition data on a scheduled, periodic basis, but at least once a day.

  • It is acceptable to send duplicate disposition statuses for an application. However, avoid this practice when possible.

  • You can send multiple unique disposition statuses for an application in one or multiple requests to the API.

    In both cases, sort the data by the status change timestamp in ascending order before you send it.

  • When possible, combine requests by sending multiple disposition data in one API request. However, send a maximum of 500 disposition data in one request.

    If the amount of disposition data exceeds this threshold, split them into multiple requests.

How to call the API

To call the API, POST the request to the following endpoint:

POST https://apis.indeed.com/graphql
Note: Use the POST method for all queries and mutations. The API does not support the GET method.

In the POST request body, include the mutation or query, an optional operation name, and variable inputs:

{
  "query": "...",
  "operationName": "...",
  "variables": {
    "myVariable": "someValue",
    ...
  }
}

In response to your API requests, the API identifies which data was processed successfully or unsuccessfully, with corresponding reasons for any failures.

To call the API, you must provide a valid OAuth token. Otherwise, you receive the 403 Forbidden error.

Back to top

Send disposition data for Indeed Apply jobs

Request – Send disposition data for Indeed Apply jobs

sendIndeedApplyDispositions (input: [IndeedApplyDispositionInput!]!) : SendIndeedApplyDispositionsPayload

Call the API by using the sendIndeedApplyDispositions mutation:

mutation {
  sendIndeedApplyDispositions(
    input: [{
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        indeedApplyID: "12345",
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      },
      {
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        indeedApplyID: "12345",
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      }
    ]
  ) {
    numberGoodDispositions,
    failedDispositions {
      IndeedApplyID,
      Reason
    }
  }
}

In the IndeedApplyDispositionInput input object, all fields are required:

dispositionStatus DispositionStatus required

Indeed disposition status to which the combination of raw disposition status and details best maps.
rawDispositionStatus String required

Raw application disposition status from the ATS.
rawDispositionDetails String required

Additional details about the application disposition status from the ATS. Can be blank.
indeedApplyID String required

Indeed Apply ID.
atsName String required

ATS name.
statusChangeDateTime DateTime required

Date and time when the application status changed.

Response – Send disposition data for Indeed Apply jobs

The sendIndeedApplyDispositions mutation returns the SendIndeedApplyDispositionsPayload return type.

This return type includes:

  • The number of dispositions that succeeded.
  • An array of any failed dispositions. Each disposition includes its Indeed Apply ID and the reason for the failure.

Send disposition data for non-Indeed Apply jobs with Indeed tracking token

sendITTKDispositions (input: [ITTKDispositionInput!]!) : SendITTKDispositionsPayload

Request – Send disposition data for non-Indeed Apply jobs with Indeed tracking token

Call the API by using the sendITTKDispositions mutation:

mutation {
  sendITTKDispositions(
    input: [{
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        ittk: "12345",
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      },
      {
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        ittk: "12345",
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      }
    ]
  ) {
    numberGoodDispositions,
    failedDispositions {
      ittk,
      rationale
    }
  }
}

In the array of ITTKDispositionInput input objects, all fields are required:

dispositionStatus DispositionStatus required

Indeed disposition status to which the combination of raw disposition status and details best maps.
rawDispositionStatus String required

Raw application disposition status from the ATS.
rawDispositionDetails String required

Additional details about the application disposition status from the ATS. Can be blank.
ittk String required

Indeed tracking token (Ittk).
atsName String required

ATS name.
statusChangeDateTime DateTime required

Date and time when the application status changed.

Response – Send disposition data for non-Indeed Apply jobs with Indeed tracking token

The sendITTKDispositions mutation returns the SendITTKDispositionsPayload return type.

This return type includes:

  • The number of dispositions that succeeded.
  • An array of any failed dispositions. Each disposition includes its Indeed Apply ID and the reason for the failure.

Send disposition data for non-Indeed Apply jobs with job ID and job seeker ID

sendDispositions (input: [DispositionInput!]!) : SendDispositionsPayload

Request – Send disposition data for non-Indeed Apply jobs with job ID and job seeker ID

Call the API by using the sendDispositions mutation:

mutation {
  sendDispositions(
    input: [{
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        jobIdentifier: {
          indeedJobKey: "Job12345"
        },
        jobSeekerIdentifier: {
          indeedJobSeekerKey: "JobSeeker12345"
        },
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      },
      {
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        jobIdentifier: {
          indeedJobKey: "Job12345"
        },
        jobSeekerIdentifier: {
          indeedJobSeekerKey: "JobSeeker12345"
        },
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      },
      {
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        jobIdentifier: {
          indeedJobKey: "Job12345"
        },
        jobSeekerIdentifier: {
          indeedJobSeekerKey: "JobSeeker12345"
        },
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      },
      {
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        jobIdentifier: {
          indeedJobKey: "Job12345"
        },
        jobSeekerIdentifier: {
          indeedJobSeekerKey: "JobSeeker12345"
        },
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      },
      {
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        jobIdentifier: {
          indeedJobKey: "Job12345"
        },
        jobSeekerIdentifier: {
          indeedJobSeekerKey: "JobSeeker12345"
        },
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      },
      {
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        jobIdentifier: {
          indeedJobKey: "Job12345"
        },
        jobSeekerIdentifier: {
          indeedJobSeekerKey: "JobSeeker12345"
        },
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      },
      {
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        jobIdentifier: {
          indeedJobKey: "Job12345"
        },
        jobSeekerIdentifier: {
          indeedJobSeekerKey: "JobSeeker12345"
        },
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      },
      {
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        jobIdentifier: {
          indeedJobKey: "Job12345"
        },
        jobSeekerIdentifier: {
          indeedJobSeekerKey: "JobSeeker12345"
        },
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      },
      {
        dispositionStatus: HIRED,
        rawDispositionStatus: "Hired",
        rawDispositionDetails: "",
        jobIdentifier: {
          indeedJobKey: "Job12345"
        },
        jobSeekerIdentifier: {
          indeedJobSeekerKey: "JobSeeker12345"
        },
        atsName: "MyATS",
        statusChangeDateTime: "2023-04-25T13:01:01.01Z"
      }
    ]
  ) {
    numberGoodDispositions,
    failedDispositions {
      jobSeeker,
      job,
      rationale
    }
  }
}

In the array of DispositionInput input objects, all fields are required:

dispositionStatus DispositionStatus required

Indeed disposition status to which the combination of raw disposition status and details best maps.
rawDispositionStatus String required

Raw application disposition status from the ATS.
rawDispositionDetails String required

Any additional details about the application disposition status from the ATS. Can be blank.
jobIdentifier JobIdentifierInput required

Identifier for the job for this disposition signal.
jobSeekerIdentifier JobSeekerIdentifierInput required

Identifier for the job seeker for this disposition signal.
jobIdentifier JobIdentifierInput required

Identifier for the job for this disposition signal.
atsName String required

ATS name.
statusChangeDateTime DateTime required

Date and time when the application status changed.

Response – Send disposition data for non-Indeed Apply jobs with job ID and job seeker ID

The sendDispositions mutation returns the SendDispositionsPayload return type.

This return type includes:

  • The number of dispositions that succeeded.
  • An array of any failed dispositions. Each disposition includes its Indeed Apply ID and the reason for the failure.
Back to top