Using the SCIM API for user provisioning

System for Cross-domain Identity Management (SCIM) is a standard for managing user identity information. Using SCIM guarantees that their information is consistent across all systems.

Deel can act as the system of record for your organization. You can use the SCIM API to pull information about users created in Deel and create user accounts in other systems such as identity providers (IdPs) or third-party applications.

This guide explains how to create a user provisioning integration using Deel's SCIM API and shares some best practices to follow.

📘

The SCIM API is only available to Deel HR clients

Table of contents

In this article:

• What you need
• Authenticating your calls
• SCIM users scopes
• SCIM user object
• Retrieving the user list
• Syncing with your system
• Frequently-asked questions (FAQs)

What you need

To use Deel's SCIM API, you'll need:

• An active Deel account
• Users to provision to your system already exist in Deel
• A Deel user with the Organization Admin or IT Developer Admin role

Also, before starting to build the integration, we recommend becoming familiar with the SCIM API endpoints.

📘

The SCIM API doesn't return manager-type users

This guide leverages the SCIM API, which currently only supports worker-type users, manager-type users are not supported.

Authenticating your calls

There are 2 ways to authenticate your SCIM integration:

• Using OAuth2
• Using access tokens

📘

Choose organization-level permissions

Whether you use OAuth2 or access tokens, SCIM integrations require organization-level permissions. Make sure to choose the correct permissions when generating a token or creating a new OAuth2 app.

SCIM users scopes

A SCIM user provisioning integration requires the users:read scope, make sure to select it when creating the token. OAuth2 apps include all the available scopes, so there's no need to specify the scope in this case.

SCIM user object

SCIM users are built around their work_email. If their work_email is not set, they won't be showing up in the list of users returned by the SCIM API. For more information, see List users.

Here's an example of a SCIM user object:

{
  "active": true,
  "id": "ecce878f-dd78-4e09-a663-51599ce47f3e",
  "emails": [
    {
      "value": "[email protected]",
      "type": "home",
      "primary": true
    },
    {
      "value": "[email protected]",
      "type": "work",
      "primary": false
    },
    {
      "value": "[email protected]",
      "type": "other",
      "primary": false
    }
  ],
  "name": {
    "familyName": "Scott",
    "givenName": "Michael"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "",
    "costCenter": "US entity",
    "organization": "Dunder Mifflin",
    "manager": {
      "value": "",
      "displayName": " ",
      "email": ""
    }
  },
  "urn:ietf:params:scim:schemas:extension:2.0:User": {
    "preferredFirstName": "Michael",
    "preferredLastName": "Scott",
    "preferredName": "Michael Scott",
    "workerId": "310",
    "organizationalStructures": [],
    "startDate": "2024-09-09",
    "endDate": "",
    "birthday": "",
    "hiringStatus": "onboarding_overdue",
    "state": "BC",
    "country": "CA",
    "employments": [
      {
        "contractId": "nw7n2ev",
        "title": "Product manager",
        "startDate": "2024-09-09",
        "contractType": "direct_employee",
        "state": "PA",
        "country": "USA",
        "active": false,
        "team": {
          "name": "USA - group"
        }
      }
    ],
    "customFields": [],
    "isManager": false,
    "departmentHierarchy": null,
    "departmentExternalId": null,
    "departmentExternalIdHierarchy": null
  },
  "userName": "[email protected]",
  "title": "Product manager",
  "userType": "direct_employee",
  "addresses": [
    {
      "streetAddress": "Parkour Road 1",
      "locality": "Scranton",
      "region": "PA",
      "postalCode": "12345",
      "country": "USA",
      "type": "other"
    }
  ],
  "meta": {
    "created": "2024-10-15T09:23:55.881Z",
    "lastModified": "2024-10-15T10:36:57.100Z",
    "resourceType": "User",
    "location": "https://api.letsdeel.com/scim/v2/Users/ecce878f-dd78-4e09-a663-51599ce47f3e"
  }
}

Retrieving the user list

To retrieve the users that you want to provision through the integration, you must use the List users endpoint.

By default, the endpoint returns 50 users for each request, but you can change the limit up to 99 by using the count query parameter. When creating the integration, make sure that all the users are retrieved before syncing them with your system.

For example, if you want to retrieve the first 99 users, you can use the following query:

curl --request GET \
GET curl --location 'https://api.letsdeel.com/scim/v2/Users?startIndex=1&count=99' \
--header 'Authorization: Bearer {token}' \

📘

The SCIM API is base 1

Counting for the filters starts at 1 instead of 0.

Syncing with your system

After retrieving the user list, build your application so that it syncs users with your system periodically.

The sync frequency depends on how often your workers are onboarded or offboarded:

• If it happens happens once a day, set the sync to happen every 24 hours
• If it happens multiple multiple times a day, you could sync the worker, we recommend syncing no more than every 3 hours to avoid hitting rate limits

Frequently-asked questions (FAQs)

Does the Deel SCIM API support user groups?

Our SCIM API doesn't currently support user groups.