Teams

A team is a named group of users inside a company account. These endpoints create and change teams and manage who belongs to them.

Every endpoint below shows its parameters and response fields in the middle and a request sample with an example response on the right.

Base URL https://api.sally.ioVersion v1.0 current, not frozen yetHow versioning works

Lists the teams of a directory

GET/v1.0/directories/{directoryId}/teams

Field overview from the specification

Each item has:

• teamId (string): id of the team.
• name (string): team name.
• code (string | null): optional team code.
• isScimGroup (boolean): whether the team is synced from a SCIM identity provider.
• memberCount (number): number of active members.

Path parameters

• directoryIdstringrequired

  Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

Query parameters

• fieldsstringoptional

  Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.

  Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.

  On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.

  Selectable here: code, isScimGroup, memberCount, name, teamId.

  Example: code,isScimGroup

Response

• teamIdstringrequired

  Id of the team.

• namestringrequired

  Team name.

• codestringrequirednullable

  Optional team code.

• isScimGroupbooleanrequired

  Whether the team is synced from a SCIM identity provider.

• memberCountnumberrequired

  Number of active members.

Status codes

• 200Success
• 400

  Invalid request (validation error).

• 401

  Missing or invalid bearer token.

• 404

  Resource not found or not accessible.

• 429

  Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.

• 500

  Internal server error.

Request

cURL

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/teams" \
  -H "Authorization: Bearer $SALLY_TOKEN"

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/teams`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

Python

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/teams",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 200 OK

[
  {
    "teamId": "3c35d421-a578-4ce7-aebb-c5add21907bd",
    "name": "Sales",
    "code": "string",
    "isScimGroup": true,
    "memberCount": 3
  }
]

Creates a team

POST/v1.0/directories/{directoryId}/teams

Only admins/owners may create teams.

Field overview from the specification

Body fields:

• name (string, required): team name.
• code (string, optional): optional team code.

Path parameters

• directoryIdstringrequired

  Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

Query parameters

• fieldsstringoptional

  Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.

  Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.

  On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.

  Selectable here: code, isScimGroup, memberCount, name, teamId.

  Example: code,isScimGroup

Request body application/json

• namestringrequired

  Team name.

• codestringoptionalnullable

  Optional team code.

Response

• teamIdstringrequired

  Id of the team.

• namestringrequired

  Team name.

• codestringrequirednullable

  Optional team code.

• isScimGroupbooleanrequired

  Whether the team is synced from a SCIM identity provider.

• memberCountnumberrequired

  Number of active members.

Status codes

• 200Success
• 400

  Invalid request (validation error).

• 401

  Missing or invalid bearer token.

• 403

  Forbidden (insufficient permissions).

• 404

  Resource not found or not accessible.

• 429

  Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.

• 500

  Internal server error.

Request

cURL

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/teams" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Example"
}'

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/teams`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example"
  }),
});
const data = await response.json();

Python

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/teams",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "name": "Example",
    },
)
data = response.json()

Response example 200 OK

{
  "teamId": "3c35d421-a578-4ce7-aebb-c5add21907bd",
  "name": "Sales",
  "code": "string",
  "isScimGroup": true,
  "memberCount": 3
}

Updates a team (rename + optional code)

PATCH/v1.0/directories/{directoryId}/teams/{teamId}

Only admins/owners.

Field overview from the specification

Body fields:

• name (string, required): new team name.
• code (string, optional): new team code; null clears it, omit to leave unchanged.

Path parameters

• directoryIdstringrequired

  Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

• teamIdstringrequired

  Id of the team.

Query parameters

• fieldsstringoptional

  Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.

  Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.

  On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.

  Selectable here: code, isScimGroup, memberCount, name, teamId.

  Example: code,isScimGroup

Request body application/json

• namestringrequired

  New team name.

• codestringoptionalnullable

  New team code; null to clear, omit to leave unchanged.

Response

• teamIdstringrequired

  Id of the team.

• namestringrequired

  Team name.

• codestringrequirednullable

  Optional team code.

• isScimGroupbooleanrequired

  Whether the team is synced from a SCIM identity provider.

• memberCountnumberrequired

  Number of active members.

Status codes

• 200Success
• 400

  Invalid request (validation error).

• 401

  Missing or invalid bearer token.

• 403

  Forbidden (insufficient permissions).

• 404

  Resource not found or not accessible.

• 429

  Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.

• 500

  Internal server error.

Request

cURL

curl -X PATCH "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/teams/$TEAM_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Example"
}'

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/teams/${teamId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Example"
  }),
});
const data = await response.json();

Python

import os
import requests

response = requests.patch(
    f"https://api.sally.io/v1.0/directories/{directory_id}/teams/{team_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "name": "Example",
    },
)
data = response.json()

Response example 200 OK

{
  "teamId": "3c35d421-a578-4ce7-aebb-c5add21907bd",
  "name": "Sales",
  "code": "string",
  "isScimGroup": true,
  "memberCount": 3
}

Removes (archives) a team

DELETE/v1.0/directories/{directoryId}/teams/{teamId}

Soft-delete (archive) of the team and all its memberships. Only admins/owners.

Path parameters

• directoryIdstringrequired

  Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

• teamIdstringrequired

  Id of the team.

Status codes

• 204Success
• 400

  Invalid request (validation error).

• 401

  Missing or invalid bearer token.

• 403

  Forbidden (insufficient permissions).

• 404

  Resource not found or not accessible.

• 429

  Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.

• 500

  Internal server error.

Request

cURL

curl -X DELETE "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/teams/$TEAM_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN"

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/teams/${teamId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
console.log(response.status); // 204

Python

import os
import requests

response = requests.delete(
    f"https://api.sally.io/v1.0/directories/{directory_id}/teams/{team_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
print(response.status_code)  # 204

Response example 204 No Content

No content. A successful call returns an empty body.

Lists the memberships of a team

GET/v1.0/directories/{directoryId}/teams/{teamId}/memberships

Membership scalars only (userId, isMainTeam); fetch user details via GET .../teams/{teamId}/memberships/users/{userId}.

Field overview from the specification

Each item has:

• teamId (string): id of the team.
• userId (string): id of the member user.
• isMainTeam (boolean): whether this team is the user’s main team.

Path parameters

• directoryIdstringrequired

  Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

• teamIdstringrequired

  Id of the team.

Query parameters

• fieldsstringoptional

  Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.

  Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.

  On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.

  Selectable here: isMainTeam, teamId, userId.

  Example: isMainTeam,teamId

Response

• teamIdstringrequired

  Id of the team.

• userIdstringrequired

  Id of the member user.

• isMainTeambooleanrequired

  Whether this team is the user’s main team.

Status codes

• 200Success
• 400

  Invalid request (validation error).

• 401

  Missing or invalid bearer token.

• 404

  Resource not found or not accessible.

• 429

  Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.

• 500

  Internal server error.

Request

cURL

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/teams/$TEAM_ID/memberships" \
  -H "Authorization: Bearer $SALLY_TOKEN"

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/teams/${teamId}/memberships`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

Python

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/teams/{team_id}/memberships",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 200 OK

[
  {
    "teamId": "3c35d421-a578-4ce7-aebb-c5add21907bd",
    "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
    "isMainTeam": true
  }
]

Sets the members of a team (full replace-set)

PUT/v1.0/directories/{directoryId}/teams/{teamId}/memberships

Only admins/owners.

Field overview from the specification

Body fields:

• userIds (array of strings, required): full replace-set of member user ids. Users not in the list are removed.

Path parameters

• directoryIdstringrequired

  Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

• teamIdstringrequired

  Id of the team.

Query parameters

• fieldsstringoptional

  Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.

  Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.

  On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.

  Selectable here: isMainTeam, teamId, userId.

  Example: isMainTeam,teamId

Request body application/json

• userIdsstring[]required

  Full replace-set of member user ids. Users not in the list are removed.

Response

• teamIdstringrequired

  Id of the team.

• userIdstringrequired

  Id of the member user.

• isMainTeambooleanrequired

  Whether this team is the user’s main team.

Status codes

• 200Success
• 400

  Invalid request (validation error).

• 401

  Missing or invalid bearer token.

• 403

  Forbidden (insufficient permissions).

• 404

  Resource not found or not accessible.

• 429

  Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.

• 500

  Internal server error.

Request

cURL

curl -X PUT "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/teams/$TEAM_ID/memberships" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "userIds": [
    "11f967df-7dd1-4719-a9aa-46530940c443"
  ]
}'

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/teams/${teamId}/memberships`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "userIds": [
      "11f967df-7dd1-4719-a9aa-46530940c443"
    ]
  }),
});
const data = await response.json();

Python

import os
import requests

response = requests.put(
    f"https://api.sally.io/v1.0/directories/{directory_id}/teams/{team_id}/memberships",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "userIds": [
            "11f967df-7dd1-4719-a9aa-46530940c443",
        ],
    },
)
data = response.json()

Response example 200 OK

[
  {
    "teamId": "3c35d421-a578-4ce7-aebb-c5add21907bd",
    "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
    "isMainTeam": true
  }
]

Lists the users (members) of a team

GET/v1.0/directories/{directoryId}/teams/{teamId}/memberships/users

Field overview from the specification

Each item has:

• userId (string): id of the user.
• email (string): email address of the user.
• firstName (string): first name.
• lastName (string): last name.
• pictureFileUrl (string | null): absolute URL of the profile picture, or null. Requires the same Bearer token as the API.

Path parameters

• directoryIdstringrequired

  Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

• teamIdstringrequired

  Id of the team.

Query parameters

• fieldsstringoptional

  Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.

  Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.

  On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.

  Selectable here: email, firstName, lastName, pictureFileUrl, userId.

  Example: email,firstName

Response

• userIdstringrequired

  Id of the user.

• emailstringrequired

  Email address of the user.

• firstNamestringrequired

  First name.

• lastNamestringrequired

  Last name.

• pictureFileUrlstringrequirednullable

  Absolute URL of the profile picture, or null. Requires the same Bearer token as the API.

Status codes

• 200Success
• 400

  Invalid request (validation error).

• 401

  Missing or invalid bearer token.

• 404

  Resource not found or not accessible.

• 429

  Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.

• 500

  Internal server error.

Request

cURL

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/teams/$TEAM_ID/memberships/users" \
  -H "Authorization: Bearer $SALLY_TOKEN"

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/teams/${teamId}/memberships/users`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

Python

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/teams/{team_id}/memberships/users",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 200 OK

[
  {
    "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
    "email": "anna.berger@example.com",
    "firstName": "Anna",
    "lastName": "Berger",
    "pictureFileUrl": "https://example.com/hooks/sally"
  }
]

Returns a single user (member) of a team

GET/v1.0/directories/{directoryId}/teams/{teamId}/memberships/users/{userId}

The user must be a member of the team, otherwise 404.

Field overview from the specification

Response fields:

• userId (string): id of the user.
• email (string): email address of the user.
• firstName (string): first name.
• lastName (string): last name.
• pictureFileUrl (string | null): absolute URL of the profile picture, or null. Requires the same Bearer token as the API.

Path parameters

• directoryIdstringrequired

  Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

• teamIdstringrequired

  Id of the team.

• userIdstringrequired

  Id of the user.

Query parameters

• fieldsstringoptional

  Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.

  Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.

  On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.

  Selectable here: email, firstName, lastName, pictureFileUrl, userId.

  Example: email,firstName

Response

• userIdstringrequired

  Id of the user.

• emailstringrequired

  Email address of the user.

• firstNamestringrequired

  First name.

• lastNamestringrequired

  Last name.

• pictureFileUrlstringrequirednullable

  Absolute URL of the profile picture, or null. Requires the same Bearer token as the API.

Status codes

• 200Success
• 400

  Invalid request (validation error).

• 401

  Missing or invalid bearer token.

• 404

  Resource not found or not accessible.

• 429

  Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.

• 500

  Internal server error.

Request

cURL

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/teams/$TEAM_ID/memberships/users/$USER_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN"

JavaScript

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/teams/${teamId}/memberships/users/${userId}`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

Python

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/teams/{team_id}/memberships/users/{user_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 200 OK

{
  "userId": "11f967df-7dd1-4719-a9aa-46530940c443",
  "email": "anna.berger@example.com",
  "firstName": "Anna",
  "lastName": "Berger",
  "pictureFileUrl": "https://example.com/hooks/sally"
}