Nummerprovisionering & KYC

Dit document beschrijft de volledige levenscyclus van het provisioneren van een telefoonnummer via het Audact-platform — van het indienen van Know-Your-Customer-documenten (KYC) tot het plaatsen van bestellingen bij de carrier en het beheren van nummers in de pool.

Het Audact-platform beheert nummers namens tenants via de Telnyx-carrier. Nummers worden besteld, opgeslagen en aan agenten toegewezen via een self-service-KYC-namens-tenant-model: de tenant uploadt wettelijke compliancedocumenten (bijv. handelsregistratie, adresbewijs), Audact versleutelt deze in rust en dient ze in bij Telnyx ter goedkeuring. Na goedkeuring kan de tenant nummers bestellen voor elke land-/typecombinatie die door die goedkeuring wordt gedekt. De facturering verloopt via het Telnyx-platformaccount van Audact; verbindings- en factureringsinstellingen worden automatisch door het platform geconfigureerd en hoeven niet door de client te worden opgegeven.

Het proces verloopt in vijf logische stappen:

1. KYC-documenten — Documenten uploaden, versleutelen en de status van wettelijke compliancedocumentatie bijhouden
2. Documentsets — Documenten groeperen in vereistensets die worden vergeleken met de wettelijke vereisten van Telnyx
3. Nummerbestellingen — Bestellingen bij de carrier plaatsen op basis van goedgekeurde sets; DID's in de pool ontvangen
4. Toewijzing & routering — Nummers aan agenten toewijzen en opschorten/hervatten beheren
5. Vrijgave & verwijdering — Nummers terugsturen naar de pool of permanent verwijderen (en vrijgeven bij de carrier)

Stap 1: KYC-documenten

POST /v1/kyc/documents — Een compliancedocument uploaden (bijv. handelsregistratie, adresbewijs).

Het verzoek moet multipart/form-data zijn met:

• document (bestandsveld, vereist) — de onbewerkte documentbytes (PDF, afbeelding, enz.; max. 15 MiB per document)
• doc_type (formulierveld, vereist) — het type Telnyx-wettelijke vereiste dat dit document vervult (bijv. "business_registration", "certificate_of_authority")
• filename (formulierveld, optioneel) — leesbare bestandsnaam; standaard de uploadbestandsnaam als niet opgegeven

De respons bevat:

• id (string) — unieke document-UUID
• doc_type (string) — het opgegeven type
• filename (string) — de bestandsnaam
• content_type (string) — MIME-type (bijv. "application/pdf")
• size_bytes (integer) — niet-gecomprimeerde grootte van het originele bestand
• sha256 (string) — SHA-256-controlegetal van de originele bytes in kleine letters; éénmalig berekend bij het uploaden en daarna onveranderd (voor integriteitscontrole)
• telnyx_document_id (string, nullable) — de door Telnyx toegewezen ID als dit document naar Telnyx is gestuurd
• created_at (ISO-8601-tijdstempel) — door de server gegenereerde uploadtijd
• updated_at (ISO-8601-tijdstempel) — tijdstip van laatste wijziging

Belangrijk: Documentbytes worden NOOIT door de API teruggegeven — alleen metadata. Alle documenten worden in rust versleuteld onder de KYC Document Encryption Key (DEK) van de tenant, waarbij de versleuteling is gekoppeld aan de tenant en document-ID zodat versleutelde teksten niet onder een andere identiteit kunnen worden hergebruikt.

GET /v1/kyc/documents — Alle KYC-documenten van de tenant weergeven.

Geeft een gepagineerde lijst van documentmetadata terug (alle velden uit de POST-respons, zonder bestandsbytes).

GET /v1/kyc/documents/{id} — De metadata van één document ophalen.

PUT /v1/kyc/documents/{id} — Een document vervangen (bijv. een gecorrigeerde of bijgewerkte versie uploaden).

De aanvraagbody is opnieuw multipart/form-data met document en optioneel filename en doc_type. Vervanging heeft het volgende effect:

• De nieuwe bytes worden opnieuw versleuteld onder de huidige DEK-versie
• Als dit document een al ingediende of goedgekeurde documentset ondersteunt, wordt de volledige set opnieuw geverifieerd bij Telnyx (bijgewerkte metadata wordt naar de vereistengroep gestuurd)
• 409 Conflict als een lopende nummerbestelling momenteel naar deze documentset verwijst

DELETE /v1/kyc/documents/{id} — Een document verwijderen.

Geeft 409 Conflict terug als een nummerbestelling momenteel verwijst naar de documentset die dit document bevat (de verwijderingsbeveiliging voorkomt dat een bestelling wordt verweesd). Anders wordt de bewerking voltooid en worden alle documentsets die dit document gebruikten meegewist.

Stap 2: Documentsets & vereistendekking

GET /v1/kyc/requirements — De actuele wettelijke vereisten van Telnyx opvragen voor een land en nummertype.

Queryparameters:

• country (vereist, 2-letterige ISO 3166-1 alpha-2, bijv. "US")
• number_type (vereist, bijv. "local" of "mobile")

Respons:

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

Dekkingsvalidatie: Er zijn drie mogelijke uitkomsten:

1. Telnyx heeft vereisten. De respons vermeldt elk vereist doc_type. Uw documentset moet ten minste één document bevatten dat overeenkomt met elk type.
2. Telnyx-ophaling mislukt. Als het platform Telnyx niet kan bereiken om vereisten op te vragen, is de respons 503 Service Unavailable (fail-closed). Probeer het eindpunt opnieuw zodra Telnyx bereikbaar is.
3. Geen vereisten. Voor sommige land-/typecombinaties zijn geen documenten vereist (bijv. bestaande DID's van een reseller). De respons is 200 met een lege requirements-array; dit is een geldig resultaat, geen fout.

POST /v1/kyc/document-sets — Een documentset aanmaken.

Aanvraagbody:

{
  "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"
    }
  ]
}

Het platform valideert:

1. Elke requirement_id staat vermeld in de huidige Telnyx-vereisten voor (country, number_type)
2. Elke document_id verwijst naar een bestaand document van deze tenant
3. Elke Telnyx-vereiste voor het paar wordt door ten minste één document in de set vervuld (geen hiaten)
4. De set is niet leeg

Als de validatie slaagt, wordt de set als "vereistengroep" ingediend bij Telnyx en wordt het volgende teruggegeven:

• id (string) — set-UUID
• country (string) — landcode
• number_type (string) — het type
• status (string) — altijd "submitted" bij aanmaak
• telnyx_requirement_group_id (string) — de Telnyx-ID voor deze groep
• documents (array) — de toegewezen documenten met metadata
• created_at (ISO-8601-tijdstempel)
• updated_at (ISO-8601-tijdstempel)

Foutmodi:

• 400 Bad Request als de document-/vereistentypen ongeldig zijn of de dekking onvolledig is
• 422 Unprocessable Entity als Telnyx de indiening afwijst (bijv. problemen met documentkwaliteit)
• 503 Service Unavailable als Telnyx niet bereikbaar is (fail-closed; probeer later opnieuw)

Asynchrone goedkeuring: Na aanmaak verifieert Telnyx de documenten asynchroon. Wanneer de verificatie is voltooid (binnen uren of dagen), levert Telnyx een ondertekende webhook met event_type: "requirement_group.verified" en werkt het platform de status van de set atomisch bij:

• "approved" — Telnyx heeft alle documenten geaccepteerd; de set is nu bruikbaar voor nummerbestellingen
• "rejected" — Telnyx heeft een of meer documenten afgewezen; de set kan niet worden gebruikt; controleer de afwijzingsreden en dien documenten opnieuw in via PUT

GET /v1/kyc/document-sets — Alle documentsets van de tenant weergeven.

Geeft een gepagineerde lijst terug met status ("submitted", "approved" of "rejected"), land, nummertype en de toegewezen documenten voor elke set.

GET /v1/kyc/document-sets/{id} — De details van één set ophalen.

Bevat de volledige lijst van vereistenslots en welk document aan elk slot is gekoppeld.

DELETE /v1/kyc/document-sets/{id} — Een documentset verwijderen.

Geeft 409 Conflict terug als een nummerbestelling momenteel naar deze set verwijst (verwijderingsbeveiliging). Anders wordt de bewerking voltooid en wordt de Telnyx-vereistengroep vrijgegeven.

Stap 3: Nummerbestellingen

GET /v1/numbers/available — Beschikbare nummers opvragen om te bestellen.

Queryparameters:

• country (vereist, bijv. "US")
• number_type (vereist, bijv. "local")
• limit (optioneel, standaard 10)
• area_code (optioneel, voor US-nummers; filtert op een specifieke NPA)

De respons geeft een lijst terug van DID's die direct beschikbaar zijn voor provisionering:

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

Nummers worden bij elke query live opgehaald bij Telnyx en verschijnen niet meer zodra een bestelling ernaar verwijst.

POST /v1/numbers/orders — Een nummerbestelling plaatsen.

Aanvraagbody:

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

Parameters:

• document_set_id — UUID van een goedgekeurde (status = "approved") documentset
• country en number_type — moeten overeenkomen met het land en type van de set (validatiefout bij afwijking)
• quantity — aantal te bestellen DID's (doorgaans 1–10)
• area_code — optioneel; US-specifiek filter

Idempotentie: Geef de Idempotency-Key-header mee (willekeurige tekenreekswaarde); als een eerdere aanvraag met dezelfde sleutel is geslaagd, wordt de identieke respons teruggegeven. Dit voorkomt dubbele bestellingen bij onstabiele netwerkverbindingen.

Bij succes luidt de respons:

{
  "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..."
}

De bestelling begint in de status "pending". Het platform dient de bestelling onmiddellijk in bij de Telnyx-API en doorloopt de volgende levenscyclus, aangestuurd door Telnyx-webhookbezorging:

Foutmodi:

• 400 Bad Request als land/nummertype ongeldig zijn
• 404 Not Found als de documentset niet bestaat
• 409 Conflict als de documentset niet is goedgekeurd (status != "approved")
• 422 Unprocessable Entity als de dekkingsvalidatie mislukt (bijv. ontbrekende vereistendocumenten)
• 503 Service Unavailable als Telnyx niet bereikbaar is (fail-closed; de bestelling wordt niet aangemaakt)

Hervalidatie van dekking: Voordat de bestelling wordt geplaatst, valideert het platform opnieuw of de documentset alle actuele wettelijke vereisten van Telnyx voor (country, number_type) dekt. Dit vangt regelgevingswijzigingen op die zijn opgetreden tussen de goedkeuring van de set en het tijdstip van de bestelling. Als de dekking nu onvolledig is (Telnyx heeft na de goedkeuring van de set een nieuwe vereiste toegevoegd), mislukt de bestelling met 422.

Automatische verbinding en facturering: Zodra de bestelling de status "success" bereikt en de nummers in de pool worden ingevoegd, voert het Audact-platform automatisch het volgende uit:

• De trunk-verbinding (Telnyx SIP-trunk) voor deze tenant configureren
• De facturering koppelen aan het door Audact beheerde Telnyx-account van de tenant
• Routeringsstandaarden instellen (aanvankelijk zijn alle DID's inactief totdat ze expliciet aan een agent zijn toegewezen)

De client geeft geen verbindingsparameters of factureringsgegevens op; het platform verwerkt dit transparant.

GET /v1/numbers/orders — Alle bestellingen van de tenant weergeven.

Geeft een gepagineerde lijst terug met status, land, type, hoeveelheid en tijdstempels.

GET /v1/numbers/orders/{id} — De status van één bestelling ophalen.

Bevat de volledige levenscyclusstatus en de huidige ordered_numbers-lijst (wordt gevuld zodra de status "success" bereikt).

Stap 4: Toewijzing & routering

Zodra een nummer de pool bereikt (status = "success" in de bijbehorende bestelling), worden er nog geen oproepen gerouteerd. Door toewijzing wordt een nummer actief voor een specifieke agent.

GET /v1/numbers — Alle nummers in de pool van de tenant weergeven.

Queryparameters:

• status (optioneel, filteren op toestand: "available", "assigned", "suspended")

Respons bevat:

• id — nummer-UUID
• number — de E.164-geformatteerde DID (bijv. "+1415...")
• country, number_type — herkomst
• status — één van "available", "assigned" of "suspended"
• assigned_agent_id (nullable) — de agent-UUID indien toegewezen
• created_at, updated_at

POST /v1/numbers/{id}/assign — Een nummer aan een agent toewijzen.

Aanvraagbody:

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

Respons 200 bij succes, 404 als het nummer of de agent niet bestaat, 409 als het nummer al aan een andere agent is toegewezen.

Na toewijzing worden inkomende oproepen naar dit nummer doorgestuurd naar die agent.

DELETE /v1/numbers/{id}/assign — De toewijzing van een nummer opheffen.

Het nummer gaat terug naar "available" en oproepen worden niet langer gerouteerd (nog steeds in de pool, maar inactief).

POST /v1/numbers/{id}/suspend — De routering van een nummer opschorten.

Het nummer gaat naar de status "suspended"; oproepen ernaar worden afgewezen (niet langer naar de toegewezen agent gerouteerd). De routering kan worden hervat zonder de toewijzing te verliezen.

POST /v1/numbers/{id}/resume — Een opgeschort nummer hervatten.

Het nummer gaat terug naar de vorige status ("assigned" als toegewezen, of "available" als niet toegewezen) en de routering wordt hersteld.

Stap 5: Vrijgave & verwijdering

Er zijn twee afzonderlijke verwijderingsbewerkingen:

DELETE /v1/numbers/{id}/release — Het nummer terugsturen naar de pool (zachte verwijdering).

• Wist de agenttoewijzing (indien aanwezig)
• Gaat naar status "available"
• Verwijdert het nummer NIET permanent en geeft de DID NIET vrij bij Telnyx
• Het nummer blijft bruikbaar voor toekomstige toewijzingen

Deze bewerking wordt gebruikt wanneer een agent het nummer niet langer nodig heeft, maar u het in uw pool wilt houden voor hertoewijzing of planning.

DELETE /v1/numbers/{id} — Het nummer permanent verwijderen (harde verwijdering).

• Verwijdert het nummer volledig uit de pool
• Geeft de DID terug aan de Telnyx-voorraad (onomkeerbaar)
• Stopt de facturering voor dit nummer onmiddellijk
• De DID is daarna niet meer bereikbaar

Deze bewerking is onomkeerbaar; gebruik release als u het nummer bereikbaar wilt houden voor toekomstige hertoewijzingen. Na verwijdering is het nummer zowel op het platform als in de carrier-pool verdwenen.

Foutsemantiek & idempotentie

Fail-Closed & Fail-Open

Alle KYC- en bestellingsbewerkingen zijn fail-closed: als het platform Telnyx niet kan bereiken (netwerkfout, time-out, Telnyx-storing), mislukt de aanvraag met 503 Service Unavailable. Er wordt geen gedeeltelijke toestand aangemaakt; een nieuwe poging zodra Telnyx bereikbaar is, levert geen duplicaten op (dankzij Idempotency-Key-ondersteuning op toestandwijzigende eindpunten).

Idempotency-Key

Geef de Idempotency-Key-header mee bij:

• POST /v1/kyc/documents — document uploaden
• PUT /v1/kyc/documents/{id} — document vervangen
• POST /v1/numbers/orders — bestelling plaatsen

Twee aanvragen met dezelfde sleutel binnen 24 uur (of uw geconfigureerde idempotentievenster) geven dezelfde respons terug. Dit maakt het mogelijk aanvragen veilig opnieuw te verzenden bij netwerkfouten zonder duplicaten aan te maken.

Gebruiksconflict (409)

Documentsets en documenten zijn beveiligd tegen verwijdering terwijl een lopende bestelling ernaar verwijst:

• DELETE /v1/kyc/documents/{id} geeft 409 terug als een van de bijbehorende sets een actieve bestelling heeft
• DELETE /v1/kyc/document-sets/{id} geeft 409 terug als een actieve bestelling naar de set verwijst

Een "actieve" bestelling heeft de status {pending, requirement_review, ordering}; zodra een bestelling de eindtoestand bereikt (success of failure), is de set niet langer "lopend" en kan deze veilig worden verwijderd.

Dekkingsbereik (422)

• POST /v1/kyc/document-sets geeft 422 terug als de dekking onvolledig is (een Telnyx-vereiste heeft geen overeenkomend document)
• POST /v1/numbers/orders geeft 422 terug als de dekking is gewijzigd sinds de goedkeuring van de set (Telnyx heeft een nieuwe vereiste toegevoegd)

Beide worden gemodelleerd als niet-verwerkbare entiteiten om ze te onderscheiden van 400 (onjuiste aanvraagparameters) en 503 (backend niet beschikbaar).

Onbekend type (400)

• POST /v1/kyc/documents met een ongeldig doc_type geeft 400 Bad Request terug
• POST /v1/kyc/document-sets met een ongeldige vereisten-ID of land-/typecombinatie geeft 400 terug

Dit zijn onjuist gevormde aanvragen, geen dekkingsproblemen.

Telnyx niet bereikbaar (503)

Wanneer Telnyx niet bereikbaar is:

• POST /v1/kyc/documents-upload (vóór versleuteling) geeft 503 terug als het daaropvolgende ophalen van Telnyx-metadata mislukt
• PUT /v1/kyc/documents/{id} (tijdens herverificatie) geeft 503 terug als Telnyx niet bereikbaar is
• GET /v1/kyc/requirements geeft 503 terug als Telnyx niet kan worden bevraagd
• POST /v1/kyc/document-sets geeft 503 terug als de Telnyx-indiening mislukt
• POST /v1/numbers/orders geeft 503 terug als de Telnyx-bestellingsindiening mislukt

In alle gevallen gaat het platform niet in een gedeeltelijke toestand; probeer het opnieuw zodra Telnyx bereikbaar is.