---
title: "Get KYC form spec"
method: GET
path: "/v1/phone-numbers/kyc"
tags: ["Phone Numbers"]
---

# Get KYC form spec

`GET /v1/phone-numbers/kyc`

For a Tier 3/4 country, the fields the end customer must provide (Telnyx
regulatory requirements) before a number can be ordered: text, date,
address, or file (document) per requirement.

## Query parameters

- `country` string, required
- `numberType` 'local' | 'mobile' | 'national' | 'toll_free'

## Response `200`

The KYC form spec.

- object
  - `country` string
  - `numberType` string
  - `fields` object[]
    - `requirementId` string
    - `label` string
    - `kind` 'text' | 'date' | 'address' | 'file' | 'action' — "action" = an out-of-band verification (e.g. Onfido); not filled here, fulfilled after the order via a link.
    - `description` string, nullable — Plain-English explanation of what to provide.
    - `example` string, nullable — Concrete example value.
    - `localTo` string, nullable — ISO country the value must be local to
  - `reusable` object, nullable — Present when this account already has a reusable verification for the country (skip the form). `fromPhoneNumber`/`details` mirror the first option; `options` lists ALL reusable verifications (agencies hold one per end client), approved-first. Pass the chosen option's `id` as `reuseOptionId` on POST. Each option's `instant` says whether it activates in minutes (group-approved) or still queues for carrier review (1-3 days).
    - `available` boolean
    - `fromPhoneNumber` string
    - `details` object[] — Human-readable summary of the verification on file (field labels + values, plus the address as one line). Best-effort — may be empty if the provider lookup fails.
      - `label` string
      - `value` string
    - `options` object[] — One entry per distinct approved verification, newest first.
      - `id` string — Opaque option id — pass as `reuseOptionId` on POST. Stable selection key (a phone number is not unique across verifications).
      - `fromPhoneNumber` string — Display only — the number this verification was submitted for. Not a selection key.
      - `instant` boolean — true = group-approved, a new order activates in minutes; false = documents are reused but the order still queues for carrier review (1-3 days).
      - `details` object[]
        - `label` string
        - `value` string
        - `documentId` string — Present on document rows — the Telnyx document id. GET /v1/whatsapp/phone-numbers/kyc/document/{documentId} streams it (auth-scoped, inline PDF).
  - `pendingReview` boolean — true when this account already has a number for this country in regulatory review (status pending_regulatory). Scope is the whole account across all profiles, and the country only (any number type), so it is not a per-end-client signal on a multi-tenant setup. Informational only: it never blocks a submission, and several same-country numbers may sit in review at once. For a per-end-client view, call GET /v1/phone-numbers with `profileId` and `status=pending_regulatory`; that view also lists numbers declined in the last 30 days.

## Other responses

- `400` — Country not available
- `401` — Unauthorized

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/revisions/15e893e69e8c/schema)