---
title: "Create a hosted KYC link"
method: POST
path: "/v1/messaging/phone-numbers/kyc/share"
tags: ["Phone Numbers"]
---

# Create a hosted KYC link

`POST /v1/messaging/phone-numbers/kyc/share`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/messaging/phone-numbers/kyc/share`
- Auth: HTTP bearer

Create a single-use, 7-day hosted KYC link that your end customer
completes WITHOUT a Zernio login. Useful when the person who holds the
ID and address is not your team. They fill the regulated verification on
a Zernio-hosted page; the number provisions under YOUR account once they
submit. Only regulated (KYC) countries are valid: a country that does not
require KYC returns 400.

Pass `numberType` (`local`, `mobile`, `national`, `toll_free`) to choose
which of the country's offered types the shared form collects KYC for and
eventually orders; omitted defaults to the country's default type (which
may be `national` and therefore have no inventory in a geographic area
code). Pass `areaCode` (NDC digits) to constrain the eventual order to a
specific area; it is validated against the chosen `numberType`.

White-label the page with `branding` (your company name, logo, brand
color). Supply `redirect_url` to send the end customer back to your own
site after a successful submit (completion params are appended; see
below). Listen for the `whatsapp.number.kyc_submitted` webhook to react
when the form is completed.


**Billing:** Request; paid actions are priced in credits (see GET /v1/messaging/prices) · **Rate limit:** 60/min

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Request body

- object
  - `country` string, required: ISO 3166-1 alpha-2 country code (must be a regulated/KYC country).
  - `areaCode` string: Area code (NDC) the eventual number must be in. Hard constraint carried by the link; the end customer filling the form makes no area choice. Options come from GET /v1/phone-numbers/availability (areaOptions).
  - `branding` object: Optional white-label of the hosted page the end customer sees.
    - `logoUrl` string, uri: Logo shown above the form.
    - `brandColor` string: Hex color (e.g. #1a73e8) used as a brand accent on the page.
    - `companyName` string: Your company name, shown on the hosted page.
  - `language` 'en' | 'es' | 'pt-BR': Language of the hosted page: its copy, the carrier requirement texts (translated once per country and cached), the pre-submit review notes and the status emails to the end customer. Omitted: the browser language of the end customer, falling back to English. The end customer can also switch with `?lang=` on the page.
  - `redirect_url` string, uri: Where to send the end customer's browser after a successful submit. On completion Zernio appends `kyc=submitted` and `country=<ISO-2>` as query params. When omitted, the hosted page shows a built-in confirmation screen instead.

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
    - `url` string: The hosted link to send your end customer.
    - `token` string
    - `expiresAt` string, date-time
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)