SCIM API

SCIM API

Overview

The Deel SCIM API provides user provisioning capabilities based on the System for Cross-domain Identity Management (SCIM) 2.0 standard. The API enables identity providers and partner applications to manage user lifecycle operations including creation, updates, and de-provisioning.

SCIM 2.0 is an open standard for automating user provisioning between identity providers and service providers. The Deel implementation follows RFC 7643 and RFC 7644 specifications.

The SCIM API is available exclusively to Deel clients and partners with appropriate authorization.

Supported operations

The SCIM API currently supports the User resource with the following operations:

User management

  • List users: Retrieve all users within an organization with pagination and filtering support
  • Retrieve user: Fetch a specific user by their unique identifier
  • Create user: Provision new client users in Deel HRIS
  • Update user: Modify user profile information using full replacement (PUT) or partial updates (PATCH)
  • Delete user: De-provision users and remove them from the system
  • Search users: Query users using SCIM filter expressions

Configuration discovery

  • Service provider config: Retrieve SCIM implementation capabilities and supported features

Key features

  • SCIM 2.0 compliant: Implements the industry-standard protocol for cross-domain identity management.
  • Flexible filtering: Query users by email and other attributes using SCIM filter syntax.
  • Pagination support: Handle large datasets with configurable page sizes and index-based navigation.
  • Partial updates: Use PATCH operations to modify specific user attributes without full replacement.

User resource schema

The SCIM User resource includes the following attribute groups:

Core attributes

  • userName: User’s work email (required)
  • name: Given name and family name (required)
  • emails: Work email addresses with type and primary indicators
  • active: Employment status indicator
  • title: Job title
  • userType: User classification (employee, contractor, client)
  • addresses: Physical addresses with country and region codes

Enterprise extension

The urn:ietf:params:scim:schemas:extension:enterprise:2.0:User extension provides:

  • department: Department name in Deel HRIS
  • manager: Manager information including ID and display name
  • costCenter: Legal entity identifier
  • organization: Organization name

Deel extension

The urn:ietf:params:scim:schemas:extension:2.0:User extension adds:

  • startDate: Employment start date
  • endDate: Employment end date
  • hiringStatus: Current hiring status
  • employments: Array of employment contracts with details
  • customFields: Organization-defined custom attributes
  • organizationalStructures: Team and department hierarchy
  • isManager: Manager role indicator

Filtering and pagination

Filter syntax

The SCIM API supports filtering using SCIM filter expressions. Currently supports the eq (equals) operator for email filtering:

$GET /scim/v2/Users?filter=email eq "user@example.com"

Pagination

Control result pagination using startIndex and count parameters:

  • startIndex: 1-based index of the first result (minimum 1, defaults to 1)
  • count: Maximum number of results per page (1-100, defaults to 50)
$GET /scim/v2/Users?startIndex=1&count=50

The response includes:

  • totalResults: Total number of matching users
  • itemsPerPage: Number of results in current page
  • startIndex: Index of the first result in the page

Example operations

Listing users

Retrieve a paginated list of users in your organization:

$curl -X GET 'https://api.letsdeel.com/scim/v2/Users?startIndex=1&count=50' \
>  -H 'Authorization: Bearer YOUR-TOKEN-HERE' \
>  -H 'Content-Type: application/scim+json'

Retrieving a user

Fetch a specific user by their unique identifier:

$curl -X GET 'https://api.letsdeel.com/scim/v2/Users/{hrisProfileOid}' \
>  -H 'Authorization: Bearer YOUR-TOKEN-HERE' \
>  -H 'Content-Type: application/scim+json'

Creating a user

Provision a new client user in Deel HRIS:

$curl -X POST 'https://api.letsdeel.com/scim/v2/Users' \
>  -H 'Authorization: Bearer YOUR-TOKEN-HERE' \
>  -H 'Content-Type: application/scim+json' \
>  -d '{
>    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
>    "userName": "jane.doe@example.com",
>    "name": {
>      "givenName": "Jane",
>      "familyName": "Doe"
>    },
>    "userType": "client"
>  }'

Partially updating a user

Use PATCH operations to modify specific user attributes:

$curl -X PATCH 'https://api.letsdeel.com/scim/v2/Users/{hrisProfileOid}' \
>  -H 'Authorization: Bearer YOUR-TOKEN-HERE' \
>  -H 'Content-Type: application/json' \
>  -d '{
>    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
>    "Operations": [
>      {
>        "op": "replace",
>        "path": "title",
>        "value": "Senior Software Engineer"
>      }
>    ]
>  }'

API endpoints

The SCIM API is available at:

  • Production: https://api.letsdeel.com/scim/v2
  • Staging: https://api-staging.letsdeel.com/scim/v2

All endpoints are documented in the API Reference.

Content types

The SCIM API supports two content types:

  • application/json - Standard JSON format
  • application/scim+json - SCIM-specific JSON format

Both content types are functionally equivalent. Use the format that best fits your integration requirements.

Error handling

The API returns SCIM-compliant error responses with the following structure:

1{
2  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
3  "status": "400",
4  "scimType": "invalidValue",
5  "detail": "The request body contains invalid user attributes"
6}

Use cases

Deel to identity provider sync

Automatically sync user accounts from Deel HRIS to identity providers such as Okta, Azure AD, or OneLogin:

  • Provision new users in the identity provider when they are hired in Deel
  • Update user information in the identity provider when it changes in Deel
  • De-provision users in the identity provider when their employment ends in Deel

Deel to other systems sync

Automatically synchronize user data from Deel HRIS to external systems, such as downstream HR or IT platforms:

  • Create user records in external systems when new hires are added in Deel
  • Update external user attributes when user details change in Deel
  • Remove or deactivate users in external systems when employment ends in Deel

Best practices

  • Enforce uniqueness: Each user must have a unique email address across the organization
  • Validate before creation: Check for existing users with the same email to avoid 409 conflicts
  • Use work emails: Provision users with organizational email addresses rather than personal emails
  • Handle email changes: Update userName when a user’s email changes
  • Parse SCIM error responses: Extract status, scimType, and detail fields for meaningful error messages
  • Retry transient failures: Implement retry logic for 429 and 500 errors with exponential backoff
  • Handle conflicts: When receiving 409 errors, retrieve the existing user instead of failing
  • Log all errors: Track API errors for debugging and monitoring integration health
  • Use appropriate page sizes: Request 50-100 users per page for optimal performance
  • Track pagination state: Store startIndex and totalResults to navigate large datasets
  • Avoid fetching all users: Use filtering to retrieve only relevant users when possible
  • Handle pagination in loops: Continue fetching pages until all results are retrieved
  • Filter by email: Use filter=email eq "user@example.com" to find specific users efficiently
  • Reduce payload size: Filtering minimizes data transfer and improves response times
  • Validate filter syntax: Ensure filter expressions follow SCIM specification
  • Combine with pagination: Use filtering with pagination for large result sets
  • Prefer partial updates: Use PATCH instead of PUT to modify only changed attributes
  • Reduce bandwidth: PATCH operations send only the fields being updated
  • Avoid overwriting data: PUT replaces the entire resource, potentially losing unchanged data
  • Support multiple operations: PATCH can apply multiple changes in a single request
  • Store tokens securely: Use environment variables or secure key storage
  • Grant minimal scopes: Only request Users:read and Users:write scopes as needed
  • Rotate tokens regularly: Generate new tokens periodically to minimize security risks
  • Use OAuth2 for partners: Implement OAuth2 for third-party integrations requiring user consent

Next steps

HRIS people

Learn about the Deel HRIS People API for workforce data management

Authentication

Set up API tokens and OAuth2 for secure SCIM API access

Webhooks

Set up webhooks to receive notifications of user changes

API Reference

View complete SCIM API endpoint documentation and schemas