Checking Portability for Toll Free Numbers

In the past, Bandwidth did not provide a means to determine toll free number status and provider information. We are happy to say that that is no longer the case.

Bandwidth provides the /accounts/{accountId}/tollFreePortingValidations endpoint to allow you to retrieve official toll free number status and provider information for up to 5000 toll free numbers per invocation. The input is simply a list of toll free numbers, and the output describes which numbers are portable, manually portable, and non-portable.

This endpoint is available to help you submit toll free port-in requests to Bandwidth that are more likely to succeed. It will help you avoid submitting non-portable numbers, or numbers that must be ported in separate port requests because they are hosted by different providers.

Because it can take several minutes to retrieve toll free number information from SOMOS (the North American toll free number administrator), the /tollFreePortingValidations API is asynchronous. This means that your request will create an order that you can either poll for results, or you may subscribe to notifications about state changes. Please refer to Order Model for details.

Note: You may skip this request and proceed directly to submission of a port-in request, using POST /accounts/{accountId}/portins. This will cause Bandwidth to perform the same validation. If the request contains non-portable toll free numbers, or numbers that cannot be ported together, the port-in will transition to an INVALID_TFNS state.

Interpreting Results

The /tollFreePortingValidations API includes the following information in the response payloads.

Element	Description
AccountId	The Bandwidth account for which the toll free porting validations order has been submitted.
Breakdown	A structure that separates the toll free numbers into portable, manually portable, and non-portable. This element may not be available yet, if the ProcessingStatus is Submitted or Processing, or if the order was cancelled. The breakdown categories are: Portable - Toll free numbers that have status WORKING, RESERVED, ASSIGNED or SUSPENDED are portable. Manually Portable - Toll free numbers that have status DISCONNECTED or TRANSITIONAL may be ported, but you will have to contact Bandwidth to create a manual toll free port. Non-Portable - Toll free numbers that have status SPARE or UNAVAILABLE may not be ported.
CreatedByUser	The user name of the user that created the free porting validations order.
CustomerOrderId	The optional customer-provided order-id. This value allows you to provide your own order-id for correlation purposes, should you choose.
ErrorList	An optional list of errors.
OrderCreateDate	The date and time when the toll free porting validations order was created.
OrderId	The unique order-id assigned by Bandwidth to refer to this order in subsequent GET or PATCH operations.
ProcessingStatus	The status of the order. It may be one of the following: SUBMITTED - The order has been submitted to SOMOS, but we have not yet received an acknowledgement. PROCESSING - The order is being processed by SOMOS. The breakdown is not yet available. FAILED - The order has failed, meaning that either we could not retrieve the toll free number status from SOMOS, or some of the toll free numbers are not portable. COMPLETE - The order has completed. All of the toll free numbers are portable, although possibly not in one port-in request. CANCELLED - The order has been successfully cancelled. This will only occur if you use the PATCH operation to cancel the order.
TollFreeNumberList	The list of toll free numbers that were submitted to the toll free porting validations order.

Port-in Request Rules

Toll free numbers may be ported in one port-in request, provided that they meet the following criteria:

• The toll free numbers are portable.
• The toll free numbers all have the same controlling RespOrg (i.e. same provider).
• The toll free numbers may be authorized to port by the same person.

The first two bullets may be determined using the /tollFreePortingValidations response when the ProcessingStatus is either COMPLETE or FAILED.

Note: The actual RespOrg ID is hidden because we are not allowed to show it unless it is a RespOrg ID that you own and is configured on your account. But you can see which TNs belong to the same RespOrg IDs, enabling you to properly break down the toll free numbers into separate port-in requests if needed.

Sample Responses

In this section, we’ll show sample order response payloads for each ProcessingStatus value.

Here is a sample request payload:

<TollFreePortingValidation>
  <!-- The CustomerOrderId is an optional string that may be associated with the order.  -->
  <!-- It will be included in all responses and notifications related to the order, and may be used to correlate with an order in a customer system. -->
  <CustomerOrderId>MyOptionalOrderId</CustomerOrderId>
  <!-- The TollFreeNumberList is a list of toll free telephone numbers for which you want information about the status and RespOrg from SOMOS. -->
  <!-- The list may consist of up to 5,000 toll free telephone numbers in one order.  The more numbers in the order, the longer it will take the order to complete. -->
  <TollFreeNumberList>
    <TollFreeNumber>8442948899</TollFreeNumber>
    <TollFreeNumber>8774024485</TollFreeNumber>
  </TollFreeNumberList>
</TollFreePortingValidation>

ProcessingStatus SUBMITTED or PROCESSING

<TollFreePortingValidationResponse>
  <TollFreePortingValidation>
    <CustomerOrderId>MyOptionalOrderId</CustomerOrderId>
    <ProcessingStatus>PROCESSING</ProcessingStatus>
    <AccountId>9900572</AccountId>
    <CreatedByUser>testuser</CreatedByUser>
    <OrderCreateDate>2020-08-20T14:51:58.695Z</OrderCreateDate>
    <OrderId>e2b029cf-1cfa-4285-a875-80e8fd951208</OrderId>
    <TollFreeNumberList>
      <TollFreeNumber>8442948899</TollFreeNumber>
      <TollFreeNumber>8774024485</TollFreeNumber>
    </TollFreeNumberList>
  </TollFreePortingValidation>
</TollFreePortingValidationResponse>

The Breakdown element is not present, because SOMOS is still processing the request.

ProcessingStatus COMPLETE

<TollFreePortingValidationResponse>
  <TollFreePortingValidation>
    <CustomerOrderId>MyOptionalOrderId</CustomerOrderId>
    <ProcessingStatus>COMPLETE</ProcessingStatus>
    <AccountId>9900572</AccountId>
    <CreatedByUser>testuser</CreatedByUser>
    <OrderCreateDate>2020-08-20T14:51:58.695Z</OrderCreateDate>
    <OrderId>e2b029cf-1cfa-4285-a875-80e8fd951208</OrderId>
    <TollFreeNumberList>
      <TollFreeNumber>8442948899</TollFreeNumber>
      <TollFreeNumber>8774024485</TollFreeNumber>
    </TollFreeNumberList>
    <Breakdown>
      <PortableTollFreeNumberList>
        <RespOrgList>
          <RespOrg>
            <Id>RespOrg 1</Id>
            <RespOrgException>true</RespOrgException>
            <TollFreeNumberList>
              <TollFreeNumber>8442948899</TollFreeNumber>
              <TollFreeNumber>8774024485</TollFreeNumber>
            </TollFreeNumberList>
          </RespOrg>
        </RespOrgList>
      </PortableTollFreeNumberList>
    </Breakdown>
  </TollFreePortingValidation>
</TollFreePortingValidationResponse>

Here, the Breakdown is present, but only includes PortableTollFreeNumberList because there were no Manually Portable or Non-Portable numbers in the request. In this example, both toll free numbers were associated with the same RespOrg.

ProcessingStatus FAILED

<TollFreePortingValidationResponse>
  <TollFreePortingValidation>
    <CustomerOrderId>MyOptionalOrderId</CustomerOrderId>
    <ProcessingStatus>FAILED</ProcessingStatus>
    <AccountId>9900572</AccountId>
    <CreatedByUser>testuser</CreatedByUser>
    <OrderCreateDate>2020-08-20T14:51:58.695Z</OrderCreateDate>
    <OrderId>e2b029cf-1cfa-4285-a875-80e8fd951208</OrderId>
    <TollFreeNumberList>
      <TollFreeNumber>8442948899</TollFreeNumber>
      <TollFreeNumber>8774024485</TollFreeNumber>
      <TollFreeNumber>8662894621</TollFreeNumber>
      <TollFreeNumber>8773732047</TollFreeNumber>
      <TollFreeNumber>8449978331</TollFreeNumber>
      <TollFreeNumber>8003985992</TollFreeNumber>
    </TollFreeNumberList>
    <ErrorList>
      <Error>
        <Code>7859</Code>
        <Description>Description for error 7859</Description>
      </Error>
      <Error>
        <Code>9877</Code>
        <Description>Description for error 9877</Description>
      </Error>
    </ErrorList>
    <Breakdown>
      <PortableTollFreeNumberList>
        <RespOrgList>
          <RespOrg>
            <Id>RespOrg1</Id>
            <RespOrgException>false</RespOrgException>
            <TollFreeNumberList>
              <TollFreeNumber>8662894621</TollFreeNumber>
            </TollFreeNumberList>
          </RespOrg>
        </RespOrgList>
      </PortableTollFreeNumberList>
      <ManuallyPortableTollFreeNumberList>
        <DisconnectedTollFreeNumberList>
          <TollFreeNumber>8449978331</TollFreeNumber>
        </DisconnectedTollFreeNumberList>
        <TransitionalTollFreeNumberList>
          <TollFreeNumber>8003985992</TollFreeNumber>
        </TransitionalTollFreeNumberList>
      </ManuallyPortableTollFreeNumberList>
      <NonPortableTollFreeNumberList>
        <SpareTollFreeNumberList>
          <TollFreeNumber>8442948899</TollFreeNumber>
        </SpareTollFreeNumberList>
        <UnavailableTollFreeNumberList>
          <TollFreeNumber>8774024485</TollFreeNumber>
        </UnavailableTollFreeNumberList>
        <DeniedTollFreeNumberList>
          <DeniedTollFreeNumber>
            <TollFreeNumber>8773732047</TollFreeNumber>
            <SomosErrorCode>07</SomosErrorCode>
            <SomosErrorDescription>NXX CLOSED</SomosErrorDescription>
          </DeniedTollFreeNumber>
        </DeniedTollFreeNumberList>
      </NonPortableTollFreeNumberList>
    </Breakdown>
  </TollFreePortingValidation>
</TollFreePortingValidationResponse>

For this order the ProcessingStatus is FAILED because the request included manually portable or non-portable toll free numbers. The Breakdown is included with one portable number, two manually portable numbers, and three non-portable numbers. For manually portable and non-portable, the reasons are included. If a toll free number is “denied”, it generally means something is wrong with the number. The denial reason from SOMOS is included.

ProcessingStatus CANCELLED

<TollFreePortingValidationResponse>
  <TollFreePortingValidation>
    <CustomerOrderId>MyOptionalOrderId</CustomerOrderId>
    <ProcessingStatus>CANCELLED</ProcessingStatus>
    <AccountId>9900572</AccountId>
    <CreatedByUser>testuser</CreatedByUser>
    <OrderCreateDate>2020-08-20T14:51:58.695Z</OrderCreateDate>
    <OrderId>e2b029cf-1cfa-4285-a875-80e8fd951208</OrderId>
    <TollFreeNumberList>
      <TollFreeNumber>8442948899</TollFreeNumber>
      <TollFreeNumber>8774024485</TollFreeNumber>
    </TollFreeNumberList>
  </TollFreePortingValidation>
</TollFreePortingValidationResponse>

This response does not include a Breakdown because the order was cancelled prior to receiving a response from SOMOS. Really the only reason to cancel a tollFreePortingValidations order is if you realize you’ve submitted an incorrect list of numbers. Even then, there is no harm in letting the request run to completion.