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 enable third-party systems to make API calls into Indeed on the user's behalf to synchronize user directories for Indeed PLUS integrations. Typically, these users are in resource groups that isolate them from Indeed.com users. These resource groups enable the third-party system to have direct ownership over these users, including create, delete, and assign permissions, without the user having to create an account on Indeed themselves.

From the end users' point of view, they never have an account on Indeed, because the third-party user cannot sign in to Indeed directly but can only sign in indirectly through the third-party system, and only to access APIs within the context of the third-party user.

This table lists the third-party callers and their use cases for 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 that they can access tools like Scout.
Recruit-owned job boards	Link their users to Indeed to access Indeed’s moderation capabilities.
Partners, like Glassdoor	Manage their user linking for a consistent experience across Glassdoor and Indeed.

To get information about SCIM API supported and optional schemas, see SCIM API schemas.

To get started with this integration or if you have 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. On the Dashboard, select your app in the Apps list.

   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 ensures it has not expired. The SCIM service checks the token's 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 not valid 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 the unique ID. Call this operation to access or verify the user's details, such as 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 for the account.
Delete user by ID	Hard-delete an Indeed user account, erasing 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.

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

For example, during a full synchronization, the IdP might query the SP to determine which users to add, delete, or update to ensure the SP matches the IdP after all operations complete.

This operation returns a maximum of one user. If multiple users match the criteria, 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 the unique user ID.

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

For example, when a user changes in the IdP, the IdP can query the SP to determine the current state of the SP user, then send 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 can call this operation to add the user's information to the SP, ensuring they have access to 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, overwriting all values for the user account, even if an attribute is empty or not provided.

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, erasing the user's identity data from Indeed.

The IdP can call this operation to remove a user from the system when an employee leaves the organization. This operation erases the user's identity data within Indeed and prevents reactivation, ensuring that they no longer have access to the organization's resources and services.

note

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?