Déposer les justificatifs de titularité d'un numéro

Certains pays exigent de savoir qui détient un numéro avant qu'il puisse acheminer du trafic. Tant que ces justificatifs ne sont pas acceptés et que l'enregistrement du numéro n'est pas terminé, le numéro vous est attribué et facturé, mais son status vaut pending_ownership_registration : il n'achemine aucun appel vocal entrant ou sortant et n'envoie aucun SMS. Le numéro achemine du trafic dès que son status vaut active et que son ownership.blocked_at vaut null. Vous déposez les justificatifs depuis le tableau de bord ou avec API, et les deux méthodes appliquent les mêmes exigences, les mêmes règles d'examen et le même processus d'enregistrement. Le champ ownership.next du numéro indique chaque étape, y compris le moment où déposer une nouvelle soumission.

Les réponses que vous déposez constituent une déclaration juridique faite au nom de votre entreprise. Une fois acceptées, elles sont transmises à l'opérateur ou à l'autorité de régulation du pays concerné, au nom de l'entreprise qu'elles décrivent. Faites-les donc valider par la personne qui en est responsable avant de les déposer, et ne laissez pas une tâche automatisée déposer des réponses que personne n'a vérifiées.

Avant de commencer

• Pour déposer depuis le tableau de bord, votre rôle dans l'espace de travail doit autoriser la modification des informations de conformité. Sans cette autorisation, le numéro affiche son statut de titularité, mais aucun bouton de dépôt.
• Pour déposer via les endpoints de conformité autonomes, il vous faut une clé API disposant du scope compliance en écriture. Une clé en lecture peut consulter les exigences et suivre l'examen, mais pas déposer. La lecture du numéro nécessite aussi le scope numbers en lecture. Dans le sélecteur de clés du tableau de bord, compliance se trouve sous Compliance.
• L'identifiant nda_ du numéro, obtenu avec GET /v1/numbers. Trouver un numéro dans votre liste explique comment le retrouver.

Les exemples API lisent votre clé dans BIRD_API_KEY, son hôte régional dans BIRD_API_URL et l'identifiant du numéro dans NUMBER_ID. Chaque étape suivante indique la variable qu'elle définit. Les commandes jq extraient un champ d'une réponse ; si vous n'utilisez pas jq, lisez ce champ manuellement.

Vérifier si un numéro nécessite des justificatifs

Lisez le numéro avec GET /v1/numbers/{number_id} :

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

Conservez la valeur country_code du numéro dans COUNTRY_CODE ; la lecture des exigences et la soumission l’utilisent toutes les deux :

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

ownership vaut null lorsque le pays du numéro n’exige aucun dossier. Il vaut aussi null lorsque nous n’avons pas pu lire l’avancement du dossier et qu’aucun blocage n’est enregistré sur le numéro ; lisez à nouveau le numéro. Sinon, il contient :

• status : needs_input signifie que des réponses manquent ou doivent être corrigées, under_review signifie que vos réponses sont en cours d’examen, approval_pending signifie que le dossier est accepté et que l’enregistrement est encore en attente ; les appels et les SMS sortants restent bloqués tant que blocked_at est défini. approved signifie que l’enregistrement est approuvé, mais les appels et les SMS sortants restent bloqués tant que blocked_at est défini. not_required signifie que plus rien n’est demandé. rejected signifie que la soumission a été clôturée, ou qu’un délai de correction a expiré, et qu’elle n’accepte plus de corrections. Contactez le support pour la faire rouvrir. unknown signifie que le statut n’a pas pu être lu ; lisez à nouveau le numéro.
• next : les étapes qui font avancer le dossier, dans l’ordre. Une étape wait signifie que rien ne vous est demandé pour l’instant. Relisez ce champ après chaque modification.
• submission_id : la soumission la plus récente pour le numéro, dès qu’il en existe une.
• blocked_at : le moment où le blocage lié à la propriété a commencé, ou null une fois qu’il est levé. Le blocage empêche les appels vocaux entrants et sortants ainsi que les SMS sortants.

Le statut d’un numéro attribué explique le lien entre ownership et le status propre au numéro.

Déposer le dossier depuis le tableau de bord

1. Ouvrez le numéro depuis la page Numbers. Sa ligne Ownership affiche le statut du dossier et les prochaines étapes.
2. Lorsque le statut est Details needed, sélectionnez Update ownership details. Le formulaire Prove ownership of this number s’ouvre.
3. Choisissez l’entreprise titulaire du numéro, ou décrivez-en une nouvelle, puis répondez à chaque élément et importez les documents demandés. Lorsqu’un élément propose un formulaire vierge, il fournit un lien pour le télécharger, le remplir et le réimporter.
4. Sélectionnez Submit answers.

La ligne Ownership passe à Under review. Si un examinateur rejette une réponse, la ligne revient à Details needed : sélectionnez de nouveau Update ownership details, corrigez les réponses que le formulaire indique, puis sélectionnez Update ownership details à la fin du formulaire pour les envoyer.

Si aucun formulaire n’existe encore pour le pays du numéro, la page du formulaire affiche Ownership form unavailable. Contactez le support pour demander ce pays.

Déposer avec l’API

Pour déposer avec l’API, lisez ce que le pays demande, téléversez chaque document, soumettez toutes les réponses en une fois, puis lisez le numéro pour suivre l’examen.

Lire ce que le pays demande

Lisez les exigences du numéro avec GET /v1/compliance/requirements. Définissez subject_kind sur number, subject_id sur l’identifiant nda_ du numéro, et country_code sur le COUNTRY_CODE propre au numéro :

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

La réponse indique le program sous lequel le numéro est enregistré, qui dépend de son type de numéro ; conservez-le dans PROGRAM. Elle liste dans fields chaque élément auquel répondre, dans l’ordre où les présenter. Pour chaque champ :

• key est la clé sous laquelle vous envoyez la réponse.
• data_type indique comment y répondre. Un champ document attend un fichier téléversé ; tous les autres types attendent une chaîne : un nombre s’envoie donc sous la forme "1500" et un oui ou non sous la forme "true". Un champ enum accepte l’une de ses valeurs options.
• required indique si l’approbation en dépend, et help_text décrit une réponse valable.
• max_items est défini sur un champ qui accepte plusieurs réponses.
• template_url donne le lien vers un formulaire vierge à télécharger, remplir et téléverser, lorsque le champ en possède un.
• state indique l'état de l'élément : not_supplied avant votre réponse, puis supplied, in_review, approved ou rejected, avec le reason de l'examinateur sur un élément refusé. Une réponse acceptée peut ensuite indiquer expired et doit alors être fournie de nouveau, et not_applicable signale un élément qui ne vous concerne pas.

submission_id vaut null tant que vous n'avez rien déposé. needs_input vaut true tant qu'un élément attend une action de votre part.

Une réponse 422 avec E19001 signifie que nous ne disposons pas encore de formulaire de propriété pour ce pays. Contactez le support pour le demander.

Téléverser chaque document

Téléversez chaque fichier demandé par un champ document avec POST /v1/compliance/attachments, sous forme de corps multipart/form-data contenant les octets dans une partie file. Conservez le id de la réponse, l'identifiant tca_ de la pièce jointe, dans ATTACHMENT_ID :

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

Les fichiers PNG, JPEG et PDF jusqu'à 10 Mo sont acceptés, et le type est déterminé à partir du contenu du fichier. Une réponse 201 renvoie la nouvelle pièce jointe. Si vous téléversez de nouveau le même fichier, la première pièce jointe est renvoyée avec 200 : réessayer un téléversement ne crée donc pas de doublon. Une pièce jointe citée par aucune soumission expire au bout de sept jours.

Le download_url de la pièce jointe est un lien signé valable 24 heures à partir du moment où vous avez récupéré la pièce jointe. Listez vos pièces jointes avec GET /v1/compliance/attachments pour en obtenir un nouveau, ou téléchargez directement les octets avec GET /v1/compliance/attachments/{attachment_id}.

Soumettre toutes les réponses

Déposez les réponses avec POST /v1/compliance/submissions. Envoyez subject_kind et subject_id, le program indiqué par la lecture des exigences, ainsi que le country_code du numéro. Dans answers, envoyez une entrée pour chaque champ dont le required vaut true, et une pour chaque champ facultatif auquel vous pouvez donner une vraie réponse. Omettez un champ facultatif plutôt que de lui inventer une valeur. Un champ typé prend value, un champ de document prend attachment_id, et un champ avec max_items prend values ou attachment_ids. Enregistrez le corps dans submission.json, en remplaçant <NUMBER_ID>, <PROGRAM>, <COUNTRY_CODE> et <ATTACHMENT_ID> par vos valeurs. L'exemple montre trois des réponses demandées par un formulaire :

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

Envoyez-le avec une Idempotency-Key. Ne réutilisez la clé que pour réessayer avec le même corps : un refus peut être conservé et rejoué. Après une réponse 422, corrigez donc le corps et envoyez-le avec une nouvelle clé. Idempotence explique ce qui est conservé.

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

Il n'existe pas de brouillon : cette requête dépose les réponses pour examen, elle doit donc contenir toutes les réponses obligatoires. Si vous omettez un champ obligatoire ou si le formulaire refuse une réponse, vous recevez une réponse 422 avec E01001 et une entrée dans details par champ, nommé dans param, et rien n'est déposé. Une réponse 201 renvoie la soumission avec toutes ses réponses. Conservez son id, l'identifiant csb_ de la soumission, dans SUBMISSION_ID.

Une entreprise décrite par votre espace de travail est une identité. Créez-en une dans l'Identity Center du tableau de bord ou avec POST /v1/compliance/identities, en envoyant son name d'affichage. Une soumission de numéro peut aussi contenir un identity intégré au lieu d'un identity_id. Le identity_id de la réponse à la soumission désigne la nouvelle identité, que POST /v1/compliance/identities renvoie sous la forme id. Réutilisez-la pour les numéros suivants au lieu d'en créer une autre. Pour déposer au nom d'une identité, ajoutez son identity_id : les réponses qu'elle contient complètent celles que vous omettez. GET /v1/compliance/identities liste les identités d'entreprise. Les réponses à valeur unique que vous déposez sont enregistrées sur l'identité quelle que soit la décision de l'examen, et la soumission suivante qui la désigne part donc de ces réponses. Les documents et les réponses à valeurs multiples sont redemandés à chaque fois. Utilisez une identité par entreprise : si vous déposez pour plusieurs clients finaux, attribuez à chacun sa propre identité, sinon les réponses approuvées d'un client compléteront celles d'un autre.

Suivez ownership.next plutôt que de déposer une nouvelle soumission. Un numéro a une seule soumission par version du formulaire de son pays : déposer de nouveau pendant que cette soumission est ouverte renvoie 409 avec E19009. Corrigez-la plutôt, comme l’explique Corriger une réponse rejetée. Lorsque nous rouvrons une soumission fermée après une modification du formulaire, next demande une nouvelle soumission à POST /v1/compliance/submissions.

Suivre l’examen

Chaque réponse est examinée séparément. Lisez de nouveau le numéro et vérifiez ownership.status et ownership.next, comme dans Vérifier si un numéro nécessite des justificatifs. Pour savoir comment chaque réponse a été évaluée, lisez la soumission avec GET /v1/compliance/submissions/{submission_id}, ou lisez de nouveau les exigences : chaque champ indique son state et, s’il est rejeté, son reason.

À la fin d’un examen, nous envoyons le résultat par e-mail aux propriétaires de votre organisation et, le cas échéant, à la dernière personne enregistrée ayant déposé ou corrigé la soumission. Un premier dépôt effectué avec une clé API est notifié aux propriétaires. Une correction ultérieure effectuée avec une clé API conserve la personne enregistrée précédemment comme destinataire. Votre intégration obtient le résultat en lisant ownership.status.

Corriger une réponse rejetée

Envoyez les réponses de remplacement à POST /v1/compliance/submissions/{submission_id}/resupply. N’incluez que les réponses que vous remplacez ; les autres restent inchangées. Prenez le submission_id dans le ownership du numéro ou dans la lecture des exigences :

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

Une réponse 200 renvoie la soumission avec vos remplacements, qui repartent en examen. Dès qu’aucune réponse obligatoire n’est plus rejetée, expirée ou manquante, le ownership.status du numéro revient à under_review. Remplacez les réponses dont le state est rejected, expired ou not_supplied. Si nous demandons une correction après avoir accepté vos réponses, une réponse dont le editable_for_verifier_repair est true peut aussi être remplacée jusqu’à la clôture de cette correction. Une réponse dans tout autre état, par exemple encore en cours d’examen ou acceptée en dehors d’une correction que nous avons demandée, renvoie 422 avec E19003. Un document de remplacement est un nouveau téléversement : téléversez-le d’abord, puis envoyez son attachment_id.

Déposer les justificatifs avec la commande

Si vous connaissez les réponses au moment d’acheter le numéro, envoyez-les dans le bloc compliance de la commande sur POST /v1/numbers/orders, avec la même structure answers que la soumission. Pour savoir ce que le pays demande avant de détenir le numéro, appelez la lecture des exigences sans subject_id, en définissant COUNTRY_CODE et NUMBER_TYPE sur le country_code et le number_type du numéro dans 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"

Une commande comportant un bloc compliance utilise le scope numbers existant de la commande, au niveau écriture.

Une fois la commande acceptée, elle aboutit dans tous les cas : si le dépôt du bloc compliance est refusé, le numéro vous appartient quand même, et vous déposez les justificatifs avec POST /v1/compliance/submissions comme dans Soumettre toutes les réponses. Une fois les réponses déposées, le nouveau numéro indique under_review avec son submission_id. Acheter et libérer un numéro décrit la commande elle-même.

Réutiliser l’identité d’une entreprise

Utilisez GET /v1/compliance/identities/{identity_id} pour lire l’entreprise et ses réponses enregistrées. Les réponses enregistrées peuvent inclure un state de revue, reason et decided_at ; une valeur sans décision de revue peut omettre son état. Renommez l’entreprise avec PATCH /v1/compliance/identities/{identity_id} ou supprimez-la avec DELETE /v1/compliance/identities/{identity_id}. Les lectures nécessitent compliance:read ; la création, le renommage et la suppression nécessitent compliance:write.

Pour faire vérifier l’entreprise elle-même, créez d’abord l’identité. Lisez les exigences avec subject_kind=identity, son identifiant cid_ comme subject_id, program=business et country_code=ZZ. Déposez ensuite le dossier pour cette même identité. Une identité intégrée à une soumission de numéro ne remplace pas ce processus de vérification d’identité.

La revue s’appuie sur les informations d’entreprise soumises, les contacts déclarés et les justificatifs de vérification. Déposer le dossier avec une clé API ou depuis le tableau de bord n’établit pas une relation commerciale différente. Tenez les coordonnées à jour et fournissez les justificatifs demandés par le formulaire.

Déposer plutôt le dossier d’un expéditeur SMS

Le dossier d’un expéditeur SMS utilise les mêmes requêtes d’exigences, de pièces jointes, de soumission et de correction, avec l’enregistrement de l’expéditeur comme objet. Enregistrer un expéditeur SMS via l’API explique comment obtenir cet enregistrement et vérifier d’abord son prix.

Quand une requête est refusée

Erreurs décrit le corps de la réponse d'erreur et son remediation.

Étapes suivantes

• Présentation des numéros
• Acheter et libérer un numéro
• Gérer vos numéros de téléphone
• Migrer de Telserv vers Bird