Eigentumsnachweis für eine Nummer einreichen

Manche Länder verlangen Angaben dazu, wer eine Nummer hält, bevor sie Datenverkehr übertragen kann. Bis dieser Nachweis akzeptiert und die Registrierung der Nummer abgeschlossen ist, ist die Nummer Ihnen zugewiesen und wird berechnet, ihr status ist jedoch pending_ownership_registration: Sie überträgt keine eingehenden oder ausgehenden Sprachanrufe und sendet keine SMS. Die Nummer überträgt Datenverkehr, sobald ihr status active und ihr ownership.blocked_at null ist. Sie reichen den Nachweis im Dashboard oder über die API ein. Beide Wege verwenden dieselben Anforderungen, Prüfregeln und denselben Registrierungsprozess. Das Feld ownership.next der Nummer nennt jeden Schritt, auch wann Sie eine neue Einreichung vornehmen müssen.

Die Angaben, die Sie einreichen, sind eine rechtsverbindliche Erklärung im Namen Ihres Unternehmens. Nach der Annahme werden sie unter dem Namen des beschriebenen Unternehmens an den Netzbetreiber oder die Regulierungsbehörde des jeweiligen Landes weitergegeben. Lassen Sie die Angaben deshalb vor dem Einreichen von der verantwortlichen Person bestätigen, und lassen Sie keinen automatisierten Job Angaben einreichen, die niemand geprüft hat.

Bevor Sie beginnen

• Um im Dashboard einzureichen, muss Ihre Rolle im Workspace das Bearbeiten von Compliance-Angaben erlauben. Ohne diese Berechtigung zeigt die Nummer ihren Eigentumsstatus, aber keine Schaltfläche zum Einreichen.
• Um über die eigenständigen Compliance-Endpunkte einzureichen, benötigen Sie einen API-Schlüssel mit dem Scope compliance auf Schreibebene. Ein Schlüssel mit Leseebene kann Anforderungen und den Prüffortschritt abfragen, aber nichts einreichen. Zum Lesen der Nummer ist zusätzlich der Scope numbers auf Leseebene nötig. In der Schlüsselauswahl des Dashboards finden Sie compliance unter Compliance.
• Die nda_-Kennung der Nummer aus GET /v1/numbers. Eine Nummer in Ihrer Liste finden zeigt, wie Sie sie ermitteln.

Die API-Beispiele lesen Ihren Schlüssel aus BIRD_API_KEY, seinen regionalen Host aus BIRD_API_URL und die Kennung der Nummer aus NUMBER_ID. Jeder spätere Schritt nennt die Variable, die er setzt. Die jq-Befehle extrahieren ein Feld aus einer Antwort. Wenn Sie jq nicht verwenden, lesen Sie das Feld manuell ab.

Prüfen, ob eine Nummer einen Nachweis benötigt

Lesen Sie die Nummer mit GET /v1/numbers/{number_id}:

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

Speichern Sie die country_code der Nummer als COUNTRY_CODE; sowohl das Abrufen der Anforderungen als auch die Einreichung benötigen sie:

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

ownership ist null, wenn das Land der Nummer keine Unterlagen verlangt. Es ist außerdem null, wenn wir den Bearbeitungsstand der Unterlagen nicht lesen konnten und für die Nummer keine Sperre erfasst ist; rufen Sie die Nummer dann erneut ab. Andernfalls enthält es:

• status: needs_input bedeutet, dass Antworten fehlen oder korrigiert werden müssen, under_review bedeutet, dass Ihre Antworten geprüft werden, approval_pending bedeutet, dass die Unterlagen angenommen sind und die Registrierung noch aussteht; Anrufe und ausgehende SMS bleiben gesperrt, solange blocked_at gesetzt ist. approved bedeutet, dass die Registrierung genehmigt ist, Anrufe und ausgehende SMS bleiben jedoch gesperrt, solange blocked_at gesetzt ist. not_required bedeutet, dass nichts weiter verlangt wird. rejected bedeutet, dass die Einreichung geschlossen wurde oder eine Korrekturfrist abgelaufen ist und keine weiteren Korrekturen mehr angenommen werden. Wenden Sie sich an den Support, um sie wieder öffnen zu lassen. unknown bedeutet, dass der Status nicht gelesen werden konnte; rufen Sie die Nummer erneut ab.
• next: die Schritte, mit denen die Unterlagen vorankommen, in ihrer Reihenfolge. Ein Schritt wait bedeutet, dass derzeit nichts von Ihnen verlangt wird. Rufen Sie ihn nach jeder Änderung erneut ab.
• submission_id: die letzte Einreichung für die Nummer, sobald eine vorhanden ist.
• blocked_at: der Zeitpunkt, zu dem die Eigentümersperre begann, oder null, sobald sie aufgehoben ist. Die Sperre blockiert eingehende und ausgehende Sprachanrufe sowie ausgehende SMS.

Der Status einer zugewiesenen Nummer erklärt, wie ownership mit dem eigenen status der Nummer zusammenhängt.

Über das Dashboard einreichen

1. Öffnen Sie die Nummer auf der Seite Numbers. Die Zeile Ownership zeigt den Status der Unterlagen und die nächsten Schritte.
2. Wenn der Status Details needed lautet, wählen Sie Update ownership details. Das Formular Prove ownership of this number öffnet sich.
3. Wählen Sie das Unternehmen, das die Nummer hält, oder beschreiben Sie ein neues. Beantworten Sie dann jeden Punkt und laden Sie die verlangten Dokumente hoch. Bietet ein Punkt ein leeres Formular an, ist es verlinkt, damit Sie es herunterladen, ausfüllen und wieder hochladen können.
4. Wählen Sie Submit answers.

Die Zeile Ownership wechselt zu Under review. Lehnt ein Prüfer eine Antwort ab, kehrt die Zeile zu Details needed zurück: Wählen Sie erneut Update ownership details, korrigieren Sie die Antworten, die das Formular anzeigt, und wählen Sie dann am Ende des Formulars Update ownership details, um sie zu senden.

Gibt es für das Land der Nummer noch kein Formular, zeigt die Formularseite Ownership form unavailable an. Wenden Sie sich an den Support, um ein Formular für dieses Land anzufragen.

Über die API einreichen

Um über die API einzureichen, lesen Sie, was das Land verlangt, laden Sie jedes Dokument hoch, senden Sie alle Antworten auf einmal und lesen Sie dann die Nummer, um die Prüfung zu verfolgen.

Lesen, was das Land verlangt

Lesen Sie die Anforderungen für die Nummer mit GET /v1/compliance/requirements. Setzen Sie subject_kind auf number, subject_id auf die nda_-Kennung der Nummer und country_code auf das eigene COUNTRY_CODE der 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"

Die Antwort nennt das program, unter dem die Nummer registriert wird; es richtet sich nach dem Nummerntyp. Speichern Sie es als PROGRAM. Die Antwort listet in fields jeden zu beantwortenden Punkt auf, in der Reihenfolge, in der Sie ihn anzeigen sollen. Für jedes Feld gilt:

• key gibt an, unter welchem Schlüssel Sie die Antwort senden.
• data_type gibt an, wie Sie das Feld beantworten. Ein document-Feld erwartet eine hochgeladene Datei; alle anderen Typen erwarten einen String, eine Zahl senden Sie also als "1500" und ein Ja oder Nein als "true". Ein enum-Feld akzeptiert einen seiner options.
• required gibt an, ob die Genehmigung von diesem Feld abhängt, und help_text beschreibt, wie eine gültige Antwort aussieht.
• max_items ist bei einem Feld gesetzt, das mehr als eine Antwort annimmt.
• template_url verlinkt ein leeres Formular, das Sie herunterladen, ausfüllen und wieder hochladen, sofern das Feld eines hat.
• state gibt an, wo das Element steht: not_supplied, bevor Sie antworten, danach supplied, in_review, approved oder rejected, wobei ein abgelehntes Element den reason des Prüfers trägt. Eine akzeptierte Antwort kann später expired anzeigen und muss dann erneut eingereicht werden. not_applicable kennzeichnet ein Element, das für Sie nicht gilt.

submission_id ist null, bis Sie einreichen. needs_input ist true, solange ein Element auf Sie wartet.

Ein 422 mit E19001 bedeutet, dass wir für dieses Land noch kein Eigentumsformular haben. Wenden Sie sich an den Support, um es anzufragen.

Jedes Dokument hochladen

Laden Sie jede Datei, die ein document-Feld verlangt, mit POST /v1/compliance/attachments hoch, als multipart/form-data-Body mit den Bytes in einem file-Teil. Speichern Sie die id aus der Antwort, also die tca_-Kennung des Anhangs, als ATTACHMENT_ID:

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

Akzeptiert werden PNG-, JPEG- und PDF-Dateien bis 10 MB. Der Typ wird aus dem Inhalt der Datei ermittelt. Eine 201-Antwort gibt den neuen Anhang zurück. Wenn Sie dieselbe Datei erneut hochladen, erhalten Sie den ersten Anhang mit 200 zurück. Ein erneuter Versuch beim Hochladen erzeugt also kein Duplikat. Ein Anhang, auf den sich keine Einreichung bezieht, läuft nach sieben Tagen ab.

Die download_url des Anhangs ist ein signierter Link, der ab dem Abrufen des Anhangs 24 Stunden gültig ist. Für einen neuen Link listen Sie Ihre Anhänge mit GET /v1/compliance/attachments auf, oder laden Sie die Bytes direkt mit GET /v1/compliance/attachments/{attachment_id} herunter.

Alle Antworten einreichen

Reichen Sie die Antworten mit POST /v1/compliance/submissions ein. Senden Sie subject_kind und subject_id, die program aus dem Abruf der Anforderungen sowie die country_code der Nummer. Senden Sie in answers einen Eintrag für jedes Feld, dessen required true ist, und einen für jedes optionale Feld, für das Sie eine echte Antwort haben. Lassen Sie ein optionales Feld weg, statt einen Wert dafür zu erfinden. Ein typisiertes Feld erhält value, ein Dokumentfeld attachment_id und ein Feld mit max_items erhält values oder attachment_ids. Speichern Sie den Body als submission.json und setzen Sie Ihre Werte anstelle von <NUMBER_ID>, <PROGRAM>, <COUNTRY_CODE> und <ATTACHMENT_ID> ein. Das Beispiel zeigt drei der Antworten, die ein Formular verlangt:

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

Senden Sie ihn mit einem Idempotency-Key. Verwenden Sie den Schlüssel nur dann erneut, wenn Sie denselben Body erneut senden: Eine Ablehnung kann gespeichert und wiedergegeben werden. Korrigieren Sie daher nach einem 422 den Body und senden Sie ihn mit einem neuen Schlüssel. Idempotenz erklärt, was gespeichert wird.

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

Es gibt keine Entwürfe: Diese Anfrage reicht die Antworten zur Prüfung ein und muss daher jede erforderliche Antwort enthalten. Fehlt ein erforderliches Feld oder lehnt das Formular eine Antwort ab, erhalten Sie einen 422 mit E01001 und einem Eintrag in details pro Feld, benannt in param. Dann wird nichts eingereicht. Eine 201-Antwort gibt die Einreichung mit allen Antworten zurück. Speichern Sie deren id, die csb_-Kennung der Einreichung, als SUBMISSION_ID.

Ein Unternehmen, das Ihr Workspace beschreibt, ist eine Identität. Erstellen Sie eine im Identity Center des Dashboards oder mit POST /v1/compliance/identities und senden Sie dabei ihren Anzeige-name. Eine Einreichung für eine Nummer kann statt einer identity_id auch eine Inline-identity enthalten. Die identity_id in der Antwort auf die Einreichung benennt die neue Identität, die POST /v1/compliance/identities als id zurückgibt. Verwenden Sie diese für weitere Nummern, statt eine neue zu erstellen. Um für eine Identität einzureichen, fügen Sie ihre identity_id hinzu. Die dort gespeicherten Antworten ergänzen dann die Antworten, die Sie weglassen. GET /v1/compliance/identities listet die Unternehmensidentitäten auf. Die eingereichten Einzelwert-Antworten werden unabhängig vom Prüfergebnis in die Identität zurückgeschrieben, sodass die nächste Einreichung mit dieser Identität von ihnen ausgeht. Dokumente und Mehrfachwert-Antworten werden jedes Mal neu abgefragt. Verwenden Sie eine Identität pro Unternehmen: Wenn Sie für mehrere Endkunden einreichen, geben Sie jedem eine eigene Identität. Sonst ergänzen die genehmigten Antworten eines Kunden die eines anderen.

Folgen Sie ownership.next, statt erneut einzureichen. Eine Nummer hat pro Version des Formulars ihres Landes eine Einreichung. Wenn Sie erneut einreichen, während diese Einreichung offen ist, antwortet die API mit 409 und E19009. Korrigieren Sie die Einreichung stattdessen, wie Abgelehnte Antwort korrigieren zeigt. Wenn wir eine geschlossene Einreichung nach einer Formularänderung wieder öffnen, fordert next eine neue Einreichung an POST /v1/compliance/submissions an.

Prüfung verfolgen

Jede Antwort wird einzeln geprüft. Lesen Sie die Nummer erneut und prüfen Sie ownership.status und ownership.next, wie unter Prüfen, ob eine Nummer Unterlagen benötigt beschrieben. Um zu sehen, wie jede Antwort bewertet wurde, lesen Sie die Einreichung mit GET /v1/compliance/submissions/{submission_id} oder lesen Sie die Anforderungen erneut: Jedes Feld enthält seinen state und bei einer Ablehnung seinen reason.

Wenn eine Prüfung abgeschlossen ist, senden wir das Ergebnis per E-Mail an die Inhaber Ihrer Organisation und, falls vorhanden, an die zuletzt erfasste Person, die die Einreichung eingereicht oder korrigiert hat. Eine erste Einreichung per API-Schlüssel geht an die Inhaber. Bei einer späteren Korrektur per API-Schlüssel bleibt die zuvor erfasste Person Empfänger. Ihre Integration erfährt das Ergebnis, indem sie ownership.status liest.

Abgelehnte Antwort korrigieren

Senden Sie die Ersatzantworten an POST /v1/compliance/submissions/{submission_id}/resupply. Geben Sie nur die Antworten an, die Sie ersetzen; die übrigen bleiben unverändert. Entnehmen Sie die submission_id dem ownership der Nummer oder dem Abruf der Anforderungen:

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

Eine Antwort mit 200 gibt die Einreichung mit Ihren Ersatzantworten zurück, die erneut geprüft werden. Sobald keine erforderliche Antwort mehr abgelehnt, abgelaufen oder fehlend ist, kehrt der ownership.status der Nummer zu under_review zurück. Ersetzen Sie Antworten, deren state rejected, expired oder not_supplied ist. Wenn wir nach der Annahme Ihrer Antworten eine Korrektur anfordern, können Sie auch eine Antwort mit dem editable_for_verifier_repair true ersetzen, bis diese Korrektur abgeschlossen ist. Für eine Antwort in einem anderen Zustand, etwa eine noch in Prüfung befindliche oder eine außerhalb einer von uns angeforderten Korrektur angenommene, antwortet die API mit 422 und E19003. Ein Ersatzdokument ist ein neuer Upload: Laden Sie es zuerst hoch und senden Sie seine attachment_id.

Unterlagen mit der Bestellung einreichen

Wenn Sie die Antworten beim Kauf der Nummer kennen, senden Sie sie im compliance-Block der Bestellung an POST /v1/numbers/orders, in derselben answers-Struktur wie bei der Einreichung. Um vor dem Erwerb der Nummer zu lesen, was das Land verlangt, rufen Sie die Anforderungen ohne subject_id ab und setzen Sie COUNTRY_CODE und NUMBER_TYPE auf country_code und number_type der 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"

Eine Bestellung mit einem compliance-Block verwendet den bestehenden numbers-Scope der Bestellung mit Schreibrecht.

Sobald die Bestellung angenommen ist, wird sie in jedem Fall abgeschlossen: Wird die Einreichung im compliance-Block abgelehnt, gehört die Nummer trotzdem Ihnen, und Sie reichen mit POST /v1/compliance/submissions ein, wie unter Alle Antworten einreichen beschrieben. Sobald die Antworten eingereicht sind, zeigt die neue Nummer under_review mit ihrem submission_id. Nummer kaufen und freigeben beschreibt die Bestellung selbst.

Unternehmensidentität wiederverwenden

Mit GET /v1/compliance/identities/{identity_id} lesen Sie das Unternehmen und seine gespeicherten Antworten. Gespeicherte Antworten können einen Prüfstatus state, reason und decided_at enthalten; bei einem Wert ohne Prüfentscheidung kann der Status fehlen. Benennen Sie das Unternehmen mit PATCH /v1/compliance/identities/{identity_id} um, oder entfernen Sie es mit DELETE /v1/compliance/identities/{identity_id}. Lesezugriffe benötigen compliance:read; Erstellen, Umbenennen und Löschen benötigen compliance:write.

Um das Unternehmen selbst zu verifizieren, erstellen Sie zuerst die Identität. Lesen Sie die Anforderungen mit subject_kind=identity, ihrer cid_-Kennung als subject_id, program=business und country_code=ZZ. Reichen Sie die Unterlagen für genau diese Identität ein. Eine Inline-Identität in einer Einreichung für eine Nummer ersetzt diesen Ablauf zur Identitätsverifizierung nicht.

Die Prüfung stützt sich auf Ihre eingereichten Unternehmensangaben, die angegebenen Kontakte und die Nachweise zur Verifizierung. Eine Einreichung über einen API-Schlüssel oder das Dashboard begründet keine andere Geschäftsbeziehung. Halten Sie die Kontaktdaten aktuell, und legen Sie die Nachweise vor, die das Formular verlangt.

Unterlagen stattdessen für einen SMS-Absender einreichen

Für die Unterlagen eines SMS-Absenders gelten dieselben Anforderungen, Anhänge sowie Anfragen zur Einreichung und Korrektur; Gegenstand ist dabei die Registrierung des Absenders. Einen SMS-Absender über die API registrieren beschreibt, wie Sie diese Registrierung erhalten und vorher ihren Preis prüfen.

Wenn eine Anfrage abgelehnt wird

Fehler erklärt die Fehlerantwort und ihr Feld remediation.

Nächste Schritte

• Übersicht über Nummern
• Eine Nummer kaufen und freigeben
• Ihre Telefonnummern verwalten
• Von Telserv zu Bird migrieren