--- title: "Submit KYC" method: POST path: "/v1/messaging/phone-numbers/kyc" tags: ["Phone Numbers"] --- # Submit KYC `POST /v1/messaging/phone-numbers/kyc` ## Request - Base URL: `https://apihub.co.il` - URL: `https://apihub.co.il/v1/messaging/phone-numbers/kyc` - Auth: HTTP bearer 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. **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 - `reuse` boolean: Reuse a prior approved verification for this country (skips document/field collection; places the order immediately). - `values` object: requirementId → textual value - `address` object - `locality` string - `last_name` string - `first_name` string - `postal_code` string - `country_code` string - `business_name` string - `requirementId` string - `street_address` string - `extended_address` string: Address complement: apartment, suite, unit, or the quadra/lote used in some countries. Optional. Does not substitute for a building number on street_address. - `administrative_area` string - `country` string, required - `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. - `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. - `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. - `documents` union[]: 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). - union - object - `base64` string, required - `filename` string, required - `requirementId` string, required - object - `issuedAt` string, date: Date printed on the document (YYYY-MM-DD), for slots the regulator windows such as proof of address. The pre-submit review trusts it over its own read of the PDF. - `documentId` string, required: Id from POST /v1/phone-numbers/kyc/upload-document. - `requirementId` string, required - `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. - `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. - `reuseOptionId` string: Which reusable verification to use (GET reusable.options[].id). The unambiguous selection key. Omitted = the approved default. No match = 409. - `endUserLastName` string: End user's legal last name. Same condition as endUserFirstName. - `endUserFirstName` string: End user's legal first name. Required when the country has an action/ID-verification (Onfido) requirement. ## 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` - `status` 'kyc_submitted' | 'kyc_reused' | 'kyc_already_submitted' - `numbers` object[]: Every number provisioned from this submission. Length equals the requested `quantity` on full success (fewer if some orders failed; best-effort). The first element mirrors `phoneNumber`. - `id` string - `status` string - `country` string - `phoneNumber` string - `preOrder` boolean: True when this submission placed a pre-order instead of an order from stock: the country and type had nothing deliverable, the picked areaCode was sold out (preOrder: true sent), or the country requires the number's area to cover the registered address, that area has no stock, and the caller accepted the offer (preOrder true after a 409 area_pre_order_available; the carrier is then asked for a number in exactly that area). The number stays `pending_regulatory` until we get it, from regular stock the moment it returns or sourced by the carrier (usually 2 to 4 weeks, never guaranteed), and is not billed until active. Releasing it (DELETE /v1/phone-numbers/{id}) cancels the pre-order. A pre-order is one number: `quantity` above 1 is rejected with 400. - `phoneNumber` object: The first/primary number, kept at the top level for backward compatibility. See `numbers` for the full set when `quantity` > 1. - `id` string - `status` string - `country` string - `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)