Vocabulary

The vocabulary holds terms that improve transcription, such as names and technical terms. These endpoints manage the vocabulary entries of a company account.

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 vocabulary entries of a directory

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

Returns all directory-wide entries plus the caller's own personal entries, sorted by phrase.

Field overview from the specification

Each item has:

vocabularyId (string): id of the vocabulary entry.
phrase (string): the term/phrase Sally should recognize preferentially.
manualReplacePhrases (string | null): alternative spellings/misrecognitions that get replaced with phrase in the transcript (comma-separated); null if none.
description (string | null): free-text note describing the entry (not used for recognition); null if unset.
languageCode (string | null): language the entry applies to, as an IETF language tag (e.g. de-DE, en-US); null = applies to all languages.
isDirectoryWide (boolean): scope — true = directory-wide (recognized for every member of the organization), false = personal (only the caller's own recordings).
createdOn (string): when the entry was created (UTC ISO-8601).
modifiedOn (string): when the entry was last changed (UTC ISO-8601).

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: createdOn, description, isDirectoryWide, languageCode, manualReplacePhrases, modifiedOn, phrase, vocabularyId.
Example: createdOn,description

Response

vocabularyIdstringrequired
Id of the vocabulary entry.
phrasestringrequired
The term/phrase Sally should recognize preferentially.
manualReplacePhrasesstringrequirednullable
Alternative spellings/misrecognitions that get replaced with phrase in the transcript (comma-separated); null if none.
descriptionstringrequirednullable
Free-text note describing the entry (not used for recognition); null if unset.
languageCodestringrequirednullable
Language the entry applies to, as an IETF language tag (e.g. de-DE, en-US); null = applies to all languages.
isDirectoryWidebooleanrequired
Scope: true = directory-wide (recognized for every member of the organization), false = personal (only the caller's own recordings).
createdOnstringrequired
When the entry was created (UTC ISO-8601).
modifiedOnstringrequired
When the entry was last changed (UTC ISO-8601).

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/vocabulary" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/vocabulary`, {
  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}/vocabulary",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 200 OK

[
  {
    "vocabularyId": "b10870ac-d73b-44b4-ad6d-b8bc0df4c37c",
    "phrase": "string",
    "manualReplacePhrases": "string",
    "description": "string",
    "languageCode": "de-DE",
    "isDirectoryWide": true,
    "createdOn": "2026-09-24T09:30:00Z",
    "modifiedOn": "2026-09-24T09:30:00Z"
  }
]

Creates a vocabulary entry

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

Personal entries are allowed for any member; directory-wide entries require admin/owner rights.

Field overview from the specification

Body fields:

phrase (string, required): the term/phrase to recognize (max. 400 characters).
manualReplacePhrases (string, optional): manual alternative spellings (max. 4000 characters); null to clear.
description (string, optional): free-text description/note (max. 4000 characters); null to clear.
languageCode (string, optional): language as an IETF language tag (e.g. de-DE); null/omitted for language-agnostic.
isDirectoryWide (boolean, optional, default false): false = personal to the caller, true = directory-wide (requires admin/owner rights).

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: createdOn, description, isDirectoryWide, languageCode, manualReplacePhrases, modifiedOn, phrase, vocabularyId.
Example: createdOn,description

Request body application/json

phrasestringrequired
The term/phrase Sally should recognize preferentially (max. 400 characters).
manualReplacePhrasesstringoptionalnullable
Alternative spellings/misrecognitions to replace with phrase (comma-separated, max. 4000 characters); null to clear.
descriptionstringoptionalnullable
Free-text note describing the entry, not used for recognition (max. 4000 characters); null to clear.
languageCodestringoptionalnullable
Language the entry applies to, as an IETF language tag (e.g. de-DE, en-US); null/omitted = applies to all languages.
isDirectoryWidebooleanoptional
Scope (default false): true = directory-wide (recognized for every member), false = personal (only the caller's own recordings). Directory-wide entries require admin/owner rights; personal entries are allowed for any member.

Response

vocabularyIdstringrequired
Id of the vocabulary entry.
phrasestringrequired
The term/phrase Sally should recognize preferentially.
manualReplacePhrasesstringrequirednullable
Alternative spellings/misrecognitions that get replaced with phrase in the transcript (comma-separated); null if none.
descriptionstringrequirednullable
Free-text note describing the entry (not used for recognition); null if unset.
languageCodestringrequirednullable
Language the entry applies to, as an IETF language tag (e.g. de-DE, en-US); null = applies to all languages.
isDirectoryWidebooleanrequired
Scope: true = directory-wide (recognized for every member of the organization), false = personal (only the caller's own recordings).
createdOnstringrequired
When the entry was created (UTC ISO-8601).
modifiedOnstringrequired
When the entry was last changed (UTC ISO-8601).

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/vocabulary" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "phrase": "string"
}'

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

import os
import requests

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

Response example 200 OK

{
  "vocabularyId": "b10870ac-d73b-44b4-ad6d-b8bc0df4c37c",
  "phrase": "string",
  "manualReplacePhrases": "string",
  "description": "string",
  "languageCode": "de-DE",
  "isDirectoryWide": true,
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Updates a vocabulary entry

PUT/v1.0/directories/{directoryId}/vocabulary/{vocabularyId}

Personal entries are allowed for any member; directory-wide entries require admin/owner rights.

Field overview from the specification

Body fields:

phrase (string, required): the term/phrase to recognize (max. 400 characters).
manualReplacePhrases (string, optional): manual alternative spellings (max. 4000 characters); null to clear.
description (string, optional): free-text description/note (max. 4000 characters); null to clear.
languageCode (string, optional): language as an IETF language tag (e.g. de-DE); null/omitted for language-agnostic.
isDirectoryWide (boolean, optional, default false): false = personal to the caller, true = directory-wide (requires admin/owner rights).

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.
vocabularyIdstringrequired
Id of the vocabulary.

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: createdOn, description, isDirectoryWide, languageCode, manualReplacePhrases, modifiedOn, phrase, vocabularyId.
Example: createdOn,description

Request body application/json

phrasestringrequired
The term/phrase Sally should recognize preferentially (max. 400 characters).
manualReplacePhrasesstringoptionalnullable
Alternative spellings/misrecognitions to replace with phrase (comma-separated, max. 4000 characters); null to clear.
descriptionstringoptionalnullable
Free-text note describing the entry, not used for recognition (max. 4000 characters); null to clear.
languageCodestringoptionalnullable
Language the entry applies to, as an IETF language tag (e.g. de-DE, en-US); null/omitted = applies to all languages.
isDirectoryWidebooleanoptional
Scope (default false): true = directory-wide (recognized for every member), false = personal (only the caller's own recordings). Directory-wide entries require admin/owner rights; personal entries are allowed for any member.

Response

vocabularyIdstringrequired
Id of the vocabulary entry.
phrasestringrequired
The term/phrase Sally should recognize preferentially.
manualReplacePhrasesstringrequirednullable
Alternative spellings/misrecognitions that get replaced with phrase in the transcript (comma-separated); null if none.
descriptionstringrequirednullable
Free-text note describing the entry (not used for recognition); null if unset.
languageCodestringrequirednullable
Language the entry applies to, as an IETF language tag (e.g. de-DE, en-US); null = applies to all languages.
isDirectoryWidebooleanrequired
Scope: true = directory-wide (recognized for every member of the organization), false = personal (only the caller's own recordings).
createdOnstringrequired
When the entry was created (UTC ISO-8601).
modifiedOnstringrequired
When the entry was last changed (UTC ISO-8601).

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 PUT "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/vocabulary/$VOCABULARY_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "phrase": "string"
}'

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

import os
import requests

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

Response example 200 OK

{
  "vocabularyId": "b10870ac-d73b-44b4-ad6d-b8bc0df4c37c",
  "phrase": "string",
  "manualReplacePhrases": "string",
  "description": "string",
  "languageCode": "de-DE",
  "isDirectoryWide": true,
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Deletes a vocabulary entry

DELETE/v1.0/directories/{directoryId}/vocabulary/{vocabularyId}

Soft-deletes the entry. Deleting a directory-wide entry requires admin/owner rights.

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.
vocabularyIdstringrequired
Id of the vocabulary.

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/vocabulary/$VOCABULARY_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/vocabulary/${vocabularyId}`, {
  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}/vocabulary/{vocabulary_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 vocabulary entries of a directory​

Path parameters

Query parameters

Response

Status codes

Creates a vocabulary entry​

Path parameters

Query parameters

Request body application/json

Response

Status codes

Updates a vocabulary entry​

Path parameters

Query parameters

Request body application/json

Response

Status codes

Deletes a vocabulary entry​

Path parameters

Status codes

Lists the vocabulary entries of a directory

Creates a vocabulary entry

Updates a vocabulary entry

Deletes a vocabulary entry