KYC for regulated countries

Many countries regulate who can hold a phone number. Before a number in those countries is ordered, the registrant (you, or your customer) proves who they are and where they are. Pozy collects the details, files them with the carrier and tracks the review. Numbers usually activate 1 to 3 business days after you submit.

You hit this flow when GET /v1/phone-numbers/countries shows needsKyc: true, or when a purchase answers 202 with status: "kyc_required".

#Two ways to collect the details

#Hand the form to your customer

POST /v1/phone-numbers/kyc/share returns a single-use page, valid for 7 days, that walks your customer through the country's requirements. It needs no Pozy login.

curl -X POST https://api.pozy.ai/v1/phone-numbers/kyc/share \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "6650c1f0a2b3c4d5e6f70812",
    "country": "GB",
    "language": "en",
    "branding": { "companyName": "Acme", "logoUrl": "https://acme.example.com/logo.png", "brandColor": "#1a73e8" },
    "redirect_url": "https://acme.example.com/numbers/done"
  }'

const res = await fetch("https://api.pozy.ai/v1/phone-numbers/kyc/share", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    profileId: "6650c1f0a2b3c4d5e6f70812",
    country: "GB",
    language: "en",
    branding: { companyName: "Acme", logoUrl: "https://acme.example.com/logo.png", brandColor: "#1a73e8" },
    redirect_url: "https://acme.example.com/numbers/done",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.url, data.expiresAt);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/phone-numbers/kyc/share",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "profileId": "6650c1f0a2b3c4d5e6f70812",
        "country": "GB",
        "branding": {"companyName": "Acme", "logoUrl": "https://acme.example.com/logo.png"},
        "redirect_url": "https://acme.example.com/numbers/done",
    },
    timeout=30,
)
print(resp.json()["url"])

• branding puts your company name, logo and colour on the page.
• language sets the page language: en, es or pt-BR. Without it, the page follows the browser and falls back to English.
• redirect_url sends the customer back to your app afterwards, with kyc=submitted and country=<code> added to the query string.
• areaCode holds the order to one area.

When your customer submits, the number enters review under your workspace and whatsapp.number.kyc_submitted fires.

#Submit through the API

{
  "country": "GB",
  "numberType": "local",
  "fields": [
    { "requirementId": "d7e8f9a0-b1c2-4d3e-9f4a-5b6c7d8e9f0a", "label": "Business name", "kind": "text", "example": "Acme Ltd" },
    { "requirementId": "e8f9a0b1-c2d3-4e4f-8a5b-6c7d8e9f0a1b", "label": "Proof of identity", "kind": "file" },
    { "requirementId": "f9a0b1c2-d3e4-4f5a-9b6c-7d8e9f0a1b2c", "label": "Business address", "kind": "address", "localTo": "GB" }
  ],
  "reusable": null,
  "pendingReview": false
}

curl -X POST https://api.pozy.ai/v1/phone-numbers/kyc \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "6650c1f0a2b3c4d5e6f70812",
    "country": "GB",
    "submissionId": "acme-gb-0001",
    "values": { "d7e8f9a0-b1c2-4d3e-9f4a-5b6c7d8e9f0a": "Acme Ltd" },
    "documents": [
      { "requirementId": "e8f9a0b1-c2d3-4e4f-8a5b-6c7d8e9f0a1b", "filename": "passport-both-sides.pdf", "base64": "JVBERi0xLjQK..." }
    ],
    "address": {
      "requirementId": "f9a0b1c2-d3e4-4f5a-9b6c-7d8e9f0a1b2c",
      "country_code": "GB",
      "street_address": "221 Baker Street",
      "locality": "London",
      "administrative_area": "London",
      "postal_code": "NW1 6XE"
    }
  }'

Document bytes go straight to the carrier with the request. Pozy does not keep a copy.

#Out of stock: pre-order

When available is false but preOrderable is true, submit the same form with preOrder: true. Pozy takes the next number that comes back in stock, or one the carrier sources for this registration.

• Sourcing usually takes 2 to 4 weeks and is not guaranteed.
• The number stays pending_regulatory until sourced. Nothing is billed until it is active.
• If the carrier cannot source it, the number is declined and nothing is charged.
• To cancel, release the pending number with DELETE /v1/phone-numbers/{id}.

In geo countries the area comes from the address. If that area has no stock, the first submit returns 409 with code: "area_pre_order_available" and details (areaCode, areaName, estimatedWeeks, billedWhenActive). The error text is ready to show your customer. Once they agree to wait, resend the same body with preOrder: true.

#Forward the identity-check link

Some countries (Australian mobiles, for example) need the end user to pass a live identity check after the order is placed. When the form had an action field:

1. Poll GET /v1/phone-numbers/{id} after submitting. The check link appears on the number in onfidoVerificationUrl once the order exists.
2. Or listen for whatsapp.number.verification_required, which carries the same link in verificationUrl.
3. Send the link to the person whose ID is on file. The review waits until they finish.

#Fix a declined number

A declined number stays in your list with status: "regulatory_declined" and a regulatoryDeclineReason. You do not start over.

1. GET /v1/phone-numbers/{id}/remediate returns only the requirements the reviewer flagged.
2. POST /v1/phone-numbers/{id}/remediate with corrected values, documents or address.

The number goes back to pending_regulatory on the same record and is not billed again.

#Answer the reviewer

Sometimes the reviewer asks a question rather than flagging a field ("is this a personal or a business line?"). POST /v1/phone-numbers/{id}/remediate/respond sends a message, plus any corrected documents or address and up to 5 attachments (PDF, JPG, PNG or WebP, sent as base64, about 3 MB in total per request). The response status is replied for a message alone and resubmitted when corrections went with it.

curl -X POST https://api.pozy.ai/v1/phone-numbers/6650d2e1b3c4d5e6f7081923/remediate/respond \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "This is a business line for Acme Ltd. The utility bill is in the company name." }'

#Statuses and events

These events carry a whatsapp. prefix for historical reasons and fire for every number. No event fires when you submit through the API, because you already know.

#Limits

#Errors

#Endpoints

#Webhook events