Flex Users API (public beta)

(new)

Flex Users API in public beta

The Flex Users API is currently available as a public beta product and the information contained in this document is subject to change. This means that some features are not yet implemented and others may be changed before the product is declared as generally available. Public beta products are not covered by an SLA.

Flex User resource

A Flex User acts as the parent entity for a TaskRouter Worker and an Insights User. When a Flex User is provisioned, the corresponding TaskRouter Worker is automatically created. If Flex Insights is enabled, an Insights User is automatically created as well. When the Flex User is deprovisioned, the associated TaskRouter Worker and Insights User (if applicable) are removed, and the Flex User itself is deactivated.

(information)

Info

When you manually create a TaskRouter Worker using the TaskRouter API, it isn't associated with a Flex User. Flex User provisioning occurs only through the Flex provisioning API that's documented here or through just-in-time (JIT) provisioning when the user first signs in to Flex using SSO.

List Flex Users

Path parameters

Name	Type	Description	PII?
InstanceSid (required)	String	A 34-character string that identifies the Flex instance.	Not PII

Your Flex instance is the container that holds your Flex resources. You can find your Flex instance SID in Console on the Flex overview page.

Query parameters

Name	Type	Description	PII?
PageSize	Integer or null <=1000	Page size. The default value is 50.	Not PII
PageToken	Integer or null	Page token for pagination.	Not PII

Flex User response schema

Schema name	Type	Description	PII?
flex_user_sid	String	Unique ID that identifies this resource.	Not PII
account_sid	String	Unique ID of the account.	Not PII
instance_sid	String	Unique ID of the Flex instance.	Not PII
team_sid	String	Unique ID of the team that the user is a member of.	Not PII
worker_sid	String or null	Unique ID of the TaskRouter worker associated with this user.	Not PII
workspace_sid	String or null	Unique ID of the TaskRouter workspace of the Flex instance.	Not PII
username	String	Human-readable unique string to identify the user.	PII MTL: 30 days
full_name	String	Human-readable name of this user.	PII MTL: 30 days
email	String	Email address of this user.	PII MTL: 30 days
roles	List	An array of Flex roles to be assigned to the user. Valid roles include agent, supervisor, and admin.	Not PII
created_date	String	Date that this resource was created.	Not PII
updated_date	String	Date that this resource was updated.	Not PII
version	Integer	The current iteration, incrementing with each update to reflect changes.	Not PII
deactivated	Boolean	Whether the user is deactivated. The associated TaskRouter Worker and Flex Insights User are deleted when the user is deactivated.	Not PII
deactivated_date	String	Date this resource was deactivated, either through SCIM or the `/Deprovision` API.	Not PII

Example request and response

GET request

1curl -X GET "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Users" \
2    -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1{
2  "users": [
3    {
4      "account_sid": "AC00000000000000000000000000000000",
5      "created_date": "2025-04-22T05:18:13Z",
6      "deactivated": true,
7      "deactivated_date": "2025-10-17T17:10:18Z",
8      "email": "jane@example.com",
9      "flex_team_sid": "Q000000000000000000000000000000000",
10      "flex_user_sid": "FU00000000000000000000000000000001",
11      "full_name": "Jane Doe",
12      "instance_sid": "GO00000000000000000000000000000000",
13      "locale": null,
14      "roles": [
15        "agent"
16      ],
17      "updated_date": "2025-10-17T17:10:15Z",
18      "username": "Jane",
19      "version": 24895,
20      "worker_sid": null,
21      "workspace_sid": "WS00000000000000000000000000000000"
22    },
23    {
24      "account_sid": "AC00000000000000000000000000000000",
25      "created_date": "2025-01-29T14:57:56Z",
26      "deactivated": false,
27      "deactivated_date": null,
28      "email": "foo@example.com",
29      "flex_team_sid": "Q000000000000000000000000000000000",
30      "flex_user_sid": "FU00000000000000000000000000000002",
31      "full_name": "Foo Bar",
32      "instance_sid": "GO00000000000000000000000000000000",
33      "locale": null,
34      "roles": [
35        "admin"
36      ],
37      "updated_date": "2025-03-04T16:17:57Z",
38      "username": "foo133",
39      "version": 2,
40      "worker_sid": "WK00000000000000000000000000000000",
41      "workspace_sid": "WC00000000000000000000000000000000"
42    }
43  ],
44  "meta": {
45    "first_page_url": "https://flex-api.twilio.com/v1/Instances/GO00000000000000000000000000000000/Users?PageSize=50&Page=0",
46    "key": "users",
47    "next_page_url": null,
48    "page": 0,
49    "page_size": 50,
50    "previous_page_url": null,
51    "url": "https://flex-api.twilio.com/v1/Instances/GO00000000000000000000000000000000/Users?PageSize=50&Page=0"
52  }
53}

Provision a Flex user

Available in the v4 API path or later.

Use the POST method on the user's /Provision endpoint to create or update a Flex User along with its associated entities, such as the TaskRouter Worker and Insights User. The API is idempotent, meaning that repeated requests with the same data will not create duplicate resources.

Request body parameters

Encoding type:application/json

Path parameters

Name	Type	Description	PII?
InstanceSid (required)	String	A 34-character string that identifies the Flex instance.	Not PII

Request schema

Schema name	Type	Description	PII
username (required)	String [1 .. 256] characters	A unique string that identifies the user, such as an email address.	PII MTL: 30 days
roles (required)	List	An array of Flex roles to be assigned to the user. Valid roles include agent, supervisor, and admin.	Not PII
full_name (required)	String [1 .. 256] characters	The full name of the user.	PII MTL: 30 days
email (required)	String [1 .. 256] characters	The email of the user.	PII MTL: 30 days
worker (required)	Object	JSON blob with optional TaskRouter Worker routing attributes. Can be empty `{}`.	Not PII

The username value is assigned as the friendly_name of the corresponding TaskRouter Worker.

Example request and response

POST request

1curl -X POST "https://flex-api.twilio.com/v4/Instances/{InstanceSid}/Users/Provision" \
2-u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
3-H "Content-Type: application/json" \
4--data-raw '{
5"username": "my.unique.username",
6"email": "my.unique.username@acme.com",
7"full_name": "Foo Bar",
8"roles": ["agent"],
9"worker" : {
10    "attributes" : {
11        "channel.voice.capacity" : 10,
12        "language": "english, spanish",
13        "more.stringarray" : "more,more2"
14    }
15}
16}'

Response

1{
2"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3"flex_user_sid": "FUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5"username": "my.unique.username",
6"email": "my.unique.username@acme.com",
7"full_name": "Foo Bar",
8"flex_team_sid": "QO00000000000000000000000000000000",
9"roles": [
10"agent"
11],
12"locale": "string",
13"worker": {
14"worker_sid": "WKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
15"workspace_sid": "WSaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
16},
17"deactivated": false,
18"created_date": "2019-08-24T14:15:22Z",
19"updated_date": "2019-08-24T14:15:22Z",
20"deactivated_date": null,
21"version": 1
22}

Deprovision a Flex user

Available in the v4 API path or later.

Deactivate a Flex user and delete associated TaskRouter worker a POST request to the /Deprovision endpoint.

Request body parameters

Encoding type:application/json

Path parameters

Name	Type	Description	PII?
InstanceSid (required)	String	A 34-character string that identifies the Flex instance	Not PII

Request schema

Schema name	Type	Description	PII?
flex_user_sid (required)	String	The unique ID that identifies this resource.	Not PII

Example request and response

POST request

1
2curl -x POST 'http://flex-api.twilio.com/v4/Instances/{InstanceSid}/Users/Deprovision' \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
4{
5  "flex_user_sid": "FU00000000000000000000000000000000"
6}

Response

Get Flex user by username

Available in the v4 API path or later.

Fetch a Flex user by username. The response returns 0 or 1 results.

Path parameters

Name	Type	Description	PII?
InstanceSid (required)	String	A 34-character string that identifies the Flex instance.	Not PII

Your Flex instance is the container that holds your Flex resources. You can find your Flex instance SID in Console on the Flex overview page.

Query parameters

Name	Type	Description	PII?
Username (required)	String	Username of the Flex user to fetch.	PII MTL: 30 days

Example request and response

GET request

1curl -X GET "https://flex-api.twilio.com/v4/Instances/{InstanceSid}/Users?Username=Jane" \
2    -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1{
2  "account_sid": "AC00000000000000000000000000000000",
3  "instance_sid": "GO00000000000000000000000000000000",
4  "users": [
5    {
6      "account_sid": "AC00000000000000000000000000000000",
7      "created_date": "2025-10-23T15:05:27Z",
8      "deactivated": false,
9      "deactivated_date": null,
10      "email": "jane@example.com",
11      "flex_team_sid": "QO00000000000000000000000000000000",
12      "flex_user_sid": "FU00000000000000000000000000000000",
13      "full_name": "Jane Doe",
14      "instance_sid": "GO00000000000000000000000000000000",
15      "locale": null,
16      "roles": [
17        "agent"
18      ],
19      "updated_date": "2025-10-23T15:20:47Z",
20      "username": "Jane",
21      "version": 5,
22      "workspace_sid": "WS00000000000000000000000000000000"
23    }
24  ],
25  "meta": {
26    "direct_token": true,
27    "list_key": "users",
28    "next_token": null,
29    "page_size": 50,
30    "previous_token": null
31  }
32}

Get Flex user by Flex user SID

Available in the v4 API path or later.

Fetch a Flex user by user SID. The response returns 0 or 1 results.

Path parameters

Name	Type	Description	PII?
InstanceSid (required)	String	A 34-character string that identifies the Flex instance.	Not PII
FlexUserSid (required)	String	Unique ID of the Flex user to fetch.	Not PII

Example request and response

GET request

1curl -X GET "https://flex-api.twilio.com/v4/Instances/{InstanceSid}/Users/{FlexUserSid}" \
2    -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1{
2  "account_sid": "AC00000000000000000000000000000000",
3  "created_date": "2025-04-22T05:18:13Z",
4  "deactivated": false,
5  "deactivated_date": null,
6  "email": "jane@example.com",
7  "flex_team_sid": "Q000000000000000000000000000000000",
8  "flex_user_sid": "FU00000000000000000000000000000001",
9  "full_name": "Jane Doe",
10  "instance_sid": "GO00000000000000000000000000000000",
11  "locale": null,
12  "roles": [
13    "agent"
14  ],
15  "updated_date": "2025-10-17T17:10:15Z",
16  "username": "Jane",
17  "version": 24895,
18  "worker_sid": "WK00000000000000000000000000000000",
19  "workspace_sid": "WS00000000000000000000000000000000"
20}