Zum Inhalt springen
Hilfe-Center
Support kontaktierenApp öffnen

Termine auflisten

GET
/v1/appointments
curl --request GET \
--url 'https://api.speakki.de/v1/appointments?status=planned' \
--header 'Authorization: Bearer <token>'

Termine aus dem Kalender der Organisation, nach Beginn aufsteigend. Mit from und to grenzen Sie den Zeitraum ein.

Berechtigung: appointments:read.

from
string format: date-time

Beginn ab diesem Zeitpunkt (einschließlich).

to
string format: date-time

Beginn vor diesem Zeitpunkt (ausschließlich).

status
string
Allowed values: planned done canceled

Nur Termine in diesem Status.

limit
integer
>= 1 <= 100

Termine je Seite, 1 bis 100, Standard 25.

cursor
string
>= 1 characters <= 200 characters

next_cursor der vorigen Seite.

Eine Seite Termine.

Media typeapplication/json

Eine Seite Termine, nach Beginn aufsteigend.

object
data
required

Die Einträge dieser Seite.

Array<object>

Ein Termin aus dem Kalender der Organisation.

object
id
required

ID des Termins.

string format: uuid
type
required

appointment Termin, callback_deadline Frist für einen Rückruf, other sonstiger Eintrag.

string
Allowed values: appointment callback_deadline other
status
required

planned geplant, done erledigt, canceled abgesagt.

string
Allowed values: planned done canceled
title
required

Titel des Termins.

string
customer_name
required

Name, auf den der Termin läuft.

string
description
required

Notiz zum Termin.

string | null
starts_at
required

Beginn des Termins.

string format: date-time
ends_at
required

Ende des Termins.

string format: date-time
service
required
Any of:
object
id
required

ID der Leistung.

string format: uuid
name
required

Name der Leistung.

string
party_size
required
Any of:
integer
contact_id
required
Any of:
string format: uuid
conversation_id
required
Any of:
string format: uuid
created_at
required

Angelegt am.

string format: date-time
updated_at
required

Zuletzt geändert am.

string format: date-time
next_cursor
required

Für die nächste Seite als cursor senden. null = keine weitere Seite.

string | null

Example

{
"data": [
{
"id": "e5b1d7a3-8c2f-4e6a-9d0b-3f7c1a5e8b42",
"type": "appointment",
"status": "planned",
"title": "Heizungswartung",
"customer_name": "Max Mustermann",
"description": null,
"starts_at": "2026-11-20T09:00:00.000Z",
"ends_at": "2026-11-20T10:00:00.000Z",
"service": {
"id": "f2c4a6e8-1b3d-4f5a-8c7e-0a9b2d4f6e83",
"name": "Wartung"
},
"party_size": null,
"contact_id": "a4d2c8e6-5f1b-4a3d-8c7e-9b0f2d4a6c81",
"conversation_id": "c1a7e3f9-2b4d-4c6e-9f8a-0d3b5e7a9c21",
"created_at": "2026-11-16T09:02:50.000Z",
"updated_at": "2026-11-16T09:02:50.000Z"
}
]
}

Ungültige Anfrage.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleinvalid_request
{
"error": {
"code": "invalid_request",
"message": "Die Anfrage ist ungültig."
}
}

API-Schlüssel fehlt oder ist ungültig.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleunauthorized
{
"error": {
"code": "unauthorized",
"message": "Der API-Schlüssel fehlt oder ist ungültig. Senden Sie ihn als „Authorization: Bearer spk_live_…“."
}
}

Nicht erlaubt: Tarif, Freischaltung oder Berechtigung des Schlüssels.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

{
"error": {
"code": "insufficient_scope",
"message": "Diesem API-Schlüssel fehlt die Berechtigung für diese Anfrage."
}
}

Zu viele Anfragen. retry-after und x-ratelimit-reset nennen die Sekunden, bis wieder Anfragen möglich sind.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Examplerate_limited
{
"error": {
"code": "rate_limited",
"message": "Zu viele Anfragen. Bitte versuchen Sie es gleich noch einmal."
}
}

Interner Fehler.

Media typeapplication/json

Einheitliches Fehlerformat aller Antworten unter /v1.

object
error
required

Der Fehler.

object
code
required

Fester Code für Programme. Neue Codes können dazukommen, bestehende ändern sich nicht.

string
Allowed values: unauthorized insufficient_scope invalid_request not_found conflict rate_limited internal_error plan_required access_not_approved billing_blocked assistant_not_found assistant_outbound_disabled from_number_missing from_number_not_allowed invalid_number country_not_allowed special_number own_number suppressed contact_blocked outside_call_hours daily_limit_reached number_called_today missing_variables
message
required

Meldung für Menschen, auf Deutsch.

string
details

Zusatz je Code, z. B. fields bei invalid_request oder missing_variables bei missing_variables.

object
key
additional properties

Examples

Exampleinternal_error
{
"error": {
"code": "internal_error",
"message": "Interner Fehler. Bitte versuchen Sie es später noch einmal."
}
}