How Porting In Works

Being able to keep their previous number when changing their subscription is an important consideration for many users. Fortunately, this is a well supported feature within the Gigs API.

Generally, two entities are involved in the process. First, create a Porting entity and reference it when creating the actual Subscription. The porting resource allows you to collect all necessary information from the donor provider to authorize the porting and helps you track its lifecycle.

This process involves a few steps on your side:

Check if the number the user wants to bring is eligible: There is a few reasons why the number might not be eligible, such as if it's a different type of number, if the provider doesn't support it, if the number is already with the recipient provider, and more.
Provide basic information: Depending on the constellation of providers and the involved jurisdiction the requirements can vary greatly. However, some information is always required: the number that you are porting in and the recipient provider. These are also the only pieces of information you need before creating the subscription.
Create the subscription: With the porting created as above, you can create a subscription. Not providing the reference to a porting will lead to a new number being allocated.
Provide all required information: Next, you need to submit all the required information. The Gigs API will tell you exactly what information will be required to start the porting process.
Deal with any port-in issues: In case the porting process runs into issues (e.g. due to the user providing incorrect information), the API will let you receive notifications and address any issues as necessary.

Alternatively, depending on your implementation preferences, you can collect all required information before creating a subscription. Which one is preferable for you, will depend on what kind of flow you have in mind and which jurisdiction you are in.

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

Porting In Process

1. Check the eligibility

To port a number, we must first check if the recipient provider can accept it. This can be accomplished by creating a Porting with the desired phone number and provider ID. If the number is accepted, a porting will be created with a draft status, which can be used to collect all the necessary information.

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 will be deleted after 30 days if they are not used to create a subscription.

2. Collect all the required information

In order for the donor provider to approve the porting, we need to provide them with information about both the current account holder and the account itself. You will likely have to collect this information from the user. The specific parameters required for this process vary by country and by the providers involved. To view all required parameters, inspect the required property of the porting.

For example, US-based service providers typically require the collection of the current account holder's name and account number and PIN. In some cases, the billing address may also be required. These requirements are illustrated in the following example:

A draft porting with required parameters

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

Next, ask the user for this information and update the porting to include it. Note that the porting cannot be processed 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"
  }'

3. Create a new subscription

Creating a subscription with the porting will initiate the porting process. If all necessary information has been collected, the porting status will transition to pending until the system processes the request and send it to the network. When the submission has been completed, it will transition to requested until we receive a positive or negative response from the provider.

Alternatively, if we did not collect all the information upfront in the previous step, the porting status will transition to informationRequired until we update it with all the required parameters.

The subscription will remain pending until the porting is completed or the subscription is ended.

4. Deal with any issues

Portings may be declined by the donor provider for various reasons, including discrepancies in the information provided, locks or debts on existing accounts, and other situations. In such cases, the porting status will change to declined and include a declinedCode and declinedMessage explaining the reasons for the rejection. We can then address the issues and update the porting with any new information, which would change its status back to pending and attempt the porting again with the donor provider.

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 a porting without providing any new information, simply update the porting with an empty request.

5. Wait for completion

After all the necessary information has been collected and any issues with the existing provider have been addressed, the porting process should be completed shortly or on the scheduled date. This can take anywhere from a few minutes to a few days, but eventually the porting status will transition to completed, and the related subscription will be activated as usual.

A completed porting

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

Porting Lifecycle

Porting a phone number is a process that involves multiple parties - the user, Gigs, the donor provider, and the recipient provider - and can take from minutes to days. To keep track of all the stages that a porting goes through, we use a status field.

The following section explains:

all potential status values and their meaning,
state diagrams visualizing transitions throughout that lifecycle.

Porting Statuses

Here is a glossary of all the potential porting statuses and the required action required to move forward.

Status	Description	Action
`draft`	The porting has not been used in a subscription yet.	You must create a subscription or request a port-in on an active subscription using the porting to start the process.
`informationRequired`	The porting does not have all the required information to be processed.	You must collect the information from the user and attach it to the porting. Updating the porting with the required information will continue with the porting process.
`pending`	The porting is awaiting to be processed by our system. This usually only takes a few seconds.	No action required.
`requested`	The porting is awaiting processing by either the donor or the recipient provider. If the porting is scheduled for a specific date, it will remain in a requested state until the date the porting is scheduled for has passed. The time it takes to request a porting process depends on the countries and providers involved, and can range from a few minutes to a few days.	No action required.
`declined`	The porting was declined by either the donor or the recipient provider. The reason for the decline can be found in the `declinedCode` and `declinedMessage` attached to the porting.	You must check the reason for the decline and follow up with the necessary actions. Updating the porting with new or corrected information will retry the porting attempt.
`completed`	The porting process was completed successfully. The underlying subscription will now activate with the ported number.	No action required.
`canceled`	The porting was canceled. Portings can be canceled via the API when the porting is not being processed, such as after it has been declined. The subscription activates with a new number if the subscription was created with the porting. Existing subscriptions will continue to use the original number.	No action required.
`expired`	The porting has expired. If this porting was used when creating a new subscription, that subscription has been ended. If it was used for an active subscription, the subscription remains active with the original number.	To continue the porting process, you will need to start from the beginning with a new porting and a new subscription.

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. This is permitted unless the port is in the requested state and the scheduled date has been reached, if set. A cancellation of the porting leads to the activation of the attached subscription with a new number.

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-->[*]

Complete Porting Lifecycle

The following state diagram displays the complete porting lifecycle. We do not recommend to hardcode these state transitions.

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

Porting decline codes

Here is a glossary of all the current decline codes that we support. This list is not exhaustive and may grow as new situations are handled. Therefore, it is important to ensure that your application is forward-compatible with any new codes that may be added.

Code	Description
`portingDeclined`	The porting was declined for an unknown reason. Please contact customer support.
`portingPhoneNumberNotFound`	The donor carrier has no active record of the provided phone number. Ensure the number is correct and associated with an active account.
`portingSameNewAndOldNetworkProvider`	The porting request involves the same network provider for both donor and recipient carriers, which is not permitted. Select a different recipient carrier.
`portingUserInformationMismatch`	The personal information (name or address) in the porting request does not match the donor carrier’s records. Confirm the name, address, and postal code match what is on record with the donor provider, then update the porting request.
`portingPhoneNumberNotActive`	The phone number is not active with the donor carrier, indicating it may be suspended or deactivated. Ensure the number is active and correct with the donor carrier before resubmitting the request.
`portingPhoneNumberAdministrative`	The phone number is designated for administrative or internal carrier purposes and is not eligible for porting.
`portingPendingOtherProvider`	An active porting request for the phone number exists with another carrier. Contact the donor carrier to cancel existing port requests, then resubmit the porting request.
`portingDuplicated`	A pending porting request for the phone number already exists in the system. Cancel the existing port request with the donor carrier before submitting a new request.
`portingPhoneNumberPortProtected`	The phone number has port protection enabled, preventing unauthorized transfers. Contact the donor carrier to disable port protection, then resubmit the porting request.
`portingAccountPinRequiredOrInvalid`	Account Pin is required or invalid.
`portingAccountNumberRequiredOrInvalid`	Account Number is required or invalid.
`portingAddressRequiredOrInvalid`	Address is required or invalid.
`portingPostalCodeRequiredOrInvalid`	Postal Code is required or invalid.
`portingFirstNameRequiredOrInvalid`	First Name is required or invalid.
`portingLastNameRequiredOrInvalid`	Last Name is required or invalid.