Managing Teams via the Compose API

The Compose API offers many ways to manage the Teams on your account. The main endpoints that allow team management on the account-level are:

/2016-07/teams
/2016-07/teams/:id
/2016-07/teams/:id/users

A full API reference can be found in the API Documentation.

List Teams

To get a list of the teams on your account, send a GET request to /2016-07/teams.

export API_TOKEN=your_apitoken_here
curl -X GET -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" "https://api.compose.io/2016-07/teams"

This will give you a list of all the teams and the users currently assigned to each team.

Create a New Team

To create a new team on your account, send a POST request to /2016-07/teams.

export API_TOKEN=your_apitoken_here
curl -X POST "https://api.compose.io/2016-07/teams" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{    
  "team": {
      "name" : "Billing"
    }
  }'

A new team will be created with the name you specify in the body parameter, and you will get back the name, id, and user list for the team. The user list should be empty.

Place/Replace Users on a Team

If you have a team that needs users, or a change in team composition, send a PUT request to /2016-07/teams/:team_id/users with the id of the team you wish to change and the body parameter the new user list for the team.

export API_TOKEN=your_apitoken_here
export TEAM_ID=your_team_id
curl -X PUT "https://api.compose.io/2016-07/teams/{$TEAM_ID}/users" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{    
  "user_ids": [
    "{newuserid1}",
    "{newuserid2}"
    ]}'

Two things to note:

• The new user list will replace the old team users. So if you need to add a user to an exsiting team with existing users, you will need to submit the list with the current users and the new user added to it.
• It is not possible to send in an empty list. If you need to remove all users from the team, delete the team entirely.
  The response will have the updated list of users on the team.

Get a Specific Team

Retrieve a list of users currently on a specific team by sending a GET request to /2016-07/teams/:team_id. You will need the id of the team.

export API_TOKEN=your_apitoken_here
export TEAM_ID=your_team_id
curl -X GET -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" "https://api.compose.io/2016-07/teams/${TEAM_ID}"

The response will contain all users on the team along with their ids.

Rename Team

To rename an existing team, send a PATCH request to the /2016-07/teams/:team_id endpoint. This only will update the team name, it will keep the user list and the id the same.

export API_TOKEN=your_apitoken_here
export TEAM_ID=your_team_id
curl -X PATCH "https://api.compose.io/2016-07/teams/{$TEAM_ID}" \
-H "Authorization: Bearer $API_TOKEN" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{    
  "team" : {
    "name": "Accountants"
    }
  }'

The response will show the team id, name, and the users on the team.

Delete Team

If you wish to remove a team from your account, send a DELETE request to /2016-07/teams/:team_id with the id of the team to delete. This will not remove users; any users on the team will remain associated with your account. Any roles given to the team will no longer be associated with the users unless those roles are given to the user elsewhere.

export API_TOKEN=your_apitoken_here
export TEAM_ID=your_team_id
curl -X DELETE -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" "https://api.compose.io/2016-07/teams/${TEAM_ID}"

The response will be the id and name of the deleted team and the user list.

Team Roles

Currently, there is no way to manage team roles on an account level via the Compose API. To manage the roles assigned to your teams, please use the Teams section of your Account in the Compose application. For more information please see the Compose Access Controls page.

Still Need Help?

If this article didn't solve things, summon a human and get some help!