Skip to contentSkip to navigationSkip to topbar
On this page

Flex Teams API (public beta)


The Flex Teams API resource contains code showing how to create, fetch (get), read (list), update, and delete teams in your Flex instance.

(warning)

Flex Teams API in public beta

Teams, including the Flex Teams 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.

(warning)

Do not use Personally Identifiable Information (PII) for the `FriendlyName` or `Description` fields

Avoid using a person's name, home address, email, phone number, or other PII in the FriendlyName or Description fields. Instead, use some form of pseudonymized identifier.

Learn more about how we process your data in our privacy policy(link takes you to an external page).


Teams resource

teams-resource page anchor

Flex Teams are configurable grouping structures applied to agents and supervisors to facilitate fine-grained access control policies based on group memberships.

This page details the Flex Team API resource. Check out the additional documentation to learn more about working with Flex Teams.


To review your account's current Flex Team configuration, fetch the Team resource instance by making a GET request to the /Teams endpoint.

(information)

Info

By default, all Flex users in a Flex instance are automatically added to the default team. The default team is a system-generated team that cannot be deleted.

Request body parameters

request-body-parameters page anchor

Encoding type:application/x-www-form-urlencoded

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
NameTypeDescriptionPII?
PageSizeInteger or Null <=1000The page size. The default value is 50.Not PII
PageTokenInteger or NullPage token for pagination.Not PII
OwnerString or NullTeam owner in FlexUserSid format. If not provided, will return all teams in the instance, otherwise will return teams owned by the owner.Not PII
IncludeTransitiveBoolean or NullWhen listing teams for an owner, indicating True will include teams transitively owned by the owner. For example, if turned on, it will return all level 2 and level 1 teams under the level 3 team owner. The default is false.Not PII
Schema nameTypeDescriptionPII?
team_sidStringThe unique ID that identifies this resource.Not PII
friendly_nameStringThe human-readable name of this team.PII MTL: 30 days
member_countIntegerRepresents the total number of members.Not PII
account_sidStringThe unique ID of the account responsible for the team.Not PII
instance_sidStringThe unique ID of the Flex related resources responsible for the team.Not PII
date_createdStringThe date that this resource was created.Not PII
date_updatedStringThe date that this resource was updated.Not PII
versionIntegerRepresents the current iteration of the team's configuration, incrementing with each update to reflect changes.Not PII
levelInteger or NullAllows teams to be categorized into different hierarchical structures, enabling better organization and role-based access control.Not PII
parent_team_sidString or NullThe unique ID that uniquely identifies the parent team of this resource.Not PII
descriptionString or NullDescription of the team providing a brief summary of the team's purpose and focus.PII MTL: 30 days

Example request and response

example-request-and-response page anchor

GET request

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

Response

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"teams": [
5
{
6
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8
"team_sid": "QO00000000000000000000000000000000",
9
"friendly_name": "default",
10
"member_count": 10,
11
"description": "default team",
12
"level": 1,
13
"parent_team_sid": null,
14
"date_created": "2024-08-01T22:10:40Z",
15
"date_updated": "2024-08-01T22:10:40Z",
16
"version": 1
17
}
18
],
19
"meta": {
20
"key": "teams",
21
"page": 0,
22
"page_size": 50,
23
"first_page_url": "https://flex-api.twilio.com/v1/Instances/GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Teams?PageSize=50&Page=0",
24
"url": "https://flex-api.twilio.com/v1/Instances/GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Teams?PageSize=50&Page=0",
25
"next_page_url": null,
26
"previous_page_url": null
27
}
28
}

Retrieve information about a specific team by making a GET request to the /Teams endpoint.

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
TeamSid (required)StringA 34 character string that uniquely identifies this resource.Not PII
Schema nameTypeDescriptionPII?
team_sidStringThe unique ID that uniquely identifies this resource.Not PII
account_sidStringThe unique ID of the account responsible for the team.Not PII
instance_sidStringThe unique ID of the Flex related resources responsible for the team.Not PII
friendly_nameStringThe human-readable name of this team.PII MTL: 30 days
descriptionString or NullDescription of the team providing a brief summary of the team's purpose and focus.PII MTL: 30 days
levelInteger or NullTeam level.Not PII
parent_team_sidString or NullThe unique ID that uniquely identifies the parent team of this resource.Not PII
member_countIntegerRepresents the total number of members.Not PII
date_createdStringThe date that this resource was created.Not PII
date_updatedStringThe date that this resource was updated.Not PII
versionIntegerRepresents the current iteration of the team's configuration, incrementing with each update to reflect changes.Not PII

Example GET request and response

example-get-request-and-response page anchor

GET request

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

Response

1
{
2
"team_sid": "QO00000000000000000000000000000000",
3
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"friendly_name": "default",
6
"member_count": 10,
7
"description": "default team",
8
"level": 1,
9
"parent_team_sid": "QO00000000000000000000000000000001",
10
"date_created": "2024-08-01T22:10:40Z",
11
"date_updated": "2024-08-01T22:10:40Z",
12
"version": 1
13
}

Fetch all Team Members for a Team

fetch-all-team-members-for-a-team page anchor

To review all team Members assigned to a team, fetch the Team resource instance by making a GET request to the /Members endpoint.

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
TeamSid (required)StringA 34 character string that uniquely identifies this resource.Not PII
NameTypeDescriptionPII?
PageSizeInteger or Null <=1000Page size. The default value is 50.Not PII
PageTokenInteger or NullPage token for pagination.Not PII

Member array response schema

member-array-response-schema page anchor
Schema nameTypeDescriptionPII?
flex_user_sidStringThe unique ID of the Flex User.Not PII
account_sidStringThe unique ID of the account responsible for the team.Not PII
instance_sidStringThe unique ID of the Flex related resources responsible for the team.Not PII
team_sidString or NullA 34 character string that uniquely identifies this resource.Not PII
friendly_nameString or NullThe human-readable name of the Flex user.PII MTL: 30 days
emailString or NullUniquely identifies a team member user through their email address.PII MTL: 30 days
worker_sidString or NullThe SID of the Worker resource.Not PII

Example request and response

example-request-and-response-1 page anchor

GET request

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

Response

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"members": [
5
{
6
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8
"team_sid": "QO00000000000000000000000000000000",
9
"flex_user_sid": "FU00000000000000000000000000000000",
10
"friendly_name": "userName",
11
"email": "test@twilio.com",
12
"worker_sid": "WK00000000000000000000000000000000"
13
}
14
],
15
"meta": {
16
"list_key": "members",
17
"page": 0,
18
"page_size": 50,
19
"first_page_url": "https://flex-api.twilio.com/v1/Instances/GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Teams/QO00000000000000000000000000000000/Members?PageSize=50&Page=0",
20
"url": "https://flex-api.twilio.com/v1/Instances/GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Teams/QO00000000000000000000000000000000/Members?PageSize=50&Page=0",
21
"next_page_url": null,
22
"previous_page_url": null
23
}
24
}

Fetch all Team Owners for a Team

fetch-all-team-owners-for-a-team page anchor

To review all team owners assigned to a team, fetch the Team resource instance by making a GET request to the /Owners endpoint.

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
TeamSid (required)StringA 34 character string that uniquely identifies this resource.Not PII
NameTypeDescriptionPII?
IncludeTransitiveBoolean or NullIndicating True will include teams "transitively" owned by the owner. For example, if turned on, it will return all level 2 and level 1 teams under the level 3 team owner.Not PII

Owner response array schema

owner-response-array-schema page anchor
Schema nameTypeDescriptionPII
flex_user_sidStringThe unique ID of the Flex User.Not PII
account_sidStringThe unique ID of the account responsible for the team.Not PII
instance_sidStringThe unique ID of the Flex related resources responsible for the team.Not PII
team_sidString or NullA 34 character string that uniquely identifies this resource.Not PII
friendly_nameString or NullThe human-readable name of the Flex user.PII MTL: 30 days
emailString or NullUniquely identifies a team member user through their email address.PII MTL: 30 days
worker_sidString or NullThe SID of the Worker resource.Not PII

Example request and response

example-request-and-response-2 page anchor

GET request

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

Response

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"owners": [
5
{
6
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
8
"team_sid": "QO00000000000000000000000000000000",
9
"flex_user_sid": "FU00000000000000000000000000000000",
10
"friendly_name": "userName",
11
"email": "test@twilio.com",
12
"worker_sid": "WK00000000000000000000000000000000"
13
}
14
],
15
"meta": {
16
"direct_token": true,
17
"key": "owners",
18
"next_token": null,
19
"page_token": null,
20
"previous_token": null
21
}
22
}

To create a team make a POST request to the /Teams endpoint.

(information)

Info

The Team API uses the level field to organize teams into a three-tiered hierarchy for better structure and access control. Level 3 represents the top-level hierarchy of groups containing only owners and serving as the parent for Level 2 groups of teams. Level 3 cannot have a parent team. Level 2, forms the middle tier, containing only owners and acting as the parent for Level 1 teams. Level 1, the "team" level, is the bottom tier where both members and owners reside.

Encoding type:application/x-www-form-urlencoded

NameTypeDescriptionPII
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
Schema nameTypeDescriptionPII
FriendlyName (required)String [1 .. 100] charactersA descriptive string that you create to describe the team. Must be unique.PII MTL: 30 days
DescriptionString [1 .. 1000] charactersDescription of the team providing a brief summary of the team’s purpose and focus.PII MTL: 30 days
LevelInteger <int32> [ 1 .. 3 ]Hierarchy level of the resource. Bottom level is 1. The middle level group of teams is 2 and the top level hierarchy of groups is 3. Default is 1.Not PII
ParentTeamSidstringThe unique sid ID that identifies the parent team of this resource. Level 3 hierarchy cannot have a parent resource.Not PII

Example request and response

example-request-and-response-3 page anchor

POST request

1
curl -X POST "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams" \
2
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
3
4
{
5
"FriendlyName": "teamName",
6
"Description": "description",
7
"Level": 1,
8
"ParentTeamSid": "QO00000000000000000000000000000001"
9
}

Response

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"team_sid": "QO00000000000000000000000000000002",
5
"friendly_name": "teamName",
6
"member_count": 10,
7
"description": "description",
8
"level": 1,
9
"parent_team_sid": "QO00000000000000000000000000000001",
10
"date_created": "2024-08-01T22:10:40Z",
11
"date_updated": "2024-08-01T22:10:40Z",
12
"version": 1
13
}

Update a team by making a POST request to the /Teams endpoint.

Encoding type:application/x-www-form-urlencoded

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
TeamSid (required)StringA 34 character string that uniquely identifies this resource.Not PII
Schema nameTypeDescriptionPII?
FriendlyName (required)String [1 …100] charactersA descriptive string that you create to describe the Flex Team. Must be unique.PII MTL: 30 days
Description (required)String [0 … 1000] charactersA description for the team.PII MTL: 30 days
ParentTeamSid (required)StringParent team sid.Not PII
Schema nameTypeDescriptionPII
team_sidStringThe unique ID that uniquely identifies this resource.Not PII
account_sidStringThe unique ID of the account responsible for the team.Not PII
instance_sidStringThe unique ID of the Flex related resources responsible for the team.Not PII
friendly_nameStringThe human-readable name of this team.PII MTL: 30 days
descriptionString or NullDescription of the team providing a brief summary of the team's purpose and focus.PII MTL: 30 days
levelInteger or NullAllows teams to be categorized into different hierarchical structures, enabling better organization and role-based access control.Not PII
parent_team_sidString or NullThe unique ID that uniquely identifies the parent team of this resource.Not PII
member_countIntegerRepresents the total number of members.Not PII
date_createdStringThe date that this resource was created.Not PII
date_updatedStringThe date that this resource was updated.Not PII
versionIntegerRepresents the current iteration of the team's configuration, incrementing with each update to reflect changes.Not PII

Example request and response

example-request-and-response-4 page anchor

POST request

1
curl -X POST "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/{TeamSid}" \
2
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
3
4
{
5
"FriendlyName": "newTeamName",
6
"Description": "description",
7
"ParentTeamSid": "QO00000000000000000000000000000001"
8
}
9

Response

1
{
2
"team_sid": "QO00000000000000000000000000000002",
3
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
5
"friendly_name": "newTeamName",
6
"member_count": 10,
7
"description": "description",
8
"level": 1,
9
"parent_team_sid": "QO00000000000000000000000000000001",
10
"date_created": "2024-08-01T22:10:40Z",
11
"date_updated": "2024-08-01T22:10:40Z",
12
"version": 1
13
}

Add an Owner to a Team by making a POST request to the /Owners endpoint.

(information)

Info

Team owners are typically supervisors. Owners can be an owner of multiple teams. Owners can also be a member of a team. Limit of 50 owners per team.

Encoding type:application/x-www-form-urlencoded

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
TeamSid (required)StringA 34 character string that uniquely identifies this resource.Not PII
Schema nameTypeDescription
FlexUserSid (required)StringUser SID of the Flex user to add to the team as an owner.
Schema nameTypeDescriptionPII
account_sidStringThe unique ID of the account responsible for the team.Not PII
instance_sidStringThe unique ID of the Flex related resources responsible for the team.Not PII
flex_user_sidStringThe unique ID of the Flex User.Not PII
team_sidString or NullA 34 character string that uniquely identifies this resource.Not PII
friendly_nameString or NullThe human-readable name of the Flex user.PII MTL: 30 days
emailString or NullUniquely identifies a team member user through their email address.PII MTL: 30 days
worker_sidString or NullThe SID of the Worker resource.Not PII

Example request and response

example-request-and-response-5 page anchor

POST request

1
curl -X POST "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/{TeamSid}/Owners" \
2
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
3
4
{
5
"FlexUserSid": "FU00000000000000000000000000000000"
6
}

Response

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"team_sid": "QO00000000000000000000000000000000",
5
"flex_user_sid": "FU00000000000000000000000000000000",
6
"friendly_name": "userName",
7
"email": "test@twilio.com",
8
"worker_sid": "WK00000000000000000000000000000000"
9
}
10

Add a user as a Member to a Team by making a POST request to the /Members endpoint.

(information)

Info

The /Members endpoint should be used to remove users from a team by reassigning them to another team, as there is no dedicated Delete Member API.

To remove members from a team:

  • Assign them to a different team using the /Members endpoint.
  • If the member should no longer belong to a specific team but is still a part of the organization, they can be moved back to the default team.

Encoding type:application/x-www-form-urlencoded

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
TeamSid (required)StringA 34 character string that uniquely identifies this resource.Not PII
Schema nameTypeDescription
FlexUserSid (required)StringTeam member's Flex User SID.
Schema nameTypeDescriptionPII?
account_sidStringThe unique ID of the account responsible for the team.Not PII
instance_sidStringThe unique ID of the Flex related resources responsible for the team.Not PII
team_sidString or NullA 34 character string that uniquely identifies this resource.Not PII
flex_user_sidStringThe unique ID of the Flex user.Not PII
friendly_nameString or NullThe human-readable name of the Flex user.PII MTL: 30 days
emailString or NullUniquely identifies a team member user through their email address.PII MTL: 30 days

Example POST request and response

example-post-request-and-response page anchor

POST request

1
curl -X POST "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/{TeamSid}/Members" \
2
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
3
4
{
5
"FlexUserSid": "FU00000000000000000000000000000000"
6
}

Response

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"instance_sid": "GOaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
"team_sid": "QO00000000000000000000000000000000",
5
"flex_user_sid": "FU00000000000000000000000000000000",
6
"friendly_name": "userName",
7
"email": "test@twilio.com",
8
"worker_sid": "WK00000000000000000000000000000000"
9
}

Delete an Owner of a team by making a DELETE request to the /Owners endpoint.

Encoding type:application/x-www-form-urlencoded

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
TeamSid (required)StringA 34 character string that uniquely identifies this resource.Not PII
FlexUserSid (required)StringThe unique ID of the Flex User.Not PII

Example DELETE request and response

example-delete-request-and-response page anchor

Delete request

1
curl -X DELETE "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/{TeamSid}/Owners/{FlexUserSid}" \
2
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
3
4

Response

204 Successfully deleted team owner.


Delete a team by making a DELETE request to the /Teams endpoint.

Encoding type:application/x-www-form-urlencoded

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
TeamSid (required)StringA 34 character string that uniquely identifies this resource.Not PII

Example DELETE request and response

example-delete-request-and-response-1 page anchor

DELETE request

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

Response

204 Successfully deleted.


Get teams context by making a GET request to the /Context endpoint.

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII

Example GET request and response

example-get-request-and-response-1 page anchor

GET request

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

Response

1
{
2
"team_setup_complete": true
3
}

Set team context by making a POST request to the /Context endpoint.

NameTypeDescriptionPII?
InstanceSid (required)StringA 34 character string that identifies the Flex related resource responsible for the team.Not PII
Schema nameTypeDescription
TeamSetupComplete (required)BooleanIndicates team setup to be displayed in Flex UI. When set to True, controls whether Teams View is displayed in Flex. The default setting is False.

Example POST request and response

example-post-request-and-response-1 page anchor

POST request

1
curl -X POST "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/Context" \
2
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
3
4
{
5
"TeamSetupComplete": true
6
}

Response

1
{
2
"team_setup_complete": true
3
}