Port-In Request Object

The Port-In Request object represents a request to port one or more phone numbers from another carrier (the losing carrier) onto the CarrierX network. It holds the account holder's information at the losing carrier, the phone numbers to be ported, and the current lifecycle status of the request.

A port-in request moves through a series of statuses as it is validated, submitted to the losing carrier, approved, and activated. Refer to the Port-In Request Status Values section below for details on each status, and to Update Port-In Request for how a partner drives a request through the workflow.

Once a request reaches carrier_approved, a Phone Number object is created for the partner with a pending_port_in status. When the request is completed, the phone number is activated and moved to assigned status.

Port-In Request Object Attributes

The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Attribute	Data Type	Description
account_number createupdate	string	The account number for the customer's account with the losing carrier.
account_pin createupdate	string	The PIN set by the customer on their losing carrier account, used to authorize the port-out request. The losing carrier validates this value before releasing the number; a mismatch will cause the port to be rejected
customer_address1 createupdate	string	Service address line 1 for the account holder at the losing carrier.
customer_address2 createupdate	string	Service address line 2 for the account holder at the losing carrier.
customer_city createupdate	string	Service address city for the account holder at the losing carrier.
customer_company createupdate	string	The company name of the account holder at the losing carrier, if applicable.
customer_full_name createupdate	string	The full name of the account holder at the losing carrier.
customer_state createupdate	string	Service address state for the account holder at the losing carrier, as a 2-letter code.
customer_zip createupdate	string	Service address ZIP code for the account holder at the losing carrier.
date_created read only	string	The date and time when the request was created.
date_modified read only	string	The date and time when the request was last modified.
errors read only	array of objects	The list of validation and carrier errors reported against the request. Refer to the table below for more information, and to Get Port-In Request Errors to retrieve this list directly.
existing_service_provider read only	string	The SPID (Service Provider ID) of the losing carrier, i.e. the carrier the phone numbers are being ported away from. This value is derived automatically from the phone numbers provided during system precheck and cannot be set directly by the partner.
gaining_service_provider read only	string	The SPID of the gaining carrier, i.e. the carrier the phone numbers are being ported to. This value is derived from the partner's underlying carrier configuration and cannot be set directly.
loa createupdate	string	A link to the signed Letter of Authorization (LOA) document authorizing the port. A signed LOA is required for every port-in request, submitted through this API or otherwise. The list of phone numbers does not need to be included on the LOA itself if there are too many to list.
partner_sid read only	string	The secure ID of the partner that owns this request. This value is set automatically from the authenticated partner making the request.
phonenumbers createupdate	array of strings	The phone numbers to be ported, in E.164-without-plus format (digits only, e.g. ["19512623062"]).
port_in_sid read only	string	The port-in request secure ID.
requested_activation_date update	string	The date and time the port is requested to be activated. Set by the partner together with a status value of activation_requested, once the request reaches carrier_approved — refer to Status Transitions.
requested_effective_date createupdate	string	The date and time the partner would like the port to become effective with the losing carrier.
status update	string	The current lifecycle status of the request. Most transitions are applied internally by CarrierX, but the partner can PATCH or PUT this value directly in two cases: to cancelled from precheck_failed or carrier_rejected, and to activation_requested (together with requested_activation_date) from carrier_approved. Any other value is rejected with a 422 error. Refer to the table below for all possible values, and to Status Transitions for the full rules.

Sample Port-In Request Object

{
    "account_number": "8675309",
    "account_pin": "1234",
    "customer_address1": "123 Main St",
    "customer_address2": "",
    "customer_city": "Austin",
    "customer_company": "",
    "customer_full_name": "Jane Doe",
    "customer_state": "TX",
    "customer_zip": "78701",
    "date_created": "2026-07-01T14:32:00.000Z",
    "date_modified": "2026-07-03T09:10:00.000Z",
    "errors": [],
    "existing_service_provider": "321J",
    "gaining_service_provider": "252F",
    "loa": "https://api.carrierx.com/core/v2/storage/files/2ab7081f-db4a-42b3-b7ed-74e1019f30a6",
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "phonenumbers": ["19512623062"],
    "port_in_sid": "c7eae0b4-5eda-4964-8998-d514903b4af0",
    "requested_activation_date": null,
    "requested_effective_date": "2026-08-01T00:00:00.000Z",
    "status": "carrier_submitted"
}

Port-In Request Status Values

Value	Description
created	The default status assigned when the request is created. The request is queued for automated system precheck validation.
system_precheck_passed	Automated system prechecks passed. The request is queued for manual review before submission to the losing carrier.
precheck_failed	Automated or manual review found a problem with the request data. Refer to Get Port-In Request Errors and Port-In Error Object for details, then either PATCH the request data to return it to created for reprocessing, or PATCH/PUT status to cancelled directly.
carrier_submitted	The request has been submitted to the losing carrier through NumHub.
carrier_rejected	The losing carrier rejected the request. Refer to Get Port-In Request Errors and Port-In Error Object for details, then either PATCH the request data to return it to created for resubmission, or PATCH/PUT status to cancelled directly.
carrier_approved	The losing carrier approved the request. A Phone Number DID object is created for the partner with a pending_port_in status. Request data fields can no longer be modified, but the partner can PATCH/PUT status to activation_requested (with requested_activation_date) to request activation — refer to Status Transitions. Cancelling from this status is admin-only.
activation_requested	Activation has been requested for the port, together with requested_activation_date. The partner reaches this status by PATCHing or PUTting status to activation_requested from carrier_approved — refer to Status Transitions.
completed	The port has completed. The associated phone numbers are activated (moved to assigned status) and the pending_port_in flag is cleared. This is a terminal status.
failed	The activation attempt failed. This is a terminal status.
cancelled	The request was cancelled and will not proceed further. This is a terminal status.

Status Change Callback

If the partner has configured a porting_port_in URL in the callbacks attribute of their Partner object, CarrierX sends a POST request to that URL every time a port-in request's status changes, including system-driven transitions.

The callback body is a compact version of the Port-In Request object: phonenumbers is replaced with a phonenumbers_count, and errors is omitted.

Sample Status Change Callback Payload

{
    "account_number": "8675309",
    "account_pin": "1234",
    "customer_address1": "123 Main St",
    "customer_address2": "",
    "customer_city": "Austin",
    "customer_company": "",
    "customer_full_name": "Jane Doe",
    "customer_state": "TX",
    "customer_zip": "78701",
    "date_created": "2026-07-01T14:32:00.000Z",
    "date_modified": "2026-07-03T09:10:00.000Z",
    "existing_service_provider": "321J",
    "gaining_service_provider": "252F",
    "loa": null,
    "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
    "phonenumbers_count": 1,
    "port_in_sid": "c7eae0b4-5eda-4964-8998-d514903b4af0",
    "requested_activation_date": null,
    "requested_effective_date": "2026-08-01T00:00:00.000Z",
    "status": "carrier_submitted"
}

Port-In Error Object

Each error entry identifies whether a validation or carrier issue was found, which field it relates to (if any), and a human-readable message. Refer to Get Port-In Request Errors to retrieve this list directly.

Attribute	Data Type	Description
type read only	string	The category of the error. Values accepted in this field are validation for errors found during system precheck, and carrier for errors returned by the losing carrier.
field read only	string	The name of the request field the error relates to, if applicable.
message read only	string	A human-readable description of the error.

Sample Port-In Error Object

{
    "type": "validation",
    "field": "account_number",
    "message": "account_number does not match the losing carrier's records"
}