Skip to main content

​
KYC Documents & the Compliance-Profile Lifecycle

Regulated markets don’t accept “trust me” — a carrier or regulator wants proof of who you are before it lets a phone number activate or a Sender ID carry traffic. Orbit models that proof as two things you own: a document library (the files themselves) and compliance profiles (the structured identity the documents back up). This page explains what a profile captures, how documents move from upload to reuse to renewal, where the same document gets referenced, and how to see an expiry coming before it costs you a number. All endpoints below are rooted at https://api.orbit.devotel.io/api/v1/compliance.
Orbit stores your documents, carries them to the carrier, and surfaces their review status — final approval is always granted by the carrier or regulator in each country, not by the platform. Supplying and renewing the documents themselves stays with you.

​
What a compliance profile is

A compliance profile (cprof_…) is one regulatory identity bundle: who the end user is, for which use case, in which country. Carriers review the profile as a unit — approve it once and every number or sender that profile covers can use it. A profile’s own status moves draft → pending_review → approved (or rejected / partially_rejected), and to expired when its validity window closes. Only an approved profile satisfies a country’s checks.

​
The document lifecycle

Documents live in a tenant-wide library, separate from any single profile. Upload a passport once and you can attach it to a German phone-number profile today and reuse the same file for a Sender-ID registration tomorrow — no second upload.

​
1. Upload

POST /compliance/documents takes a multipart/form-data upload and returns the document’s library ID, which always starts with doc_:
Files are encrypted before they leave the API and held in private storage; nothing about a doc_… ID is guessable or shareable outside your organization. List the library any time with GET /compliance/documents.

​
2. Reference by doc_… ID

A document by itself is inert — it does regulatory work only when it is attached to a profile with a role:
Roles (id_proof, address_proof, business_doc, authorization, other) tell the carrier which requirement the document satisfies. The same doc_… ID may play a different role in a different profile.

​
3. Expiry

Many regulators treat documents as stale after a fixed age — UK Ofcom, Germany’s BNetzA, and France’s ARCEP, among others, generally require ID or address proof to be no older than 3–12 months. Orbit records an expires_at per attached document; once a document lapses, it stops counting toward the country’s requirements even while the file itself is still in your library.

​
4. Renewal

Renewing is a fresh upload, not an edit: upload the replacement document, attach it to the profile in the same role, then detach (and optionally delete, with DELETE /compliance/documents/:id) the expired one. Profiles already approved stay approved while you swap the document — the submission is re-reviewed on next use.
Deleting a document is refused while it is still attached to any profile. Detach it from every profile first, then delete.

​
Where documents are reused

The doc_… ID is the single pointer three product surfaces share:
  1. Sender-ID registration. Each country entry in Sender-ID Registration carries document_refs: a list of doc_… IDs backing that country’s filing. The registration route never accepts files — reference the library IDs you already uploaded, and the same document backs as many countries as accept it.
  2. Numbers regulatory preview. The regulatory-preview check returns compliance_profile_satisfies: true only when a profile covers every required field and its attached documents are non-expired — an expired document flips the flag to false even on an otherwise complete profile.
  3. Number purchase gating. Buying a number in a regulated country without a satisfying profile lands the number at pending_compliance: it’s debited, but it won’t activate until an approved profile is attached. If the carrier’s verify-by deadline passes while the number is still waiting, the number can be auto-released — see Number Lifecycle for release and recovery.

​
Monitor expiry before it costs you a number

Orbit derives per-number expiry alerts from the timestamps it already stores: each document’s expires_at, and the carrier verify-by deadline on numbers waiting at pending_compliance. Read them with:
Every alert names the number, the soonest binding expiry (earliest_expiry_at), whether it came from a document or the carrier deadline (earliest_expiry_source), the whole days until it lapses (negative once it already has), and a suggested_action:
  • renew — still valid but inside your alert window; upload the replacement now.
  • renew_or_release — already lapsed; renew immediately or decide to let the number go.
The look-ahead window defaults to 30 days. Tune it per organization with the numbers.document_expiry_alert_days setting (1–365 days), or preview a different window ad hoc with the ?days= query parameter. Response rows are sorted most-urgent first; a very large at-risk inventory is capped and reports truncated: true, so narrow the window if you hit the cap.

​
Tenant-owned by design

The split of responsibility is deliberate: Orbit never invents or auto-renews identity documents on your behalf — the regulator is verifying your identity, so a renewal always starts with a new upload from you. What the platform guarantees is that a document you supply once is reusable everywhere it’s accepted, and that you’ll see its expiry coming with enough lead time to act.