Team API

The following article covers Sigma’s developer API for organization teams.

Contents

Endpoints

The team object

Attributes

List all teams

Look up a team

List team members

Create a new team

Assign a user attribute to a team

Update an existing team

Update team members

Delete a team

Related resources

Endpoints

GET /v2/teams

      Returns a list of teams in your organization.

      Try it in Swagger

GET /v2/teams/{teamId}

      Returns a team object based on its unique identifier, teamId.

      Try it in Swagger

GET /v2/teams/{teamId}/members

      Returns a paginated list of team members.

      Try it in Swagger

POST /v2/teams

      Creates a new team, and returns a team object.

      Try it in Swagger

POST /v2/user-attributes/{userAttributeId}/teams

      Assigns a user attribute to a team.

      Try it in Swagger

PATCH /v2/teams/{teamId}

      Updates the team's metadata and returns the associated a team object.

      Try it in Swagger

PATCH /v2/teams/{teamId}/members

      Adds or removes team members, based on the entered parameters. Returns an empty object. 

      Try it in Swagger

DELETE /v2/teams/{teamId}

      Deletes a team based on the provided unique identifier, teamId. Returns an empty object.

      Try it in Swagger

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

Try it in Swagger

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}

Try it in Swagger

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

Try it in Swagger

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

Try it in Swagger

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}

Try it in Swagger

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

Try it in Swagger

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}

Try it in Swagger

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

Product documentation

People & Teams

Was this page helpful?
Yes No