---
title: "Port numbers in"
method: POST
path: "/v1/phone-numbers/port-in"
tags: ["Phone Numbers"]
---

# Port numbers in

`POST /v1/phone-numbers/port-in`

Submit a port-in for one or more existing numbers from another carrier.
Creates the carrier order(s), attaches the end-user (current account)
info plus the LOA and invoice documents, and submits to the losing
carrier. The transfer PIN is forwarded to the carrier and never stored.
Ported numbers arrive voice-ready (and SMS-ready where the order
supports messaging).

Run the portability check (POST /v1/phone-numbers/port-in/check) and
upload the two documents (POST /v1/phone-numbers/port-in/documents)
first — uploaded documents must be attached to an order within 30
minutes or the carrier deletes them, so upload right before this call.
The carrier may split the numbers into several orders (by country,
number type, losing carrier); `orders` carries per-order results, and a
partial failure still returns 201 with the failed orders' `error` set
(they stay as cancellable drafts).

Non-US/CA numbers additionally need the country-specific values from
GET /v1/phone-numbers/port-in/requirements, passed via `requirements`,
and must be submitted one country per request. When required
information is still missing after submission, the order is kept as a
resumable draft whose `error` / `declineReason` names the gaps.

## Request body

- object
  - `phoneNumbers` string[], required — E.164 numbers to port in.
  - `endUser` object, required — End-user / current-carrier account info that authorizes the port. The losing carrier matches every field against its records and rejects the whole port on a mismatch — enter values exactly as they appear on the carrier bill.
    - `entityName` string, required — Account holder / business name, as on the carrier account.
    - `authPersonName` string, required — Full name (first + last) of the person authorizing the port — must match the LOA signature.
    - `billingPhoneNumber` string — Phone number on the losing carrier's bill. Defaults to the ported number itself on single-number orders. Validated as a real phone number when present.
    - `accountNumber` string, required — Account number with the losing carrier — required (carriers reject ports without it; on prepaid mobile plans it is often the phone number itself).
    - `pinPasscode` string — Transfer PIN. Required for US/CA mobile numbers (wireless carriers reject PIN-less ports). Forwarded to the carrier, never stored. International porting codes (e.g. the UK PAC) go through `requirements` instead.
    - `taxIdentifier` string — Company tax id on the carrier account (EU ports, e.g. Spanish CIF).
    - `businessIdentifier` string — Business registration id on the carrier account (EU ports).
    - `streetAddress` string, required
    - `extendedAddress` string
    - `locality` string, required
    - `administrativeArea` string — Region. Required for US/CA as the 2-letter state/province code (full names are accepted and normalized); optional elsewhere.
    - `postalCode` string, required — Postal code. Validated as a US ZIP / Canadian postal code for US/CA; free-form elsewhere.
    - `countryCode` 'US' | 'CA' | 'GB' | 'ES' | 'DE' | 'FR' | 'NL' | 'AU' | 'BR', required — Service-address country (a supported port-in country).
  - `loaDocumentId` string, required — Document id from POST /v1/phone-numbers/port-in/documents (kind=loa).
  - `invoiceDocumentId` string, required — Document id from POST /v1/phone-numbers/port-in/documents (kind=invoice).
  - `focDatetimeRequested` string, date-time — Requested port date; the carrier confirms the actual FOC later. US/CA default is one week out (shifted off weekends); international orders are scheduled into the carrier's next allowed porting window at or after this date.
  - `customerReference` string
  - `portType` 'full' | 'partial' — Whether the losing account ports all its numbers (full) or keeps some (partial).
  - `requirements` object[] — Country-specific requirement values for international ports (from GET /v1/phone-numbers/port-in/requirements). Not needed for US/CA. The LOA and invoice requirements are satisfied automatically by loaDocumentId/invoiceDocumentId, and address-type requirements by the endUser service address.
    - `requirementTypeId` string, required — The requirement's id, from the requirements endpoint.
    - `fieldValue` string, required — Text value, ISO datetime, or a documentId from POST /v1/phone-numbers/port-in/documents, per the requirement's kind.

## Response `201`

Port submitted. Top-level fields mirror the first successfully submitted order; per-order truth (including failures) is in `orders`.

- object
  - `id` string — Porting order ID.
  - `telnyxPortingOrderId` string
  - `status` 'draft' | 'pending' | 'foc_confirmed' | 'ported' | 'exception' | 'cancelled'
  - `phoneNumbers` string[]
  - `orders` object[]
    - `id` string
    - `telnyxPortingOrderId` string
    - `status` string
    - `phoneNumbers` string[]
    - `error` string — Present when this split order failed to submit (it stays as a cancellable draft).

## Other responses

- `400` — Invalid request
- `401` — Unauthorized
- `409` — A number is already provisioned, or already in an in-flight port
- `422` — A number is not portable (reason included), numbers span multiple non-US/CA countries, or every split order failed to submit

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/revisions/5bcceb4c15ba/schema)