Sign in

v2

latestOpenAPI 3.1.02026-08-075421692.0 MB
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

Request body

profileIdstring required
countrystring required
submissionIdstring

Idempotency token for this submission attempt. A retry/double-submit with the same token returns the same number; omit and each call creates a new number.

quantityinteger

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.

reuseboolean

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

reuseOptionIdstring

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

reuseFromstring

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

areaCodestring

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.

endUserFirstNamestring

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

endUserLastNamestring

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

valuesobject

requirementId → textual value

Response

KYC submitted (or already submitted); number pending review.

status'kyc_submitted' | 'kyc_reused' | 'kyc_already_submitted'