Intégration KYC/KYB/IDV de l’organisation

L’étape 5 de la Quickstart nomme deux contrôles obligatoires avant le trafic en direct : un KYC d’organisation approuvé et un solde approvisionné. Le KYC d’organisation est une revue unique par workspace — il vérifie l’entreprise elle-même, pas ses numéros (les dossiers de documents par numéro sont une préoccupation distincte ; comparez à la fin de ce guide). Ce guide couvre la boucle complète — soumission, session optionnelle de vérification d’identité hébergée, consultation du verdict, re-soumission après rejet — puis les contrôles restants avant le go-live.

1. Pourquoi le trafic en direct est bloqué

Les envois en direct sont restreints jusqu’à ce qu’un membre de l’équipe d’exploitation Devotel ait examiné un profil d’entreprise réel. Tant que l’approbation n’est pas acquise :

L’achat de numéros reste possible, mais aucun SMS, message WhatsApp ni appel vocal ne quitte la plateforme.
Le tableau de bord affiche le statut dans une bannière ; la même page traitée par ce guide est accessible depuis Paramètres → KYC.

Deux statuts font avancer la revue. not_started signifie que le formulaire n’a jamais été soumis. pending_review signifie qu’une file d’attente d’opérateurs traite la soumission (le webhook de confirmation d’email pré-inscrit ce statut à l’inscription ; le formulaire ci-dessous le remplace par un dossier détaillé). Après décision, vous obtenez approved ou rejected.

2. Soumettez le formulaire

POST vers /api/v1/organization/kyc/submit avec le profil d’entreprise. L’API valide : nom de l’entreprise et pays obligatoires, site web facultatif, description d’au moins dix caractères, bénéficiaires effectifs facultatifs (20 maximum, pour le ciblage de screening).

curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/submit \
  -H "X-API-Key: $ORBIT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Logistics Ltd.",
    "company_website": "https://acme-logistics.example",
    "country": "US",
    "industry": "Logistique",
    "use_case": "Notifications de statut de livraison envoyées aux clients ayant souscrit au moment du paiement.",
    "estimated_monthly_volume": 45000,
    "registration_number": "DE-554433",
    "beneficial_owners": [
      { "name": "Maria Alvarez", "ownership_percentage": 100 }
    ]
  }'

import { Devotel } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

const result = await orbit.organization.kyc.submit({
  company_name: 'Acme Logistics Ltd.',
  company_website: 'https://acme-logistics.example',
  country: 'US',
  industry: 'Logistique',
  use_case: 'Notifications de livraison pour clients ayant consenti.',
  estimated_monthly_volume: 45000,
});
console.log(result.data.status); // "pending_review"

Une réponse réussie inscrit pending_review et renvoie l’enregistrement stocké plus le verdict de screening — la revue est humaine, rien ne s’approuve ni ne se rejette automatiquement. Réponse (200) :

{
  "data": {
    "status": "pending_review",
    "kyc": {
      "status": "pending_review",
      "company_name": "Acme Logistics Ltd.",
      "country": "US",
      "submitted_at": "2026-09-04T09:12:33Z"
    },
    "kyb": {
      "status": "review",
      "matches": [],
      "legal_name": "Acme Logistics Ltd.",
      "country": "US",
      "screened_at": "2026-09-04T09:12:33Z"
    },
    "message": "Your KYC submission has been received and is awaiting review."
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-09-04T09:12:33Z" }
}

data.kyb est le signal de screening (clear si l’entité est propre, review si un pays sanctionné ou une partie interdite a matché). Il est examiné avec le formulaire — il ne bloque pas la soumission et un verdict review nécessite la même relecture humaine. Le champ est omis lorsque le screening n’a pas pu s’exécuter (file manuelle alors activée).

3. Marches par marché — ce que votre destination exige réellement

Le formulaire ci-dessus est soumis une seule fois par organisation, mais le poids des champs à la revue dépend de la destination. Le country soumis ancre le marché — répondez avec la destination marché et non l’adresse de facturation ; un expéditeur visant l’UK qui renseigne country: "US" reçoit simplement un renvoi pour correction. Deux groupes de champs arrivent toujours au réviseur : use_case, et les champs identitaires KYB (registration_number, beneficial_owners). Une organisation ciblant plusieurs marchés bloqués répéte le modèle documentaire une fois par destination — regroupez les uploads par destination dans la bibliothèque plutôt que de diluer un seul formulaire. Les marchés ci-dessous bloquent les envois jusqu’à enregistrement préalable. Pour chacun : les champs à accentuer, et les rôles documentaires que le régulateur demande. Les uploads vont sous Conformité → Documents et se référencent par identifiant à travers les enregistrements ; les rôles visibles de revue sont business_doc, address_proof, id_proof, authorization. La matrice marché Sender-ID porte le niveau live registration par pays ; le guide documents couvre le flux d’upload.

Allemagne — BNetzA identité entity

BNetzA (registre des registres) valide l’identité derrière chaque alphabétique et chaque participation vocale KYC. Accentuez registration_number (le registre du commerce local) et une vraie dénomination sociale. Documents demandés : business_doc (extrait du registre du commerce).

Espagne — CNMC voe sender-id / Itinérances

La CNMC valide les envois dérivant sur un sender-id enregistré avant sortie du sandbox. Accentuez registration_number et une use_case ciblée sur le destinataire espagnol (SMS de suivi). Documents : business_doc (CIF/NIF de l’entité).

France — ARCEP registration d’identité

L’ARCEP et les opérateurs registrent l’identité portant le sender alphabétique ; les marques non déposées reçoivent un rejet des routes SMS. Accentuez registration_number (immatriculation RCS) avec une use_case refermé sur le trafic déclaré. Documents : business_doc (extrait Kbis ou SIREN) plus authorization si un encquirement agit pour une marque.

Turquie — BTK sender-name

Le BTK enregistre le nom de l’envoyeur — pas simplement la route : déposez le nom que vos clients verront et mentionnez-le en use_case. Documents : business_doc (veilles documents de la chambre de commerce).

Marchés arabes — exemple EAU TDRA

Certains marchés arabophones (EAU par exemple, TDRA + opérateurs e&/du) attendent une marque KYC-bliée au sender — l’habillage la plus susceptible de renvoyer une soumission mince. Accentuez company_name, company_website et une use_case complète. Documents : business_doc plus authorization de marque. Dans chaque marché le but est le même : décidez ce que vous écrivez dans company_name, use_case et registration_number avant qu’un filtre à l’envoi ne rejette le trafic avec un 422. Send Gates explique comment une destination required bloque les envois non enregistrés. Pour la lecture sous les marchés anglophones ou historiques (UK, Arabie Saoudite, EAU, Brésil, Inde DLT, US 10DLC), consulter la version anglaise du guide.

4. Option : ajoutez une session IDV hébergée

Certains opérateurs exigent une pièce d’identité gouvernementale puis un liveness-check avant de signer. POST /api/v1/organization/kyc/idv/session ouvre une session hébergée chez le fournisseur provisionné ; ouvrez l’URL renvoyée dans un navigateur ou remettez-la au signataire.

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/idv/session \
  -H "X-API-Key: $ORBIT_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "redirect_url": "https://your-app.example/kyc/return" }'

Réponse (200) :

{
  "data": {
    "status": "pending",
    "provider": "idv",
    "session_id": "sess_9f2b7c",
    "hosted_url": "https://hosted-idv.example/sessions/sess_9f2b7c",
    "reason": null,
    "created_at": "2026-09-04T09:13:04Z",
    "updated_at": "2026-09-04T09:13:04Z"
  },
  "meta": { "request_id": "req_def456", "timestamp": "2026-09-04T09:13:04Z" }
}

Tant qu’aucun opérateur n’a provisionné un fournisseur, le endpoint répond 503 :

{ "error": { "code": "IDV_NOT_CONFIGURED", "message": "Identity verification is not available for this account", "status": 503 } }

Obtenez le verdict du provider avec GET /api/v1/organization/kyc/idv/status. Il se reconcialise : tant que la session stockée est pending, chaque GET interroge le fournisseur puis inscrit la transition terminale. Un terminal verified, declined ou expired — avec un reason quand le provider le fournit — rejoint le signal que l’opérateur pèse. Il n’est pas auto-approuveur : un verified identifer n’approuve PAS le KYC, et un declined ne le rejette pas.

{
  "data": {
    "status": "verified",
    "provider": "idv",
    "session_id": "sess_9f2b7c",
    "hosted_url": "https://hosted-idv.example/sessions/sess_9f2b7c",
    "reason": null,
    "created_at": "2026-09-04T09:13:04Z",
    "updated_at": "2026-09-04T09:44:12Z",
    "configured": true
  }
}

5. Surveillez le verdict de l’organisation

Pollez GET /api/v1/organization/kyc/status jusqu’au verdict. Les états disponibles sont not_started, pending (transitoire avant soumission), pending_review, approved et rejected ; la réponse écho aussi les champs d’entreprise soumis et reviewed_at une fois la décision rendue.

cURL

curl https://api.orbit.devotel.io/api/v1/organization/kyc/status \
  -H "X-API-Key: $ORBIT_TEST_KEY"

Réponse (200) :

{
  "data": {
    "status": "pending_review",
    "company_name": "Acme Logistics Ltd.",
    "country": "US",
    "industry": "Logistique",
    "submitted_at": "2026-09-04T09:12:33Z",
    "reviewed_at": null,
    "source": null
  },
  "meta": { "request_id": "req_ghi789", "timestamp": "2026-09-04T09:15:00Z" }
}

Les anciennes versions du SDK lisent parfois le chemin bat GET /api/v1/organization/kyc ; il sert le même schéma de réponse, donc diriger vers /kyc/status reste sûr et rétro-compatible. Le endpoint est sûr à poller depuis le tableau de bord ou un serveur — il dégrade en not_started neutre sur un blip de base de données transitoire plutôt que de gâcher un 503, et la lecture suivante s’auto-corrige.

6. Re-soumission et la barrière « déjà vérifié »

POSTer à nouveau le formulaire est la bonne démarche sur un rejected : l’écriture re-tamponne pending_review, écrase le bloc formulaire et relance le screening avec les réponses corrigées. Une re-soumission encore pending_review est aussi acceptée — elle remplace le profil en vol. Re-soumettre une organisation approved renvoie 409 :

{
  "error": {
    "code": "ALREADY_VERIFIED",
    "message": "KYC verification has already been approved",
    "status": 409
  }
}

La même barrière s’applique à une session IDV une fois l’identité verified — un POST sur le endpoint de session reçoit alors 409 ALREADY_VERIFIED, et une re-capture ne fait sens qu’après une rejet de l’org relancé.

7. Ce qu’un rejet signifie et que faire

Un rejet est un verdict humain — l’opérateur parcourt le panneau d’exploitation Devotel, lit vos champs plus le screening et l’IDO, et frappe approve ou reject. La surface client n’expose jamais de raison machinale ; l’email de décision nomme le vide et la correction. Traitez rejected comme agissant :

Relisez les champs soumis pour l’exactitude (un nom légal mal émis ou une use-case mince est le bloc le plus fréquent).
Corrigez tout match kyb et tout résultat IDV declined.
Re-soumettez avec les données corrigées — le endpoint accepte et la file se réordonne.

Si le rejet est clairement une erreur — par exemple un sel dans le panneau d’opérateur plutôt que dans vos données — déposez auprès du support avec l’id de compte et l’identifiant req_ de la consultation de status ; le propriétaire de la file de revue peut rouvrir le dossier et l’approuver côté opérateur.

Ce que cette barrière n’est PAS : documents par numéro

Le KYC d’organisation se place à côté des dossiers documentaires que les opérateurs demandent par numéro — ceux-ci (enregistrement d’entreprise, justificatif d’adresse, identité) couvrent un numéro que vous possédez et suivent une boucle de revue distincte sous Conformité → Documents. Approuver l’organisation ne réglera pas un dossier par numéro, et inversement: voir le guide documents KYC par numéro pour ce registre séparé.

8. Une fois approuvé — les dernières barrières du go-live

L’approbation bascule le verdict d’organisation, donc GET /organization/kyc/status renvoie approved. Achevez les deux derniers contrôles de la checklist go-live :

Frappez la clé en direct. Sous Paramètres → Clés API, créez un secret avec le préfixe dv_live_sk_ et remplacez la clé sandbox dv_test_sk_ — les formes de requête sont identiques, donc aucun rewrite du code n’est requis.
Approvisionnez le solde. Ajoutez des fonds sous Paramètres → Facturation ; SMS, WhatsApp et voix déduisent de ce portefeuille, et les envois en direct échouent avec une erreur de facturation tant que le solde est vide.
SMS US : ajoutez 10DLC. Si la destination inclut les long-codes US, achevez le brand + campaign 10DLC. L’approbation KYC seule ne remplace jamais l’enregistrement carrier ; les deux barrières doivent être vertes avant qu’un send US SMS ne quitte le sandbox.

Une fois les deux contrôles obligatoires et les enregistrements de canal passés, l’envoi en direct se comporte exactement comme l’envoi sandbox — même endpoint, même enveloppe webhook, aucune boucle d’approbation supplémentaire.

Références associées

Go-live checklist — premiers paliers avant le trafic en direct.
Sender-ID Registration — enregistrements par pays étayés par les identifiants doc_.
Documents KYC par numéro — la bibliothèque documentaire tenant-owned.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Intégration KYC/KYB/IDV de l'organisation

Intégration KYC/KYB/IDV de l’organisation

1. Pourquoi le trafic en direct est bloqué

2. Soumettez le formulaire

3. Marches par marché — ce que votre destination exige réellement

Allemagne — BNetzA identité entity

Espagne — CNMC voe sender-id / Itinérances

France — ARCEP registration d’identité

Turquie — BTK sender-name

Marchés arabes — exemple EAU TDRA

4. Option : ajoutez une session IDV hébergée

5. Surveillez le verdict de l’organisation

6. Re-soumission et la barrière « déjà vérifié »

7. Ce qu’un rejet signifie et que faire

Ce que cette barrière n’est PAS : documents par numéro

8. Une fois approuvé — les dernières barrières du go-live

Références associées

​Intégration KYC/KYB/IDV de l’organisation

​1. Pourquoi le trafic en direct est bloqué

​2. Soumettez le formulaire

​3. Marches par marché — ce que votre destination exige réellement

​Allemagne — BNetzA identité entity

​Espagne — CNMC voe sender-id / Itinérances

​France — ARCEP registration d’identité

​Turquie — BTK sender-name

​Marchés arabes — exemple EAU TDRA

​4. Option : ajoutez une session IDV hébergée

​5. Surveillez le verdict de l’organisation

​6. Re-soumission et la barrière « déjà vérifié »

​7. Ce qu’un rejet signifie et que faire

​Ce que cette barrière n’est PAS : documents par numéro

​8. Une fois approuvé — les dernières barrières du go-live

​Références associées

Intégration KYC/KYB/IDV de l’organisation

1. Pourquoi le trafic en direct est bloqué

2. Soumettez le formulaire

3. Marches par marché — ce que votre destination exige réellement

Allemagne — BNetzA identité entity

Espagne — CNMC voe sender-id / Itinérances

France — ARCEP registration d’identité

Turquie — BTK sender-name

Marchés arabes — exemple EAU TDRA

4. Option : ajoutez une session IDV hébergée

5. Surveillez le verdict de l’organisation

6. Re-soumission et la barrière « déjà vérifié »

7. Ce qu’un rejet signifie et que faire

Ce que cette barrière n’est PAS : documents par numéro

8. Une fois approuvé — les dernières barrières du go-live

Références associées