Organization KYC/KYB/IDV onboarding

The Quickstart Step 5 names two hard gates on live traffic: approved organization KYC and a funded balance. Organization KYC is a once-per-workspace review — it verifies the business itself, not its numbers (per-number document bundles are a separate concern; see the comparison at the end). This guide walks the full loop — submit, optionally add a hosted identity-verification session, poll for the verdict, resubmit on rejection — then picks up the remaining go-live gates.

1. Why live traffic is gated

Live sends are restricted until someone on the Devotel operations team has looked at a real business profile. That friction exists because automated signup farms were draining trial credit into disposable accounts; a human review is the one control that breaks that loop. Until approval lands:

Buying numbers is still possible, but no SMS, WhatsApp, or voice message will leave the platform.
The dashboard surfaces the status as a banner; the same page this guide covers is reachable from Settings → KYC.

Two statuses carry the review forward. not_started means the form has never been submitted. pending_review means an operators queue has the submission (the email-confirmation webhook pre-stamps this on signup; the form below replaces it with rich detail). After a decision you get approved or rejected.

2. Submit the form

POST to /api/v1/organization/kyc/submit with the business profile. Field by field the API validates: company name and country are required, the website is optional, the use-case description must be ten characters or more, and beneficial-owner entries feed the sanctioned-party screening step (optional, max 20).

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": "Logistics",
    "use_case": "Delivery-status notifications sent to customers who opted in at checkout.",
    "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: 'Logistics',
  use_case: 'Delivery-status notifications sent to customers who opted in at checkout.',
  estimated_monthly_volume: 45000,
});
console.log(result.data.status); // "pending_review"

A successful call stamps the organization pending_review and returns the stored record plus the business-screening verdict. Review is operator-run — nothing auto-approves or auto-rejects. Response (200):

{
  "data": {
    "status": "pending_review",
    "kyc": {
      "status": "pending_review",
      "company_name": "Acme Logistics Ltd.",
      "company_website": "https://acme-logistics.example",
      "country": "US",
      "industry": "Logistics",
      "use_case": "Delivery-status notifications sent to customers who opted in at checkout.",
      "estimated_monthly_volume": 45000,
      "submitted_at": "2026-09-04T09:12:33Z"
    },
    "kyb": {
      "status": "review",
      "matches": [],
      "legal_name": "Acme Logistics Ltd.",
      "country": "US",
      "registration_number": "DE-554433",
      "beneficial_owners": [
        { "name": "Maria Alvarez", "ownership_percentage": 100, "country": null }
      ],
      "screened_at": "2026-09-04T09:12:33Z"
    },
    "message": "Your KYC submission has been received and is awaiting review. You will receive an email once approved."
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-09-04T09:12:33Z" }
}

data.kyb is the business-screening signal (clear when the entity is clean, review when any sanctioned-country or denied-party match fired). It is reviewed alongside the form — it never blocks submission, and a review verdict still requires the same human pass. The response omits kyb entirely when the screening step could not run (e.g. its non-blocking engine was unreachable, flagged for manual review instead).

3. Per-market overlays — what your destination actually requires

The form above is submitted once per organization, but the fields a reviewer screens hardest depend on where you send. The country you submit anchors the overlay — answer it with the destination market, not the billing address; a UK-bound sender filing country: "US" just earns a bounce-back for correction. Whatever the market, two field groups always reach the reviewer: the free-text use_case description, and the KYB identity fields (registration_number, beneficial_owners). An organization sending to several gated markets repeats the document pattern once per destination — group uploads per destination in the document library rather than diluting one form. The overlays below cover the destinations that hold sends until pre-registration clears. For each: the profile fields to emphasize, and the document roles the regulator asks for. Upload documents under Compliance → Documents and reference them by ID across registrations; the reviewer-facing roles are business_doc, address_proof, id_proof, and authorization. The sender-ID market matrix carries the live registration level per country; the documents guide covers the upload flow.

United Kingdom — Ofcom / PRA registration of alphabetic sender ids

The UK gates alphabetic (alphanumeric) sender ids at required level with Ofcom / PRA. Emphasize an accurate legal company_name, a populated registration_number, and a use_case that names the traffic type. Documents the registry asks for: business_doc (entity registration), plus authorization when an agency files on a brand’s behalf.

Saudi Arabia — CITC sender-name registration

CITC gates the sender name, not just the route: file the name your customers will see, and note it in use_case. Documents: business_doc proving the entity behind the name.

United Arab Emirates — TDRA plus carrier KYC-backed brand identity

TDRA and the UAE carriers (e&, du) expect a KYC-backed brand identity attached to the sender name, so this is the overlay most likely to bounce a thin submission. Emphasize company_name, company_website, and a complete use_case. Documents: business_doc plus brand authorization.

Brazil — Anatel alphabetic registration

Anatel accepts no dynamic (unregistered) alphabetic senders: register before the first send. Emphasize registration_number and a use_case scoped to Brazilian recipients. Documents: business_doc held at country level before sends originate.

India — TRAI DLT with headers and content templates

India is not a plain sender-id registration: the TRAI DLT regime registers headers (sender ids) and content templates, and every send carries a template id. Work through the DLT-India guide; treat an approved organization KYC as a prerequisite, never as a DLT green light. Documents: business_doc (entity) plus per-template authorization.

United States — 10DLC brand + campaign, separate from KYC

US A2P rides 10DLC long codes, not alphabetic senders: register a brand and campaign per US long number under the 10DLC guide, and treat organization KYC and 10DLC as parallel gates — approval of one never clears the other. Documents: business_doc for the brand registration; concentrate accuracy work on company_name, company_website, and use_case. In every market the point of the overlay is the same: decide what to write into company_name, use_case, and registration_number before a send-time gate bounces the traffic with a 422. Send Gates covers how a required destination blocks unregistered sends.

4. Optional: add a hosted ID verification session

Some operators require a government-ID document plus a selfie-liveness check before they sign off. POST /api/v1/organization/kyc/idv/session opens a hosted session with the configured provider; open the returned URL in a browser or hand it to the signer.

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

Response (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" }
}

Until an operator provisions a vendor, the endpoint answers 503:

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

Check the provider’s verdict with GET /api/v1/organization/kyc/idv/status. It self-reconciles: as long as the stored session is pending, each GET asks the provider for the latest outcome and writes back a terminal transition. A terminal verified, declined, or expired — plus a reason when the provider supplies one — joins the review signal the operator weighs next to the submission. It is never self-approving: a verified identity does NOT approve KYC, and a declined outcome does not reject it.

{
  "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. Poll for the organization verdict

Poll GET /api/v1/organization/kyc/status until the org-level verdict lands. The available states are not_started, pending (pre-submission transient), pending_review, approved, and rejected; the response also echoes the submitted company fields and reviewed_at once a decision was made.

cURL

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

Response (200):

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

Old SDK builds and hand-rolled integrations may read the bare GET /api/v1/organization/kyc path; it serves the same response shape, so targeting /kyc/status is safe while still compatible. A client-side loop with backoff (pseudocode):

attempts = 0
while status not in {"approved", "rejected"}:
    sleep backoff[min(attempts, len(backoff))]   # e.g. 5s, 15s, 60s, 300s
    status = GET /organization/kyc/status
    attempts += 1
if status == "rejected":
    surface the rejection and follow section 7

The endpoint is safe to poll from the dashboard or a server — it degrades to a neutral not_started read on a transient database blip instead of surfacing a 503, and the next poll self-corrects.

6. Re-submitting and the already-approved guard

POSTing the form again is the correct move on a rejected org: the write re-stamps pending_review, overwrites the form block, and re-runs the business screen with the corrected answers. A still-pending_review resubmission is also accepted — it replaces the in-flight profile. Trying to resubmit an approved organization returns 409:

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

The same guard applies to an IDV session once the identity is verified — a POST to the session endpoint then gets 409 ALREADY_VERIFIED, and a re-capture only makes sense after the org was rejected and is being re-driven.

7. What a rejection means and what to do about it

A rejection is a human verdict — the operator walks the Devotel operations panel, reads your form fields plus the business-screening and identity-verification signals, and hits approve or reject. The customer-facing surface never exposes a machine rationale; the decision email names the gap and the fix. Treat rejected as actionable:

Re-read the submitted fields for accuracy (a mismatched legal name or a thin use-case description is the most common flag).
Fix any business-screening (kyb) match and any declined IDV result.
Res-submit with the corrected data — the endpoint accepts it and the queue re-orders.

If the rejection is clearly an error — for example a typo in the operator panel rather than in your data — file through support with the account id and the req_* id from the status poll; the review queue owner can re-open the file and approve it from the operator side.

What this gate is NOT: per-number sender documents

Organization KYC sits beside the per-number document bundles that carriers ask for per sender — the latter (business registration, address proof, identity) cover a specific number you own and follow a different review loop in Compliance → Documents. Approving the organization does not settle a number-level bundle, and vice versa. See the per-number KYC documents guide for that separate register.

8. Once approved — the remaining go-live gates

Approval flips the organization verdict, so GET /organization/kyc/status returns approved. Finish the two remaining gates from the go-live checklist:

Mint the live key. Under Settings → API Keys, create a secret with the dv_live_sk_ prefix and swap it in for the sandbox dv_test_sk_ key — request shapes are identical, so no code rewrite is needed.
Fund the balance. Add funds under Settings → Billing; SMS, WhatsApp, and voice all deduct from this wallet, and live sends fail with a billing error while the balance is empty.
US SMS: layer 10DLC. If the destination includes US long codes, finish the 10DLC brand + campaign registration. KYC approval alone never substitutes for carrier registration; both gates must be green before a US SMS send leaves the sandbox tier.

Once the two hard gates plus any channel registrations pass, the live send behaves exactly like the sandbox send — same endpoint, same webhook envelope, no further approval loop.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Organization KYC/KYB/IDV onboarding

Organization KYC/KYB/IDV onboarding

1. Why live traffic is gated

2. Submit the form

3. Per-market overlays — what your destination actually requires

United Kingdom — Ofcom / PRA registration of alphabetic sender ids

Saudi Arabia — CITC sender-name registration

United Arab Emirates — TDRA plus carrier KYC-backed brand identity

Brazil — Anatel alphabetic registration

India — TRAI DLT with headers and content templates

United States — 10DLC brand + campaign, separate from KYC

4. Optional: add a hosted ID verification session

5. Poll for the organization verdict

6. Re-submitting and the already-approved guard

7. What a rejection means and what to do about it

What this gate is NOT: per-number sender documents

8. Once approved — the remaining go-live gates

​Organization KYC/KYB/IDV onboarding

​1. Why live traffic is gated

​2. Submit the form

​3. Per-market overlays — what your destination actually requires

​United Kingdom — Ofcom / PRA registration of alphabetic sender ids

​Saudi Arabia — CITC sender-name registration

​United Arab Emirates — TDRA plus carrier KYC-backed brand identity

​Brazil — Anatel alphabetic registration

​India — TRAI DLT with headers and content templates

​United States — 10DLC brand + campaign, separate from KYC

​4. Optional: add a hosted ID verification session

​5. Poll for the organization verdict

​6. Re-submitting and the already-approved guard

​7. What a rejection means and what to do about it

​What this gate is NOT: per-number sender documents

​8. Once approved — the remaining go-live gates

Organization KYC/KYB/IDV onboarding

1. Why live traffic is gated

2. Submit the form

3. Per-market overlays — what your destination actually requires

United Kingdom — Ofcom / PRA registration of alphabetic sender ids

Saudi Arabia — CITC sender-name registration

United Arab Emirates — TDRA plus carrier KYC-backed brand identity

Brazil — Anatel alphabetic registration

India — TRAI DLT with headers and content templates

United States — 10DLC brand + campaign, separate from KYC

4. Optional: add a hosted ID verification session

5. Poll for the organization verdict

6. Re-submitting and the already-approved guard

7. What a rejection means and what to do about it

What this gate is NOT: per-number sender documents

8. Once approved — the remaining go-live gates