How Porting In Works

This guide walks you through the process of porting a phone number to Gigs using the Gigs API. Follow these steps to ensure a smooth port-in experience for your users.

Step-by-Step Porting Guide

Start a Porting Request
Begin by creating a porting with the user's phone number, user ID, and recipient provider. Gigs will check if the number is eligible to be ported.
Create a Subscription
Create a subscription and reference the porting. If you skip this, a new number will be assigned. The porting status will update to pending or informationRequired.
Submit Required Information
Update the porting to provide all information requested by the API. See the required attribute in your porting object as requirements vary by country and provider.
Resolve Issues
If the porting is declined (e.g. due to incorrect information), update the porting with corrected details to retry.

You can also collect all required information before creating the subscription, depending on your workflow and jurisdiction.

Portings have country-specific requirements (e.g. different porting behaviors in the United Kingdom). See the bottom of this guide for details.

Porting In Process

1. Create a Porting

Create a porting with the desired phone number and provider ID. On creation, Gigs will check if the provider can accept the number. If eligible, you'll get a porting with draft status.

Create a porting

curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/portings" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "phoneNumber": "+19591234567",
    "provider": "p4",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  }'

Draft portings are deleted after 30 days if not used to create a subscription.

2. Collect Required Information

Gather the necessary details from the user. The API will list required fields in the required property.

For example, US-based providers typically require the current account holder's name, account number and account pin. In some cases, the billing address may also be required.

A porting with required parameters

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "required": [
    "accountNumber",
    "accountPin",
    "address",
    "firstName",
    "lastName"
  ],
  ...
}

Ask the user for this information and update the porting. The porting can't proceed until all required information is provided.

Update a porting

curl --request PATCH \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/portings/${PORTING_ID}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "accountNumber": "123456789",
    "accountPin": "1234",
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5",
      "postalCode": "10024",
      "state": "NY"
    },
    "firstName": "Jerry",
    "lastName": "Seinfeld"
  }'

Create a subscription with the porting to start the process. The porting status will update to pending if all information is present. If information is missing, the status will be informationRequired. Continue by updating the porting with the missing details from the required property.

The subscription stays pending until porting completes or the porting is canceled. You can cancel the porting or end the subscription if needed.

4. Handle Issues

If declined, the porting will show a code and message. Update the porting with corrected information to retry. Keep an eye on the required property in case additional information is needed.

A declined porting with code and message

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "status": "declined",
  "declinedCode": "portingPhoneNumberPortProtected",
  "declinedMessage": "The phone number has port protection on the provider.",
  ...
}

To retry without changes, update the porting with an empty request. Only do this if the decline wasn't due to missing or incorrect information.

5. Wait for Completion

Once all issues are resolved, the porting will complete and the subscription will activate with the ported number.

A completed porting

{
  "object": "porting",
  "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
  "status": "completed",
  ...
}

Porting Lifecycle

Porting involves several parties and can take minutes to days. The status field tracks progress.

Porting Statuses

Below is a summary of each porting status and what to do next. The cancelable column indicates whether a porting can be canceled in that status.

Status	Description	Action	Cancelable
`draft`	Porting not used in a subscription yet.	Create a subscription or request port-in to start.	No
`initiated`	Awaiting end-user consent. Only appears in markets requiring user consent.	Wait for the user to approve the consent request.	Yes
`informationRequired`	Missing required information.	Collect and update information to continue.	Yes
`pending`	All required information collected. Awaiting Gigs to request the port from the donor provider.	No action needed.	Yes
`requested`	Awaiting processing by providers or scheduled date.	No action needed.	Only if `scheduledOn` is in the future
`declined`	Declined by provider, with reason code/message.	Review reason, update information, and retry.	Yes
`completed`	Porting finished successfully.	No action needed.	No
`canceled`	Porting canceled. Subscription activates with new number.	No action needed.	No
`expired`	Porting expired at the donor provider.	Start over with a new porting and subscription.	No
`failed`	Consent request expired or was canceled before the port could be requested. Only appears in markets requiring user consent.	Start over with a new porting and subscription.	No

Resolved States

Once a porting reaches one of completed, canceled, expired, or failed, it never transitions again. The four resolved states differ by who ended the porting and why:

completed — the donor provider confirmed the port and the number is now active on Gigs. The associated subscription activates with the ported number.
canceled — the porting was canceled either explicitly via the API, or implicitly when the parent subscription ended while the porting was still unresolved. The subscription activates with a new number if the port had not yet completed.
expired — the donor provider's window to act on the port closed before the port could complete. Only reachable from requested or declined, since expiry is a donor-side outcome.
failed — only appears in markets requiring user consent. The user did not approve the consent request in time, so the port was never requested from the donor provider. Only reachable from initiated. The subscription was never activated against this porting.

`lastDeclinedAt` and `declinedAttempts`

lastDeclinedAt is a historical timestamp, not a state indicator. It records the most recent time the porting transitioned into declined. Once set, it persists for the lifetime of the porting — it is never cleared, even when the porting moves out of declined (back to pending via an update, or onward to completed, canceled, expired, or failed). A porting can therefore have a non-null lastDeclinedAt while its current status is completed.

declinedAttempts is a cumulative counter incremented on each transition into declined. Together, the two fields let you answer "has this porting ever been declined, and when most recently?" without having to scan event history.

To check whether a porting is currently in the declined state, read status, not lastDeclinedAt.

State Diagrams

Simplified Porting Lifecycle

The following state diagram shows the typical porting process with back and forth between user and donor provider or recipient provider. Ultimately, the porting is either completed successfully or canceled by the user.

After creation, the porting is in draft mode. It stays in draft mode until it is referenced in a subscription. From there, the porting either moves to informationRequired if required information is missing or to pending if all information is present. Once it is in pending, our system starts processing the porting and requesting the porting. After the port has been successfully processed, it moves to completed or if the port has been declined by the provider it moves to declined. When declined, the porting moves back to pending once the porting is updated via the API and we start processing the porting again. This loop continues until the porting is successfully completed.

If at any point in this lifecycle the user decides not to port their number, the porting can be canceled. A cancellation of the porting leads to the activation of the attached subscription with a new number. See the cancelable column in the status table above for the precise rules.

stateDiagram-v2 direction LR [*]-->draft draft-->pending draft-->informationRequired pending-->requested informationRequired-->pending declined-->pending requested-->completed requested-->declined declined-->canceled informationRequired-->canceled completed-->[*] canceled-->[*]

Standard Porting Lifecycle

The following state diagram displays the full porting lifecycle in markets that do not require explicit user consent. We do not recommend to hardcode these state transitions.

Cancellation is permitted from pending, informationRequired, and declined. A requested porting is cancelable only when it is scheduled and the scheduled date is in the future.

stateDiagram-v2 direction LR [*]-->draft draft-->pending draft-->informationRequired pending-->requested pending-->declined pending-->canceled informationRequired-->pending informationRequired-->canceled declined-->pending declined-->informationRequired declined-->expired declined-->canceled requested-->completed requested-->declined requested-->expired requested-->canceled completed-->[*] canceled-->[*] expired-->[*]

Porting Lifecycle in Markets Requiring User Consent

In markets that require explicit user consent before contacting the donor provider, the porting begins in initiated while the consent request is outstanding. Once the user approves, the porting moves to pending (or informationRequired if data is still missing). If the user does not approve in time, the porting transitions to failed. An initiated porting is cancelable.

stateDiagram-v2 direction LR [*]-->draft draft-->initiated initiated-->pending initiated-->informationRequired initiated-->canceled initiated-->failed pending-->requested pending-->declined pending-->canceled informationRequired-->pending informationRequired-->canceled declined-->pending declined-->informationRequired declined-->expired declined-->canceled requested-->completed requested-->declined requested-->expired requested-->canceled completed-->[*] canceled-->[*] expired-->[*] failed-->[*]

Porting Decline Codes

Here are the possible decline codes and their meanings. Your app should handle new codes as they are added.

Code	Description
`portingDeclined`	Unknown reason. Contact support.
`portingPhoneNumberNotEligible`	Number not eligible for porting.
`portingPhoneNumberNotFound`	Number not found with donor carrier.
`portingSameNewAndOldNetworkProvider`	Same provider for donor and recipient.
`portingUserInformationMismatch`	Information mismatch with donor carrier records.
`portingPhoneNumberNotActive`	Number not active with donor carrier.
`portingPhoneNumberAdministrative`	Number reserved for carrier use.
`portingPendingOtherProvider`	Active porting request exists with another carrier.
`portingDuplicated`	Pending porting request already exists.
`portingPhoneNumberPortProtected`	Port protection enabled.
`portingAccountPinRequiredOrInvalid`	Account PIN required or invalid.
`portingAccountNumberRequiredOrInvalid`	Account number required or invalid.
`portingAddressRequiredOrInvalid`	Address required or invalid.
`portingPostalCodeRequiredOrInvalid`	Postal code required or invalid.
`portingFirstNameRequiredOrInvalid`	First name required or invalid.
`portingLastNameRequiredOrInvalid`	Last name required or invalid.
`portingBillingPinRequiredOrInvalid`	Billing pin required or invalid.