> This page is for API, version 2026-01-01 (Stable) (default).
> For other versions, use one of these documentation indexes:
> - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# SCIM API

> Provision, manage, and de-provision users programmatically using the SCIM 2.0 standard

## 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](https://www.rfc-editor.org/rfc/rfc7643) and [RFC 7644](https://www.rfc-editor.org/rfc/rfc7644) specifications.

> **Note**
>
> 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:

```bash
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)

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`
* **Staging**: `https://api-staging.letsdeel.com/scim`

All endpoints are documented in the [API Reference](/api/hris-endpoints/users).

## 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:

```json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "400",
  "scimType": "invalidValue",
  "detail": "The request body contains invalid user attributes"
}
```

## 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

#### Use unique email addresses

* **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

#### Implement proper error handling

* **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

#### Optimize pagination

* **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

#### Leverage filtering

* **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

#### Use PATCH for updates

* **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

#### Secure token management

* **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](/api/hris/introduction)

Learn about the Deel HRIS People API for workforce data management

#### [Authentication](/api/authentication)

Set up API tokens and OAuth2 for secure SCIM API access

#### [Webhooks](/api/webhooks/introduction)

Set up webhooks to receive notifications of user changes

#### [API Reference](/api/reference)

View complete SCIM API endpoint documentation and schemas