OnePort Portability Checker

Bandwidth provides the /porting/portability/phoneNumbers API to allow customers to check portability of a phone number. Numbers have to be entered in E164 format.

The API will help do the following:

• Determine if the numbers they want to port are portable to Bandwidth
• Determine the porting documentation requirements for the numbers
• Determine the compliance requirements for the numbers
• Determine the earliest estimated port date
• Determine the losing carrier for US/Canada numbers

This information is necessary to identify which telephone numbers can be ported together when planning to use the /portins API to create stand-alone port-ins. If the customer prefers to use /bulkPortins, the bulk port-in software will take care of creating the stand-alone child port-ins for any telephone numbers that can be ported together.

The /porting/portability/phoneNumbers API can return the following elements in its 200 response payload. Details for each field are provided below:

Portable Phone Number Groups

Portable Group will be classified under portablePhoneNumbers with the following fields:

Field	Description
countryCodeA3	This will show the country code in ISO format. Ie. IRE for Ireland
phoneNumberType	Depending on the phone number, it will show its configured type based on our network coverage. This could either be Geographic, National or Toll Free.
portType	This field shows how the port will be handled internally by our Bandwidth Team based on our local processes. The response will show either Manual or Automated
earliestEstimate	The earliest estimate field indicates the soonest we can target to port the number. The field is calculated based on the local framework in each country and takes a variety of factors into consideration.
phoneNumbers	This will present the phone number in question. If you see multiple numbers in this field, that means they can be grouped together in one request.
losingCarrier (name and spid)	This field is specific to US and Canada numbers. As we are able to fetch this information locally, this will be presented in the response as well.
rateCenter (name, lata, state, tier, vendor)	This field is specific to US and Canada (NANP) numbers.
respOrg (exception ID)	This field is specific to US/Canada Toll Free numbers.
portingDocuments	This field will specify which documents are required to be submitted with the port request. Every country has different documentation requirements set by the local regulators. The field will not be displayed if there are no documents mandatory to upload with the port request for processing.
complianceRequirements	Regulators in several countries require end-user information to allow activation of phone number services. These documents are required for you to verify your Requirements Package. A Requirements Package contains all information required to validate the identity of the end user. Requirements Package have to be submitted and verified prior to submitting the port requests. If a specific port request requires a verified Requirements Package, you will be able to select it during the port creation process. For more information see Restrictions and Requirements page in our support center.

Non-Portable Phone Number Groups

Numbers that are not portable will be classified under nonPortablePhoneNumbers with the following fields:

Field	Description
phoneNumber	This will contain the phone number that is not portable.
countryCodeA3	This will show the country code in ISO format, i.e. IRE for Ireland.
reasons	This field will list the reason(s) why the phone number in this group is not portable.

Sample Payload

Below is an example of the payload in JSON format for Global Portability Checker API:

{
  "phoneNumbers": [
    "+44203789761",
    "+44203657891",
    "+44161789761",
    "+35319876890",
    "+32278909878",
    "+32800789972",
    "+32800789907",
    "+19198729048",
    "+18887892789",
    "+49800890997"
  ]
}

Sample Responses

200 OK Response

Below is the 200 response after the numbers are processed:

{
  "links": [
    {
      "href": "https://api.bandwidth.com/api/v2/accounts/6777777/porting/portability/phoneNumbers",
      "rel": "self",
      "method": "POST"
    }
  ],
  "data": {
    "portablePhoneNumbers": [
      {
        "countryCodeA3": "IRL",
        "phoneNumberType": "GEOGRAPHIC",
        "portType": "MANUAL",
        "earliestEstimate": "2025-06-18T00:00:00Z",
        "phoneNumbers": [
          "+35319876890"
        ],
        "complianceRequirements": [],
        "portingDocuments": [
          {
            "name": "LOA"
          },
          {
            "name": "COB"
          }
        ]
      },
      {
        "countryCodeA3": "USA",
        "phoneNumberType": "GEOGRAPHIC",
        "portType": "AUTOMATED",
        "earliestEstimate": "2025-06-16T11:30:00Z",
        "phoneNumbers": [
          "+19198729048"
        ],
        "losingCarrier": {
          "name": "BellSouth-AT&T Wireline/1",
          "spid": "9417"
        },
        "rateCenter": {
          "name": "RALEIGH",
          "lata": "426",
          "state": "NC",
          "tier": 2,
          "vendor": "Bandwidth CLEC"
        }
      },
      {
        "countryCodeA3": "USA",
        "phoneNumberType": "TOLL_FREE",
        "portType": "MANUAL_TOLLFREE",
        "earliestEstimate": "2025-06-16T11:30:00Z",
        "phoneNumbers": [
          "+18887892789"
        ],
        "portingDocuments": [
          {
            "name": "LOA"
          }
        ],
        "respOrg": {
          "exception": false,
          "id": "ZPL01"
        }
      }
    ],
    "nonPortablePhoneNumbers": [
      {
        "phoneNumber": "+44203789761",
        "reasons": [
          "This number is not valid"
        ]
      },
      {
        "phoneNumber": "+44161789761",
        "reasons": [
          "This number is not valid"
        ]
      },
      {
        "phoneNumber": "+32800789907",
        "countryCodeA3": "BEL",
        "reasons": [
          "This number is not valid"
        ]
      },
      {
        "phoneNumber": "+44203657891",
        "reasons": [
          "This number is not valid"
        ]
      },
      {
        "phoneNumber": "+49800890997",
        "countryCodeA3": "DEU",
        "reasons": [
          "This number is not valid"
        ]
      },
      {
        "phoneNumber": "+32278909878",
        "countryCodeA3": "BEL",
        "reasons": [
          "This number is not valid"
        ]
      },
      {
        "phoneNumber": "+32800789972",
        "countryCodeA3": "BEL",
        "reasons": [
          "This number is not valid"
        ]
      }
    ]
  },
  "errors": []
}

400 Bad Request

This error occurs when too many phone numbers have been provided in the portability request.

{
  "data": null,
  "errors": [
    {
      "code": 1010,
      "description": "Too many phone numbers have been provided in the portability request",
      "type": "too-many-phone-numbers-provided"
    }
  ],
  "links": []
}

500 Internal Server Error

This error indicates that an unexpected error occurred on the server.

{
  "data": null,
  "errors": [
    {
      "code": 1050,
      "description": "An unexpected error occurred on the server",
      "type": "internal-server-error"
    }
  ],
  "links": []
}