Zernio
Zernio
API Reference

Phone Numbers

Numbers

List phone numbersGETGet phone numberGETPurchase phone numberPOSTResolve a number claimGETRelease phone numberDELETE

Availability

List offerable number countriesGETCheck country availabilityGETSearch available numbersGET

Stock Watches

List stock watchesGETWatch an out-of-stock countryPOSTStop watching a countryDELETE

KYC

Get KYC form specGETSubmit KYCPOSTPre-validate KYC addressPOSTPre-review a KYC packetPOSTUpload a KYC documentPOSTView a KYC document on fileGETCreate a hosted KYC linkPOST

Remediation

Get declined requirementsGETResubmit a declined numberPOSTReply to the regulatory reviewerPOSTRespond to the regulatory reviewer (message + corrections)POST

Porting

Check portabilityPOSTCountry porting requirementsGETPort numbers inPOSTList port-in ordersGETResolve a port claimGETA port-in order's pending requirementsGETUpload a porting documentPOSTCancel a port-inDELETE

Other

Request the WhatsApp verification code for a numberPOST
Dashboard
llms.txtOpenAPI
OverviewPlatformsAPI ReferenceResources
Phone Numbers

Submit KYC

Submit the end customer's KYC (textual values, uploaded documents, address) for a Tier 3/4 country. Documents are streamed straight to the number provider and are not stored by Zernio. Builds + submits a regulatory requirement group and claims a pending_regulatory slot; the number is ordered + activated once the provider approves (asynchronous). A customer may hold several same-country numbers in review at once; a double-submit of the SAME attempt is deduped via submissionId.

For an ID-card document requirement, carriers commonly require BOTH sides: combine the front and back into a single file before uploading (the dashboard does this automatically). A one-sided ID is a common decline reason; fix it via POST /v1/phone-numbers/{id}/remediate.

Before submitting, call GET /v1/phone-numbers/availability to check the country has deliverable inventory and, for geographic-match countries, which area the address must be in. Otherwise the submission can pass review yet never be assignable a number.

POST
/v1/phone-numbers/kyc

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication: send your Zernio API key in the Authorization header, prefixed with Bearer.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

import Zernio from '@zernio/node';const zernio = new Zernio({ apiKey: process.env.ZERNIO_API_KEY });const { data } = await zernio.phonenumbers.submitPhoneNumberKyc({  body: {    profileId: 'profile_abc123',    country: 'string',  },});console.log(data);
{  "status": "kyc_submitted",  "preOrder": true,  "phoneNumber": {    "id": "string",    "status": "string",    "country": "string"  },  "numbers": [    {      "id": "string",      "status": "string",      "phoneNumber": "string",      "country": "string"    }  ]}
Was this page helpful?

Get KYC form spec

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.

Pre-validate KYC address

Optional early check for the address step of a Tier 4 (end-user identity) registration: validates a postal address for deliverability BEFORE the full KYC submit, so it can be corrected before any documents are uploaded. The full submit (POST /v1/phone-numbers/kyc) re-validates the address, so this call is purely a fast feedback path and skipping it is safe. Only the postal address is sent (no documents, no gov-ID fields). A region (`administrative_area`) is required by the validator; when it is omitted the pre-check is skipped and `{ ok: true, skipped: true }` is returned (the final submit still validates).

profileId*string
country*string
submissionId?string

Idempotency token for this submission attempt. Once the number has been ordered, a retry with the same token returns that same number instead of ordering another. A submission that fails before the number is ordered releases the token, so you can correct your details and re-submit with it. Omit it and every call provisions a new number.

quantity?integer

Provision several same-country numbers from one submission (1-5). The single verification covers all of them; each number is billed only when it activates. Numbers that fail to order are skipped (best-effort). With areaCode, a quantity above that area's live stock is rejected with a 400.

Range1 <= value <= 5
Default1
reuse?boolean

Reuse a prior approved verification for this country (skips document/field collection; places the order immediately).

reuseOptionId?string

Which reusable verification to use (GET reusable.options[].id). The unambiguous selection key. Omitted = the approved default. No match = 409.

reuseFrom?string

Legacy fallback for reuseOptionId: the source phone number (GET reusable.options[].fromPhoneNumber). Ambiguous when a number labels two verifications, so prefer reuseOptionId. Omitted = the approved default. No match = 409.

areaCode?string

Area code (NDC) the number must be in. Hard constraint: an empty area pool fails with 409 code AREA_CODE_UNAVAILABLE instead of ordering from another area. Omit for any area. Options come from GET /v1/phone-numbers/availability (areaOptions); the purchase 202 kycUrl echoes the areaCode picked at purchase time so it can be passed here.

Match^\d{1,4}$
preOrder?boolean

With areaCode: pre-order that area when it has no stock (an area listed in soldOutAreas with preOrderable true) instead of failing with AREA_CODE_UNAVAILABLE. The carrier sources a number in that area. Without areaCode it accepts the pre-order a previous submit offered with 409 code area_pre_order_available (a geographic-match country whose address area has no stock): resend the same body with preOrder true and the order is placed for that area. A whole pair with no stock is pre-ordered without either flag.

endUserFirstName?string

End user's legal first name. Required when the country has an action/ID-verification (Onfido) requirement.

endUserLastName?string

End user's legal last name. Same condition as endUserFirstName.

values?

requirementId → textual value

documents?array<|>

One per document requirement. Each is EITHER inline base64 OR a documentId returned by POST /v1/phone-numbers/kyc/upload-document (use the upload endpoint for large files to stay under the request-size limit).

address?