SCIM API reference

The SCIM API provides endpoints to manage organization users. All endpoints are compliant with SCIM 2.0 standards and are for organization-managed users only.

Base URL: https://iam.twilio.com/scim/v2

(information)

Info

Verify users' email domains in your organization before managing them through the SCIM API.

Create a user

Create a user using the SCIM core user schema.

POST /scim/v2/Users

Requirements

This endpoint has the following requirements:

The userName must match the primary email address (emails[primary=true].value).
The user's email domain must be verified by the organization.
Required fields: userName, emails.

After successful creation, the user receives a welcome email to reset their password. If SSO is enforced, the user can sign in with their password and is then asked to verify their email.

Request body

1{
2    "externalId": "36d02f84-1c1a-4409",
3    "userName": "alex.a@example.com",
4    "displayName": "Alex A.",
5    "name": {
6        "givenName": "Alex",
7        "familyName": "A."
8    },
9    "emails": [
10        {
11            "primary": true,
12            "value": "alex.a@example.com",
13            "type": "work"
14        }
15    ],
16    "active": true,
17    "locale": "fr-FR",
18    "timezone": "UTC",
19    "schemas": [
20        "urn:ietf:params:scim:schemas:core:2.0:User"
21    ]
22}

Response

1{
2    "id": "US00000000000000000000000000000123",
3    "externalId": "36d02f84-1c1a-4409",
4    "userName": "alex.a@example.com",
5    "displayName": "Alex A.",
6    "name": {
7        "givenName": "Alex",
8        "familyName": "A."
9    },
10    "emails": [
11        {
12            "primary": true,
13            "value": "alex.a@example.com",
14            "type": "work"
15        }
16    ],
17    "active": true,
18    "locale": "fr-FR",
19    "timezone": "UTC",
20    "schemas": [
21        "urn:ietf:params:scim:schemas:core:2.0:User"
22    ],
23    "meta": {
24        "resourceType": "user",
25        "created": "2023-11-30T14:18:57.031225338Z",
26        "lastModified": "2023-11-30T14:18:57.031225338Z",
27        "version": "W/1"
28    }
29}

Error responses

409 Conflict - External ID already exists:

1{
2  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
3  "detail": "ExternalId already exists",
4  "status": "409",
5  "code": 25022
6}

400 Bad Request - Primary email doesn't match username:

1{
2  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
3  "detail": "Primary email must match username",
4  "scimType": "invalidValue",
5  "status": "400",
6  "code": 25014
7}

Retrieve a user

Retrieve detailed information about a user by providing their user SID.

GET /scim/v2/Users/{id}

Path parameters

Name	Description
`id` (required)	The Twilio User SID.

Response

1{
2    "id": "US00000000000000000000000000000123",
3    "externalId": "36d02f84-1c1a-4409",
4    "userName": "alex.a@example.com",
5    "displayName": "Alex A.",
6    "name": {
7        "givenName": "Alex",
8        "familyName": "A."
9    },
10    "emails": [
11        {
12            "primary": true,
13            "value": "alex.a@example.com",
14            "type": "work"
15        }
16    ],
17    "active": true,
18    "locale": "fr-FR",
19    "timezone": "UTC",
20    "schemas": [
21        "urn:ietf:params:scim:schemas:core:2.0:User"
22    ],
23    "meta": {
24        "resourceType": "user",
25        "created": "2023-11-30T14:18:57.031225338Z",
26        "lastModified": "2023-11-30T14:18:57.031225338Z",
27        "version": "W/1"
28    }
29}

Error response

404 Not Found - User not found:

1{
2  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
3  "detail": "User not found",
4  "status": "404",
5  "code": 25008
6}

List users

Retrieve a list of users based on filter queries.

GET /scim/v2/Users

(information)

Info

SCIM pagination parameters (startIndex, itemsPerPage) are not supported.

Query parameters

Name	Description
`filter`	Filter by `userName` or `externalId`. Only the `eq` operator is supported. Example: `?filter=userName eq "user@example.com"` Example: `?filter=externalId eq "yFXk0vS3hrgu0q1"`

Response

1{
2    "Resources": [
3        {
4            "id": "US00000000000000000000000000000123",
5            "externalId": "36d02f84-1c1a-4409",
6            "userName": "alex.a@example.com",
7            "displayName": "Alex A.",
8            "name": {
9                "givenName": "Alex",
10                "familyName": "A."
11            },
12            "emails": [
13                {
14                    "primary": true,
15                    "value": "alex.a@example.com",
16                    "type": "work"
17                }
18            ],
19            "active": true,
20            "locale": "fr-FR",
21            "timezone": "UTC",
22            "schemas": [
23                "urn:ietf:params:scim:schemas:core:2.0:User"
24            ],
25            "meta": {
26                "resourceType": "user",
27                "created": "2023-11-30T14:18:57.031225338Z",
28                "lastModified": "2023-11-30T14:18:57.031225338Z",
29                "version": "W/1"
30            }
31        }
32    ],
33    "totalResults": 1,
34    "schemas": [
35        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
36    ]
37}

Update a user (PUT)

Update an existing user's SCIM user information. This operation replaces all user attributes.

PUT /scim/v2/Users/{id}

Requirements

This endpoint has the following requirements:

Only active and inactive users can be updated. Suspended users can't be updated.
You can't update the Organization Owner through this endpoint.
Requests that update email and username are allowed, but only when the two values match. Mismatched updates are rejected.

Updatable fields

You can update the following fields:

active
name.givenName
name.familyName
displayName
timezone
locale
emails
userName

Optimistic locking

Optimistic locking is performed in the following order of precedence:

The If-Match header, if present.
The meta.version field in the request body, if the header is not present.
No locking if neither is provided.

Path parameters

Name	Description
`id` (required)	The Twilio User SID.

Request body

1{
2   "externalId": "36d02f84-1c1a-4410",
3   "userName": "dana.b@example.com",
4   "displayName": "Dana B.",
5   "name": {
6       "givenName": "Dana",
7       "familyName": "B."
8   },
9   "emails": [
10       {
11           "primary": true,
12           "value": "dana.b@example.com",
13           "type": "work"
14       }
15   ],
16   "active": true,
17   "locale": "fr-FR",
18   "timezone": "UTC",
19   "schemas": [
20       "urn:ietf:params:scim:schemas:core:2.0:User"
21   ]
22}

Response

1{
2    "id": "US00000000000000000000000000000124",
3    "externalId": "36d02f84-1c1a-4410",
4    "userName": "dana.b@example.com",
5    "displayName": "Dana B.",
6    "name": {
7        "givenName": "Dana",
8        "familyName": "B."
9     },
10     "emails": [
11         {
12            "primary": true,
13            "value": "dana.b@example.com",
14            "type": "work"
15         }
16    ],
17    "active": true,
18    "locale": "fr-FR",
19    "timezone": "UTC",
20    "schemas": [
21        "urn:ietf:params:scim:schemas:core:2.0:User"
22    ],
23    "meta": {
24        "resourceType": "user",
25        "created": "2023-11-21T13:57:43.185004629Z",
26        "lastModified": "2023-11-30T14:58:44.700924318Z",
27        "version": "W/13"
28    }
29}

Error response

400 Bad Request - Username must be present:

1{
2  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
3  "detail": "UserName must be present",
4  "scimType": "invalidValue",
5  "status": "400",
6  "code": 25005
7}

Update a user (PATCH)

Partially update an existing user's SCIM user information. This operation modifies only the specified attributes.

PATCH /scim/v2/Users/{id}

Requirements

This endpoint has the following requirements:

Only active and inactive users can be patched. Suspended users can't be patched.
You can't update the Organization Owner through this endpoint.
Requests that patch email and username are allowed, but they must match. Mismatched updates are rejected.
If any operation violates business rules, the entire request is rejected.
Operations with unrecognized paths are ignored to ensure maximum compatibility.

Patchable fields

You can patch the following fields:

active
name.givenName
name.familyName
displayName
timezone
locale
emails
userName

Optimistic locking

Optimistic locking is performed based on the If-Match header. If the header isn't present, optimistic locking isn't performed.

Path parameters

Name	Description
`id` (required)	The Twilio User SID.

Request body

1{
2  "schemas": [
3    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
4  ],
5  "Operations": [
6    {
7      "op": "replace",
8      "path": "name.givenName",
9      "value": "Jordan"
10    },
11    {
12      "op": "replace",
13      "path": "name.familyName",
14      "value": "C."
15    },
16    {
17      "op": "replace",
18      "path": "displayName",
19      "value": "Jordan C."
20    },
21    {
22      "op": "replace",
23      "path": "active",
24      "value": false
25    },
26    {
27      "op": "replace",
28      "path": "emails[primary eq true].value",
29      "value": "jordan.c@example.com"
30    }
31  ]
32}

Response

1{
2    "id": "US00000000000000000000000000000124",
3    "externalId": "36d02f84-1c1a-4410",
4    "userName": "jordan.c@example.com",
5    "displayName": "Jordan C.",
6    "name": {
7        "givenName": "Jordan",
8        "familyName": "C."
9    },
10    "emails": [
11        {
12            "primary": true,
13            "value": "jordan.c@example.com",
14            "type": "work"
15        }
16    ],
17    "active": false,
18    "locale": "fr-FR",
19    "timezone": "UTC",
20    "schemas": [
21        "urn:ietf:params:scim:schemas:core:2.0:User"
22    ],
23    "meta": {
24        "resourceType": "user",
25        "created": "2023-11-21T13:57:43.185004629Z",
26        "lastModified": "2023-11-30T14:58:44.700924318Z",
27        "version": "W/13"
28    }
29}

Error response

400 Bad Request - The primary email must match the username:

1{
2  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
3  "detail": "Primary email must match username",
4  "scimType": "invalidValue",
5  "status": "400",
6  "code": 25014
7}

Delete a user

Deactivate a user. Users aren't deleted; they're deactivated in response to delete requests.

DELETE /scim/v2/Users/{id}

(information)

Info

You can't deactivate the Organization Owner through this endpoint.

Path parameters

Name	Description
`id` (required)	The Twilio User SID.

Response

204 No Content - User successfully deactivated.

Error response

404 Not Found - User not found:

1{
2  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
3  "detail": "User not found",
4  "status": "404",
5  "code": 25008
6}

Error codes

For information about error codes returned by the SCIM API, see the Twilio error codes reference. The error code is in the code field of the response.

Example error response:

1{
2  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
3  "detail": "User not found",
4  "status": "404",
5  "code": 25008
6}