Specify HTTP request headers and parameters and review response fields in the client credentials flow (2-legged OAuth) and the authorization code flow (3-legged OAuth).

📘

Note:

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

HTTP request headers

The request headers are:

Header Value and description
Content-Type

application/x-www-form-urlencoded

Accept

application/json

Authorization

Bearer <access_token>

In each API call, pass the access token in this header with the Bearer authentication scheme.

📘 Note:

  • You can pass the Authorization header only when you request or refresh an access token through the oauth/v2/tokens endpoint.

  • When you get an access token, you can use the basic authentication scheme instead of passing your client ID and secret in the oauth/v2/tokens request body.

See also access token and basic authentication scheme.

Basic authentication scheme

When you get an access token, you can use the basic authentication scheme instead of passing your client ID and secret in the /oauth/v2/tokens request body. To use this scheme, you encode and pass these credentials in an Authorization Basic header.

See also Basic Authentication Scheme.

To generate the Authorization Basic header value:

  1. Concatenate the client_id and client_secret with a colon (:) as a separator.

    base64.encode("<client_id>:<client_secret>");
    
  2. Apply the Base64-encoding algorithm to the string:

    base64.encode("5e175cbb7f88e2048bd95323bbc9ca2fcec32ad60f95f7ee66ab53e099abe6f3:pJ4qRe2sdXRP0Whr3bwz9D37exFuuOtqJDRHMmmlLWV7J25rH7oItrPNCKzhaQf2");
    
  3. Pass the Base64-encoded string as a basic HTTP Authorization header:

    Authorization: Basic NWUxNzVjYmI3Zjg4ZTIwNDhiZDk1MzIzYmJjOWNhMmZjZWMzMmFkNjBmOTVmN2VlNjZhYjUzZTA5OWFiZTZmMzpwSjRxUmUyc2RYUlAwV2hyM2J3ejlEMzdleEZ1dU90cUpEUkhNbW1sTFdWN0oyNXJIN29JdHJQTkNLemhhUWYy
    

Scopes

📘

Note:

Some Indeed APIs have additional scopes that you must pass when you request the access token. For API-specific scopes, see the API documentation for each API.

Name Consent string Description
email View your email address.

For 3-legged authorization only.

When calling the v2/api/userinfo endpoint, returns the email and email_verified fields in the ID token. With this scope, an app can read a user's email and email_verified status from an ID token or the userinfo endpoint.

See v2/api/userinfo.

employer_access List employers associated with a user account and get an access token for an employer.

Lists all employer accounts associated with the user and is required to get an access token for an employer.

To list employers and get an access token for an employer:

offline_access Maintain the permissions that you have granted.

For 3-legged authorization only.

Required to generate a refresh token. Indeed OAuth access tokens expire after one hour. To get an access token, use a refresh token.

Request body parameters

You can include request body parameters for these endpoints:

The v2/api/userinfo endpoint has no request body parameters.

Request body parameters for oauth/v2/authorize

Name Description
client_id

Required. Client ID.

Examples:

6nwwcdklwgktryjw2j5f

xh5t2fyneule7zg7mvw3pf9

jbx3wmewzlxkdz1jxvs6b

redirect_uri

Required. URL-encoded redirect URL. Identifies the redirect page on your site where the user captures the authorization code. It must match one of the redirect URLs that your app registers.

Example:

Encode https://www.acerecruitersllc.com/oauth/indeed

To https%3A%2F%2Fwww.acerecruitersllc.com%2Foauth%2Findeed%3Fmy-param%3Dpass-me-this-value

See Step 1. Register your app.

scope

Optional. Permissions that the client app requests. You must URL-encode and space-delimit scopes, which replaces the spaces with plus signs (+).

Example: email+offline_access

See Scopes.

response_type

Required. Value is always code.

Example: code

state

Recommended. Prevents CSRF attacks. Can be any unique string your app creates to maintain state between the request and callback. Indeed passes this parameter to your redirect URI.

Example: employer1234

See also Threat: CSRF Attack against redirect-uri.

prompt

Optional. Prompts the authorizing user with an Indeed employer selection screen, from which the user chooses the employer account assigned to your access token. To do this, add the prompt=select_employer parameter to the authorization link, and include the employer_access scope.

Example: prompt=select_employer

See Show the Indeed employer selection screen.

employer

Optional. An employer ID to associate with an access token.

You can also use this parameter when you exchange a refresh token for an access token.

Example: employer=6d2f02224e30d401810b1726eb246d8d

Request body parameters for oauth/v2/tokens

Name Description
code

Optional. An authorization code to exchange for an access token.

To exchange a refresh token for an access token, specify refresh_token instead.

Example: rXZSMNyYQHQ

See authorization code.

refresh_token

Optional. A refresh token to exchange for an access token.

The refresh token returned with your user's access token.

To exchange an authorization code for an access token, specify code instead.

Example: rXZSMNyYQHQ

grant_type

Required.

To get an authorization code, this value must be authorization_code.

To submit a refresh token to get an access token, this value must be refresh_token.

Examples:

authorization_code

Or

refresh_token

client_id

Conditional. Your client ID.

Instead of sending your client_id in the request, you can pass it in an Authorization header.

Example:

6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b

See Authorization header.

client_secret

Conditional. Your client secret.

Instead of sending your client_secret in the request, you can pass it in an Authorization header.

Example:

02KKpg6yLXw2v3FKf5lqyFGtMQCvPBNbJIw89SoSd9fts1LAdlvwUQQ6dwhAhEXv

See Authorization header.

scope

Conditional. To list employer accounts associated with the user that registered the app or to get an access token for one of these associated employer accounts, pass employer_access.

Example: employer_access

redirect_uri

Required. Your URL-encoded redirect URL. Must match the redirect URL you specify when you get an authorization code.

Example:

Encode https://www.acerecruitersllc.com/oauth/indeed

To https%3A%2F%2Fwww.acerecruitersllc.com%2Foauth%2Findeed%3Fmy-param%3Dpass-me-this-value

See Step 2. Get an authorization code.

Request body parameters for v2/api/userinfo

This endpoint has no request body parameters.

Response fields

Calls to these endpoints return these response fields:

Response fields for oauth/v2/authorize

Name Type Description
code

String

Authorization code. Valid for 10 minutes.

Example: rXZSMNyYQHQ

state

String

Optional. Appears only if you pass it in the request.

Example: employer1234

Response fields for oauth/v2/tokens

Name Type Description
access_token

String

Your access token.

Example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6Ikpv[...]

id_token

String

Your ID token.

Example:

"eyJraWQiOiJlMzEzZTc4My1lM2YwLTQ3ZWMtY[...]

See ID Token.

expires_in

Integer

Token is valid for one hour (3600 seconds).

Example: 3600

token_type

String

Value is always Bearer.

Example: Bearer

refresh_token

String

You get a refresh token only when you request the offline_access scope. Store this securely. It expires 60 days after your most recent refresh request.

Example: rXZSMNyYQHQ

scope

String

The actual permissions granted to your app. For example, email and offline_access scopes. Scopes are space-delimited.

Example: email offline_access

See Scopes.

consented_scope

String

A space-delimited string of all scopes that the user has granted to your app. Can include scopes that are not in this current access token – scopes in that token are represented by the scope field. This field is only included if the user grants the offline_access scope.

Example: email offline_access

Response fields for v2/api/userinfo

Name Type Description
sub

string

Unique identifier for the user's account.

Example: 248289761001

email

string

User's email address.

Example: [email protected]

email_verified

boolean

Indicates whether the user has verified their email address.

Example: true

employers

object

List of employer accounts, including IDs and names, associated with the user account. This field requires that the user grant the employer_access scope.