Port-Out Notifications
This section describes what can happen when telephone numbers are ported out of your account.
Bandwidth has a couple of features to help you avoid unauthorized port-out requests by another provider.
- Port-out Validation (described below) allows you to be notified via a webhook when there is a request to port numbers out of your account
- Port-out Passcode Validation (also below) allows you to assign a port-out passcode to a set of your TNs, which must be provided by the winning carrier as additional proof that the port-out is authorized by the subscriber
Because the FCC forbids providers from obstructing legitimate port-out requests, the two features above must be specially contracted with Bandwidth. Bandwidth further reserves the right to disable these features should we have reason to believe that they are being abused.
It is possible to use both Port-out Passcode Validation and Port-out Validation features. In this case, the Port-out Passcode will be evaluated first. If the telephone numbers do not have a port-out passcode assigned, or the PinNumber and port-out passcode matches, Port-out Validation will occur next (assuming it is also configured).
And you may subscribe to receive port-out complete notifications (see below) to assist in management of your telephone number inventory. Unlike the two features above, this feature is an after-the-fact notification that the telephone numbers have been ported out.
Port-Out Validation
The port-out validation feature provides a webhook that is called when TNs are to be ported out of an account. The webhook gives the account owner the chance to validate whether they believe the port-out request to be authorized. If so, they simply indicate that the TNs are portable. Otherwise, they can respond with a well-defined set of reasons to dispute the port-out.
If the Port-out Passcode Validation feature is also being used, that feature is executed prior to Port-out Validation. This means that if the TNs to be ported out are configured with a port-out passcode, and the PinNumber supplied in the LSR or internal port request that triggered the port-out does not match, the port-out will be rejected by the Port-out Passcode feature and the Port-out Validation feature will not be invoked. If the TNs to be ported out do not have a configured port-out passcode, or have one and the PinNumber supplied in the LSR or internal port request that triggered the port-out matches, the Port-out Validation feature will also be invoked.
Note: This feature is only available for on-net telephone numbers. The reason that off-net telephone numbers are not supported is that Bandwidth does not receive an indication that the TNs are being ported out until the port-out is complete.
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. If Bandwidth authorizes you to use this feature, you will need to provide the following information:
- The configured URL provided by the customer that is 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 username / password credentials, or with certificates. The setup of the webhook is covered in the ticketing process.
Responsibilities
Accounts using the Port-out validation API are 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.
Webhook Request
Validation of a Port-out request begins with a notification from Bandwidth to our customer including information that can be used to validate the authenticity of the port-out request. The information may include:
- A list of on-net telephone numbers to be ported out
- A subscriber name for information purposes
- A zip code associated with the subscriber's service address
- An account code indicating the commercial or billing relationship with the subscriber
- A PIN that helps to authenticate the subscriber. Note that this is the same value as the passcode used for the Port-out Passcode feature, if configured.
Responding to the Port-out Validation Notification
Approving the Port-out
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.
A valid response indicating that the TNs may be ported is a 200 response with a payload element indicating “Portable” as true.
Disputing the Port-out
To dispute the port-out (i.e. a negative response indicating that the port-out request is considered to be invalid, based on the information received), the 200 response must contain at least one error response code that indicates the reason for the rejection. This information is passed back to the requesting party to allow them to attempt to correct 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 good 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. If no response is received within 30 seconds, Bandwidth will retry the notification 8 times at 5-minute intervals. If no response is received by the end of the retry period, the port-out is considered to be approved.
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 were not provided in the original request, that indicates that the field was missing from the request and should be provided
- If the returned field/fields were different than provided, 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 |
Please refer to the /callbacks/portOutValidationCallbackApi for details about the webhook payload and response payloads.
Port-Out Passcode Validation
The port-out passcode validation feature allows you to assign passcodes to your telephone numbers, using the /accounts/{accountId}/tnoptions endpoint. When an attempt is made to port a TN out of the account, the PinNumber in the LSR or internal port-in request is compared with the passcode of each telephone number to be ported out. If the values match, the port-out proceeds. If not, the port-out is placed in the Exception state.
In general, each billing account should have one PIN that is known to the subscriber. If the subscriber wishes to port the numbers out of the account, they must supply this PIN to the provider that they wish to port their numbers to. That provider will then supply the PIN as the PinNumber element in the LSR or internal port-in request that they submit to Bandwidth. The PinNumber supplied by the prospective new service provider will be compared to the port-out passcode associated with each TN to be ported out. This implies that all TNs on the billing account should be configured with the same port-out passcode value.
If the Port-out Validation feature is also being used, that feature is executed after Port-out Passcode Validation. This means that if the TNs to be ported out are configured with a port-out passcode, and the PinNumber supplied in the LSR or internal port request that triggered the port-out does not match, the port-out will be rejected by the Port-out Passcode feature and the Port-out Validation feature will not be invoked. If the TNs to be ported out do not have a configured port-out passcode, or have one and the PinNumber supplied in the LSR or internal port request that triggered the port-out matches, the Port-out Validation feature will also be invoked.
Note: This feature is only available for on-net telephone numbers. The reason that off-net telephone numbers are not supported is that Bandwidth does not receive an indication that the TNs are being ported out until the port-out is complete.
Configuration
The configuration of the Port-out Passcode Validation feature is done by Bandwidth staff. Configuration of this service is performed on the submission of a Ticket, and on completion of the required contract extensions.
Responsibilities
Accounts using the Port-out Passcode Validation feature are required to extend the contractual relationship with Bandwidth to ensure clarity around the responsibilities of our customers in the use of the feature, 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.
Port-Out Complete Notification
If you want to know about telephone numbers that have been ported out of your account, you may subscribe to notification of port-out completions. Unlike the Port-out Validation and Port-out Passcode Validation features described above, this is an after-the-fact notification that the telephone numbers have been ported out, not an indication that they are about to be ported out. Also unlike those features, this feature works for both on-net and off-net telephone numbers.
Like all Bandwidth notifications, you may subscribe to receive port-out complete notifications by email or by webhook. If you choose email, you have the further choice of receiving one email for each notification, or a summary digest of port-out complete notifications once per day.
For details on how to subscribe to port-out notifications, please refer to the Order Webhook Guide, and the /accounts/{accountId}/subscriptions API.