Skip to main content

Portout Validation Webhook

The port out validation API is used for portout management purposes and gives the losing side customer the possibility to validate the portout process. Please contact support to enable Portout Validation.

Table of Contents#

Configuration#

The configuration of the call-back API used for port-out validation is done by Bandwidth development staff. Configuration of this service is performed on the submission of a Ticket, and on completion of the required contract extensions.

  • The configured URL provided by the customer that will be invoked by Bandwidth in order to validate a port-out request.
  • The security of the exchange can be protected within an https exchange, and can be authenticated with userid / password credentials, or with certificates. The setup of the webhook will be covered in the ticketing process.

Responsibilities#

Accounts using the Port-out verification API will likely be required to extend the contractual relationship with Bandwidth to ensure clarity around the responsibilities of our customers in the use of the API, and the rights of Bandwidth to withhold this capability if we believe that the capability is being used in contravention of FCC best practices, guidelines and recommendations. Please review these requirements with your Bandwidth representative.

Summary#

Validation of a Port-out request will begin with a submission from Bandwidth to our customer including information used to validate the correctness of the port-out request. The included information may include:

  • A list of telephone numbers to be ported out
  • A subscriber name for information purposes
  • A zip code associated with the subscriber, presumably relating to a billing or service address
  • An account code, presumably related to an account used to reflect the commercial or billing relationship with the subscriber
  • A PIN established by the end user that helps to identify that end user / subscriber
  • Failure to return a valid response will be considered an approval of the port-out request.
  • Failure to return any response will be considered an approval of the port-out request.

Responding to Portout Event#

Webhook Request Parameters#

ParameterTypeDescription
PONstringPON for information and correlation purposes. (optional)( 25 characters )
PinintPIN (optional) ( 10 digits )
AccountNumberstringAccount Number (optional) ( 25 digits )
ZipCodestringZipcode (optional) ( 15 characters )
SubscriberNamestringSubscriber name for information purposes. (optional)( 93 characters )
TelephoneNumbersList of <TelephoneNumber>list of one or more telephone numbers (at least one telephone number will be provided) ( 10 digits )

Example of Incoming Portout Validation Webhook#

POST your_url.com/portoutWebhookService HTTP/1.1
Content-Type: application/xml; charset=utf-8
<?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>

Allow Portout Response#

To validate the portout (IE positive validation of the port-out request), there is no additional information required. Reply with the <Portable>true</Portable> to approve the portout.

  • Failure to return a valid response will be considered an approval of the port-out request.
  • Failure to return any response will be considered an approval of the port-out request.
ParameterTypeDescription
PortablebooleanMust be true
PONstringPON for information and correlation purposes. (optional)( 25 characters )

Example 1 of 1: Allow Portout Response#

HTTP/1.1 200 OK
Content-Type: application/xml
<PortOutValidationResponse>
<Portable>true</Portable>
<PON>some_pon</PON>
</PortOutValidationResponse>

Deny Portout Response#

To deny the portout (IE a negative response indicating that the port-out request is considered to be invalid, based on the information received). The response must contain error response codes that will support updating of the request with valid data. This information will be passed back to the requesting party to allow them to attempt to improve the request.

The response should contain data that would have allowed to port-out to be considered valid:

  • This data is intended for dispute resolution, and for review by Bandwidth to see if the port appears to be valid based on the available data.
  • All fields are considered optional.
  • Failure to return any data may be considered to be equivalent to approving the port-out request.
  • Subsequent submission of the data provided in the response should cause acceptance of the port-out request.
  • This information will not be passed directly on to the requesting party

The above exchange of information is intended to support best faith resolution of port-requests within the constraints imposed by the FCC. The objective is consistent achievement of the middle ground between slamming and unjustified blocking 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.

This exchange of information is synchronous in nature, and will not permit extensive delays in response, and will not create a series of linked transactions for resolving a dispute, or in attempting the port-out with different information. Updated submissions will be treated as new requests. Responses to the API call are expected within 30 seconds.

The error codes and error explanation payloads below are the ones that we expect to see in response to the port-out validation webhook. This uniform set of responses allows a consistent and clear dialog with the prospective winning carrier about the nature of the validation failure.

  • If the returned field/fields was/were not provided in the original request then that indicates that the field was missing from the request and should be provided
  • If the returned field/fields was/were different than provided then that indicates an error in the requesting information
  • For the port-out to be considered valid all telephone numbers in the request should be returned - If one telephone number is invalid then the request fails.
  • Failure to return a valid response will be considered an approval of the port-out request.
  • Failure to return any response will be considered an approval of the port-out request.
CodeMeaningDisposition
7510Required Account Code missingRequest placed in Exception
7511Invalid Account CodeRequest placed in Exception
7512Required PIN missingRequest placed in Exception
7513PIN InvalidRequest placed in Exception
7514Required ZIP Code missingRequest placed in Exception
7515Invalid ZIP CodeRequest placed in Exception
7516Telephone Number not recognized or invalid for this accountRequest Cancelled
7517Too many Telephone numbers in this requestRequest Cancelled
7518Telephone Number Not ActiveRequest Cancelled
7519Customer info does not matchRequest placed in Exception
7598Invalid Request -Request placed in Exception
7599Fatal Error in ProcessingRequest succeeds
nnnnAnything ElseRequest succeeds
ParameterTypeDescription
PortablebooleanMust be false
PONstringPON for information and correlation purposes. (optional, 25 characters)
ErrorsList of <Error>A recognizable error code values must be returned, unrecognized error codes will be ignored and not treated as error codes. The list of acceptable error codes is provided above.
Error.CodeintSpecific Error code as defined
Error.DescriptionstringCustom error description
AcceptableValuesObjectShould contain at least one of the optional fields that could be used to validate the port-out request.
PinintPIN (optional, 10 digits )
AccountNumberstringAccount Number (optional) ( 25 digits )
ZipCodestringZipcode (optional) ( 15 characters )
SubscriberNamestringSubscriber name for information purposes. (optional)( 93 characters )
TelephoneNumbersList of <TelephoneNumber>Contains the telephone numbers considered valid

Example of Denying a Portout Response#

HTTP/1.1 200 OK
Content-Type: application/xml
<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>