Tags

Ein Tag kennzeichnet Termine und Aufnahmen. Diese Endpunkte verwalten den Tag-Katalog eines Unternehmenskontos und listen die Farben, die ein Tag haben kann.

Jeder Endpunkt unten zeigt in der Mitte seine Parameter und Antwortfelder und rechts ein Anfragebeispiel mit Beispielantwort.

Basis-URL https://api.sally.ioVersion v1.0 aktuell, noch nicht eingefrorenSo funktioniert die Versionierung

Listet den Tag-Katalog eines Unternehmenskontos auf (meistgenutzte zuerst)

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

Gibt alle aktiven Tags des Unternehmenskontos zurück, meistgenutzte zuerst.

Feldübersicht aus der Spezifikation

Felder der Antwort:

items (array): die Tags im Katalog. Jeder Eintrag enthält:
- tagId (string): Id des Tags.
- name (string): Anzeigename des Tags.
- colorCode (string | null): ein Farbschlüssel aus der Sally-Tag-Palette (ein Farbname wie blue/red/green, kein roher Hex-Wert; vollständige Liste im Schema); null, wenn nicht gesetzt.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.

Query-Parameter

fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: colorCode, name, tagId.
Beispiel: colorCode,name

Antwort

itemsobject[]Pflicht
Die Tags im Katalog.
3 Unterfelder
- tagIdstringPflicht
  Id des Tags.
- namestringPflicht
  Anzeigename des Tags.
- colorCodestringPflichtkann null sein
  Farbe des Tags als Schlüssel aus Sallys fester Tag-Palette: ein Farb-NAME, kein roher Hex-Wert. Einer von: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. Der Client ordnet den Schlüssel der tatsächlichen Farbe (hell/dunkel) zu; null oder ein unbekannter Schlüssel wird in der neutralen Standardfarbe dargestellt. Null, wenn nicht gesetzt.

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Anfrage

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()

Beispielantwort 200 OK

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

Erstellt einen Katalog-Tag mit optionaler Farbe (nur Admin/Owner)

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

Namen werden ohne Beachtung der Groß- und Kleinschreibung dedupliziert.

Feldübersicht aus der Spezifikation

Body-Felder:

name (string, Pflicht): Anzeigename des Tags (max. 100 Zeichen).
colorCode (string, optional): ein Farbschlüssel aus der Sally-Tag-Palette (ein Farbname wie blue/red/green, kein roher Hex-Wert; vollständige Liste im Schema); null zum Entfernen.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.

Query-Parameter

fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: colorCode, name, tagId.
Beispiel: colorCode,name

Request-Body application/json

namestringPflicht
Anzeigename des Tags (max. 100 Zeichen).
colorCodestringoptionalkann null sein
Farbe des Tags als Schlüssel aus der festen Tag-Palette von Sally, also ein Farb-NAME, kein roher Hex-Wert. Einer von: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. Ein unbekannter Schlüssel wird in der neutralen Standardfarbe dargestellt; null entfernt die Farbe.

Antwort

tagIdstringPflicht
Id des Tags.
namestringPflicht
Anzeigename des Tags.
colorCodestringPflichtkann null sein
Farbe des Tags als Schlüssel aus Sallys fester Tag-Palette: ein Farb-NAME, kein roher Hex-Wert. Einer von: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. Der Client ordnet den Schlüssel der tatsächlichen Farbe (hell/dunkel) zu; null oder ein unbekannter Schlüssel wird in der neutralen Standardfarbe dargestellt. Null, wenn nicht gesetzt.

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
403
Verboten (unzureichende Berechtigungen).
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Anfrage

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()

Beispielantwort 200 OK

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

Listet die verfügbaren Tag-Farben auf

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

Gibt die feste Menge an Farbschlüsseln zurück, die der colorCode eines Tags annehmen kann, also einen Farb-NAMEN, keinen rohen Hex-Wert. Der Client ordnet jedem Schlüssel die tatsächliche (vom Theme abhängige) Farbe zu; ein unbekannter Schlüssel oder null wird in der neutralen Standardfarbe dargestellt.

Feldübersicht aus der Spezifikation

Jeder Eintrag enthält:

colorCode (string): ein gültiger Tag-Farbschlüssel (z. B. blue, red, green).

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.

Query-Parameter

fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: colorCode.
Beispiel: colorCode

Antwort

colorCodestringPflicht
Ein gültiger Tag-Farbschlüssel: ein Farb-NAME (kein Hex-Wert), der dem colorCode eines Tags zugewiesen werden kann (z. B. blue, red, green).

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Anfrage

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()

Beispielantwort 200 OK

[
  {
    "colorCode": "indigo"
  }
]

Benennt einen Katalog-Tag um und/oder ändert seine Farbe (nur Admin/Owner)

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

Sende name zum Umbenennen und/oder colorCode zum Ändern der Farbe; mindestens eines davon ist Pflicht.

Feldübersicht aus der Spezifikation

Body-Felder:

name (string, optional): neuer Anzeigename des Tags (max. 100 Zeichen).
colorCode (string, optional): ein Farbschlüssel aus der Sally-Tag-Palette (ein Farbname wie blue/red/green, kein roher Hex-Wert; vollständige Liste im Schema); null entfernt die Farbe.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.
tagIdstringPflicht
Id des Tags.

Query-Parameter

fieldsstringoptional
Kommagetrennte Liste der Felder, die zurückgegeben werden sollen. Lässt du den Parameter weg, bekommst du alle Felder, auch solche, die in Zukunft hinzukommen. Das ist deine Entscheidung: Nenne deine Felder explizit, wenn du davor geschützt sein willst.
Nur Felder der ersten Ebene können angegeben werden. Eine verschachtelte Liste wie attendees, tags oder sectionItems wird ganz oder gar nicht zurückgegeben; attendees.name wird nicht unterstützt.
Bei einer paginierten Antwort gilt die Auswahl für die Einträge in items; page, pageSize, total und hasMore werden immer zurückgegeben. Ein unbekannter Name wird mit 400 abgelehnt statt ignoriert.
Hier auswählbar: colorCode, name, tagId.
Beispiel: colorCode,name

Request-Body application/json

namestringPflicht
Anzeigename des Tags (max. 100 Zeichen).
colorCodestringoptionalkann null sein
Farbe des Tags als Schlüssel aus der festen Tag-Palette von Sally, also ein Farb-NAME, kein roher Hex-Wert. Einer von: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. Ein unbekannter Schlüssel wird in der neutralen Standardfarbe dargestellt; null entfernt die Farbe.

Antwort

tagIdstringPflicht
Id des Tags.
namestringPflicht
Anzeigename des Tags.
colorCodestringPflichtkann null sein
Farbe des Tags als Schlüssel aus Sallys fester Tag-Palette: ein Farb-NAME, kein roher Hex-Wert. Einer von: indigo, purple, fuchsia, pink, rose, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, slate, gray, zinc, stone, neutral. Der Client ordnet den Schlüssel der tatsächlichen Farbe (hell/dunkel) zu; null oder ein unbekannter Schlüssel wird in der neutralen Standardfarbe dargestellt. Null, wenn nicht gesetzt.

Statuscodes

200Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
403
Verboten (unzureichende Berechtigungen).
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Anfrage

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()

Beispielantwort 200 OK

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

Löscht einen Katalog-Tag (nur Admin/Owner)

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

Löscht den Tag weich (Soft Delete) und entfernt ihn von allen Terminen und Aufnahmen.

Pfadparameter

directoryIdstringPflicht
Id des Unternehmenskontos (des Sally-Firmenkontos), zu dem die Ressource gehört. Die Unternehmenskonten, die ein Token ansprechen kann, listet GET /v1.0/me/directories/memberships auf.
tagIdstringPflicht
Id des Tags.

Statuscodes

204Erfolg
400
Ungültige Anfrage (Validierungsfehler).
401
Fehlender oder ungültiger Bearer-Token.
403
Verboten (unzureichende Berechtigungen).
404
Ressource nicht gefunden oder nicht zugänglich.
429
Rate-Limit überschritten (pro Token/IP). Transkriptions-Uploads können außerdem den code FUP_LIMIT_EXCEEDED oder TOO_MANY_CONCURRENT_TRANSCRIPTIONS zurückgeben.
500
Interner Serverfehler.

Anfrage

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

Beispielantwort 204 No Content

Kein Inhalt. Ein erfolgreicher Aufruf liefert einen leeren Body.

Listet den Tag-Katalog eines Unternehmenskontos auf (meistgenutzte zuerst)​

Pfadparameter

Query-Parameter

Antwort

Statuscodes

Erstellt einen Katalog-Tag mit optionaler Farbe (nur Admin/Owner)​

Pfadparameter

Query-Parameter

Request-Body application/json

Antwort

Statuscodes

Listet die verfügbaren Tag-Farben auf​

Pfadparameter

Query-Parameter

Antwort

Statuscodes

Benennt einen Katalog-Tag um und/oder ändert seine Farbe (nur Admin/Owner)​

Pfadparameter

Query-Parameter

Request-Body application/json

Antwort

Statuscodes

Löscht einen Katalog-Tag (nur Admin/Owner)​

Pfadparameter

Statuscodes

Listet den Tag-Katalog eines Unternehmenskontos auf (meistgenutzte zuerst)

Erstellt einen Katalog-Tag mit optionaler Farbe (nur Admin/Owner)

Listet die verfügbaren Tag-Farben auf

Benennt einen Katalog-Tag um und/oder ändert seine Farbe (nur Admin/Owner)

Löscht einen Katalog-Tag (nur Admin/Owner)