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

# Pre-purchase regulatory preview for one country

> Live, single-country regulatory preview a buyer calls BEFORE `/numbers/purchase`: the identity/address documents and data fields a purchase will require, the expected activation window for regulated countries, and — scoped to the caller's organization — whether an existing compliance profile already satisfies the requirements (`compliance_profile_satisfies`). Use the all-country catalog `/numbers/regulatory-requirements` for bulk discovery; use this for the at-a-glance 'documents needed' disclosure on a specific country/line type. Pre-purchase discovery read; scoped on `numbers:read`.



## OpenAPI

````yaml /openapi.yaml get /api/v1/numbers/regulatory-preview
openapi: 3.1.0
info:
  title: Devotel CPaaS API
  description: Orbit by Devotel — Communications Platform as a Service API
  version: 1.0.0
  contact:
    name: Devotel
    url: https://devotel.io
    email: support@devotel.io
  license:
    name: Proprietary
servers:
  - url: https://api.orbit.devotel.io
    description: Production
security:
  - Bearer: []
  - ApiKey: []
tags:
  - name: Messages
    description: >-
      Send and manage messages across all channels (SMS, WhatsApp, RCS, Email,
      Viber, etc.)
  - name: Agents
    description: AI agent creation, configuration, and execution
  - name: Voice
    description: Voice calls, IVR, conferencing, and SIP trunking
  - name: Webhooks
    description: Webhook endpoint management and delivery logs
  - name: Numbers
    description: Phone number search, provisioning, and configuration
  - name: Contacts
    description: Contact management, segmentation, and lifecycle tracking
  - name: Campaigns
    description: Marketing campaign orchestration and analytics
  - name: Flows
    description: Automation flow builder and execution engine
  - name: Templates
    description: Message template management and approval workflows
  - name: Settings
    description: Organization, channel, and user preference settings
  - name: Verify
    description: OTP generation and verification across channels
  - name: Push
    description: Push notification delivery via FCM and APNs
  - name: Telegram
    description: >-
      Telegram bring-your-own-bot channel: connect a bot, verify a chat against
      the shared sandbox bot, and read unified channel state. Production sends
      go through the Messaging API.
  - name: USSD
    description: >-
      Menu-driven USSD for feature phones: define a menu tree, simulate session
      steps, and host the tenant-scoped aggregator callback.
  - name: Integrations
    description: Third-party service connections and OAuth management
  - name: Files
    description: >-
      Server-to-server media upload, listing, retrieval, and deletion
      (signed-URL backed)
  - name: Messaging Services
    description: >-
      Twilio MessagingService-parity containers bundling sender pool, opt-out
      list, inbound webhook, and sticky-sender/geomatch flags
  - name: Sender Pools
    description: >-
      Group sending numbers into pools with a selection strategy (sticky /
      round-robin / random) for outbound sends
  - name: Opt-Out Lists
    description: >-
      Per-list STOP / HELP / START keyword sets and auto-response copy (Twilio
      Advanced Opt-Out parity)
  - name: SMPP
    description: Tenant BYO-SMPP bind credentials and upstream termination carriers
  - name: Commerce
    description: >-
      Unified omnichannel conversational-commerce: cart/checkout state machine,
      cross-channel payment reconciliation, hosted pay-by-link, native WhatsApp
      checkout, and agentic-checkout payment mandates
  - name: Orby
    description: >-
      In-dashboard Orby operator assistant: streamed assistant turns,
      conversation threads, product knowledge-base search, and the tool-action
      approval gate. Available to signed-in operators only (dashboard session
      auth — API-key requests are rejected).
paths:
  /api/v1/numbers/regulatory-preview:
    get:
      tags:
        - Numbers
      summary: Pre-purchase regulatory preview for one country
      description: >-
        Live, single-country regulatory preview a buyer calls BEFORE
        `/numbers/purchase`: the identity/address documents and data fields a
        purchase will require, the expected activation window for regulated
        countries, and — scoped to the caller's organization — whether an
        existing compliance profile already satisfies the requirements
        (`compliance_profile_satisfies`). Use the all-country catalog
        `/numbers/regulatory-requirements` for bulk discovery; use this for the
        at-a-glance 'documents needed' disclosure on a specific country/line
        type. Pre-purchase discovery read; scoped on `numbers:read`.
      parameters:
        - schema:
            type: string
          in: query
          name: country
          required: false
          description: >-
            ISO 3166-1 alpha-2 country code (required — a missing/invalid value
            returns a 422 envelope from the handler).
        - schema:
            type: string
          in: query
          name: phone_number_type
          required: false
          description: >-
            Line type the requirements vary by — one of `local` | `mobile` |
            `toll_free` (default `local`).
        - schema:
            type: string
          in: query
          name: provider
          required: false
          description: >-
            Optional carrier to narrow the schema to — one of `telnyx` |
            `didww`. When omitted, the requirement sets from every provider that
            could serve the country are unioned.
        - name: X-Test-Mode
          in: header
          required: false
          description: >-
            Sandbox opt-in for Clerk-session-authenticated requests. Set to
            `true` to route the call through the test-mode pipeline: no real
            provider delivery, no credits deducted, response `meta.test_mode:
            true`. **Ignored for live API keys (`dv_live_sk_*`)** —
            server-to-server clients must use a test-prefixed key
            (`dv_test_sk_*`) to exercise sandbox. Test-prefixed keys
            unconditionally enable sandbox regardless of this header.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
      responses:
        '200':
          description: Single-country pre-purchase regulatory preview
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                description: Single-country pre-purchase regulatory preview
                properties:
                  data:
                    type: object
                    additionalProperties: true
                    properties:
                      country:
                        type: string
                      provider:
                        type: string
                        description: >-
                          `platform` when the requirement sets were unioned
                          across carriers, or the specific carrier when
                          `?provider=` was pinned.
                      phone_number_type:
                        type: string
                      activation_eta:
                        type:
                          - 'null'
                          - object
                        additionalProperties: true
                        description: >-
                          Expected review window for regulated countries, or
                          null when the country/type activates instantly.
                        properties:
                          typical_minutes:
                            type: integer
                          max_hours:
                            type: integer
                      fields:
                        type: array
                        description: Data fields the carrier/registry requires.
                        items:
                          type: object
                          additionalProperties: true
                          properties:
                            name:
                              type: string
                            type:
                              type: string
                            description:
                              type: string
                            required:
                              type: boolean
                      document_roles:
                        type: array
                        description: >-
                          Document roles to collect (e.g. `id_proof`,
                          `address_proof`).
                        items:
                          type: string
                      known_compliance_profile_id:
                        type: string
                        description: >-
                          Existing org compliance profile that covers this
                          country, when one is found.
                      compliance_profile_satisfies:
                        type: boolean
                        description: >-
                          True iff the caller org already has a profile
                          satisfying the required fields + documents (always
                          true for unregulated countries).
                      unregulated:
                        type: boolean
                        description: >-
                          True when neither the registry nor the live carrier
                          asks for any docs/fields — render an
                          instant-activation panel.
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                        description: >-
                          Unique request identifier (also returned in
                          X-Request-Id header)
                      timestamp:
                        type: string
                        format: date-time
                        description: ISO 8601 UTC timestamp of the response
        '400':
          $ref: '#/components/responses/StandardError'
        '401':
          $ref: '#/components/responses/StandardError'
        '403':
          $ref: '#/components/responses/StandardError'
        '404':
          $ref: '#/components/responses/StandardError'
        '422':
          description: >-
            Unprocessable entity — the request was well-formed but semantically
            invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                      - status
                    properties:
                      code:
                        type: string
                        description: >-
                          Machine-readable error code (e.g.
                          INVALID_PHONE_NUMBER)
                      message:
                        type: string
                        description: Human-readable error description
                      status:
                        type: integer
                        description: HTTP status code
                      details:
                        type: object
                        additionalProperties: true
                        description: Additional context about the error
                  meta:
                    type: object
                    properties:
                      request_id:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
                      docs_url:
                        type: string
                        format: uri
                        description: Link to relevant error documentation
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/StandardError'
components:
  responses:
    StandardError:
      description: >-
        Standard error envelope. `error.code` is machine-readable; see the
        [error reference](https://docs.orbit.devotel.io/reference/error-codes)
        for the catalogue.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - status
                properties:
                  code:
                    type: string
                    description: Machine-readable error code (e.g. INVALID_PHONE_NUMBER)
                  message:
                    type: string
                    description: Human-readable error description
                  status:
                    type: integer
                    description: HTTP status code
                  details:
                    type: object
                    additionalProperties: true
                    description: Additional context about the error
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  docs_url:
                    type: string
                    format: uri
                    description: Link to relevant error documentation
    RateLimitedResponse:
      description: >-
        Rate limit exceeded. Wait `error.retry_after` seconds (or read the
        `Retry-After` header) before retrying. Returned when the request would
        exceed the bucket identified by `X-RateLimit-Bucket`.
      headers:
        X-RateLimit-Limit:
          description: Total request quota for the current window.
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Remaining:
          description: Requests remaining in the current window.
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Reset:
          description: >-
            Absolute unix-epoch-seconds timestamp at which the current window
            resets.
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Bucket:
          description: >-
            Name of the rate-limit bucket the request was bound by (e.g.
            `auth-write`, `money`, `agent-invoke`, or `custom:<max>/<window>`).
            Stripe-style — lets clients see which named cap they hit.
          schema:
            type: string
        RateLimit-Limit:
          description: >-
            draft-ietf-httpapi-ratelimit-headers no-prefix mirror of
            `X-RateLimit-Limit`. Some SDKs read only this form.
          schema:
            type: integer
            minimum: 0
        RateLimit-Remaining:
          description: >-
            draft-ietf-httpapi-ratelimit-headers no-prefix mirror of
            `X-RateLimit-Remaining`.
          schema:
            type: integer
            minimum: 0
        RateLimit-Reset:
          description: >-
            draft-ietf-httpapi-ratelimit-headers no-prefix mirror — delta
            seconds from now until the window resets (NOT epoch).
          schema:
            type: integer
            minimum: 0
        Retry-After:
          description: >-
            RFC 7231 §7.1.3 — number of seconds the client should wait before
            retrying.
          schema:
            type: integer
            minimum: 1
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                required:
                  - code
                  - message
                  - status
                  - retry_after
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMITED
                    description: >-
                      Always `RATE_LIMITED` — the global request-limiter 429.
                      Distinct from `RATE_LIMIT_EXCEEDED`, the live
                      per-recipient/per-tenant/per-resource frequency-cap 429
                      (not retired).
                  message:
                    type: string
                  status:
                    type: integer
                    enum:
                      - 429
                  retry_after:
                    type: integer
                    minimum: 1
                    description: >-
                      Seconds to wait before retrying. Mirrors `Retry-After`
                      header.
              meta:
                type: object
                properties:
                  request_id:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  docs_url:
                    type: string
                    format: uri
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Dashboard JWT token from Clerk
    ApiKey:
      type: apiKey
      name: X-API-Key
      in: header
      description: Server-to-server API key (dv_live_sk_*)

````