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. 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
  }
}

4. 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 6

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.

5. 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.

6. 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.

7. 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

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. Optional: add a hosted ID verification session

4. Poll for the organization verdict

5. Re-submitting and the already-approved guard

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

What this gate is NOT: per-number sender documents

7. Once approved — the remaining go-live gates

​Organization KYC/KYB/IDV onboarding

​1. Why live traffic is gated

​2. Submit the form

​3. Optional: add a hosted ID verification session

​4. Poll for the organization verdict

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

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

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

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

Organization KYC/KYB/IDV onboarding

1. Why live traffic is gated

2. Submit the form

3. Optional: add a hosted ID verification session

4. Poll for the organization verdict

5. Re-submitting and the already-approved guard

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

What this gate is NOT: per-number sender documents

7. Once approved — the remaining go-live gates