The Flex Teams API resource contains code showing how to create, fetch (get), read (list), update, and delete teams in your Flex instance.
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.
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.
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.
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.
Encoding type:application/x-www-form-urlencoded
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
Name | Type | Description | PII? |
---|---|---|---|
PageSize | Integer or Null <=1000 | The page size. The default value is 50. | Not PII |
PageToken | Integer or Null | Page token for pagination. | Not PII |
Owner | String or Null | Team owner in FlexUserSid format. If not provided, will return all teams in the instance, otherwise will return teams owned by the owner. | Not PII |
IncludeTransitive | Boolean or Null | When 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 name | Type | Description | PII? |
---|---|---|---|
team_sid | String | The unique ID that identifies this resource. | Not PII |
friendly_name | String | The human-readable name of this team. | PII MTL: 30 days |
member_count | Integer | Represents the total number of members. | Not PII |
account_sid | String | The unique ID of the account responsible for the team. | Not PII |
instance_sid | String | The unique ID of the Flex related resources responsible for the team. | Not PII |
date_created | String | The date that this resource was created. | Not PII |
date_updated | String | The date that this resource was updated. | Not PII |
version | Integer | Represents the current iteration of the team's configuration, incrementing with each update to reflect changes. | Not PII |
level | Integer or Null | Allows teams to be categorized into different hierarchical structures, enabling better organization and role-based access control. | Not PII |
parent_team_sid | String or Null | The unique ID that uniquely identifies the parent team of this resource. | Not PII |
description | String or Null | Description of the team providing a brief summary of the team's purpose and focus. | PII MTL: 30 days |
GET
request
1curl -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": 117}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": null27}28}
Retrieve information about a specific team by making a GET
request to the /Teams
endpoint.
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
TeamSid (required) | String | A 34 character string that uniquely identifies this resource. | Not PII |
Schema name | Type | Description | PII? |
---|---|---|---|
team_sid | String | The unique ID that uniquely identifies this resource. | Not PII |
account_sid | String | The unique ID of the account responsible for the team. | Not PII |
instance_sid | String | The unique ID of the Flex related resources responsible for the team. | Not PII |
friendly_name | String | The human-readable name of this team. | PII MTL: 30 days |
description | String or Null | Description of the team providing a brief summary of the team's purpose and focus. | PII MTL: 30 days |
level | Integer or Null | Team level. | Not PII |
parent_team_sid | String or Null | The unique ID that uniquely identifies the parent team of this resource. | Not PII |
member_count | Integer | Represents the total number of members. | Not PII |
date_created | String | The date that this resource was created. | Not PII |
date_updated | String | The date that this resource was updated. | Not PII |
version | Integer | Represents the current iteration of the team's configuration, incrementing with each update to reflect changes. | Not PII |
GET
request
1curl -X GET "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/{TeamSid}" \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN3
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": 113}
To review all team Members assigned to a team, fetch the Team resource instance by making a GET
request to the /Members
endpoint.
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
TeamSid (required) | String | A 34 character string that uniquely identifies this resource. | Not PII |
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 |
Schema name | Type | Description | PII? |
---|---|---|---|
flex_user_sid | String | The unique ID of the Flex User. | Not PII |
account_sid | String | The unique ID of the account responsible for the team. | Not PII |
instance_sid | String | The unique ID of the Flex related resources responsible for the team. | Not PII |
team_sid | String or Null | A 34 character string that uniquely identifies this resource. | Not PII |
friendly_name | String or Null | The human-readable name of the Flex user. | PII MTL: 30 days |
String or Null | Uniquely identifies a team member user through their email address. | PII MTL: 30 days | |
worker_sid | String or Null | The SID of the Worker resource. | Not PII |
GET
request
1curl -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": null23}24}
To review all team owners assigned to a team, fetch the Team resource instance by making a GET
request to the /Owners
endpoint.
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
TeamSid (required) | String | A 34 character string that uniquely identifies this resource. | Not PII |
Name | Type | Description | PII? |
---|---|---|---|
IncludeTransitive | Boolean or Null | 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. | Not PII |
Schema name | Type | Description | PII |
---|---|---|---|
flex_user_sid | String | The unique ID of the Flex User. | Not PII |
account_sid | String | The unique ID of the account responsible for the team. | Not PII |
instance_sid | String | The unique ID of the Flex related resources responsible for the team. | Not PII |
team_sid | String or Null | A 34 character string that uniquely identifies this resource. | Not PII |
friendly_name | String or Null | The human-readable name of the Flex user. | PII MTL: 30 days |
String or Null | Uniquely identifies a team member user through their email address. | PII MTL: 30 days | |
worker_sid | String or Null | The SID of the Worker resource. | Not PII |
GET
request
1curl -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": null21}22}
To create a team make a POST
request to the /Teams
endpoint.
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
Name | Type | Description | PII |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
Schema name | Type | Description | PII |
---|---|---|---|
FriendlyName (required) | String [1 .. 100] characters | A descriptive string that you create to describe the team. Must be unique. | PII MTL: 30 days |
Description | String [1 .. 1000] characters | Description of the team providing a brief summary of the team’s purpose and focus. | PII MTL: 30 days |
Level | Integer <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 |
ParentTeamSid | string | The unique sid ID that identifies the parent team of this resource. Level 3 hierarchy cannot have a parent resource. | Not PII |
POST
request
1curl -X POST "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams" \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN34{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": 113}
Update a team by making a POST
request to the /Teams
endpoint.
Encoding type:application/x-www-form-urlencoded
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
TeamSid (required) | String | A 34 character string that uniquely identifies this resource. | Not PII |
Schema name | Type | Description | PII? |
---|---|---|---|
FriendlyName (required) | String [1 …100] characters | A descriptive string that you create to describe the Flex Team. Must be unique. | PII MTL: 30 days |
Description (required) | String [0 … 1000] characters | A description for the team. | PII MTL: 30 days |
ParentTeamSid (required) | String | Parent team sid. | Not PII |
Schema name | Type | Description | PII |
---|---|---|---|
team_sid | String | The unique ID that uniquely identifies this resource. | Not PII |
account_sid | String | The unique ID of the account responsible for the team. | Not PII |
instance_sid | String | The unique ID of the Flex related resources responsible for the team. | Not PII |
friendly_name | String | The human-readable name of this team. | PII MTL: 30 days |
description | String or Null | Description of the team providing a brief summary of the team's purpose and focus. | PII MTL: 30 days |
level | Integer or Null | Allows teams to be categorized into different hierarchical structures, enabling better organization and role-based access control. | Not PII |
parent_team_sid | String or Null | The unique ID that uniquely identifies the parent team of this resource. | Not PII |
member_count | Integer | Represents the total number of members. | Not PII |
date_created | String | The date that this resource was created. | Not PII |
date_updated | String | The date that this resource was updated. | Not PII |
version | Integer | Represents the current iteration of the team's configuration, incrementing with each update to reflect changes. | Not PII |
POST
request
1curl -X POST "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/{TeamSid}" \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN34{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": 113}
Add an Owner to a Team by making a POST
request to the /Owners
endpoint.
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
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
TeamSid (required) | String | A 34 character string that uniquely identifies this resource. | Not PII |
Schema name | Type | Description |
---|---|---|
FlexUserSid (required) | String | User SID of the Flex user to add to the team as an owner. |
Schema name | Type | Description | PII |
---|---|---|---|
account_sid | String | The unique ID of the account responsible for the team. | Not PII |
instance_sid | String | The unique ID of the Flex related resources responsible for the team. | Not PII |
flex_user_sid | String | The unique ID of the Flex User. | Not PII |
team_sid | String or Null | A 34 character string that uniquely identifies this resource. | Not PII |
friendly_name | String or Null | The human-readable name of the Flex user. | PII MTL: 30 days |
String or Null | Uniquely identifies a team member user through their email address. | PII MTL: 30 days | |
worker_sid | String or Null | The SID of the Worker resource. | Not PII |
POST
request
1curl -X POST "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/{TeamSid}/Owners" \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN34{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.
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:
/Members
endpoint.Encoding type:application/x-www-form-urlencoded
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
TeamSid (required) | String | A 34 character string that uniquely identifies this resource. | Not PII |
Schema name | Type | Description |
---|---|---|
FlexUserSid (required) | String | Team member's Flex User SID. |
Schema name | Type | Description | PII? |
---|---|---|---|
account_sid | String | The unique ID of the account responsible for the team. | Not PII |
instance_sid | String | The unique ID of the Flex related resources responsible for the team. | Not PII |
team_sid | String or Null | A 34 character string that uniquely identifies this resource. | Not PII |
flex_user_sid | String | The unique ID of the Flex user. | Not PII |
friendly_name | String or Null | The human-readable name of the Flex user. | PII MTL: 30 days |
String or Null | Uniquely identifies a team member user through their email address. | PII MTL: 30 days |
POST
request
1curl -X POST "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/{TeamSid}/Members" \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN34{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
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
TeamSid (required) | String | A 34 character string that uniquely identifies this resource. | Not PII |
FlexUserSid (required) | String | The unique ID of the Flex User. | Not PII |
Delete
request
1curl -X DELETE "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/{TeamSid}/Owners/{FlexUserSid}" \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN34
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
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
TeamSid (required) | String | A 34 character string that uniquely identifies this resource. | Not PII |
DELETE
request
1curl -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.
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
GET
request
1curl -X GET "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/Context" \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN3
Response
1{2"team_setup_complete": true3}
Set team context by making a POST
request to the /Context
endpoint.
Name | Type | Description | PII? |
---|---|---|---|
InstanceSid (required) | String | A 34 character string that identifies the Flex related resource responsible for the team. | Not PII |
Schema name | Type | Description |
---|---|---|
TeamSetupComplete (required) | Boolean | Indicates 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. |
POST
request
1curl -X POST "https://flex-api.twilio.com/v1/Instances/{InstanceSid}/Teams/Context" \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN34{5"TeamSetupComplete": true6}
Response
1{2"team_setup_complete": true3}