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
• Responsibilities
• Summary
• webhook Request
• Allow Portout
• Deny Portout

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

Parameter	Type	Description
PON	string	PON for information and correlation purposes. (optional)( 25 characters )
Pin	int	PIN (optional) ( 10 digits )
AccountNumber	string	Account Number (optional) ( 25 digits )
ZipCode	string	Zipcode (optional) ( 15 characters )
SubscriberName	string	Subscriber name for information purposes. (optional)( 93 characters )
TelephoneNumbers	List 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.

Parameter	Type	Description
Portable	boolean	Must be true
PON	string	PON 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.

Code	Meaning	Disposition
7510	Required Account Code missing	Request placed in Exception
7511	Invalid Account Code	Request placed in Exception
7512	Required PIN missing	Request placed in Exception
7513	PIN Invalid	Request placed in Exception
7514	Required ZIP Code missing	Request placed in Exception
7515	Invalid ZIP Code	Request placed in Exception
7516	Telephone Number not recognized or invalid for this account	Request Cancelled
7517	Too many Telephone numbers in this request	Request Cancelled
7518	Telephone Number Not Active	Request Cancelled
7519	Customer info does not match	Request placed in Exception
7598	Invalid Request -	Request placed in Exception
7599	Fatal Error in Processing	Request succeeds
nnnn	Anything Else	Request succeeds

Parameter	Type	Description
Portable	boolean	Must be false
PON	string	PON for information and correlation purposes. (optional, 25 characters)
Errors	List 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.Code	int	Specific Error code as defined
Error.Description	string	Custom error description
AcceptableValues	Object	Should contain at least one of the optional fields that could be used to validate the port-out request.
Pin	int	PIN (optional, 10 digits )
AccountNumber	string	Account Number (optional) ( 25 digits )
ZipCode	string	Zipcode (optional) ( 15 characters )
SubscriberName	string	Subscriber name for information purposes. (optional)( 93 characters )
TelephoneNumbers	List 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>