Nummernbereitstellung & KYC

Vollständiger Lebenszyklus der Bereitstellung einer Telefonnummer: KYC-Dokumente, Dokumentensets, Nummernbestellungen, Zuweisung, Routing und Freigabe.

Dieses Dokument beschreibt den vollständigen Lebenszyklus der Bereitstellung einer Telefonnummer über die Audact-Plattform — vom Einreichen von Know-Your-Customer-Dokumenten (KYC) über die Auftragserteilung beim Carrier bis hin zur Verwaltung von Nummern im Pool.

Die Audact-Plattform verwaltet Nummern im Auftrag von Mandanten über den Carrier Telnyx. Nummern werden bestellt, gespeichert und Agenten über ein Self-Service-KYC-im-Namen-des-Mandanten-Modell zugewiesen: Der Mandant lädt behördliche Dokumente hoch (z. B. Handelsregistereintrag, Adressnachweis), Audact verschlüsselt diese im Ruhezustand und übermittelt sie zur Genehmigung an Telnyx. Nach der Genehmigung kann der Mandant Nummern für jede vom Dokumentenset abgedeckte Länder-/Typkombination bestellen. Die Abrechnung erfolgt über das Telnyx-Plattformkonto von Audact; Verbindungs- und Abrechnungseinstellungen werden automatisch von der Plattform konfiguriert und müssen vom Client nicht angegeben werden.

Der Prozess gliedert sich in fünf logische Schritte:

KYC-Dokumente — Dokumente hochladen, verschlüsseln und den Status der behördlichen Konformitätsdokumentation verfolgen
Dokumentensets — Dokumente zu Anforderungssets gruppieren, die gegen die regulatorischen Anforderungen von Telnyx abgeglichen werden
Nummernbestellungen — Bestellungen beim Carrier gegen genehmigte Sets aufgeben; DIDs in den Pool erhalten
Zuweisung & Routing — Nummern Agenten zuweisen und Sperren/Fortsetzen verwalten
Freigabe & Löschung — Nummern in den Pool zurückgeben oder dauerhaft löschen (und beim Carrier freigeben)

Schritt 1: KYC-Dokumente

POST /v1/kyc/documents — Ein Konformitätsdokument hochladen (z. B. Handelsregistereintrag, Adressnachweis).

Die Anfrage muss multipart/form-data sein mit:

document (Dateifeld, erforderlich) — die rohen Dokumentbytes (PDF, Bild usw.; max. 15 MiB pro Dokument)
doc_type (Formularfeld, erforderlich) — der Telnyx-Regulierungsanforderungstyp, den dieses Dokument erfüllt (z. B. "business_registration", "certificate_of_authority")
filename (Formularfeld, optional) — menschenlesbarer Dateiname; standardmäßig der Upload-Dateiname, falls nicht angegeben

Die Antwort enthält:

id (string) — eindeutige Dokument-UUID
doc_type (string) — der angegebene Typ
filename (string) — der Dateiname
content_type (string) — MIME-Typ (z. B. "application/pdf")
size_bytes (integer) — unkomprimierte Größe der Originaldatei
sha256 (string) — SHA-256-Prüfsumme der Originalbytes in Kleinbuchstaben; wird einmalig beim Upload berechnet und danach nicht verändert (zur Integritätsprüfung)
telnyx_document_id (string, nullable) — die von Telnyx zugewiesene ID, falls dieses Dokument an Telnyx übermittelt wurde
created_at (ISO-8601-Zeitstempel) — vom Server generierte Upload-Zeit
updated_at (ISO-8601-Zeitstempel) — Zeitpunkt der letzten Änderung

Wichtig: Dokumentbytes werden von der API NIEMALS zurückgegeben — nur Metadaten. Alle Dokumente werden im Ruhezustand unter dem KYC-Document-Encryption-Key (DEK) des Mandanten verschlüsselt, wobei die Verschlüsselung auf Mandant und Dokument-ID abgestimmt ist, sodass Chiffretexte nicht unter einer anderen Identität wiederverwandt werden können.

GET /v1/kyc/documents — Alle KYC-Dokumente des Mandanten auflisten.

Gibt eine paginierte Liste der Dokumentmetadaten zurück (alle Felder aus der POST-Antwort, ohne Datei-Bytes).

GET /v1/kyc/documents/{id} — Metadaten eines einzelnen Dokuments abrufen.

PUT /v1/kyc/documents/{id} — Ein Dokument ersetzen (z. B. eine korrigierte oder aktualisierte Version hochladen).

Der Anfrage-Body ist erneut multipart/form-data mit document und optional filename und doc_type. Ein Ersetzen bewirkt:

Erneute Verschlüsselung der neuen Bytes unter der aktuellen DEK-Version
Falls dieses Dokument ein bereits eingereichtes oder genehmigtes Dokumentenset stützt, wird das gesamte Set bei Telnyx erneut verifiziert (aktualisierte Metadaten werden an die Anforderungsgruppe übermittelt)
409 Conflict, wenn eine laufende Nummernbestellung derzeit auf dieses Dokumentenset verweist

DELETE /v1/kyc/documents/{id} — Ein Dokument löschen.

Gibt 409 Conflict zurück, wenn eine Nummernbestellung derzeit auf das Dokumentenset verweist, das dieses Dokument enthält (der Löschschutz verhindert das Verwaisen einer Bestellung). Andernfalls wird der Vorgang erfolgreich abgeschlossen und kaskadiert auf alle Dokumentensets, die dieses Dokument verwendet haben.

Schritt 2: Dokumentensets & Anforderungsabdeckung

GET /v1/kyc/requirements — Die aktuellen regulatorischen Anforderungen von Telnyx für ein Land und einen Nummerntyp abfragen.

Abfrageparameter:

country (erforderlich, 2-stelliges ISO-3166-1-Alpha-2-Kürzel, z. B. "US")
number_type (erforderlich, z. B. "local" oder "mobile")

Antwort:

json

{
  "requirements": [
    {
      "requirement_id": "string",
      "doc_type": "string",
      "description": "string"
    }
  ]
}

Abdeckungsvalidierung: Es gibt drei mögliche Ergebnisse:

Telnyx hat Anforderungen. Die Antwort listet jeden erforderlichen doc_type auf. Das Dokumentenset muss mindestens ein Dokument enthalten, das jedem Typ entspricht.
Telnyx-Abruf fehlgeschlagen. Kann die Plattform Telnyx nicht erreichen, um Anforderungen abzufragen, lautet die Antwort 503 Service Unavailable (fail-closed). Wiederholen Sie den Endpunktaufruf, sobald Telnyx erreichbar ist.
Keine Anforderungen. Für manche Länder-/Typkombinationen sind keine Dokumente erforderlich (z. B. vorhandene DIDs eines Resellers). Die Antwort ist 200 mit einem leeren requirements-Array; das ist ein legitimes Ergebnis und kein Fehler.

POST /v1/kyc/document-sets — Ein Dokumentenset erstellen.

Anfrage-Body:

json

{
  "country": "US",
  "number_type": "local",
  "documents": [
    {
      "requirement_id": "reg-001",
      "document_id": "uuid-of-uploaded-document"
    },
    {
      "requirement_id": "reg-002",
      "document_id": "uuid-of-another-document"
    }
  ]
}

Die Plattform validiert:

Jede requirement_id ist in den aktuellen Telnyx-Anforderungen für (country, number_type) aufgeführt
Jede document_id verweist auf ein vorhandenes Dokument des Mandanten
Jede Telnyx-Anforderung für das Paar wird durch mindestens ein Dokument im Set erfüllt (keine Lücken)
Das Set ist nicht leer

Bei erfolgreicher Validierung wird das Set als „Anforderungsgruppe" an Telnyx übermittelt und antwortet mit:

id (string) — Set-UUID
country (string) — Ländercode
number_type (string) — der Typ
status (string) — bei Erstellung immer "submitted"
telnyx_requirement_group_id (string) — die Telnyx-ID für diese Gruppe
documents (array) — die zugeordneten Dokumente mit Metadaten
created_at (ISO-8601-Zeitstempel)
updated_at (ISO-8601-Zeitstempel)

Fehlermodi:

400 Bad Request, wenn die Dokument-/Anforderungstypen ungültig oder die Abdeckung unvollständig ist
422 Unprocessable Entity, wenn Telnyx die Einreichung ablehnt (z. B. Probleme mit der Dokumentqualität)
503 Service Unavailable, wenn Telnyx nicht erreichbar ist (fail-closed; später erneut versuchen)

Asynchrone Genehmigung: Nach der Erstellung verifiziert Telnyx die Dokumente asynchron. Wenn die Verifizierung abgeschlossen ist (innerhalb von Stunden oder Tagen), liefert Telnyx einen signierten Webhook mit event_type: "requirement_group.verified", und die Plattform aktualisiert den Status des Sets atomar:

"approved" — Telnyx hat alle Dokumente akzeptiert; das Set ist jetzt für Nummernbestellungen verwendbar
"rejected" — Telnyx hat ein oder mehrere Dokumente abgelehnt; das Set kann nicht verwendet werden; prüfen Sie den Ablehnungsgrund und übermitteln Sie Dokumente per PUT erneut

GET /v1/kyc/document-sets — Alle Dokumentensets des Mandanten auflisten.

Gibt eine paginierte Liste zurück, einschließlich Status ("submitted", "approved" oder "rejected"), Land, Nummerntyp und den zugeordneten Dokumenten für jedes Set.

GET /v1/kyc/document-sets/{id} — Details eines einzelnen Sets abrufen.

Enthält die vollständige Liste der Anforderungs-Slots und welches Dokument jedem Slot zugeordnet ist.

DELETE /v1/kyc/document-sets/{id} — Ein Dokumentenset löschen.

Gibt 409 Conflict zurück, wenn eine Nummernbestellung derzeit auf dieses Set verweist (Löschschutz). Andernfalls wird der Vorgang erfolgreich abgeschlossen und kaskadiert, um die Telnyx-Anforderungsgruppe freizugeben.

Schritt 3: Nummernbestellungen

GET /v1/numbers/available — Verfügbare Nummern zur Bestellung abfragen.

Abfrageparameter:

country (erforderlich, z. B. "US")
number_type (erforderlich, z. B. "local")
limit (optional, Standard 10)
area_code (optional, für US-Nummern; filtert nach einer bestimmten NPA)

Die Antwort gibt eine Liste von DIDs zurück, die zur sofortigen Bereitstellung verfügbar sind:

json

{
  "available_numbers": [
    {
      "number": "+1415...",
      "region": "San Francisco, CA",
      "features": ["sms", "voice", "mms"]
    }
  ]
}

Nummern werden bei jeder Abfrage live von Telnyx abgerufen und erscheinen nicht erneut, sobald eine Bestellung auf sie verweist.

POST /v1/numbers/orders — Eine Nummernbestellung aufgeben.

Anfrage-Body:

json

{
  "document_set_id": "uuid-of-approved-set",
  "country": "US",
  "number_type": "local",
  "quantity": 5,
  "area_code": "415"
}

Parameter:

document_set_id — UUID eines genehmigten (Status = "approved") Dokumentensets
country und number_type — müssen mit Land und Typ des Sets übereinstimmen (Validierungsfehler bei Abweichung)
quantity — Anzahl der zu bestellenden DIDs (typischerweise 1–10)
area_code — optional; US-spezifischer Filter

Idempotenz: Übergeben Sie den Idempotency-Key-Header (beliebiger Stringwert); wenn eine frühere Anfrage mit demselben Schlüssel erfolgreich war, wird die identische Antwort zurückgegeben. Dadurch werden Doppelbestellungen bei instabilen Netzwerkverbindungen vermieden.

Bei Erfolg lautet die Antwort:

json

{
  "order_id": "uuid",
  "status": "pending",
  "country": "US",
  "number_type": "local",
  "quantity": 5,
  "requested_numbers": [],
  "ordered_numbers": [],
  "created_at": "2025-01-20T...",
  "updated_at": "2025-01-20T..."
}

Die Bestellung beginnt im Status "pending". Die Plattform reicht die Bestellung sofort bei der Telnyx-API ein und durchläuft den folgenden Lebenszyklus, gesteuert durch Telnyx-Webhook-Zustellungen:

Status	Bedeutung
`pending`	Bestellung lokal akzeptiert; Telnyx-Verarbeitung ausstehend
`requirement_review`	Telnyx prüft die Dokumentenset-Abdeckung für Land/Typ dieser Bestellung (selten)
`ordering`	Telnyx erwirbt die Nummern aus dem Bestand (aktiv)
`success`	Alle angeforderten Nummern wurden zugeteilt; Nummern sind jetzt im Pool
`failure`	Telnyx konnte nicht alle oder einige Nummern zuteilen (z. B. Vorwahl erschöpft); es wurden keine Nummern erstellt

Fehlermodi:

400 Bad Request, wenn Land/Nummerntyp ungültig sind
404 Not Found, wenn das Dokumentenset nicht existiert
409 Conflict, wenn das Dokumentenset nicht genehmigt ist (Status != "approved")
422 Unprocessable Entity, wenn die Abdeckungsvalidierung fehlschlägt (z. B. fehlende Anforderungsdokumente)
503 Service Unavailable, wenn Telnyx nicht erreichbar ist (fail-closed; die Bestellung wird nicht erstellt)

Erneute Abdeckungsvalidierung: Vor der Auftragserteilung validiert die Plattform erneut, dass das Dokumentenset alle aktuellen regulatorischen Anforderungen von Telnyx für (country, number_type) abdeckt. Dadurch werden regulatorische Änderungen zwischen Set-Genehmigung und Bestellzeitpunkt abgefangen. Wenn die Abdeckung jetzt unvollständig ist (Telnyx hat nach der Set-Genehmigung eine neue Anforderung hinzugefügt), schlägt die Bestellung mit 422 fehl.

Automatische Verbindung und Abrechnung: Sobald die Bestellung den Status "success" erreicht und die Nummern in den Pool eingefügt werden, führt die Audact-Plattform automatisch folgende Schritte durch:

Konfiguration der Trunk-Verbindung (Telnyx-SIP-Trunk) für diesen Mandanten
Verknüpfung der Abrechnung mit dem von Audact verwalteten Telnyx-Konto des Mandanten
Festlegen der Routing-Standardwerte (zunächst sind alle DIDs inaktiv, bis sie explizit einem Agenten zugewiesen werden)

Der Client gibt keine Verbindungsparameter oder Abrechnungsdaten an; die Plattform übernimmt dies transparent.

GET /v1/numbers/orders — Alle Bestellungen des Mandanten auflisten.

Gibt eine paginierte Liste mit Status, Land, Typ, Menge und Zeitstempeln zurück.

GET /v1/numbers/orders/{id} — Den Status einer einzelnen Bestellung abrufen.

Enthält den vollständigen Lebenszyklusstatus und die aktuelle ordered_numbers-Liste (wird befüllt, sobald der Status "success" erreicht).

Schritt 4: Zuweisung & Routing

Sobald eine Nummer den Pool erreicht (Status = "success" in ihrer Bestellung), werden noch keine Verbindungen geroutet. Durch die Zuweisung wird eine Nummer für einen bestimmten Agenten aktiv.

GET /v1/numbers — Alle Nummern im Pool des Mandanten auflisten.

Abfrageparameter:

status (optional, nach Zustand filtern: "available", "assigned", "suspended")

Antwort enthält:

id — Nummer-UUID
number — die E.164-formatierte DID (z. B. "+1415...")
country, number_type — Herkunft
status — eines von "available", "assigned" oder "suspended"
assigned_agent_id (nullable) — die Agenten-UUID, falls zugewiesen
created_at, updated_at

POST /v1/numbers/{id}/assign — Eine Nummer einem Agenten zuweisen.

Anfrage-Body:

json

{
  "agent_id": "uuid-of-agent"
}

Antwort 200 bei Erfolg, 404 wenn die Nummer oder der Agent nicht existiert, 409 wenn die Nummer bereits einem anderen Agenten zugewiesen ist.

Nach der Zuweisung werden eingehende Verbindungen an diese Nummer an den Agenten weitergeleitet.

DELETE /v1/numbers/{id}/assign — Die Zuweisung einer Nummer aufheben.

Die Nummer wechselt zurück zu "available" und Verbindungen werden nicht mehr geroutet (noch im Pool, aber inaktiv).

POST /v1/numbers/{id}/suspend — Das Routing einer Nummer sperren.

Die Nummer wechselt in den Status "suspended"; Verbindungen zu ihr werden abgelehnt (nicht mehr an den zugewiesenen Agenten geroutet). Das Routing kann ohne Verlust der Zuweisung fortgesetzt werden.

POST /v1/numbers/{id}/resume — Eine gesperrte Nummer fortsetzen.

Die Nummer wechselt zurück in ihren vorherigen Status ("assigned" wenn zugewiesen, oder "available" wenn nicht zugewiesen) und das Routing wird wiederhergestellt.

Schritt 5: Freigabe & Löschung

Es gibt zwei unterschiedliche Entfernungsoperationen:

DELETE /v1/numbers/{id}/release — Die Nummer in den Pool zurückgeben (Soft-Delete).

Löscht die Agentenzuweisung (falls vorhanden)
Wechselt zu Status "available"
Löscht die Nummer NICHT dauerhaft und gibt die DID bei Telnyx NICHT frei
Die Nummer bleibt für zukünftige Zuweisungen verwendbar

Diese Operation wird verwendet, wenn ein Agent die Nummer nicht mehr benötigt, sie aber im Pool für Neuzuweisung oder Planung behalten werden soll.

DELETE /v1/numbers/{id} — Die Nummer dauerhaft löschen (Hard-Delete).

Entfernt die Nummer vollständig aus dem Pool
Gibt die DID an das Telnyx-Inventar zurück (irreversibel)
Beendet die Abrechnung für diese Nummer sofort
Die DID kann danach nicht mehr kontaktiert werden

Diese Operation ist irreversibel; verwenden Sie release, wenn die Nummer für zukünftige Neuzuweisungen weiterhin erreichbar sein soll. Nach dem Löschen ist die Nummer weder auf der Plattform noch im Carrier-Pool vorhanden.

Fehlersemantik & Idempotenz

Fail-Closed & Fail-Open

Alle KYC- und Bestelloperationen sind fail-closed: Wenn die Plattform Telnyx nicht erreichen kann (Netzwerkfehler, Timeout, Telnyx-Ausfall), schlägt die Anfrage mit 503 Service Unavailable fehl. Es wird kein partieller Zustand erstellt; ein erneuter Versuch, sobald Telnyx erreichbar ist, führt nicht zu Duplikaten (dank Idempotency-Key-Unterstützung für zustandsändernde Endpunkte).

Idempotency-Key

Übergeben Sie den Idempotency-Key-Header bei:

POST /v1/kyc/documents — Dokument hochladen
PUT /v1/kyc/documents/{id} — Dokument ersetzen
POST /v1/numbers/orders — Bestellung aufgeben

Zwei Anfragen mit demselben Schlüssel innerhalb von 24 Stunden (oder Ihrem konfigurierten Idempotenz-Fenster) geben dieselbe Antwort zurück. Dies ermöglicht das sichere Wiederholen von Anfragen bei Netzwerkfehlern ohne Erstellung von Duplikaten.

Verwendungskonflikt (409)

Dokumentensets und Dokumente sind gegen das Löschen gesichert, solange sie von einer laufenden Bestellung referenziert werden:

DELETE /v1/kyc/documents/{id} gibt 409 zurück, wenn eines der zugehörigen Sets eine aktive Bestellung hat
DELETE /v1/kyc/document-sets/{id} gibt 409 zurück, wenn eine aktive Bestellung auf das Set verweist

Eine „aktive" Bestellung hat den Status {pending, requirement_review, ordering}; sobald eine Bestellung den terminalen Status (success oder failure) erreicht, ist das Set nicht mehr „laufend" und kann sicher gelöscht werden.

Abdeckungsbereich (422)

POST /v1/kyc/document-sets gibt 422 zurück, wenn die Abdeckung unvollständig ist (eine Telnyx-Anforderung hat kein passendes Dokument)
POST /v1/numbers/orders gibt 422 zurück, wenn sich die Abdeckung seit der Set-Genehmigung geändert hat (Telnyx hat eine neue Anforderung hinzugefügt)

Beide werden als nicht verarbeitbare Entitäten modelliert, um sie von 400 (fehlerhafte Anfrageparameter) und 503 (Backend nicht verfügbar) zu unterscheiden.

Unbekannter Typ (400)

POST /v1/kyc/documents mit einem ungültigen doc_type gibt 400 Bad Request zurück
POST /v1/kyc/document-sets mit einer ungültigen Anforderungs-ID oder Land-/Typkombination gibt 400 zurück

Das sind fehlerhafte Anfragen, keine Abdeckungsprobleme.

Telnyx nicht erreichbar (503)

Wenn Telnyx nicht erreichbar ist:

POST /v1/kyc/documents-Upload (vor der Verschlüsselung) gibt 503 zurück, wenn der nachfolgende Telnyx-Metadatenabruf fehlschlägt
PUT /v1/kyc/documents/{id} (bei der erneuten Verifizierung) gibt 503 zurück, wenn Telnyx nicht erreichbar ist
GET /v1/kyc/requirements gibt 503 zurück, wenn Telnyx nicht abgefragt werden kann
POST /v1/kyc/document-sets gibt 503 zurück, wenn die Telnyx-Einreichung fehlschlägt
POST /v1/numbers/orders gibt 503 zurück, wenn die Telnyx-Bestelleinreichung fehlschlägt

In allen Fällen geht die Plattform nicht in einen partiellen Zustand; wiederholen Sie den Vorgang, sobald Telnyx erreichbar ist.