Regulatory Preview

Many countries regulate who can hold a phone number and require identity or address documentation before activation. The regulatory-preview endpoint surfaces those requirements inline, before checkout — so you can show an at-a-glance “Documents needed” disclosure instead of forcing the buyer into the compliance wizard to discover the list.

curl "https://api.orbit.devotel.io/api/v1/numbers/regulatory-preview?country=GB&phone_number_type=local" \
  -H "X-API-Key: dv_live_sk_..."

Query parameters

Parameter	Type	Default	Description
`country`	ISO 3166-1 alpha-2	— (required)	Country to preview (e.g. `GB`, `DE`).
`phone_number_type`	`local` \| `mobile` \| `toll_free`	`local`	Number type you intend to buy.
`provider`	`telnyx` \| `didww`	—	Optional. When omitted, requirements from every provider that could serve the country are unioned. Mostly used by admin tooling.

How checkout uses this

Call this endpoint before you let a buyer commit to a purchase. The Orbit dashboard does exactly this on the Numbers → Buy page: as soon as you pick a country and number type, it calls GET /numbers/regulatory-preview and renders the response as an inline disclosure on the checkout form — before you click Buy. Build the same flow into any custom purchasing UI:

Buyer picks a country and number type.
Your UI calls regulatory-preview with those two values.
Render one of two panels from the response:
- unregulated: true → an “instant activation” panel. No documents, no review wait.
- unregulated: false → a “Documents needed” disclosure listing fields and document_roles, plus the expected review window from activation_eta.
Use compliance_profile_satisfies to decide the call to action:
- true → show “Your profile covers this” and let the purchase proceed.
- false → link the buyer into the compliance wizard before they buy, so money is never debited into an inactive number.

Because the endpoint answers “what will this country ask for?” rather than “what did this tenant already submit?”, it is safe to call it as early as the country picker — you do not need a number selected first.

Unregulated vs regulated

The response has two binary shapes. Read unregulated first.

Unregulated — `unregulated: true`

Some markets (for example the United States) impose no carrier or registry document requirements for local numbers. The preview returns empty requirement lists and no review window:

{
  "data": {
    "country": "US",
    "provider": "platform",
    "phone_number_type": "local",
    "activation_eta": null,
    "fields": [],
    "document_roles": [],
    "compliance_profile_satisfies": true,
    "unregulated": true
  }
}

Render your “instant activation” state and skip the compliance wizard entirely. compliance_profile_satisfies is true here because nothing needs satisfaction.

Regulated — `unregulated: false`

Most of Europe (and much of APAC/LATAM) requires documentation. Germany is one of the heavier sets — identity, address, and business documents:

{
  "data": {
    "country": "DE",
    "provider": "platform",
    "phone_number_type": "local",
    "activation_eta": { "typical_minutes": 120, "max_hours": 72 },
    "fields": [
      { "name": "business_name", "type": "text", "description": "Registered business name", "required": true },
      { "name": "street_address", "type": "address", "description": "Registered address", "required": true }
    ],
    "document_roles": ["id_proof", "address_proof", "business_doc"],
    "known_compliance_profile_id": "cprof_abc123",
    "compliance_profile_satisfies": false,
    "unregulated": false
  }
}

Here the buyer needs identity proof, a proof of address, and a business document. Two tenants can both preview Germany and see different compliance_profile_satisfies values: the flag is evaluated against your compliance profiles on every call, while the requirements themselves are tenant-agnostic. A false means “you haven’t completed this country’s profile yet” — not “nobody can buy this number.” You can also pin provider to compare carriers. The default unioned response (provider: "platform") returns the strictest combined requirement set, which is what the purchase gate will actually enforce.

Response

{
  "data": {
    "country": "GB",
    "provider": "platform",
    "phone_number_type": "local",
    "activation_eta": {
      "typical_minutes": 120,
      "max_hours": 72
    },
    "fields": [
      {
        "name": "business_name",
        "type": "text",
        "description": "Registered business name",
        "required": true
      }
    ],
    "document_roles": ["id_proof", "address_proof"],
    "known_compliance_profile_id": "cprof_abc123",
    "compliance_profile_satisfies": true,
    "unregulated": false
  }
}

Fields

Field	Description
`provider`	`platform` when requirements are unioned across carriers; the specific carrier name only when you pinned `provider`.
`activation_eta`	`{ typical_minutes, max_hours }` for the carrier review window, or `null` when the country/type activates instantly. When unioning providers, the longer window is returned so the ETA never under-promises.
`fields`	Array of required/optional data fields, each `{ name, type, description?, required }`.
`document_roles`	Document roles the carrier needs (e.g. `id_proof`, `address_proof`).
`known_compliance_profile_id`	Present when one of your existing compliance profiles already covers this country.
`compliance_profile_satisfies`	Always a boolean. `true` means an existing profile (or an unregulated country) covers every required field + non-expired document — you can buy immediately. `false` means complete a compliance profile first.
`unregulated`	`true` when neither the registry nor the carrier asks for any docs/fields — render an “instant activation” panel.

Field-to-KYC mapping

document_roles names the document categories a country expects; the files themselves live in your KYC document library. Map each role back to the upload type you registered the document with, then attach it to the compliance profile by its doc_… ID under that role:

`document_roles` value	Upload as (`type`)	Attach with role
`id_proof`	`id_card`, `passport`, or `drivers_license`	`id_proof`
`address_proof`	`utility_bill`, `bank_statement`, or `proof_of_address`	`address_proof`
`business_doc`	`business_registration` or `vat_certificate`	`business_doc`
`authorization`	`power_of_attorney`	`authorization`
`other`	Any accepted type	`other`

A document only satisfies a role while it is non-expired. When a required document lapses, compliance_profile_satisfies flips to false on the next preview call even if nothing else changed. Structured fields (business name, address, tax ID) map to the profile’s data — set them with PUT /compliance/compliance-profiles/:id/data, and re-run the preview after each update to confirm the flag flipped to true.

Carrier regulatory schemas are cached for 24 hours (they change on quarterly cycles), but the compliance_profile_satisfies check runs on every request against your profiles, scoped to your organization — so attaching a new profile updates the flag immediately.

A compliance_profile_satisfies of false for a regulated country means a purchase would land at pending_compliance and require you to attach an approved compliance profile before the number activates. Check this flag before buying to avoid a debited-but-inactive number.

After purchase: the `pending_compliance` state

If you do buy with compliance_profile_satisfies: false, the number is debited but held at pending_compliance — it routes nothing until you attach an approved profile. Two follow-on behaviors to plan for:

Carrier deadline. The carrier sets a verify-by window on the order. If the window expires while the number still waits, it can be auto-released and the inventory returned. Watch the document-expiry alerts banner to see the deadline before it costs you the number.
Recovery. Complete the profile, attach it to the number, and activation proceeds without a second purchase. The lifecycle is documented in Number Lifecycle.

Because the requirements schema is cached for 24 hours, a brand-new carrier requirement may lag behind the preview by up to a day — but your own eligibility (compliance_profile_satisfies) always reflects your profiles as of the current call, never a cached snapshot.

Uploading the documents this check counts

document_roles tells you which document categories the carrier wants (e.g. id_proof, address_proof); the actual files are uploaded once into your KYC document library, attached to a compliance profile by their doc_… IDs, and flagged here as satisfied only while they remain non-expired. See KYC Documents & the Compliance-Profile Lifecycle for upload, reuse, and renewal.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Regulatory preview: country requirements before purchase

Regulatory Preview

Query parameters

How checkout uses this

Unregulated vs regulated

Unregulated — `unregulated: true`

Regulated — `unregulated: false`

Response

Fields

Field-to-KYC mapping

After purchase: the `pending_compliance` state

Uploading the documents this check counts

​Regulatory Preview

​Query parameters

​How checkout uses this

​Unregulated vs regulated

​Unregulated — unregulated: true

​Regulated — unregulated: false

​Response

​Fields

​Field-to-KYC mapping

​After purchase: the pending_compliance state

​Uploading the documents this check counts

Regulatory Preview

Query parameters

How checkout uses this

Unregulated vs regulated

Unregulated — `unregulated: true`

Regulated — `unregulated: false`

Response

Fields

Field-to-KYC mapping

After purchase: the `pending_compliance` state

Uploading the documents this check counts