How to protect yourself from unauthorized port-outs

Ever wonder how you can ensure that port outs for on-net numbers within your account are valid? While receiving carriers of ported numbers work hard to ensure that all ports are legitimate, Bandwidth offers you one additional way to reduce invalid requests through the use of our Port Out Validation API.

The Port Out Validation API will send a callback to a URL you specify containing details about the port. It is then up to you to validate this information and let us know via the callback response if the port should continue or not. The goal here is to balance FCC-mandated portability of numbers while ensuring the legitimacy of the request to port a number.

How port-out validation works

With the Port Out Validation API, Bandwidth will send you a webhook whenever a port out is attempted on an on-net number in your account. The destination of this webhook is defined ahead of time and has to be manually set up by our porting team. Your representative at Bandwidth can initiate the process of defining this webhook destination.

In addition to the phone number to be ported, the webhook will contain FCC acceptable data which may include some or all of the following, if applicable: account ID, zip code, and PIN, which you can use to auto-validate the port out request.  Based on your response to the port out validation API webhook, Bandwidth decides whether or not to proceed with the port. This is an instantaneous, automated process based on the response Bandwidth receives from you for the port out validation webhook.

Please note that at this time port out validation is a functionality for on-net numbers only.

Structure of the webhook

The webhook will appear as follows, where Pin, AccountNumber, ZipCode, and SubscriberName are optional fields filled based on the data we receive in the port out request:

<?xml version="1.0"?>
<PortOutValidationRequest>
    <PON>some_pon</PON>
    <Pin>1111</Pin>
    <AccountNumber>777</AccountNumber>
    <ZipCode>62025</ZipCode>
    <SubscriberName>Subscriber Name</SubscriberName>
    <TelephoneNumbers>
        <TelephoneNumber>2223331000</TelephoneNumber>
        <TelephoneNumber>2223331001</TelephoneNumber>
    </TelephoneNumbers>
</PortOutValidationRequest>

Your response

If Bandwidth receives a 4XX or 5XX HTTP response code, the port out will proceed unhindered. 

With a 200 OK response, you can provide data that tells us either that the port out has passed validation or it has not.

If the port out passes validation, all you have to send us back is the following:

<PortOutValidationResponse>
    <Portable>true</Portable>
    <PON>some_pon</PON>
</PortOutValidationResponse>

If validation fails, you must send us back a response that includes XML indicating that the request is not portable, the PON of the request, and two further sections of XML: an error section and an acceptable values section. The error XML indicates all errors that led to the failure of the port-out request.

The acceptable values XML indicates values for fields that would make the request valid, and these acceptable values are seen only by Bandwidth, not by the original sender of the port out request. We will explore both of these sections in detail, but for now, here is an example of a properly formatted “validation failed” response:

<PortOutValidationResponse>
    <Portable>false</Portable>
    <PON>some_pon</PON>
    <Errors>
        <Error>
            <Code>75xx</Code>
            <Description>Customer api error description</Description>
        </Error>
        <Error>
            <Code>75xx</Code>
            <Description>Customer api error description</Description>
        </Error>
    </Errors>
    <AcceptableValues>
        <Pin>2222</Pin>
        <AccountNumber>555</AccountNumber>
        <ZipCode>02154</ZipCode>
        <TelephoneNumbers>
            <TelephoneNumber>2223331000</TelephoneNumber>
        </TelephoneNumbers>
    </AcceptableValues>
</PortOutValidationResponse>

It is important to note that if the response from you is not properly formatted, the port out will proceed.

The request/response process here is synchronous in nature. Each webhook is a unique request–there is no multiple back-and-forths over one request. A port out request that has been updated to try to pass validation is treated as an entirely new request as far as this API is concerned.

We wait 30 seconds for a response to the webhook. If no response is received in this time, the port out validation passes and the port out will proceed.

This exchange of information is intended to support the best faith resolution of port requests within the timing guidelines imposed by the FCC. The objective is consistent with the achievement of the balance between preventing unauthorized ports, and timely completion of valid requests.  Information returned to Bandwidth is to aid in dispute resolution and is considered to be covered by CPNI limitations and thereby not intended for distribution to any third parties. Note that failure of the winning carrier to match the values exchanged by the API may not prevent porting-out of the number. FCC guidelines must still be followed in dispute resolution.

Errors

We have a predefined list of error codes that can be sent back to us, indicating the problem with a specific port out request. See the below chart.

A properly formatted error section in your XML looks like:

<Errors>
    <Error>
        <Code>75xx</Code>
        <Description>Customer api error description</Description>
    </Error>
    <Error>
        <Code>75xx</Code>
        <Description>Customer api error description</Description>
    </Error>
</Errors>

One or more errors can be returned as appropriate.

Acceptable Values

For any issues with the data in the webhook, you should return to us the data you would expect for a valid port out. These acceptable values can be any combination of Pin, AccountNumber, ZipCode, and TelephoneNumbers.

For example, if a request comes in with an incorrect PIN, your response should contain the correct PIN.

If a request comes missing a field that you require, you should return the required field and its proper value, which tells us that value is required.

If a request contains a ZIP code when you do not require a ZIP code for validation, you can leave that value out of the acceptable values section.

A properly formatted acceptable values section looks like:

<AcceptableValues>
    <Pin>2222</Pin>
    <AccountNumber>555</AccountNumber>
    <ZipCode>02154</ZipCode>
    <TelephoneNumbers>
        <TelephoneNumber>2223331000</TelephoneNumber>
    </TelephoneNumbers>
</AcceptableValues>

Character Limits

For your reference, here are our defined character limits for each data field in the port out validation API.

• PIN: 10 characters
• Account Number: 25 characters
• ZIP code: 15 characters
• Subscriber name: 93 characters
• Telephone numbers: 10 digits
• PON: 25 characters

Bandwidth’s Port Out Validation API enables an important verification step for port out requests on your account, ensuring FCC regulatory compliance and greater porting process visibility for you.

This overview is Part 1 of a three-part series on Port Out Validation. Parts 2 and 3 contain example code of implementations of this API and its webhooks.