Eigendomsdocumenten voor een nummer indienen

Sommige landen willen weten wie een nummer bezit voordat het verkeer mag afhandelen. Totdat die documenten zijn geaccepteerd en de registratie van het nummer is voltooid, is het nummer aan je toegewezen en wordt het gefactureerd, maar is de status pending_ownership_registration: het nummer handelt geen inkomende of uitgaande spraakoproepen af en verstuurt geen SMS. Het nummer handelt verkeer af zodra de status active is en de ownership.blocked_at null is. Je dient de documenten in via het dashboard of met de API. Beide routes gebruiken dezelfde vereisten, beoordelingsregels en hetzelfde registratieproces. De ownership.next van het nummer noemt elke stap, ook wanneer je een nieuwe indiening moet doen.

De antwoorden die je indient, zijn een juridische verklaring namens je bedrijf. Na acceptatie worden ze doorgegeven aan de provider of toezichthouder van dat land, onder de naam van het bedrijf dat ze beschrijven. Controleer ze daarom met de verantwoordelijke persoon voordat je ze indient, en laat geen geautomatiseerd proces antwoorden indienen die niemand heeft gecontroleerd.

Voordat je begint

• Om via het dashboard in te dienen, moet je rol in de werkruimte het bewerken van compliancegegevens toestaan. Zonder die rechten toont het nummer de eigendomsstatus, maar geen knop om in te dienen.
• Om via de losse compliance-endpoints in te dienen, heb je een API-sleutel nodig met de scope compliance op schrijfniveau. Met een sleutel op leesniveau kun je vereisten en de voortgang van de beoordeling bekijken, maar niet indienen. Om het nummer te lezen heb je ook de scope numbers op leesniveau nodig. In de sleutelkiezer van het dashboard staat compliance onder Compliance.
• De nda_-identificatie van het nummer, uit GET /v1/numbers. Een nummer in je lijst vinden laat zien hoe je die opzoekt.

De API-voorbeelden lezen je sleutel uit BIRD_API_KEY, de bijbehorende regionale host uit BIRD_API_URL en de identificatie van het nummer uit NUMBER_ID. Elke volgende stap noemt de variabele die hij instelt. De jq-opdrachten halen één veld uit een antwoord. Gebruik je geen jq, lees het veld dan zelf af.

Controleren of een nummer documenten nodig heeft

Lees het nummer met GET /v1/numbers/{number_id}:

curl "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Bewaar de country_code van het nummer als COUNTRY_CODE; zowel het opvragen van de vereisten als de indiening hebben die nodig:

COUNTRY_CODE=$(curl -s "$BIRD_API_URL/v1/numbers/$NUMBER_ID" \
  --header "Authorization: Bearer $BIRD_API_KEY" | jq -r .country_code)

ownership is null als het land van het nummer geen papierwerk vraagt. Het is ook null als we de voortgang van het papierwerk niet konden lezen en er geen blokkade op het nummer is vastgelegd; lees het nummer dan opnieuw. In alle andere gevallen bevat het:

• status: needs_input betekent dat er antwoorden ontbreken of gecorrigeerd moeten worden, under_review betekent dat je antwoorden worden beoordeeld, approval_pending betekent dat het papierwerk is geaccepteerd en de registratie nog loopt; gesprekken en uitgaande SMS blijven geblokkeerd zolang blocked_at is ingesteld. approved betekent dat de registratie is goedgekeurd, maar gesprekken en uitgaande SMS blijven geblokkeerd zolang blocked_at is ingesteld. not_required betekent dat er niets meer wordt gevraagd. rejected betekent dat de indiening is gesloten of dat een termijn voor correcties is verstreken, en dat er geen correcties meer mogelijk zijn. Neem contact op met support om de indiening te laten heropenen. unknown betekent dat de status niet kon worden gelezen; lees het nummer opnieuw.
• next: de stappen die het papierwerk verder brengen, op volgorde. Een stap wait betekent dat er nu niets van je wordt gevraagd. Lees dit veld opnieuw na elke wijziging.
• submission_id: de meest recente indiening voor het nummer, zodra die er is.
• blocked_at: wanneer de eigendomsblokkade begon, of null zodra die is opgeheven. De blokkade houdt inkomende en uitgaande gesprekken en uitgaande SMS tegen.

De status van een toegewezen nummer legt uit hoe ownership zich verhoudt tot de eigen status van het nummer.

Indienen via het dashboard

1. Open het nummer vanaf de pagina Numbers. De rij Ownership toont de status van het papierwerk en de volgende stappen.
2. Als de status Details needed is, selecteer je Update ownership details. Het formulier Prove ownership of this number wordt geopend.
3. Kies het bedrijf dat het nummer houdt, of beschrijf een nieuw bedrijf. Beantwoord daarna elk onderdeel en upload de documenten die het vraagt. Bij onderdelen met een leeg formulier staat een link waarmee je het downloadt, invult en weer uploadt.
4. Selecteer Submit answers.

De rij Ownership gaat naar Under review. Als een beoordelaar een antwoord afwijst, keert de rij terug naar Details needed. Selecteer dan opnieuw Update ownership details, corrigeer de antwoorden die het formulier toont en selecteer onderaan het formulier Update ownership details om ze te versturen.

Als er voor het land van het nummer nog geen formulier is, toont de formulierpagina Ownership form unavailable. Neem contact op met support om het voor dat land aan te vragen.

Indienen met de API

Om met de API in te dienen, lees je wat het land vraagt, upload je elk document, verstuur je alle antwoorden tegelijk en lees je daarna het nummer om de beoordeling te volgen.

Lees wat het land vraagt

Lees de vereisten voor het nummer met GET /v1/compliance/requirements. Stel subject_kind in op number, subject_id op de nda_-identifier van het nummer en country_code op de eigen COUNTRY_CODE van het nummer:

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&subject_id=$NUMBER_ID&country_code=$COUNTRY_CODE" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Het antwoord noemt de program waaronder het nummer wordt geregistreerd; die volgt uit het nummertype. Bewaar deze als PROGRAM. Het antwoord somt in fields elk te beantwoorden item op, in de volgorde waarin je ze moet tonen. Voor elk veld geldt:

• key is de naam waaronder je het antwoord verstuurt.
• data_type geeft aan hoe je het beantwoordt. Een document-veld verwacht een geüpload bestand. Elk ander type verwacht een string, dus een getal stuur je als "1500" en een ja-of-nee als "true". Een enum-veld accepteert een van zijn options.
• required geeft aan of de goedkeuring van dit veld afhangt, en help_text beschrijft hoe een goed antwoord eruitziet.
• max_items is ingesteld op een veld dat meer dan één antwoord accepteert.
• template_url linkt naar een leeg formulier dat je downloadt, invult en weer uploadt, als het veld er een heeft.
• state geeft aan waar het item staat: not_supplied voordat je antwoordt, daarna supplied, in_review, approved of rejected, met de reason van de beoordelaar bij een afgewezen item. Een geaccepteerd antwoord kan later expired tonen en moet dan opnieuw worden aangeleverd, en not_applicable markeert een item dat niet op jou van toepassing is.

submission_id is null totdat je indient. needs_input is true zolang er een item op jou wacht.

Een 422 met E19001 betekent dat we nog geen eigendomsformulier voor dat land hebben. Neem contact op met support om het aan te vragen.

Upload elk document

Upload elk bestand waar een document-veld om vraagt met POST /v1/compliance/attachments, als multipart/form-data-body met de bytes in een file-deel. Bewaar de id uit het antwoord, de tca_-identifier van de bijlage, als ATTACHMENT_ID:

curl --request POST "$BIRD_API_URL/v1/compliance/attachments" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --form "file=@registration-certificate.pdf"

PNG-, JPEG- en PDF-bestanden tot 10 MB worden geaccepteerd, en het type wordt bepaald aan de hand van de inhoud van het bestand. Een 201-antwoord geeft de nieuwe bijlage terug. Als je hetzelfde bestand opnieuw uploadt, krijg je de eerste bijlage terug met 200, dus een upload opnieuw proberen maakt geen duplicaat aan. Een bijlage waarnaar geen enkele indiening verwijst, verloopt na zeven dagen.

De download_url van de bijlage is een ondertekende link die 24 uur geldig is vanaf het moment dat je de bijlage hebt opgehaald. Vraag een lijst van je bijlagen op met GET /v1/compliance/attachments voor een nieuwe link, of download de bytes rechtstreeks met GET /v1/compliance/attachments/{attachment_id}.

Dien alle antwoorden in

Dien de antwoorden in met POST /v1/compliance/submissions. Stuur subject_kind en subject_id mee, de program die het opvragen van de vereisten opleverde, en de country_code van het nummer. Stuur in answers één item voor elk veld waarvan required true is, en één voor elk optioneel veld waarvoor je een echt antwoord hebt. Laat een optioneel veld weg in plaats van er een waarde voor te verzinnen. Een getypeerd veld krijgt value, een documentveld krijgt attachment_id en een veld met max_items krijgt values of attachment_ids. Sla de body op als submission.json, met je eigen waarden in plaats van <NUMBER_ID>, <PROGRAM>, <COUNTRY_CODE> en <ATTACHMENT_ID>. Het voorbeeld toont drie van de antwoorden waar een formulier om vraagt:

{
  "subject_kind": "number",
  "subject_id": "<NUMBER_ID>",
  "program": "<PROGRAM>",
  "country_code": "<COUNTRY_CODE>",
  "answers": [
    { "key": "legal_entity_name", "value": "Goldcrest Communications Inc" },
    { "key": "business_registration_number", "value": "90012768" },
    { "key": "business_registration_certificate", "attachment_id": "<ATTACHMENT_ID>" }
  ]
}

Verstuur het met een Idempotency-Key. Gebruik de sleutel alleen opnieuw om dezelfde body opnieuw te proberen: een afwijzing kan worden bewaard en opnieuw worden afgespeeld, dus corrigeer na een 422 de body en verstuur die met een nieuwe sleutel. Idempotentie legt uit wat er wordt bewaard.

curl --request POST "$BIRD_API_URL/v1/compliance/submissions" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ownership-$NUMBER_ID" \
  --data-binary @submission.json

Er zijn geen concepten: dit verzoek dient de antwoorden in ter beoordeling, dus het moet elk verplicht antwoord bevatten. Als je een verplicht veld weglaat of het formulier een antwoord weigert, krijg je een 422 terug met E01001 en per veld één item in details, met de naam in param, en wordt er niets ingediend. Een 201-antwoord geeft de indiening terug met alle antwoorden. Bewaar de id ervan, de csb_-identifier van de indiening, als SUBMISSION_ID.

Een bedrijf dat je werkruimte beschrijft, is een identiteit. Maak er een aan in het Identity Center van het dashboard of met POST /v1/compliance/identities, waarbij je de weergave-name meestuurt. Een indiening voor een nummer kan ook een inline identity bevatten in plaats van een identity_id. De identity_id in het antwoord op de indiening noemt de nieuwe identiteit, die POST /v1/compliance/identities teruggeeft als id. Gebruik die opnieuw voor latere nummers in plaats van een nieuwe aan te maken. Voeg de identity_id van een identiteit toe om voor die identiteit in te dienen; de antwoorden die ze bevat, vullen de antwoorden in die je weglaat. GET /v1/compliance/identities geeft de bedrijfsidentiteiten weer. De antwoorden met één waarde die je indient, worden teruggeschreven naar de identiteit, ongeacht de uitkomst van de beoordeling, zodat de volgende indiening die haar noemt daarmee begint. Documenten en antwoorden met meerdere waarden worden elke keer opnieuw gevraagd. Gebruik één identiteit per bedrijf: als je voor meerdere eindklanten indient, geef dan elke klant een eigen identiteit, anders vullen de goedgekeurde antwoorden van de ene klant die van een andere in.

Volg ownership.next in plaats van opnieuw in te dienen. Een nummer heeft één indiening per versie van het formulier van zijn land. Als je opnieuw indient terwijl die indiening openstaat, krijg je 409 met E19009: corrigeer de indiening dan, zoals Een afgewezen antwoord corrigeren laat zien. Als we een gesloten indiening heropenen nadat het formulier is gewijzigd, vraagt next om een nieuwe indiening bij POST /v1/compliance/submissions.

De beoordeling volgen

Elk antwoord wordt afzonderlijk beoordeeld. Lees het nummer opnieuw en controleer ownership.status en ownership.next, zoals in Controleren of een nummer papierwerk nodig heeft. Om te zien hoe elk antwoord is beoordeeld, lees je de indiening met GET /v1/compliance/submissions/{submission_id} of lees je de vereisten opnieuw: elk veld bevat zijn state en, bij afwijzing, zijn reason.

Als een beoordeling klaar is, mailen we het resultaat naar de eigenaren van je organisatie en, als die er is, naar de laatst geregistreerde persoon die de indiening heeft ingediend of gecorrigeerd. Een eerste indiening met een API-sleutel gaat naar de eigenaren. Bij een latere correctie met een API-sleutel blijft de eerder geregistreerde persoon ontvanger. Je integratie leest het resultaat uit ownership.status.

Een afgewezen antwoord corrigeren

Stuur de vervangende antwoorden naar POST /v1/compliance/submissions/{submission_id}/resupply. Neem alleen de antwoorden op die je vervangt; de andere blijven ongewijzigd. Haal de submission_id uit de ownership van het nummer of uit het opvragen van de vereisten:

curl --request POST "$BIRD_API_URL/v1/compliance/submissions/$SUBMISSION_ID/resupply" \
  --header "Authorization: Bearer $BIRD_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ownership-fix-1-$NUMBER_ID" \
  --data '{"answers": [{"key": "business_registration_number", "value": "90012769"}]}'

Een 200-antwoord geeft de indiening met je vervangingen terug, die opnieuw worden beoordeeld. Zodra geen enkel verplicht antwoord nog afgewezen, verlopen of ontbrekend is, gaat de ownership.status van het nummer terug naar under_review. Vervang antwoorden waarvan de state rejected, expired of not_supplied is. Als we na het accepteren van je antwoorden om een correctie vragen, kun je ook een antwoord waarvan de editable_for_verifier_repair true is vervangen totdat die correctie sluit. Voor een antwoord in een andere status, bijvoorbeeld een antwoord dat nog wordt beoordeeld of dat buiten een door ons gevraagde correctie is geaccepteerd, krijg je 422 met E19003. Een vervangend document is een nieuwe upload: upload het eerst en stuur de attachment_id ervan mee.

Het papierwerk met de bestelling indienen

Als je de antwoorden al weet wanneer je het nummer koopt, stuur ze dan mee in het compliance-blok van de bestelling op POST /v1/numbers/orders, in dezelfde answers-vorm als de indiening. Om te lezen wat het land vraagt voordat je het nummer hebt, vraag je de vereisten op zonder subject_id, met COUNTRY_CODE en NUMBER_TYPE ingesteld op de country_code en number_type van het nummer in GET /v1/numbers/available:

curl "$BIRD_API_URL/v1/compliance/requirements?subject_kind=number&country_code=$COUNTRY_CODE&program=$NUMBER_TYPE" \
  --header "Authorization: Bearer $BIRD_API_KEY"

Een bestelling met een compliance-blok gebruikt de bestaande numbers-scope van de bestelling op schrijfniveau.

Zodra de bestelling is geaccepteerd, wordt ze hoe dan ook voltooid: als de indiening in het compliance-blok wordt geweigerd, blijft het nummer van jou en dien je in met POST /v1/compliance/submissions zoals in Alle antwoorden indienen. Als de antwoorden zijn ingediend, toont het nieuwe nummer under_review met zijn submission_id. Een nummer kopen en vrijgeven behandelt de bestelling zelf.

Een bedrijfsidentiteit hergebruiken

Gebruik GET /v1/compliance/identities/{identity_id} om het bedrijf en de opgeslagen antwoorden te lezen. Opgeslagen antwoorden kunnen een beoordelings-state, reason en decided_at bevatten; bij een waarde zonder beoordelingsbesluit kan de status ontbreken. Wijzig de naam van het bedrijf met PATCH /v1/compliance/identities/{identity_id}, of verwijder het met DELETE /v1/compliance/identities/{identity_id}. Voor lezen is compliance:read nodig; voor aanmaken, hernoemen en verwijderen is compliance:write nodig.

Wil je het bedrijf zelf laten verifiëren, maak dan eerst de identiteit aan. Lees de vereisten met subject_kind=identity, de cid_-identifier van de identiteit als subject_id, program=business en country_code=ZZ. Dien de gegevens in voor diezelfde identiteit. Een inline identiteit in een nummerinzending vervangt deze verificatie van de identiteit niet.

De beoordeling gebruikt de bedrijfsgegevens, opgegeven contactpersonen en het verificatiebewijs dat je hebt ingediend. Indienen via een API-sleutel of via het dashboard levert geen andere zakelijke relatie op. Houd contactgegevens actueel en lever het bewijs aan waar het formulier om vraagt.

Gegevens indienen voor een SMS-afzender

Voor de gegevens van een SMS-afzender gebruik je dezelfde verzoeken voor vereisten, bijlagen, inzendingen en correcties, met de registratie van de afzender als onderwerp. Een SMS-afzender registreren via de API beschrijft hoe je die registratie aanvraagt en eerst de prijs controleert.

Als een verzoek wordt geweigerd

Fouten legt de body van het foutantwoord en de bijbehorende remediation uit.

Volgende stappen

• Overzicht van nummers
• Een nummer kopen en vrijgeven
• Je telefoonnummers beheren
• Migreren van Telserv naar Bird