Skip to main content

​
The KYC identity model: documents, profiles, and destinations

Every regulated surface on Orbit asks the same question — who is sending this traffic, on whose identity? The answer is split across three objects you own: a document, a compliance profile, and a destination. A first-time entrant into a regulated market almost always builds only two of the three, then wonders why a number won’t activate. This page defines the triangle, shows how expiry propagates through it, gives the renewal runbook, and routes the failures to the pages that already own them. All endpoints below are rooted at https://api.orbit.devotel.io/api/v1/compliance.
Orbit carries your identity packet to the carrier and enforces the gates; final approval is always granted by the carrier or regulator in each country, and supplying and renewing the underlying documents stays with you.

​
1. The triangle: document → profile → destination

Three objects, each with one job:
  • Document (doc_…) — the evidence file itself, uploaded once into a tenant-wide library. Inert on its own: it does regulatory work only when a destination references it.
  • Compliance profile (cprof_…) — the structured identity the documents back up: who the end user is, for which use_case, in which country. Carriers review the profile as a unit.
  • Destination — the regulated thing trying to go live: a phone number, a Sender-ID registration in one country, a 10DLC wizard draft, a WABA, an RCS agent. The destination is what gets gated.
The doc_… ID is the pointer that ties the triangle together. Upload one business-registration PDF and the exact same ID can serve all three consumers: Reuse only works when the roles and countries line up — a passport uploaded for Germany answers a German profile, and “the same document backs as many countries as accept it” is the ceiling, not the floor. What to upload for each market is in Country Compliance Requirements.

​
Which use_case does a destination demand?

The profile’s use_case field names the gate it answers to — one profile, one gate. Pick the value for the destination class, not for the document type: The full mapping with per-country requirements is on Compliance-profile use cases. Number, Sender-ID, and 10DLC use cases usually require a country_code on the profile; WhatsApp, RCS, and email accept a country-agnostic one.

​
2. Expiry mathematics: three clocks, three speeds

Expiry is not one event — it is three clocks ticking on different parts of the triangle, each with a different consequence: The clocks propagate outward: a lapsed document degrades the profile, a lapsed profile degrades the destination. Nothing in the chain self-heals — a clock that expires stays expired until you upload a replacement document or re-submit the profile.

​
What the gates do when a destination’s backing lapses

When a destination’s compliance backing goes from satisfied to lapsed, the pre-send and pre-activation checks — the same gate family described on Send Gates — refuse the surface rather than let it carry traffic:
  • A number whose profile is no longer approved sends fail with the compliance-profile error codes (COMPLIANCE_PROFILE_REQUIRED / COMPLIANCE_PROFILE_NOT_APPROVED, 422) covered on Compliance profile lifecycle errors.
  • A Sender ID whose country registration has lapsed sends fail with SENDER_ID_NOT_APPROVED — the entry exists, but its status is no longer approved.
  • A purchase attempted after the expiry lands the new number at pending_compliance, debited but inert until a satisfying profile is attached.
You don’t have to watch three clocks by hand. Orbit derives per-number alerts from the timestamps it already stores — each document’s expires_at and the carrier verify-by deadline — behind GET /numbers/document-expiry-alerts and the expiry-alerts banner on the dashboard’s Numbers page. Each alert carries a suggested_action (renew while still inside your alert window, renew_or_release once the expiry has landed). The look-ahead window defaults to 30 days; tune it with the numbers.document_expiry_alert_days setting. The full alert payload is documented on KYC Documents.

​
3. Renewal runbook: document first, references second

Renewal is always a fresh upload, then a re-reference — never an edit in place. Run it in this order:
  1. Upload the replacement first. POST /compliance/documents with the new file. You get a new doc_… ID — a renewal is a new library entry, not a version of the old one.
  2. Re-reference it on every consumer of the old ID.
    • On each affected profile: attach the new ID in the same role (POST /compliance/compliance-profiles/:id/documents), then detach the expired one. An approved profile stays approved while you swap the document; its submission is re-reviewed on next use.
    • On each Sender-ID country entry: re-submit the registration with the new doc_… ID in document_refs (the upsert is idempotent — countries you already hold approved keep their approval).
    • On any open 10DLC wizard draft: update the draft’s document references before you submit.
  3. Clean up the library — delete the old document with DELETE /compliance/documents/:id once nothing references it. Deletion is refused while a profile still has it attached, so this step is also your completeness check: if the delete is refused, a reference is still open somewhere.

​
What a carrier re-review round trip costs you

A swap is atomic on your side; the carrier’s is not. After you re-submit, the packet goes back into a review queue — the same queue a first-time submission joins. Plan for that round trip:
  • Gating time is the carrier’s review time, not Orbit’s. The platform enforces the gate the moment the backing lapses and lifts it the moment the carrier approves; the time between is review queue depth in the destination country, not platform latency.
  • Renew inside the alert window (suggested_action: renew, before the expiry lands) and the destination keeps its approved backing while the replacement is under review — you never enter a gated state. Renew after the lapse (renew_or_release) and the surface is gated from the moment the clock expired until the carrier approves the new packet. That difference — zero interruption versus a full review round trip while gated — is the entire argument for a 30-day alert window.

​
4. Failure modes: which gate fired

This page stays at the concept level. When the triangle breaks, the symptom lands on the destination — and the troubleshooting pages already own each failure class. Route by the symptom you have: The pattern across all five: the gate never lies about which object lapsed. The error names the gate family (sender identity, compliance profile, destination registration); the triangle tells you what to renew first (document → profile reference → destination resubmission).

​
5. Cross-references