> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Regulatory Preview

> See the documents and fields a country requires before you purchase a number

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

```bash theme={null}
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. |

### Response

```json theme={null}
{
  "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.                                                                                                |

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

<Warning>
  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](/numbers/lifecycle) before the number activates. Check this flag before buying to avoid a debited-but-inactive number.
</Warning>