SCIM API guide

Third-party systems can call the System for Cross-domain Identity Management (SCIM) API to synchronize user directories.

 

legal notice

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

SCIM API overview

The System for Cross-domain Identity Management (SCIM) API uses the SCIM protocol to let third-party systems call Indeed on the user's behalf and synchronize user directories for Indeed PLUS integrations. These users typically belong to resource groups that isolate them from Indeed.com users. Resource groups give the third-party system direct ownership of these users — including create, delete, and permission assignment — without requiring the user to create an Indeed account.

End users never have an Indeed account. They cannot sign in to Indeed directly; they sign in only through the third-party system, and only to access APIs in that system's context.

This table lists the third-party callers and how they use the SCIM API:

SCIM API use cases

Third-party caller	Calls the SCIM API to
Applicant tracking systems (ATSs)	Provision their employer users into Indeed resource groups so the users can access tools like Scout.
Recruit-owned job boards	Link their users to Indeed to access Indeed's moderation capabilities.
Partners, like Glassdoor	Manage user linking for a consistent experience across Glassdoor and Indeed.

For supported and optional schemas, see SCIM API schemas.

To start this integration or ask questions, contact fim-team@indeed.com.

SCIM API OAuth

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.

Complete these steps:

SCIM API OAuth

#	Step
1.	Become an Indeed partner.
2.	Get your OAuth credentials.
3.	Get an access token.

Become an Indeed partner

If you are not already a partner, become an Indeed partner.

Get your OAuth credentials

1. Sign in to Partner Console with your Indeed user account.

2. Select your app in the Apps list on the Dashboard.

   The Credentials tab on the app details page lists your OAuth credentials: a client ID and secret.

Get an access token

To get an access token, send a POST request to https://apis.indeed.com/oauth/v2/tokens with these headers and body parameters, using a command-line tool like curl or a UI tool like Insomnia.

Don't expose the client secret to end users. Indeed recommends generating tokens in the backend.

curl -L 'https://apis.indeed.com/oauth/v2/tokens' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=<client_id>' \
  -d 'client_secret=<client_secret>' \
  -d 'grant_type=client_credentials' \
  -d 'scope=employer_access'

The request headers are:

Get an access token request headers

Header	Value
Accept	application/json
Content-Type	application/x-www-form-urlencoded

The request body parameters are:

Get an access token request body parameters

Request body parameter	Value	Description
client_id	<client_id>	Replace with your client ID.
client_secret	<client_secret>	Replace with your client secret.
grant_type	client_credentials	Requests the client credentials grant (2-legged OAuth).
scope	employer_access	Lists employer accounts associated with the user that registered the app, or gets an access token for an associated employer account.

{
  "access_token": "<access_token>",
  "scope": "employer_access",
  "token_type": "Bearer",
  "expires_in": 3600
}

Your token expires in one hour (3600 seconds). Refresh your token hourly.

The SCIM service validates the access token and confirms it has not expired by checking its signature, issuer, audience, and expiration time.

If the token is valid, the SCIM service processes the request and returns the appropriate response. If the token is invalid or expired, the service returns the HTTP 401 Unauthorized status code.

SCIM API operations

After you complete OAuth, you can call these operations:

SCIM API operations

Operation	Description
Get user details by criteria	Get details for the Indeed account associated with the requesting tenant.
Get user details by ID	Get details for an Indeed user account by unique ID. Use this operation to access or verify a user's profile information, roles, or group memberships.
Create user	Create an Indeed user account.
Update user by ID	Update an Indeed account, overwriting all mutable values.
Delete user by ID	Hard-delete an Indeed user account and erase the user's identity data from Indeed.

Get user details by criteria

GET https://api.indeed.com/scim/v2/Users

Get details for the Indeed account associated with the requesting tenant.

Use this operation to synchronize user data between an Identity Provider (IdP) and a Service Provider (SP).

For example, during a full synchronization, the IdP queries the SP to identify which users to add, delete, or update so the SP matches the IdP after all operations complete.

This operation returns at most one user. If multiple users match the criteria, the operation returns an error.

For reference information and example requests and responses, see Get user details by criteria.

Get user details by ID

GET https://api.indeed.com/scim/v2/Users/:id

Get details for an Indeed user account by its unique user ID.

Use this operation to access or verify a user's details, such as profile information, roles, or group memberships.

For example, when a user changes in the IdP, the IdP queries the SP for the current state of the SP user, then sends POST or PUT commands to align the SP with the IdP.

For reference information and example requests and responses, see Get user details by ID.

Create user

POST https://api.indeed.com/scim/v2/Users 

Create an Indeed account. When an employee joins an organization, the IdP calls this operation to add the user's information to the SP so the user has access to the necessary resources and services from day one.

The required and optional fields are:

Fields for the create user operation

Field	Required	Optional
One primary email	✓
externalId	✓
familyName	✓
givenName	✓
locale		✓
phoneNumbers		✓
preferredLanguage		✓
timezone		✓
title		✓
username	✓
userType	✓
EmployerOrganizations		✓

For reference information and example requests and responses, see Create user.

Update user by ID

PUT /Users/{id}

Update an Indeed account. This operation overwrites every value on the account, even when an attribute is empty or omitted.

The required and optional fields are:

Fields for the update user by ID operation

Field	Required	Optional
One primary email	✓
externalId	✓
familyName	✓
givenName	✓
locale		✓
phoneNumbers		✓
preferredLanguage		✓
timezone		✓
title		✓
username	✓
userType	✓
EmployerOrganizations		✓

For reference information and example requests and responses, see Update user by ID.

Delete user by ID

DELETE https://api.indeed.com/scim/v2/Users/:id

Hard-delete an Indeed user account and erase the user's identity data from Indeed.

When an employee leaves the organization, the IdP calls this operation to remove the user from the system. The operation erases the user's identity data within Indeed and prevents reactivation, removing the user's access to the organization's resources and services.

This operation does not sanitize all Personally Identifiable Information (PII) for the user across all Indeed platforms. Before or after you call the DELETE operation, process any GDPR-related data sanitization requests through the appropriate channels. Both requests are handled correctly regardless of the order.

For reference information and example requests and responses, see Delete user by ID.

RFCs

• RFC 3966: The tel URI for Telephone Numbers
• RFC 7642: System for Cross-domain Identity Management: Definitions, Overview, Concepts, and Requirements
• RFC 7643: System for Cross-domain Identity Management: Core Schema
• RFC 7644: System for Cross-domain Identity Management: Protocol

See also

• HTTP request headers
• oauth/v2/tokens endpoint
• Error response
• Troubleshoot OAuth errors

 

Was this page helpful?