Team API
The following article covers Sigma’s developer API for organization teams.
Contents
Assign a user attribute to a team
Endpoints
GET /v2/teams
Returns a list of teams in your organization.
GET /v2/teams/{teamId}
Returns a team object based on its unique identifier, teamId.
GET /v2/teams/{teamId}/members
Returns a paginated list of team members.
POST /v2/teams
Creates a new team, and returns a team object.
POST /v2/user-attributes/{userAttributeId}/teams
Assigns a user attribute to a team.
PATCH /v2/teams/{teamId}
Updates the team's metadata and returns the associated a team object.
PATCH /v2/teams/{teamId}/members
Adds or removes team members, based on the entered parameters. Returns an empty object.
DELETE /v2/teams/{teamId}
Deletes a team based on the provided unique identifier, teamId. Returns an empty object.
The team object
Attributes
teamId string
The team’s unique identifier
name string
The team name
description string | null
A description of the team
createdBy string
The unique identifier, memberId, of the organization member who created the team
updatedBy string
The unique identifier, memberId, of the organization member who last made changes to the team
createdAt string
The timestamp at which the team was created
updatedAt string
The timestamp at which the team was last updated
isArchived boolean
True if the team is archived
members Array<memberId>
A list of unique identifiers (memberId) for all organization members assigned to the team
Important: This attribute is only included when the request is for a single team: GET /v2/teams/{teamId}. It is not included in responses to GET /v2/teams.
{
"teamId": "88858466-5299-4425-95c0-4b7d93268bae",
"name": "Sales US–West",
"description": "All Sales employees in the Western US region.",
"createdBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"updatedBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"createdAt": "2021-10-07T19:43:01.778Z",
"updatedAt": "2021-10-07T19:43:01.778Z",
"members": [
"6VZszXPJqLXpIezcD5adESnwfPPUg",
"7xtVWXPJqLptLezceRadESnwfttOP"
]
}
List all teams
Returns a list of teams in your organization.
GET /v2/teams
Permissions
-
The user account associated with the API access token must be a member of a team to view its details. Organization Admins have access to all teams.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Parameters
None
cURL request
curl --location --request GET 'https://api.sigmacomputing.com/v2/teams \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
Returns Array<Team>.
Array<{
"teamId": string,
"createdBy": string,
"updatedBy": string,
"createdAt": string,
"updatedAt": string,
"name": string,
"description": string | null
}>
Example
Example request:
curl --location --request GET 'https://api.sigmacomputing.com/v2/teams' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example response:
[
{
"teamId": "22340501-5fda-4000-8000-000000000001",
"createdBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"updatedBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"createdAt": "2021-10-04T20:36:40.591Z",
"updatedAt": "2021-10-04T20:36:40.591Z",
"name": "All Members",
"description": null
},
{
"teamId": "88858466-5299-4425-95c0-4b7d93268bae",
"createdBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"updatedBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"createdAt": "2021-10-07T19:43:01.778Z",
"updatedAt": "2021-10-07T19:43:01.778Z",
"name": "Sales US–West",
"description": "All Sales employees in the Western US region."
}
]
Look up a team
Returns a team object based on its unique identifier, teamId.
GET /v2/teams/{teamId}
Permissions
-
The user account associated with the API access token must be a member of the requested team. Organization Admins have access to all teams.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Parameters
None
cURL request
curl --location --request GET 'https://api.sigmacomputing.com/v2/teams/{teamId} \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
Returns a team object.
{
"teamId": string,
"createdBy": string,
"updatedBy": string,
"createdAt": string,
"updatedAt": string,
"name": string,
"description": string | null,
"isArchived": boolean,
"members": Array<string>
}
Example
Example request:
curl --location --request GET 'https://api.sigmacomputing.com/v2/teams/22340501-5fda-4000-8000-000000000001' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example response:
{
"teamId": "22340501-5fda-4000-8000-000000000001",
"createdBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"updatedBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"createdAt": "2021-10-04T20:36:40.591Z",
"updatedAt": "2021-10-04T20:36:40.591Z",
"name": "All Members",
"description": null,
"isArchived": false,
"members": [
"6VZszXPJqLXpIezcD5adESnwfPPUg",
"7xtVWXPJqLptLezceRadESnwfttOP"
]
}
List team members
Returns a paginated list of team members based on its unique identifier.
GET /v2/teams/{teamId}/members
Permissions
-
The user account associated with the API access token must be a member of the requested team. Organization Admins have access to all teams.
Note: If you encounter a permission error for the given endpoint, check the permissions associated with your API token.
Parameters
teamId string
The team’s unique identifier.
page string
An identifier used for pagination.
limit number
The number of members to be returned.
cURL request
curl --location --request GET 'https://api.sigmacomputing.com/v2/teams/{teamId}/members \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
Returns a team object.
{
"entries": [{
"userId": string,
"isTeamAdmin": boolean
}],
"nextPage": string | null,
"total": number
}
Example
Example request:
curl --location --request GET 'https://api.staging.sigmacomputing.io/v2/teams/20140501-5fca-4000-8000-000000000001/members' \ --header 'Authorization: Bearer {access_token}' \ --header 'Accept: application/json' \
Example response:
{ "entries": [ { "userId": "6VZszXPJqLXpIezcD5adESnwfPPUg", "isTeamAdmin": false }, { "userId": "7xtVWXPJqLptLezceRadESnwfttOP", "isTeamAdmin": true } ], "nextPage": null, "total": 2 }
Create a new team
Creates a new team. Returns a team object.
POST /v2/teams
Permissions
-
The user account associated with the API access token must have permission to create teams. Only Admins have this level of permission.
Note: If you encounter a permission error for the given endpoint, check the permissions associated with your API token.
Parameters
name string
The name to be assigned to the new team.
description string [optional]
A description for the team.
members Array<memberId> [optional]
A list of organization members to assign to the team.
createTeamFolder boolean [optional]
If true, a team workspace is created. The team will automatically be granted CanContribute access to this workspace.
cURL request
curl --location --request POST 'https://api.sigmacomputing.com/v2/teams/ \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": string,
"description": string, // or undefined
"members": Array<memberId>, // or undefined
"createTeamFolder": boolean // or undefined
}'
Response
Returns a team object.
{
"teamId": string,
"createdBy": string,
"updatedBy": string,
"createdAt": string,
"updatedAt": string,
"name": string,
"description": string | null,
"isArchived": boolean,
"members": Array<string>
}
Example
Example request:
curl --location --request POST 'https://api.sigmacomputing.com/v2/teams/' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Sales US-West",
"description"; null,
"members": [
"6VZszXPJqLXpIezcD5adESnwfPPUg",
"7xtVWXPJqLptLezceRadESnwfttOP"
],
"createTeamFolder": true
}'
Example response:
{
"teamId": "22340501-5fda-4000-8000-000000000001",
"createdBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"updatedBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"createdAt": "2021-10-04T20:36:40.591Z",
"updatedAt": "2021-10-04T20:36:40.591Z",
"name": "Sales US-West",
"description": null,
"isArchived": false
}
Assign a user attribute to a team
Assigns a user attribute to a team. Before you use this endpoint, you must create user attributes in the UI. For more information, see User Attributes.
POST /v2/user-attributes/{userAttributeId}/teams
Permissions
- You must be an admin to use this endpoint.
Path parameters
userAttributeId | string [required]
The ID for the user attribute that you created in the UI. To locate the userAttributeId in the admin portal, go to the User Attributes tab and click on an attribute. The ID will appear at the end of the URL. In the example below, e3e14c05-af93-4b50-a93e-eac857166728
is the userAttributeId.
https://app.sigmacomputing.com/sigma-example/admin/attributes/e3e14c05-af93-4b50-a93e-eac857166728
Request parameters
assignments | array <value> [Required]
Use this array to associate an user attribute value & data type with a team.
teamId | string [Required]
The user attribute will be assigned to this team. To locate the teamId in the admin portal, go to the Teams tab and click on the team. The ID will appear at the end of the URL. In the example below, 77f8c529-71aa-47b7-9253-65f119ffb0b1
is the teamId.
https://app.sigmacomputing.com/sigma-docs/admin/teams/77f8c529-71aa-47b7-9253-65f119ffb0b1
You can also use the Team API to fetch a list of teams in your org.
GET /v2/teams
value | string { val, type} [Required]
The user attribute value that you want to assign to a team. Type, data type, is always set to string.
cURL request
curl -X 'POST''https://api.sigmacomputing.com/v2/user-attributes/{userAttributeId}/teams' \ -H 'accept: application/json' \ -H 'Authorization: {access_token}' \ -H 'Content-Type: application/json' \ -d '{ "assignments": [ { "teamId": "string", "value": { "val": "string" "type": "string" } } ] }'
Response
Returns an empty object.
{}
Example
Example request:
curl -X 'POST''https://api.sigmacomputing.com/v2/user-attributes/e3e14c05-af93-4b50-a93e-eac857166728/teams' \
-H 'accept: application/json' \
-H 'Authorization: {access_token}' \
-H 'Content-Type: application/json' \
-d '{
"assignments": [
{
"teamId": "e3e14c05-af93-4b50-a93e-eac857166728",
"value": {
"val": "west"
"type": "string"
}
}
]
}'
Example response:
{}
Update an existing team
Updates the team's metadata and returns the associated team object.
PATCH /v2/teams/{teamId}
Permissions
-
The user account associated with the API access token must have access to edit teams. Only Admins have this level of access.
Note: If you encounter a permission error for the given endpoint, check the permissions associated with your API token.
Parameters
name string [optional]
The name to be assigned to the new team.
description string [optional]
A description for the team.
cURL request
curl --location --request PATCH 'https://api.sigmacomputing.com/v2/teams/{teamId}/ \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": string, // or undefined
"description": string, // or undefined
}'
Response
Returns a team object.
{
"teamId": string,
"createdBy": string,
"updatedBy": string,
"createdAt": string,
"updatedAt": string,
"name": string,
"description": string | null,
"isArchived": boolean
}
Example
Example request:
curl --location --request PATCH 'https://api.sigmacomputing.com/v2/teams/22340501-5fda-4000-8000-000000000001' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Sales US-West",
"description": "Sales team covering the west coast",
}'
Example response:
{
"teamId": "22340501-5fda-4000-8000-000000000001",
"createdBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"updatedBy": "6VZszXPJqLXpIezcD5adESnwfPPUg",
"createdAt": "2020-08-04T20:35:42.491Z",
"updatedAt": "2021-10-04T20:36:40.591Z",
"name": "Sales US-West",
"description": null,
"isArchived": false,
}
Add or remove team members
Based on the entered parameters, adds or removes team members. Returns an empty object.
Note: No more than a total of 100 users can be added or removed at a time.
PATCH /v2/teams/{teamId}/members
Permissions
-
The user account associated with the API access token must have permission to add/remove team members. Only Admins have this level of permission.
Note: If you encounter a permission error for the given endpoint, check the permissions associated with your API token.
Parameters
add Array<memberId> [optional]
A list of organization members to add to the team.
remove Array<memberId> [optional]
A list of organization members to remove from the team.
cURL request
curl --location --request PATCH 'https://api.sigmacomputing.com/v2/teams/{teamId}/members \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"add": Array<memberId>, // or undefined
"remove": Array<memberId> // or undefined
}'
Response
{}
Example
Example request:
curl --location --request PATCH 'https://api.sigmacomputing.com/v2/teams/22340501-5fda-4000-8000-000000000001/members \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"add": [
"6VZszXPJqLXpIezcD5adESnwfPPUg",
"7xtVWXPJqLptLezceRadESnwfttOP"
]
}'
Example response:
{}
Delete a Team
Deletes a team based on the provided unique identifier, teamId. Returns an empty object.
DELETE /v2/teams/{teamId}
Permissions
-
The user account associated with the API access token must have permission to delete teams. Only Admins have this level of permission.
Note: If you encounter a permission error for the given endpoint, check the permissions associated with your API token.
Parameters
None
cURL request
curl --location --request DELETE 'https://api.sigmacomputing.com/v2/teams/{teamId} \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
Returns an empty object.
{}
Example
Example request:
curl --location --request DELETE 'https://api.sigmacomputing.com/v2/teams/22340501-5fda-4000-8000-000000000001' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example response:
{}
Related resources
API documentation
Get started with Sigma's API
Create an API token and client ID
Identify unique IDs in Sigma