novauth
PreiseDokumentationKostenlos starten
Referenz

API-Referenz

Vollständige Referenz aller Novauth-Verifizierungsendpunkte. Jeder Kanal nutzt dasselbe Authentifizierungsmodell und dieselbe Basis-URL – nur Pfad und Payload unterscheiden sich.

BASE URLhttps://api.novauth.com/api/v1/connect-hub

Authentifizierung

Jede Anfrage muss zwei Header enthalten. Deine Zugangsdaten findest du im Bereich Entwickler → API-Schlüssel des Dashboards. Zugangsdaten werden serverseitig 5 Minuten lang gecacht, neu erstellte Schlüssel sind also innerhalb von Sekunden aktiv.

x-api-keyDein API-Schlüssel. Behandle ihn wie ein Passwort – gib ihn niemals in clientseitigem Code preis.
x-account-idDeine Konto-Kennung. Im Dashboard neben jedem API-Schlüssel angezeigt.
x-request-idOptionale Korrelations-ID. Übergib eine beliebige UUID; wird in Fehlerantworten zur Nachverfolgung zurückgegeben.

Speichere Zugangsdaten in Umgebungsvariablen (BETATEL_API_KEY, BETATEL_ACCOUNT_ID). Hardcode sie niemals in Quelldateien.

Schlüssel mit dem Präfix sk_test_ sind Sandbox-Schlüssel – sie berühren keine echten Carrier und verursachen keine Kosten. Verwende sie während der Entwicklung und tausche sie gegen deinen BTEL_-Schlüssel aus, wenn du live gehst. Sandbox-Modus →

IP-Whitelisting

Beim Erstellen eines API-Schlüssels kannst du optional eine oder mehrere IP-Adressen oder CIDR-Bereiche angeben. Wenn eine IP-Whitelist konfiguriert ist, wird jede Anfrage von einer IP außerhalb der Liste mit 401 Unauthorized abgelehnt, auch wenn der API-Schlüssel selbst gültig ist. Damit kannst du einen Schlüssel an die IP deines Servers binden, sodass er bei einem Leak nicht missbraucht werden kann.

Beispiel einer authentifizierten Anfrage
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"callee": "+14155552671"}'

Verify Call

Leitet einen kurzlebigen Klingel-und-Auflege-Anruf ein. Die Anrufer-ID kodiert den OTP – dein mobiles SDK liest die eingehende Nummer, ohne dass der Nutzer abnehmen muss.

Verify Call senden
POST/api/v1/connect-hub/call/flash
Request-Body
calleestringerforderlich
Empfängertelefon im E.164-Format (z. B. +14155552671).
callerstring
Anrufer-ID im E.164-Format. Standardmäßig die konfigurierte Nummer des Kontos.
max_ring_timenumber
Klingeldauer in Sekunden vor dem automatischen Auflegen. Standardmäßig ein Zufallswert zwischen den minimalen/maximalen Klingelzeiten des Kontos.
Antwort — 200 OK
uuidstring (ULID)
Eindeutige Anrufkennung. Speichere diese – wird für CDR-Abruf und Webhook-Reporting benötigt.
callerstring
Tatsächlich verwendete Anrufer-ID (kann von der Anfrage abweichen, falls ein Standardwert genutzt wurde).
calleestring
Empfängernummer (Echo).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "callee": "+14155552671",
    "caller": "+38761000001",
    "max_ring_time": 5
  }'

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "caller": "+38761000001",
#   "callee": "+14155552671"
# }
Call Detail Record abrufen
GET/api/v1/connect-hub/call/flash/:uuid/cdr
Antwort — 200 OK
hangup_causestring
SIP-Auflegegrund (z. B. NORMAL_CLEARING, NO_ANSWER, ORIGINATOR_CANCEL).
durationnumber
Gesamte Anrufdauer in Sekunden (Klingeln + Verbunden).
billsecnumber
Abgerechnete Dauer in Sekunden (Abnehmen bis Auflegen).
pddnumber
Post-Dial-Verzögerung in Sekunden (Zeit bis zum ersten Klingeln).
destination_countrystring
Aufgelöster Name des Ziellandes.
start_stampstring (ISO 8601)
UTC-Zeitstempel des Anrufbeginns.
bash
curl https://api.novauth.com/api/v1/connect-hub/call/flash/01KAK9KATW01A437PSXS5EVDCR/cdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "caller": "+38761000001",
#   "callee": "+14155552671",
#   "hangup_cause": "NORMAL_CLEARING",
#   "duration": 6,
#   "billsec": 0,
#   "pdd": 2,
#   "start_stamp": "2024-06-01T10:30:00.000Z",
#   "destination_country": "United States",
#   "destination_country_code": "US"
# }
Anrufdatensätze auflisten
POST/api/v1/connect-hub/call/flash/cdr

Gibt eine paginierte Liste aller Anrufe deines Kontos zurück. Verwende filter, um Ergebnisse nach beliebigen CDR-Feldern einzuschränken (z. B. callee, hangup_cause).

Request-Body
pagenumber
Seitenzahl (min: 1, Standard: 1).
rows_per_pagenumber
Datensätze pro Seite (1–100, Standard: 20).
sort_bystring
Feld zum Sortieren (z. B. start_stamp, callee).
sort_direction"ASC" | "DESC"
Sortierreihenfolge.
filterobject
Optionale Schlüssel/Wert-Filter auf CDR-Felder angewendet.
Antwort — 200 OK
totalnumber
Gesamtzahl der dem Filter entsprechenden Datensätze.
total_pagesnumber
Gesamtzahl der Seiten.
has_next_pageboolean
Ob eine nächste Seite vorhanden ist.
has_previous_pageboolean
Ob eine vorherige Seite vorhanden ist.
listCDR[]
Array der Call-Detail-Records der aktuellen Seite.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/call/flash/cdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_by": "start_stamp",
    "sort_direction": "DESC"
  }'
Anruf beenden
DELETE/api/v1/connect-hub/call/flash/:uuid

Beendet einen aktiven Anruf vor dem natürlichen Ende. Gibt bei Erfolg 204 No Content zurück.

bash
# Terminate an active call before it naturally ends
curl -X DELETE https://api.novauth.com/api/v1/connect-hub/call/flash/01KAK9KATW01A437PSXS5EVDCR \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Returns 204 No Content on success

SMS

Stellt eine Textnachricht über SMPP zu. Wird typischerweise verwendet, um einen numerischen OTP-Code zu senden, den der Nutzer in deine App eingibt.

SMS senden
POST/api/v1/connect-hub/sms
Request-Body
tostringerforderlich
Empfängertelefon im E.164-Format.
textstringerforderlich
Nachrichtentext. Bis zu 4096 Zeichen; längere Nachrichten werden in verkettete Teile aufgeteilt.
fromstring
Absender-ID (alphanumerisch oder Telefonnummer). Standardmäßig der konfigurierte Absender des Kontos.
Antwort — 200 OK
messageIdstring (UUID)
Eindeutige Nachrichtenkennung. Speichere diese – wird für SDR-Abruf und Webhook-Reporting benötigt.
fromstring
Verwendete Absender-ID.
tostring
Empfängernummer (Echo).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/sms \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "text": "Your verification code is 482910. Valid for 5 minutes.",
    "from": "Novauth"
  }'

# Response:
# {
#   "messageId": "0a62face-6d15-11f0-962f-d89d6729654c",
#   "from": "Novauth",
#   "to": "14155552671"
# }
Nachrichtenstatus abrufen
GET/api/v1/connect-hub/sms/:messageId/sdr

Ruft den Zustellstatus einer gesendeten Nachricht ab. Der Status wird asynchron aktualisiert, sobald Carrier-Zustellberichte (DLRs) eintreffen.

Antwort — Statuswerte
deliveredBestätigte Zustellung an das Endgerät.
sentAn den Carrier weitergeleitet; warte auf DLR.
failedZustellung fehlgeschlagen (ungültige Nummer, gesperrt).
undeliveredCarrier hat akzeptiert, aber Zustellung nicht bestätigt.
bash
curl https://api.novauth.com/api/v1/connect-hub/sms/0a62face-6d15-11f0-962f-d89d6729654c/sdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "...",
#   "messageId": "0a62face-6d15-11f0-962f-d89d6729654c",
#   "from": "Novauth",
#   "to": "+14155552671",
#   "status": "delivered",
#   "timestamp": "2024-06-01T10:30:00.000Z"
# }
Nachrichten auflisten
POST/api/v1/connect-hub/sms/sdr

Gibt eine paginierte Liste aller gesendeten Nachrichten zurück. Akzeptiert denselben Paginierungs-Body wie andere Listen-Endpunkte (page, rows_per_page, sort_by, filter).

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/sms/sdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

Telegram-OTP

Sendet einen numerischen OTP über das offizielle Gateway API von Telegram. Unterstützt Erreichbarkeitsprüfungen, serverseitige Code-Validierung und Widerruf mit automatischer Rückerstattung.

Telegram-OTP senden
POST/api/v1/connect-hub/telegram
Request-Body
tostringerforderlich
Empfängertelefon im E.164-Format.
codestringerforderlich
Zu übermittelnder OTP-Code (4–8 Ziffern).
ttlnumber
Code-Gültigkeit in Sekunden (30–3600). Standard: 300.
sender_usernamestring
Verifizierter Telegram-Kanalname. Weglassen, um den Kontostandard zu verwenden.
callback_urlstring
Anfragespezifische Webhook-Überschreibung. Das Telegram Gateway sendet Statusereignisse per POST direkt an diese URL.
Antwort — 200 OK
uuidstring (ULID)
Novauth-Korrelations-ID. Für Webhook-Reporting verwenden.
request_idstring
Telegram-Gateway-Anfrage-ID. Für Statusabfragen und Widerruf verwenden.
statusstring
Normalisierter Zustellstatus (sent, delivered, …).
request_costnumber
Gebühr für diese Anfrage in EUR.
remaining_balancenumber
Kontoguthaben nach der Gebühr.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "code": "482910",
    "ttl": 300
  }'

# Response:
# {
#   "uuid": "01KNV9CWW9ZEYVDFBJ1N7M1DVR",
#   "request_id": "tg_req_abc123",
#   "to": "14155552671",
#   "status": "sent",
#   "request_cost": 0.05,
#   "remaining_balance": 49.95
# }
Erreichbarkeit prüfen
POST/api/v1/connect-hub/telegram/check-send-ability

Prüft, ob die Nummer ein Telegram-Konto hat, bevor gesendet wird. Wenn is_refunded true ist, hat der Nutzer kein Telegram-Konto – die Prüfgebühr wird erstattet und du solltest auf SMS oder Verify Call zurückfallen.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-send-ability \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155552671"}'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "phone_number": "14155552671",
#   "request_cost": 0.01,
#   "is_refunded": false,
#   "remaining_balance": 49.99,
#   "delivery_status": { "status": "sent", "updated_at": 1713350400 }
# }
Verifizierungsstatus prüfen
POST/api/v1/connect-hub/telegram/check-verification-status

Fragt das Code-Eingabe-Ergebnis für eine bestimmte request_id ab. Übergib optional den vom Nutzer eingegebenen code zur serverseitigen Validierung.

verification_status-Werte
code_validNutzer hat den richtigen Code eingegeben.
code_invalidNutzer hat einen falschen Code eingegeben.
code_max_attempts_exceededZu viele fehlgeschlagene Versuche.
expiredCode-TTL abgelaufen, bevor er eingegeben wurde.
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/check-verification-status \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "tg_req_abc123",
    "code": "482910"
  }'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "verification_status": {
#     "status": "code_valid",
#     "updated_at": 1713350400
#   }
# }
Verifizierung widerrufen
POST/api/v1/connect-hub/telegram/revoke-verification

Bricht eine aktive OTP-Anfrage ab, bevor der Nutzer sie abschließt. Wenn die Nachricht noch nicht gelesen wurde, ist is_refunded true und die Gebühr wird deinem Guthaben gutgeschrieben.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/revoke-verification \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "tg_req_abc123"}'

# Response:
# {
#   "request_id": "tg_req_abc123",
#   "is_refunded": true,
#   "remaining_balance": 50.0
# }
Zustelldatensatz abrufen
GET/api/v1/connect-hub/telegram/:uuid/tdr

Ruft den vollständigen Telegram-Zustelldatensatz für eine bestimmte uuid ab (die Novauth-Korrelations-ID, die vom Sende-Endpunkt zurückgegeben wird). Enthält Zustellstatus, Verifizierungsstatus, Kosten und Land.

bash
curl https://api.novauth.com/api/v1/connect-hub/telegram/01KNV9CWW9ZEYVDFBJ1N7M1DVR/tdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response includes full TDR:
# {
#   "uuid": "01KNV9CWW9ZEYVDFBJ1N7M1DVR",
#   "to": "+14155552671",
#   "status": "DELIVERED",
#   "delivery_status": "delivered",
#   "verification_status": "code_valid",
#   "request_cost": 0.05,
#   "country": "United States",
#   "created_at": "2024-06-01T10:30:00.000Z"
# }
Zustelldatensätze auflisten
POST/api/v1/connect-hub/telegram/tdr

Gibt eine paginierte Liste aller Telegram-Zustelldatensätze zurück. Nach <code>verification_status</code>, <code>delivery_status</code> oder einem anderen TDR-Feld filtern.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/telegram/tdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

WhatsApp

Sendet eine OTP-Nachricht über die WhatsApp Business API. Der Nutzer liest den Code im WhatsApp-Gespräch und gibt ihn in deine App ein.

WhatsApp-OTP senden
POST/api/v1/connect-hub/whatsapp/otp
Request-Body
tostringerforderlich
Empfängertelefon im E.164-Format.
textstringerforderlich
Nachrichtentext. OTP-Code und Ablaufhinweis einbeziehen.
Antwort — 200 OK
uuidstring (ULID)
Eindeutige Nachrichtenkennung. Speichere diese – wird für Webhook-Reporting benötigt.
tostring
Empfängernummer (Echo).
bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/otp \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "text": "Your verification code is 482910. Valid for 5 minutes."
  }'

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "to": "+14155552671"
# }

Melde das Verifizierungsergebnis des Nutzers nach dem Senden über POST /whatsapp/webhook. Details findest du in der Webhooks-Referenz.

Zustelldatensatz abrufen
GET/api/v1/connect-hub/whatsapp/:uuid/wdr

Ruft den WhatsApp-Zustelldatensatz für eine bestimmte uuid ab, die vom Sende-Endpunkt zurückgegeben wurde.

bash
curl https://api.novauth.com/api/v1/connect-hub/whatsapp/01KAK9KATW01A437PSXS5EVDCR/wdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID"

# Response:
# {
#   "uuid": "01KAK9KATW01A437PSXS5EVDCR",
#   "to": "+14155552671",
#   "status": "DELIVERED",
#   "created_at": "2024-06-01T10:30:00.000Z"
# }
Zustelldatensätze auflisten
POST/api/v1/connect-hub/whatsapp/wdr

Gibt eine paginierte Liste aller WhatsApp-Zustelldatensätze zurück. Unterstützt denselben <code>page</code>-, <code>rows_per_page</code>-, <code>filter</code>-Body wie alle anderen Listen-Endpunkte.

bash
curl -X POST https://api.novauth.com/api/v1/connect-hub/whatsapp/wdr \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-account-id: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "rows_per_page": 20,
    "sort_direction": "DESC"
  }'

Fehlercodes

Alle Fehlerantworten folgen demselben JSON-Envelope. Das Feld error enthält einen maschinenlesbaren String; gib deine x-request-id an den Support weiter, wenn du Probleme meldest.

StatusCodeBeschreibung
400BAD_REQUESTUngültiger Request-Body – fehlendes Pflichtfeld, falsches Format oder ungültige Telefonnummer.
401UNAUTHORIZEDFehlende oder ungültige x-api-key / x-account-id-Header.
402PAYMENT_REQUIREDUnzureichendes Kontoguthaben. Lade dein Konto auf, um fortzufahren.
403FORBIDDENAPI-Schlüssel vorhanden, aber ohne Berechtigung für diese Operation.
404NOT_FOUNDDie angeforderte UUID oder Ressource existiert nicht.
409CONFLICTDoppelte Anfrage oder widersprüchlicher Zustand (z. B. Widerruf einer bereits abgelaufenen Anfrage).
480TEMPORARY_UNAVAILABLEGateway vorübergehend nicht erreichbar. Mit exponentiellem Backoff erneut versuchen.
486BUSY_HERE(Verify Call) Empfänger ist besetzt oder der Anruf wurde vom Netzwerk abgelehnt.
500INTERNAL_SERVER_ERRORUnerwarteter Serverfehler. Kontaktiere den Support mit deiner x-request-id.
503SERVICE_UNAVAILABLEGateway getrennt oder Service in Wartung. Statusseite prüfen.
603DECLINE(Verify Call) Empfänger hat den Anruf explizit abgelehnt.

Eine vollständige Liste der Fehlercodes einschließlich empfohlener Behebungsschritte findest du im Fehlerbehandlungs-Leitfaden.