Organization KYC end to end

A new organization can buy numbers and configure channels, but no SMS, WhatsApp, or voice message leaves the platform until Devotel approves the organization’s KYC profile. This guide walks the full operator loop: submit, poll to a verdict, put the approval to work on WhatsApp and RCS, and handle the failure paths. It complements Organization KYC/KYB/IDV onboarding, which is the API-reference-style tour of submit, hosted IDV, and resubmit. This page is the operator walkthrough: what to have ready per entity type, what happens while you wait, and what approval unblocks on each channel.

1. Why new accounts start throttled

Two separate checks sit between a fresh organization and full messaging volume, and operators mix them up constantly:

Organization KYC verifies the business: legal name, jurisdiction, website, industry, and use case, reviewed by the Devotel operations team. It gates whether any traffic leaves the platform at all. This is the loop this guide covers.
Meta WABA verification and tiering verify the WhatsApp account and cap how many unique recipients it can reach per 24 hours. A new WABA starts at 250 unique recipients per 24 hours and steps up to 1,000, 10,000, then 100,000 as Meta observes sustained good recipient behaviour.

KYC approval does not raise Meta’s tier by itself, and a high Meta tier does not replace organization KYC: while the organization is unapproved, nothing sends at any tier. The dependency runs one way. Approval lifts Devotel’s send gate, which turns the WABA on; from there Meta’s documented quality-and-volume path (good quality rating plus sending to the current cap inside a 7-day window) walks the tier ladder. Clearing KYC early is what makes the 250-recipient clock start as soon as the WABA is ready instead of weeks later. The full quality/tier mechanics live in WhatsApp quality and health; the WABA-side steps (Business Verification, display name review, first send) live in Set up your first WABA.

2. Submit the KYC profile

Send the business profile to POST /api/v1/organization/kyc/submit. Fields the API validates:

Field	Required	What review looks at
`company_name`	Yes	Must match the trading entity a reviewer can find in a public register or on the website.
`country`	Yes	ISO country code of incorporation; sets which screening rules the KYB check applies.
`company_website`	No, near-mandatory in practice	A live site showing what the business does. Submissions without one are the most common reject.
`industry`	Yes	Free text; keep it consistent with the website.
`use_case`	Yes	Ten characters minimum. Describe the messages you will send and to whom.
`estimated_monthly_volume`	Yes	A string, e.g. `"10000"`. A number wildly above the use case invites questions, not capacity.
`beneficial_owners`	No (max 20)	Owner entries feed the sanctioned-party screening step. Provide them when the register is not public.

On success the response returns data.status: "pending_review", an echo of the submitted kyc object, the kyb screening verdict when it has already completed, and a message with the next step. While pending_review, the same payload is queued for a super-admin decision and a business-screening (KYB) check runs against the signing entity in parallel.

Send an Idempotency-Key header on the submit call. A retried submit with the same key returns the original submission instead of queueing a duplicate for review.

Example payloads

Three worked submissions for common entity types. Adapt the website and use case; keep every field consistent with what a reviewer finds when they look the company up. US LLC

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/submit \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kyc-acme-us-001" \
  -d '{
    "company_name": "Acme Notifications LLC",
    "company_website": "https://acmenotifications.example",
    "country": "US",
    "industry": "software",
    "use_case": "Appointment reminders and delivery updates for customers who opted in at checkout",
    "estimated_monthly_volume": "25000"
  }'

EU GmbH

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/submit \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kyc-acme-de-001" \
  -d '{
    "company_name": "Acme Benachrichtigungen GmbH",
    "company_website": "https://acme-benachrichtigungen.example",
    "country": "DE",
    "industry": "logistics",
    "use_case": "Shipment status notifications to recipients who provided a phone number at order time",
    "estimated_monthly_volume": "40000",
    "beneficial_owners": [
      { "name": "Erika Mustermann", "country": "DE" }
    ]
  }'

APAC Pte Ltd

cURL

curl -X POST https://api.orbit.devotel.io/api/v1/organization/kyc/submit \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kyc-acme-sg-001" \
  -d '{
    "company_name": "Acme Messaging Pte Ltd",
    "company_website": "https://acmemessaging.example",
    "country": "SG",
    "industry": "healthcare",
    "use_case": "Clinic appointment confirmations and reschedule notices for registered patients",
    "estimated_monthly_volume": "12000"
  }'

All three return the same envelope:

{
  "data": {
    "status": "pending_review",
    "kyc": {
      "status": "pending_review",
      "company_name": "Acme Notifications LLC",
      "company_website": "https://acmenotifications.example",
      "country": "US",
      "industry": "software",
      "use_case": "Appointment reminders and delivery updates for customers who opted in at checkout",
      "estimated_monthly_volume": "25000",
      "submitted_at": "2026-10-15T09:00:00.000Z"
    },
    "kyb": { "status": "clear" },
    "message": "Your KYC submission has been received and is awaiting review. You will receive an email once approved."
  }
}

The same profile can be submitted from the dashboard at Settings → KYC; the API and the console write to the same review queue.

3. Poll the status endpoint to the verdict

GET /api/v1/organization/kyc/status returns the current state. There are exactly four:

Status	Meaning
`not_started`	No submission exists yet.
`pending_review`	The submission is in the review queue; the KYB screen is running or has completed.
`approved`	Terminal. The send gate is lifted; review timestamps are set.
`rejected`	Terminal. The response carries the review reason; see Failure paths.

cURL

curl https://api.orbit.devotel.io/api/v1/organization/kyc/status \
  -H "Authorization: Bearer $ORBIT_API_KEY"

The terminal approved response also returns what review saw, so your automation can log the verdict with its evidence:

{
  "data": {
    "status": "approved",
    "company_name": "Acme Notifications LLC",
    "country": "US",
    "industry": "software",
    "submitted_at": "2026-10-15T09:00:00.000Z",
    "reviewed_at": "2026-10-16T14:30:00.000Z"
  }
}

Notify your operators on the transition, not on every poll. The pattern that works in practice is the email receipt plus a bounded poll:

// Poll until a terminal state; both approved and rejected stop the loop.
const url = "https://api.orbit.devotel.io/api/v1/organization/kyc/status";
let status = "not_started";
while (status === "not_started" || status === "pending_review") {
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ORBIT_API_KEY}` } });
  if (!res.ok) throw new Error(`KYC status poll failed: ${res.status}`);
  ({ status } = (await res.json()).data);
  await new Promise((r) => setTimeout(r, 15 * 60 * 1000)); // every 15 minutes is fine; reviews take hours to days
}
console.log(status === "approved" ? "Cleared to send" : `Rejected - see Settings > KYC for the reason`);

There is no kyc.approved webhook event on the delivery bus today; the email to the organization’s admins and the status endpoint are the shipped completion signals. The dashboard banner on Settings → KYC flips on the same state, so a human operator does not need the poll at all.

4. Put the approval to work: WhatsApp tiering

Once status reads approved, Devotel’s send gate is gone and the channel work begins.

Connect or re-check the WABA. If the WABA was already attached while the organization was unapproved, nothing extra is needed; sends start flowing at the current tier. Set up your first WABA covers the connect flow and the Business Verification checklist.
Read the health surface. Settings → Channels → WhatsApp → Health shows, per WABA: can-send, review status, the messaging tier, the dynamic daily limit, and phone quality. This is the surface to watch while the tier climbs; the field-by-field reading is in WhatsApp quality and health.
Climb Meta’s ladder by sending well, not by asking. The tier rises automatically when you send to the current cap inside a 7-day window at high or medium quality: 250 → 1,000 → 10,000 → 100,000 unique recipients per 24 hours. Volume is not the lever; recipient satisfaction is. Send to opted-in recipients who expect the message.
When to request a raise. A manual tier-review request with Meta is only worth filing when a contracted launch legitimately needs headroom the ladder has not reached yet, quality is high, and the 7-day window history is clean. Filing one at low quality or with a thin send history wastes the review.

A low quality rating freezes progression, and seven consecutive days at low drops the tier, independent of KYC state. If a campaign pushes quality down, pause and recover per the health guide before pushing volume.

5. Carry the approval into RCS brand verification

Organization KYC and RCS brand verification are parallel identity flows: the organization review verifies the business once; each RCS brand is verified per carrier against the fields on the brand record. Approved organization KYC does not issue RCS brand verification by itself, but it is the prerequisite posture carriers expect, and the same business documents answer both reviews. The brand-side walkthrough is RCS brand verification KYC walkthrough. The crossover points:

Complete the brand fields first. /api/v1/rcs/brands captures name, website, industry, contact person, and postal address; a brand missing its contact or address block rejects verification with a 409 before any document is read.
Attach proof via the verification submit. POST /api/v1/rcs/bots/:id/verify is where KYC documents attach. Carriers in India and Brazil demand them at registration; US- or EU-only brands often need only the field block. Fill tax_id and legal_entity_name even where optional; the carriers that ask reject thin forms.
Reuse the organization profile. Keep the company name, website, and industry identical to what Devotel approved in the KYC submission. Mismatched identity data between the org review and the carrier review is a classic slow-down.
Track carrier outcomes on the webhook. Carrier KYC results for RCS arrive as bot_verification callbacks on the messaging webhook (approved or rejected plus a comment), so the brand loop has the evented completion signal the organization loop does not.

Sequence guidance: submit organization KYC first, and while it is pending_review prepare brand records and templates so carrier review can start the day approval lands.

6. Failure paths: rejection and the missing-field loop

A rejected status is terminal for that submission but not for the organization. The response and the Settings → KYC page carry the review reason, and the dashboard’s rejected state names the missing or inconsistent items. The missing-field loop, step by step:

Read the reason on Settings → KYC (or compare reviewed_at against your submit timestamp via the status endpoint to confirm the decision landed).
Fix the profile at the source: legal name as registered, website live and consistent with the industry, use case specific about recipient consent, volume credible for the use case.
Submit the corrected profile again with a fresh Idempotency-Key. The new submission re-enters the queue as pending_review; there is no separate appeal form, the resubmission with corrected fields is the appeal.
If the reason reads as a judgement call rather than a missing field (industry refused, use case against policy), contact support with the submission reference from the email; that route reaches the reviewing super-admin.

The expensive mistakes to avoid after a rejection: resubmitting the identical payload hoping for a different reviewer, and starting to send through an unverified workaround while the review runs. The send gate applies to the organization, so nothing routes around it, and screening sees repeat identical submissions as noise.

7. Renewal and re-review

An approved KYC profile does not expire on a fixed calendar cadence; review is event-driven. Re-review triggers when the verified facts change or stop matching the traffic:

Profile changes. A new legal name, jurisdiction, or website on the organization puts the profile back in front of review; keep the public register, the website, and the KYC fields in agreement.
Behavioural signals. Chargebacks, regulator or provider complaints, or traffic that contradicts the declared use case reopen the file, and the send gate can return until the review clears.
Channel-side re-verification. Meta re-checks WABA business details on its own cadence, and carriers re-verify RCS brands per their policies; those are channel reviews and follow their own guides, but they reuse the same business facts, so update the facts once, everywhere.

The operational habit that keeps renewal boring: treat the KYC profile as the single source of truth for the company’s identity, update it before (not after) registrations change, and watch the Settings → KYC banner the same way you watch the WhatsApp health tile.

Organization KYC/KYB/IDV onboarding — every field, hosted IDV, and the go-live gates.
Set up your first WABA — connect flow, Business Verification checklist, first send.
WhatsApp quality and health — tier ladder, dynamic daily limit, recovery loop.
RCS brand verification KYC walkthrough — choosing between org-level and brand-level KYC for RCS.

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

Organization KYC end to end: verify the business, lift the WhatsApp cap, issue RCS brand verification

Organization KYC end to end

1. Why new accounts start throttled

2. Submit the KYC profile

Example payloads

3. Poll the status endpoint to the verdict

4. Put the approval to work: WhatsApp tiering

5. Carry the approval into RCS brand verification

6. Failure paths: rejection and the missing-field loop

7. Renewal and re-review

​Organization KYC end to end

​1. Why new accounts start throttled

​2. Submit the KYC profile

​Example payloads

​3. Poll the status endpoint to the verdict

​4. Put the approval to work: WhatsApp tiering

​5. Carry the approval into RCS brand verification

​6. Failure paths: rejection and the missing-field loop

​7. Renewal and re-review

​Related

Organization KYC end to end

1. Why new accounts start throttled

2. Submit the KYC profile

Example payloads

3. Poll the status endpoint to the verdict

4. Put the approval to work: WhatsApp tiering

5. Carry the approval into RCS brand verification

6. Failure paths: rejection and the missing-field loop

7. Renewal and re-review

Related