API-Zugang und Tokens

Über die REST-API greifen deine eigenen Systeme auf novofon zu: Anrufe und Gesprächsverläufe auslesen, Agenten und Anrufrouten verwalten, Dokumente in die Wissensdatenbank laden. Die Authentifizierung läuft über API-Tokens, die an deine Organisation gebunden sind.

Diese Seite richtet sich an Entwickler. Die vollständige Referenz aller Endpunkte liegt als OpenAPI-Dokumentation unter /api/docs/ deiner API-Adresse.

Token anlegen

Öffne Benutzerverwaltung, Abschnitt API-Tokens am Ende der Seite. Nur Eigentümer und Administratoren sehen ihn.
Klicke auf API-Token erstellen.
Gib einen sprechenden Namen ein, etwa “Zapier-Integration”, und wähle unter Läuft ab nach 30, 90, 180 oder 365 Tage oder Nie. Voreingestellt sind 90 Tage.
Kopiere den Token sofort. Er wird aus Sicherheitsgründen nur einmal angezeigt.

Die Liste zeigt Name, Präfix, Erstellungsdatum, letzte Verwendung und Ablauf. Mit Widerrufen wird ein Token sofort ungültig, das lässt sich nicht rückgängig machen.

Abschnitt API-Tokens mit zwei Tokens in der Liste und dem Dialog API-Token erstellt mit Kopieren-Button

Anfragen authentifizieren

Schicke den Token in jedem Aufruf als Header, in einer der beiden Formen:

X-Api-Key: <dein-token>
Authorization: Api-Key <dein-token>

Ein Token kennt seine Organisation, du musst sie nicht zusätzlich angeben. Ein widerrufener Token antwortet mit “Invalid or revoked API key.”, ein abgelaufener mit “API key has expired.”

Ein API-Token hat die Rechte eines Administrators, mit Ausnahmen: Er kann keine Tokens, Benutzer oder Abrechnung verwalten und keine Telefonnummern kaufen.

Alternative: Anmeldung mit Benutzerkonto

Für Skripte, die als Benutzer handeln sollen, gibt es eine Anmeldung mit E-Mail und Passwort:

POST /api/auth/login/
{"email": "…", "password": "…"}

Die Antwort enthält ein Access-Token, drei Tage gültig, ein Refresh-Token, sieben Tage gültig, und die organization_id. Folgeanfragen tragen Authorization: Bearer <access> und X-Organization-ID: <organization_id>. Erneuern über POST /api/auth/token/refresh/. Für Integrationen sind API-Tokens die einfachere Wahl.

Beispiele

Alle Pfade beginnen mit /api/. $BASE ist die API-Adresse, $TOKEN dein Token.

Anrufe eines Zeitraums, seitenweise:

curl -H "X-Api-Key: $TOKEN" \
  "$BASE/api/telephony/calls/?start_date=2026-11-01T00:00:00Z&page=1&page_size=50"

Alle Agenten:

curl -H "X-Api-Key: $TOKEN" "$BASE/api/agents/agents/"

Ein Dokument in eine Wissensdatenbank laden:

curl -X POST -H "X-Api-Key: $TOKEN" \
  -F "title=Preisliste 2026" -F "knowledge_base=<kb-id>" -F "file=@preisliste.pdf" \
  "$BASE/api/knowledge-base/documents/"

Endpunkte für Integrationen

Bereich	Pfad
Agenten	`/api/agents/agents/`
Anrufe	`/api/telephony/calls/`, Einzelanruf unter `/api/telephony/calls/{id}/`. Filter: `caller_number`, `status`, `direction`, `agent`, `start_date`, `end_date`, `search`.
Gesprächsverläufe	`/api/conversations/`, Nachrichten unter `/api/conversations/{id}/messages/`
Telefonnummern, Anrufrouten, gesperrte Nummern	`/api/telephony/phone-numbers/`, `/api/telephony/call-routes/`, `/api/telephony/blocked-numbers/`
Wissensdatenbank	`/api/knowledge-base/`, Dokumente unter `/api/knowledge-base/documents/`
Kalender und Buchungen	`/api/calendars/calendars/`, `/api/calendars/bookings/`
SMS- und E-Mail-Vorlagen, Zustellprotokoll	`/api/communications/sms-templates/`, `/api/communications/email-templates/`, `/api/communications/delivery-logs/`

Funktionen der Premium Features, etwa Buchungen im Terminkalender oder FAQ-Einträge, setzen den passenden Tarif voraus und antworten sonst mit 403.

Seitenweiser Abruf, Fehler, Grenzen

Listen mit vielen Einträgen, etwa Anrufe, sind seitenweise: ?page= und ?page_size=, voreingestellt 20 pro Seite. Die Antwort hat die Felder count, next, previous und results. Kurze Listen wie Agenten kommen als einfaches Array.
Fehler kommen als JSON: {"detail": "…", "code": "…"} bei allgemeinen Fehlern, {"field_errors": {"feld": ["…"]}} bei ungültigen Eingaben.
Ein allgemeines Aufruflimit gibt es nicht. Die Anmeldung ist auf 30 Aufrufe pro Minute begrenzt.
Tokens inaktiver Organisationen funktionieren nicht mehr.