Porting endpoint reference

Every endpoint you need to port a number, in the order you will use them. Nothing else — account, API-key and admin management are covered by the Authentication guide, and each section below links to the guide with full request/response examples.

All endpoints take Authorization: Bearer pk_live_YOUR_KEY. Interactive schemas for every endpoint live in the API reference.

Before ordering

Method & path	Purpose
`POST /v2/portability_checks`	Can these numbers port? Country, number type, current carrier, provider
`GET /v2/porting/requirements?phone_number=` (or `?country_code=&number_type=`)	What porting that number needs — no order created; incl. the localized LOA text to show the signer

The order

Method & path	Purpose
`POST /v2/porting_orders`	Open `draft` order(s) with requirements attached — phone numbers are all it takes. JSON body; supports `Idempotency-Key`
`GET /v2/porting_orders`	List your orders — filter by `status`, `batch_id`, `customer_reference`
`GET /v2/porting_orders/{id}`	One order: status, numbers, requirements (incl. per-field status + `exception_reason`)
`PATCH /v2/porting_orders/{id}`	Edit a `draft`/`rejection` order's settings: FOC date, reference, routing, webhook override
`DELETE /v2/porting_orders/{id}`	Delete a never-submitted `draft`; frees its numbers for a new order

Requirements on the order

Method & path	Purpose
`GET /v2/porting_orders/{id}/requirements`	The order's requirements and their fulfillment status
`PATCH /v2/porting_orders/{id}/requirements/{slug}`	Fulfill one, by slug (e.g. `auth_person_name`, `location`, `recent_invoice`, `loa`): `field_value` (text, address object, or document id), `signature` (base64 PNG for the LOA), or — document requirements only — the file itself as `multipart/form-data` (uploads + attaches in one call)

The array covers everything, end-user data included: auth_person_name, entity_name, billing_phone_number and location (an address object) are ordinary requirements on every order — there is no separate end-user object to manage. How each field_type is fulfilled — with examples — is in Port-in orders → Requirements.

Documents

Method & path	Purpose
`POST /v2/documents`	Upload a file (PDF/PNG/JPEG/TIFF, ≤ 20 MB) without attaching it — useful when one file serves several orders; attach the returned id to a requirement. Direct-uploaded files (multipart PATCH on a requirement) land here too
`GET /v2/documents`	List your documents
`GET /v2/documents/{id}`	Metadata for one document
`GET /v2/documents/{id}/download`	The file itself — incl. platform-generated signed LOA PDFs

Submit and track

Method & path	Purpose
`GET /v2/porting_orders/{id}/readiness`	Dry run of the submit validation: `ready` flag + what is still missing
`POST /v2/porting_orders/{id}/submit`	Submit for review (validated first; parks in `in_review` — our desk verifies every field, then forwards it to the losing carrier)
`POST /v2/porting_orders/{id}/cancel`	Request cancellation — instant while still `in_review`; `cancel_pending` until the carrier confirms once forwarded
`GET /v2/porting/loa/signatures/{document_id}`	Audit record of a signed LOA (signer, timestamp, IP, locale, SHA-256)

Progress and results

Method & path	Purpose
`POST /v2/webhook_endpoints`	Register a URL for signed event pushes (`porting_order.status_changed`, `loa.signed`, `number.activated`, …)
`GET /v2/porting/events?porting_order_id=`	Append-only event history — the polling fallback for missed webhooks
`GET /v2/numbers`	Your registry: ported numbers, lifecycle status, routing config

Webhook signature verification, retries and the delivery audit log: Webhooks. Numbers lifecycle and routing: Numbers registry. When another carrier asks to take a number away: Port-outs.