Port a number in

Porting moves a number you already have at another carrier onto Pozy, so it keeps ringing for your customers while you gain the API. The number arrives ready for calls, and ready for SMS where the order supports messaging. Porting itself is free. The number bills its normal monthly price once it is active.

#What you need

• The number or numbers, in E.164.
• A signed Letter of Authorization (LOA) from the account holder.
• A recent invoice from the current carrier.
• The account details on that carrier: account holder name, authorized person, account number, service address, and a transfer PIN for US and Canadian mobiles.

#Where porting works

International ports can take several weeks while the carrier and the local regulator review the documents.

curl -X POST https://api.pozy.ai/v1/phone-numbers/port-in/check \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumbers": ["+34911234567", "+14155550188"] }'

const res = await fetch("https://api.pozy.ai/v1/phone-numbers/port-in/check", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phoneNumbers: ["+34911234567", "+14155550188"] }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
for (const r of data.results) console.log(r.phoneNumber, r.portable, r.notPortableReason);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/phone-numbers/port-in/check",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={"phoneNumbers": ["+34911234567", "+14155550188"]},
    timeout=30,
)
for r in resp.json()["results"]:
    print(r["phoneNumber"], r["portable"], r["notPortableReason"])

curl -X POST https://api.pozy.ai/v1/phone-numbers/port-in/documents \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -F file=@loa.pdf \
  -F kind=loa

curl -X POST https://api.pozy.ai/v1/phone-numbers/port-in \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["+34911234567"],
    "loaDocumentId": "3f2a9c1e-7b4d-4e8a-9c6f-1d2e3f4a5b6c",
    "invoiceDocumentId": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "endUser": {
      "entityName": "Acme SL",
      "authPersonName": "Lucia Martin",
      "accountNumber": "A-778812",
      "streetAddress": "Calle de Alcala 42",
      "locality": "Madrid",
      "postalCode": "28014",
      "countryCode": "ES",
      "taxIdentifier": "B12345674"
    },
    "requirements": [
      { "requirementTypeId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "fieldValue": "B12345674" }
    ],
    "customerReference": "acme-port-01"
  }'

#Submit options

Put numbers from different countries in separate requests whenever any of them is outside the US and Canada.

#Read the response

The carrier may split one request into several orders (by country, number type or current carrier). orders[] holds the result of each.

{
  "id": "67d0e1f2a3b4c5d6e7f8a9b0",
  "status": "pending",
  "phoneNumbers": ["+34911234567"],
  "orders": [
    { "id": "67d0e1f2a3b4c5d6e7f8a9b0", "status": "pending", "phoneNumbers": ["+34911234567"] }
  ]
}

A partial failure still returns 201. The failed orders carry an error and stay as drafts you can fix and resubmit. GET /v1/phone-numbers/port-in/{id}/requirements lists what an order is still missing at any time.

#Track the order

GET /v1/phone-numbers/port-in lists your orders, newest first.

Cancel any order that has not reached ported with DELETE /v1/phone-numbers/port-in/{id}.

#After the port

The ported number shows up in GET /v1/phone-numbers like a purchased one. From there:

• Route its calls.
• Enable SMS, and register it if it is a US number.
• Connect WhatsApp.

#Errors

#Endpoints