Disposition Sync API Reference

Get reference information for the Disposition Sync API, which you use to send disposition data to Indeed.

Disposition Sync API Guide

See also the Disposition Sync API Guide.


Back to top

Indeed standard disposition statuses

This table describes the Indeed standard disposition statuses, or hiring stages:

Indeed standard disposition statuses table
Indeed disposition status Description Example raw status from ATS
1 NEW The application arrived at the ATS.
  • applied
  • received
  • accepted
  • new
2 REVIEW The application is under review or has been reviewed.
  • screen
  • reviewing
  • resume downloaded
  • Application viewed
3 LIKED The application was liked by the recruiter
  • liked
  • favored
4 CONTACTED The candidate was contacted through phone or email. This status does not include rejections.
  • Emailed
  • messaged
  • initial contact
5 ASSESSMENT Candidate was asked to complete additional assessment, not included in the original job application.
  • Take home exercise
  • initial assessment
  • online test
6 INTERVIEW The candidate is in the interview process
  • phone screened
  • interview completed
  • interview set up
7 OFFER An offer of employment has been sent to a candidate.
  • offer made
  • offered
  • offer extended
8 BACKGROUND_CHECK A background check has been ordered for the candidate
  • Background check
  • pre-hire background check
9 HIRED The candidate accepted an offer of employment.
  • ready to hire
  • offer accepted
10 REJECTED A candidate has been explicitly rejected or all remaining candidates rejected after the role closed
  • rejection
  • not selected
  • does not qualify
11 DECLINED The candidate declined an offer of employment
  • Decline by candidate
  • offer not accepted
12 WITHDRAWN The candidate withdrew the application.
  • candidate withdrawn
  • candidate did not show up for interview
13 INCOMPLETE The candidate did not complete the application
  • Incomplete
  • application not completed

Mutations

sendIndeedApplyDispositions

dispositions: Array of IndeedApplyDispositionInput objects
Return type: SendIndeedApplyDispositionsPayload

Sends disposition data for Indeed Apply jobs.

sendITTKDispositions

Input object: Array of ITTKDispositionInput input objects
Return type: SendITTKDispositionsPayload

Sends disposition data for non-Indeed Apply jobs with Indeed tracking token (Ittk).

sendDispositions

Input object: Array of DispositionInput input objects
Return type: SendDispositionsPayload

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

Input objects

IndeedApplyDispositionInput

Input object that contains disposition signal for a single application to a job using an Indeed Apply ID.

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.

Back to top

ITTKDispositionInput

Input object that contains the disposition signal for a single application to a job using an Indeed tracking token (Ittk).

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.

Back to top

JobIdentifierInput

Input object that identifies the job for which disposition data is being transferred.

At least one field is required. Otherwise, this disposition is rejected.

The Indeed job key is preferred and is used instead of the ATS job ID.

indeedJobId String optional

Indeed job ID.

indeedJobKey String optional

Indeed job key.

atsJobId String optional

Identifier that the ATS uses for the job.

jobUrl String optional

External URL that links to the job.

Back to top

JobSeekerIdentifierInput

Input object that identifies the job seeker for which disposition data is being transferred.

At least one field is required. Otherwise, this disposition is rejected.

Indeed job seeker key is preferred.

indeedJobSeekerId String optional

Indeed job seeker ID./p>

indeedJobSeekerKey String optional

Indeed job seeker key.

emailAddress String optional

Email address of the job seeker.

phoneNumber String optional

Phone number of the job seeker.

Back to top

DispositionInput

Input object that contains disposition signal for a single application to a job.

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.

Back to top

Return types

SendIndeedApplyDispositionsPayload

Return type for sending a batch of Indeed Apply dispositions to Indeed.

numberGoodDispositions Int required

Number of good dispositions.

failedDispositions Array of IndeedApplyFailedDisposition return types required

Failed dispositions.

Back to top

SendITTKDispositionsPayload

Return type for sending a batch of Indeed tracking token (Ittk) dispositions to Indeed.

numberGoodDispositions Int required

Number of good dispositions.

failedDispositions Array of ITTKFailedDisposition return types required

Failed dispositions.

Back to top

SendDispositionsPayload

Return type for sending a batch of dispositions to Indeed.

numberGoodDispositions Int required

Number of good dispositions.

failedDispositions Array of FailedDisposition return types

Failed dispositions.

Back to top

IndeedApplyFailedDisposition

Return type that contains the reason why the Indeed Apply disposition failed.

IndeedApplyID String required

Indeed Apply ID for the disposition that failed.

rationale String required

Reason for this failure.

Back to top

ITTKFailedDisposition

Return type that contains the reason why the Indeed tracking token (Ittk) disposition failed.

ittk String required

Indeed tracking token (Ittk) disposition that failed.

rationale String required

Reason for this failure.

Back to top

FailedDisposition

Return type that contains the reason why the disposition failed.

jobSeeker String required

Job seeker with the failure.

job String required

Job with the failure.

rationale String required

Reason for this failure.

Back to top

Enumerations

DispositionStatus

enum DispositionStatus {
  INCOMPLETE
  NEW
  REVIEW
  LIKED
  CONTACTED
  ASSESSMENT
  INTERVIEW
  OFFER
  BACKGROUND_CHECK
  REJECTED
  HIRED
  DECLINED
  WITHDRAWN
}

Back to top

Common errors

The following table describes the common error types:

Error Description and common causes
BAD_USER_INPUT

The value of an input parameter is invalid or the server cannot process your request based on the provided input. For details, see the error message.

INTERNAL_SERVER_ERROR

The server encountered an unexpected failure, error, or exception and did not provide a response, which happens for various reasons. Indeed closely monitors this error. Try your request again.

UNAUTHENTICATED The request was not attempted because it did not include sufficient authentication credentials. For details on authentication credentials, see Authorization.
FORBIDDEN

Valid authentication credentials are present but insufficient to perform the associated query or mutation. For details, see the error message.

Troubleshooting authorization errors

Authorization endpoints, such as https://apis.indeed.com/oauth/v2/tokens, return errors in the format required by the OAuth 2.0 specification.

For example:

{
  "error_description": "Invalid grant",
  "error": "invalid_grant"
}
Error Description and common causes
invalid_grant

There was a problem with your client credentials (client ID and client secret), authorization code or refresh token.

This error is often caused by an incorrect client ID or client secret. Please check that:

  • You didn't happen to leave out or include extra characters at the beginning or the end of either credential when copying them from the Manage app credentials page.
  • If you recently rotated your client credentials (created a new client secret and deleted the old secret associated with the client ID), verify that you have updated all your credential stores with the new client secret.

If you are using Client Credentials Flow (2-legged OAuth), another common cause is that client credentials grant type isn't enabled. Please verify that Allowed grant types include Client credentials on the Manage app credentials page.

If you are using Authorization Code Flow (3-legged OAuth), common causes include:

  • Authorization code grant type wasn't enabled. Please verify that Allowed grant types include Authorization code on the Manage app credentials page.
  • The redirect_uri parameter passed to https://apis.indeed.com/oauth/v2/tokens didn't match the redirect_uri passed to https://secure.indeed.com/oauth/v2/authorize.
  • The authorization code has expired or has already been used. Each authorization code can only be used once. To renew access tokens without reauthorization, you must request the offline_access scope and store the refresh token you receive along with the first access token.
  • The refresh token is no longer valid. You must ask the user to complete the authorization flow again to receive another refresh token. The refresh token could have become invalid because:
    • The user revoked the authorization they previously gave to your app.
    • Your app has repeatedly requested authorization from the same user and the oldest refresh tokens for this user have been invalidated. Requesting authorization more than once is perfectly fine, but be sure to update the refresh token stored by your app after each successful authorization.
    • The refresh token has expired because it hasn't been used recently. Refresh tokens expire 60 days after the last usage, or 60 days after issue if never used.
  • The authorization code or refresh token is valid but was issued to a different app. Be sure to use the same client ID (and a corresponding client secret) in all stages of the authorization process.

The error_description field will only contain a generic "Invalid grant" message. To resolve this error, carefully check all the potential causes listed above that apply to your situation.

invalid_request

There was a problem with request parameters:

  • A required parameter was missing, or a parameter had an invalid value.
  • The request to https://apis.indeed.com/oauth/v2/tokens included query string parameters in the request URL. Be sure to send all parameters in the HTTP request body using the application/x-www-form-urlencoded format.
  • The app's account (2-legged OAuth) or the user (3-legged OAuth) doesn't have the permission to access the employer specified with the employer parameter.
  • The value of the employer parameter wasn't a valid employer ID. The employer IDs accepted by the employer parameter are different from the values accepted by the legacy advertiserId parameter. You can get the list of valid values by calling the AppInfo (2-legged OAuth) or UserInfo (3-legged OAuth) authorization endpoint, or if you have a master account, calling the GET /v1/subaccounts endpoint of the Sponsored Jobs API.

The message in the error_description field may help to identify the missing or invalid parameter or other problem.

unsupported_grant_type The requested grant_type was neither client_credentials (2-legged OAuth) nor authorization_code or refresh_token (3-legged OAuth). Be sure to use one of the supported grant types.

Troubleshooting disposition errors

Error Description and common causes
Unable to find IndeedApplyId

The server received your request, but could not find the provided IndeedApplyId.

This error can occur if the IndeedApplyId value in the request is invalid. You can also see this error if you have not been authorized to send disposition data.

Verify that you have completed the onboarding steps and that you are sending the correct IndeedApplyId.

Unable to create disposition

The server received your request, but encountered an unexpected failure, error, or exception.

This error can occur for various reasons. Indeed closely monitors this error.

Try your request again later.

Unable to update disposition

The server received your request, but encountered an unexpected failure, error, or exception.

This error can occur for various reasons. Indeed closely monitors this error.

Try your request again later.


Back to top