How Porting 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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.

Porting 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.

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"
  }'

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:

{
  "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.

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 5A",
      "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.

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.

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

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. 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.

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

Porting Lifecycle

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

Draft

Indicates that the porting has not been used to create a subscription yet.

Information Required

Indicates that the porting does not have all the required information to be processed.

Pending

Indicates that the porting is awaiting to be processed by our system. Usually, this only takes a few seconds.

Requested

Indicates that the porting is awaiting processing by either the donor or recipient providers. 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.

Declined

Indicates that the porting was declined by either the donor or the recipient provider. The reason for the decline can be found in the declined code and message attached to the porting.

Completed

Indicates that the porting process was completed successfully. The underlying subscription will now activate with the ported number.

Canceled

Indicates that the porting was canceled. Portings can be canceled by ending the underlying subscription when the porting is not being processed, such as after it has been declined.

Expired

Indicates that the porting has expired, and as a result, the underlying subscription has been ended. To continue the porting process, you will need to start from the beginning with a new porting and a new subscription.

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.

Test numbers

To verify that the integration with the porting API works correctly there are a set of test phone numbers to simulate different scenarios: