Tags

A tag labels appointments and recordings. These endpoints manage the tag catalog of a company account and list the colors a tag can have.

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 tag catalog of a directory (most-used first)

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

Returns all active tags of the directory, most-used first.

Field overview from the specification

Response fields:

items (array): the tags in the catalog. Each item has:
- tagId (string): id of the tag.
- name (string): tag display name.
- colorCode (string | null): a colour key from the Sally tag palette (a colour name like blue/red/green, not a raw hex value; full list in the schema); null if unset.

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: colorCode, name, tagId.
Example: colorCode,name

Response

itemsobject[]required
The tags in the catalog.
3 child fields
- tagIdstringrequired
  Id of the tag.
- namestringrequired
  Tag display name.
- colorCodestringrequirednullable
  Colour of the tag as a key from Sally's fixed tag palette — a colour NAME, not a raw hex value. One of: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. The client maps the key to the actual (light/dark) colour; null or an unknown key renders in the neutral default colour. Null if unset.

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
JavaScript
Python

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

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

import os
import requests

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

Response example 200 OK

{
  "items": [
    {
      "tagId": "18063a7e-a82b-4972-a850-f866b8b4a046",
      "name": "Customer",
      "colorCode": "indigo"
    }
  ]
}

Creates a catalog tag with an optional colour (admin/owner only)

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

Names are deduplicated case-insensitively.

Field overview from the specification

Body fields:

name (string, required): tag display name (max. 100 characters).
colorCode (string, optional): a colour key from the Sally tag palette (a colour name like blue/red/green, not a raw hex value; full list in the schema); null to clear.

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: colorCode, name, tagId.
Example: colorCode,name

Request body application/json

namestringrequired
Tag display name (max. 100 characters).
colorCodestringoptionalnullable
Colour of the tag as a key from Sally's fixed tag palette — a colour NAME, not a raw hex value. One of: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. An unknown key renders in the neutral default colour; null to clear the colour.

Response

tagIdstringrequired
Id of the tag.
namestringrequired
Tag display name.
colorCodestringrequirednullable
Colour of the tag as a key from Sally's fixed tag palette — a colour NAME, not a raw hex value. One of: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. The client maps the key to the actual (light/dark) colour; null or an unknown key renders in the neutral default colour. Null if unset.

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
JavaScript
Python

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

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

import os
import requests

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

Response example 200 OK

{
  "tagId": "18063a7e-a82b-4972-a850-f866b8b4a046",
  "name": "Customer",
  "colorCode": "indigo"
}

Lists the available tag colours

GET/v1.0/directories/{directoryId}/tags/colors

Returns the fixed set of colour keys a tag's colorCode can take — a colour NAME, not a raw hex value. The client maps each key to the actual (theme-aware) colour; an unknown key or null renders in the neutral default colour.

Field overview from the specification

Each item has:

colorCode (string): a valid tag colour key (e.g. blue, red, green).

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: colorCode.
Example: colorCode

Response

colorCodestringrequired
A valid tag colour key — a colour NAME (not a hex value) that can be assigned to a tag's colorCode (e.g. blue, red, green).

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
JavaScript
Python

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

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

import os
import requests

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

Response example 200 OK

[
  {
    "colorCode": "indigo"
  }
]

Renames a catalog tag and/or changes its colour (admin/owner only)

PATCH/v1.0/directories/{directoryId}/tags/{tagId}

Send name to rename and/or colorCode to recolour; at least one is required.

Field overview from the specification

Body fields:

name (string, optional): new tag display name (max. 100 characters).
colorCode (string, optional): a colour key from the Sally tag palette (a colour name like blue/red/green, not a raw hex value; full list in the schema); null clears the colour.

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.
tagIdstringrequired
Id of the tag.

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: colorCode, name, tagId.
Example: colorCode,name

Request body application/json

namestringrequired
Tag display name (max. 100 characters).
colorCodestringoptionalnullable
Colour of the tag as a key from Sally's fixed tag palette — a colour NAME, not a raw hex value. One of: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. An unknown key renders in the neutral default colour; null to clear the colour.

Response

tagIdstringrequired
Id of the tag.
namestringrequired
Tag display name.
colorCodestringrequirednullable
Colour of the tag as a key from Sally's fixed tag palette — a colour NAME, not a raw hex value. One of: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. The client maps the key to the actual (light/dark) colour; null or an unknown key renders in the neutral default colour. Null if unset.

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
JavaScript
Python

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

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

import os
import requests

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

Response example 200 OK

{
  "tagId": "18063a7e-a82b-4972-a850-f866b8b4a046",
  "name": "Customer",
  "colorCode": "indigo"
}

Deletes a catalog tag (admin/owner only)

DELETE/v1.0/directories/{directoryId}/tags/{tagId}

Soft-deletes the tag and removes it from all appointments and recordings.

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.
tagIdstringrequired
Id of the tag.

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
JavaScript
Python

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

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

import os
import requests

response = requests.delete(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tags/{tag_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 tag catalog of a directory (most-used first)​

Path parameters

Query parameters

Response

Status codes

Creates a catalog tag with an optional colour (admin/owner only)​

Path parameters

Query parameters

Request body application/json

Response

Status codes

Lists the available tag colours​

Path parameters

Query parameters

Response

Status codes

Renames a catalog tag and/or changes its colour (admin/owner only)​

Path parameters

Query parameters

Request body application/json

Response

Status codes

Deletes a catalog tag (admin/owner only)​

Path parameters

Status codes

Lists the tag catalog of a directory (most-used first)

Creates a catalog tag with an optional colour (admin/owner only)

Lists the available tag colours

Renames a catalog tag and/or changes its colour (admin/owner only)

Deletes a catalog tag (admin/owner only)