From 04b1fbf5f99231ccd965f214f620a6919c40bbbd Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Thu, 30 Jun 2022 14:19:19 +0300 Subject: [PATCH 01/20] Porting - split docs to subdocs --- site/docs/numbers/lsrOrders.mdx | 4 +- .../numbers/{ => porting}/bulkportins.mdx | 0 site/docs/numbers/porting/cancelPortin.mdx | 59 ++ site/docs/numbers/porting/lnpChecker.mdx | 177 ++++++ site/docs/numbers/porting/loaUpload.mdx | 115 ++++ site/docs/numbers/porting/portingNumbers.mdx | 204 ++++++ site/docs/numbers/porting/portingTypes.mdx | 139 +++++ site/docs/numbers/porting/updatePortin.mdx | 187 ++++++ site/docs/numbers/portingNumbers.mdx | 583 ------------------ site/sidebar.js | 15 +- site/specs-temp/numbers.json | 255 ++++++-- 11 files changed, 1096 insertions(+), 642 deletions(-) rename site/docs/numbers/{ => porting}/bulkportins.mdx (100%) create mode 100644 site/docs/numbers/porting/cancelPortin.mdx create mode 100644 site/docs/numbers/porting/lnpChecker.mdx create mode 100644 site/docs/numbers/porting/loaUpload.mdx create mode 100644 site/docs/numbers/porting/portingNumbers.mdx create mode 100644 site/docs/numbers/porting/portingTypes.mdx create mode 100644 site/docs/numbers/porting/updatePortin.mdx delete mode 100644 site/docs/numbers/portingNumbers.mdx diff --git a/site/docs/numbers/lsrOrders.mdx b/site/docs/numbers/lsrOrders.mdx index 7a250dbee..0f17d1485 100644 --- a/site/docs/numbers/lsrOrders.mdx +++ b/site/docs/numbers/lsrOrders.mdx @@ -70,8 +70,8 @@ The payload fields are described below: | Field | Description | |:--------------------------|:-------------------------------------| -| `Pon` | The Pon is customer specified order indentifier field. Allowed alphanumeric and "#","-","_". Up to 25 characters long. (required) | -| `CustomerOrderId` | The CustomerOrderId is customer specified order indentifier field. Allowed alphanumeric, spaces and dashes. Up to 40 characters long. (optional) | +| `Pon` | The Pon is customer specified order identifier field. Allowed alphanumeric and "#","-","_". Up to 25 characters long. (required) | +| `CustomerOrderId` | The CustomerOrderId is customer specified order identifier field. Allowed alphanumeric, spaces and dashes. Up to 40 characters long. (optional) | | `SPID` | Identifier used in porting process. If account is no multi-SPID option - default with account value, otherwise value is required. Up to 4 characters long. (required | | `BillingTelephoneNumber` | Non-tollfree 10 digit phone number (optional) | | `RequestedFocDate` | optional (next day if not specified) | diff --git a/site/docs/numbers/bulkportins.mdx b/site/docs/numbers/porting/bulkportins.mdx similarity index 100% rename from site/docs/numbers/bulkportins.mdx rename to site/docs/numbers/porting/bulkportins.mdx diff --git a/site/docs/numbers/porting/cancelPortin.mdx b/site/docs/numbers/porting/cancelPortin.mdx new file mode 100644 index 000000000..5cfb37683 --- /dev/null +++ b/site/docs/numbers/porting/cancelPortin.mdx @@ -0,0 +1,59 @@ +--- +id: cancelPortin +title: Porting Numbers +slug: /numbers/guides/portcancelPortiningNumbers +description: How to port numbers using the Bandwidth API +keywords: + - bandwidth + - numbers + - porting + - portin + - port + - cancel + - lnp +image: ../../../static/img/bandwidth-logo.png +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const accountId = "{accountId}"; +export const orderId = "{orderId}"; + +export const Highlight = ({children, color}) => ( + + {children} + + ); + +The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. + +## Cancel a Portin Order + +The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and dhe status of the order shall not be marked as `COMPLETE`. The DELETE method is used for this purpose. + +### Request URL + +DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} + +### Examples + +> Request + +```http +DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 +Content-Type: application/xml; charset=utf-8 +Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= +``` + +> Response + +```http +HTTP 200 OK +``` diff --git a/site/docs/numbers/porting/lnpChecker.mdx b/site/docs/numbers/porting/lnpChecker.mdx new file mode 100644 index 000000000..84f454780 --- /dev/null +++ b/site/docs/numbers/porting/lnpChecker.mdx @@ -0,0 +1,177 @@ +--- +id: lnpChecker +title: Lnp Checker +slug: /numbers/porting/lnpChecker +description: How to port numbers using the Bandwidth API +keywords: + - bandwidth + - numbers + - porting + - portin + - port + - lnp + - portability + - checker + - check +image: ../../../static/img/bandwidth-logo.png +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const accountId = "{accountId}"; +export const orderId = "{orderId}"; + +export const Highlight = ({children, color}) => ( + + {children} + + ); + +The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. + +Bandwidth supports two APIs for porting numbers to Bandwidth: +- /portins +- /bulkPortins + +The `/portins` API allows a set of TNs to be ported in, provided that the set of TNs meets the criteria below. +TNs can be ported in a single `/portins` request if all of the following are true: + +1. They all have the same Port Type +2. They all have the same losing carrier +3. They are all associated with the same billing TN and Service Address + +There are also a number of reasons why a TN may not be able to be ported in: + +* The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. +* The TN is an off-net TN and the account is configured to support tier zero (on-net) only. +* The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with. +* The TN is already being processed in another active port-in order. +* The Bandwidth account has not been enabled for porting. +Otherwise the user must separate the TNs into individual `/portins` requests. + +The `/lnpchecker` API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs. +The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. +Terminology + + +| Term | Description | | +|:----------------------------------|:-------------------------------------------------------| +| Port Type | A categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. See the POST operation for more information | +| On-Net | TNs that belong to a rate center covered by Bandwidth are referred to as on-net TNs | +| Off-Net | TNs that belong to a rate center covered by a Bandwidth partner are refered to as off-net TNs | +| Automated | If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention | +| Manual | If the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team | +| Internal | TNs that are being moved from one Bandwidth account to another Bandwidth account are referred to as internal ports. Internal ports are handled automatically | +| Losing carrier | The carrier from which the TN(s) is being ported | + + +## Checking for Portability + +A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the `/accounts/{accountId}/lnpChecker` API endpoint. + +The `fullcheck` query parameter values control the components of the response payload that is returned. + +### Request URL +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker + +### Request Query Parameter + +| `fullcheck` value | Description | +|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `false` (default) | Return only rate center information | +| `true` | Additional information will be provided on the losing carriers associated with the listed numbers | +| `onnetportability` | Provides rate center and losing carrier information for onnet tiers only | +| `offnetportabilty` | In addition to on-net information return off-net port information in `` element with Partner/Vendor that the port will be supported on. Contains a list of the TNs that are supported in partner rate centers, and for which we will manually execute a port if requested for help. | + +### Response Parameters + +| Element | Description | +|:----------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `SupportedRateCenters`
`PartnerSupportedRateCenters`
`UnsupportedRateCenters` | Rate Center information for the indicated set of ratecenters, containing City, State, LATA and the list of TNs for which that Rate Center applies.
The Tier information is provided for offnet rate centers. | +| `SupportedLosingCarriers`
`UnsupportedLosingCarriers` | Details on the Losing Carrier including name, SPID, whether or not the carrier is a wireless carrier, whether or not account number is required as part of the CSR check, and the anticipated minimum number of days before a FoC date will be granted. | + +### Examples + +> Request + +```xml +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker?fullcheck=true HTTP/1.1 +Content-Type: application/xml; charset=utf-8 +Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= + + + + 9195551234 + 9198675309 + + +``` + +> Response + +```xml +HTTP 200 OK +Content-Type: application/xml; charset=utf-8 + + + + MIXED + + 9198675309 + + + + RALEIGH + RALEIGH + NC + 426 + + 0 + + + 9198675309 + + + + + + DIR ASST + CUSTOMER DIRECTORY ASSISTANCE + NC + 99999 + + 9195551234 + + + + + + 979E + BANDWIDTH.COM:979E -NSR/1 + false + false + 3 + + 9198675309 + + + + + Unknown + false + false + 10 + + 9195551234 + + + + +``` diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx new file mode 100644 index 000000000..b657a1e8e --- /dev/null +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -0,0 +1,115 @@ +--- +id: loaUpload +title: LOA Upload +slug: /numbers/guides/loaUpload +description: How to port numbers using the Bandwidth API +keywords: + - bandwidth + - numbers + - porting + - portin + - lnp + - port + - loa + - file + - upload + - letter + - authorization +image: ../../../static/img/bandwidth-logo.png +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const accountId = "{accountId}"; +export const orderId = "{orderId}"; + +export const Highlight = ({children, color}) => ( + + {children} + + ); + +The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. + +## Upload Letter of Authorization (LOA) + +After successfully submitting the Create LNP Order request, an LOA may be uploaded using our LOA API. + +The following MIME types are supported for the LOA upload file: + +* PDF(“application/pdf”) +* PLAIN(“text/plain”) +* JPG(“image/jpeg”) +* TIFF(“image/tiff”) +* CSV(“text/csv”) +* XML(“application/xml”) +* WAV(“audio/x-wav”) +* ZIP(“application/zip”) + +### Request URL +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas + +### Examples + + + + +> Request + +```http +POST /api/accounts/9900778/portins/{orderId}/loas HTTP/1.1 +Host: dashboard.bandwidth.com +Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= +Content-Type: application/pdf +documentType: LOA +Accept: / +Accept-Encoding: gzip, deflate +Accept-Language: en-US,en;q=0.8 +Cache-Control: no-cache + +----WebKitFormBoundaryE19zNvXGzXaLvS5C +Content-Disposition: form-data; name="george"; filename="Bandwidth Dashboard.pdf" +Content-Type: application/pdf +----WebKitFormBoundaryE19zNvXGzXaLvS5C +``` + +> Response + +```xml +HTTP 201 Created +Content-Type: application/xml; charset=utf-8 + + + + 63097af1-37ae-432f-8a0d-9b0e6517a35b-1429550165581.pdf + 0 + LOA file uploaded successfully for order 63097af1-37ae-432f-8a0d-9b0e6517a35b + +``` + + + + +> Request + +```cURL +curl -H 'Content-Type: application/pdf' --data-binary "@Test_LOA.pdf" -iv https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{order-id}/loas +``` + + + + diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx new file mode 100644 index 000000000..94f39824d --- /dev/null +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -0,0 +1,204 @@ +--- +id: portingNumbers +title: Create Portin +slug: /numbers/guides/portingNumbers +description: How to port numbers using the Bandwidth API +keywords: + - bandwidth + - numbers + - porting + - portin + - lnp + - port +image: ../../../static/img/bandwidth-logo.png +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const accountId = "{accountId}"; +export const orderId = "{orderId}"; + +export const Highlight = ({children, color}) => ( + + {children} + + ); + +The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. + +Bandwidth supports two APIs for porting numbers to Bandwidth: +- /portins +- /bulkPortins + +The `/portins` API allows a set of TNs to be ported in, provided that the set of TNs meets the criteria below. +TNs can be ported in a single `/portins` request if all of the following are true: + +1. They all have the same Port Type +2. They all have the same losing carrier +3. They are all associated with the same billing TN and Service Address + +There are also a number of reasons why a TN may not be able to be ported in: + +* The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. +* The TN is an off-net TN and the account is configured to support tier zero (on-net) only. +* The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with. +* The TN is already being processed in another active port-in order. +* The Bandwidth account has not been enabled for porting. +Otherwise the user must separate the TNs into individual `/portins` requests. + +The `/lnpchecker` API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs. +The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. +Terminology + + +| Term | Description | | +|:----------------------------------|:-------------------------------------------------------| +| Port Type | A categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. See the POST operation for more information | +| On-Net | TNs that belong to a rate center covered by Bandwidth are referred to as on-net TNs | +| Off-Net | TNs that belong to a rate center covered by a Bandwidth partner are refered to as off-net TNs | +| Automated | If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention | +| Manual | If the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team | +| Internal | TNs that are being moved from one Bandwidth account to another Bandwidth account are referred to as internal ports. Internal ports are handled automatically | +| Losing carrier | The carrier from which the TN(s) is being ported | + + +## Checking for Portability + +A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the `/accounts/{accountId}/lnpChecker` API endpoint. + +## Create a Portin Order + +The API allows a user to create a new LNP order. An order number will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. + +As in other asynchronous workflows, the request to port in a number is created by a POST to a resource dedicated to the purpose to tracking requests – the `accounts/{accountId}/portins` resource. + +The portins endpoint is used to manage requests to port both toll free and non-toll free telephone numbers into Bandwidth. Like many other requests, the /portins endpoint causes the creation of an order that is used to manage the porting event throughout the lifecycle of the request. The various sub-resources and methods are covered in greater detail below. +When a port-in is created, a port-type is assigned based on the telephone numbers provided. A lot of the conditional payload elements are conditional on the basis of the port-type. Port-type can take on the following values: + +* MANUALOFFNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Off-net port-ins are processed manually when the Bandwidth partner does not have APIs by which the port-in can be automated, or Bandwidth has not implemented those APIs. Orders may also be processed manually if there are more numbers in the port-in than the partner’s interface supports. +* MANUALONNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. On-net port-ins are processed manually only when there are more numbers in the port-in than the porting vendor’s interface supports. +* MANUALTOLLFREE - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Currently all toll free port-ins are handled manually by Bandwidth’s Local Number Portability team. But Bandwidth is in the process of automating portions of toll free porting, with a goal of eventually automating the entire process. +* AUTOMATED - Automated means that the port-in will be processed automatically using interfaces to our porting vendors. There are several sub-types of AUTOMATED as follows: +* ON-NET - On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. There are differences in on-net port-in rules depending on whether the order is for wireless to wireless vs. one of the other 3 combinations. +* OFF-NET - Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Currently only numbers in the U.S. are automated. There are differences in port-in rules depending on whether the order has achieved FOC status. +* INTERNAL - Internal means that the telephone number is being moved from one Bandwidth account to another Bandwidth account. Internal port-in may involve on-net, off-net, or toll free telephone numbers. + +### Polling vs. Webhooks + +Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP "order". The orders are then processed and the order status is updated asynchronously. Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. + +Order processing times can vary and are not guaranteed, so bandwidth recommends relying on a webhook update from an portins subscription. + +### Request URL + +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins + +### Examples + +> Request + +```xml +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins HTTP/1.1 +Content-Type: application/xml; charset=utf-8 +Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= + + + 2016-03-25T21:15:00.000Z + X455 + 9195551234 + 9175131245 + 12345 + 660123 + + BUSINESS + First + Last + + 11235 + Back + Denver + CO + 27541 + Canyon + + + The Authguy + + 771297665AABC + 1234 + + + 9195551234 + 9195554321 + + true + +``` + +> Response + +```xml +HTTP 201 Created +Content-Type: application/xml; charset=utf-8 + + + + 03f194d5-3932-4e9f-8ba1-03ef767985e5 + + 201 + Order request received. Please use the order id to check the status of your order later. + + PENDING_DOCUMENTS + 2016-03-25T21:15:00.000Z + The Authguy + + BUSINESS + First + Last + + 11235 + Back + Denver + CO + 27541 + Canyon + United States + + + + 771297665AABC + 1234 + + 9195551234 + 9175131245 + + 9195551234 + 9195554321 + + true + +``` + +## Modify a Portin Order + +The API allows a user to modify an existing LNP order, called a SUPP request. Modifications are only allowed for orders that are not yet complete or cancelled. LNP orders can be modified with a PUT to `accounts/{accountId}/portins/{orderId}`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. +For more details follow ....TODO + +## Cancel a Portin Order + +The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and dhe status of the order shall not be marked as `COMPLETE`. The DELETE method is used for this purpose. + +TODO : reference to cancel portin + +> Response + +```http +HTTP 200 OK +``` diff --git a/site/docs/numbers/porting/portingTypes.mdx b/site/docs/numbers/porting/portingTypes.mdx new file mode 100644 index 000000000..69d868810 --- /dev/null +++ b/site/docs/numbers/porting/portingTypes.mdx @@ -0,0 +1,139 @@ +--- +id: portingTypes +title: Porting Types +slug: /numbers/guides/portingTypes +description: How to port numbers using the Bandwidth API +keywords: + - bandwidth + - numbers + - porting + - portin + - lnp + - port + - port type + - types +image: ../../../static/img/bandwidth-logo.png +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const accountId = "{accountId}"; +export const orderId = "{orderId}"; + +export const Highlight = ({children, color}) => ( + + {children} + + ); + +The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. + +Bandwidth supports two APIs for porting numbers to Bandwidth: +- /portins +- /bulkPortins + +The `/portins` API allows a set of TNs to be ported in, provided that the set of TNs meets the criteria below. +TNs can be ported in a single `/portins` request if all of the following are true: + +1. They all have the same Port Type +2. They all have the same losing carrier +3. They are all associated with the same billing TN and Service Address + +There are also a number of reasons why a TN may not be able to be ported in: + +* The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. +* The TN is an off-net TN and the account is configured to support tier zero (on-net) only. +* The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with. +* The TN is already being processed in another active port-in order. +* The Bandwidth account has not been enabled for porting. +Otherwise the user must separate the TNs into individual `/portins` requests. + +The `/lnpchecker` API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs. +The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. +Terminology + + +| Term | Description | | +|:----------------------------------|:-------------------------------------------------------| +| Port Type | A categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. See the POST operation for more information | +| On-Net | TNs that belong to a rate center covered by Bandwidth are referred to as on-net TNs | +| Off-Net | TNs that belong to a rate center covered by a Bandwidth partner are refered to as off-net TNs | +| Automated | If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention | +| Manual | If the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team | +| Internal | TNs that are being moved from one Bandwidth account to another Bandwidth account are referred to as internal ports. Internal ports are handled automatically | +| Losing carrier | The carrier from which the TN(s) is being ported | + +* MANUALOFFNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Off-net port-ins are processed manually when the Bandwidth partner does not have APIs by which the port-in can be automated, or Bandwidth has not implemented those APIs. Orders may also be processed manually if there are more numbers in the port-in than the partner’s interface supports. +* MANUALONNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. On-net port-ins are processed manually only when there are more numbers in the port-in than the porting vendor’s interface supports. +* MANUALTOLLFREE - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Currently all toll free port-ins are handled manually by Bandwidth’s Local Number Portability team. But Bandwidth is in the process of automating portions of toll free porting, with a goal of eventually automating the entire process. +* AUTOMATED - Automated means that the port-in will be processed automatically using interfaces to our porting vendors. There are several sub-types of AUTOMATED as follows: +* ON-NET - On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. There are differences in on-net port-in rules depending on whether the order is for wireless to wireless vs. one of the other 3 combinations. +* OFF-NET - Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Currently only numbers in the U.S. are automated. There are differences in port-in rules depending on whether the order has achieved FOC status. +* INTERNAL - Internal means that the telephone number is being moved from one Bandwidth account to another Bandwidth account. Internal port-in may involve on-net, off-net, or toll free telephone numbers. + + +## Create a Portin Order + +The API allows a user to create a new LNP order. An order number will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. + +As in other asynchronous workflows, the request to port in a number is created by a POST to a resource dedicated to the purpose to tracking requests – the `accounts/{accountId}/portins` resource. + +The portins endpoint is used to manage requests to port both toll free and non-toll free telephone numbers into Bandwidth. Like many other requests, the /portins endpoint causes the creation of an order that is used to manage the porting event throughout the lifecycle of the request. The various sub-resources and methods are covered in greater detail below. +When a port-in is created, a port-type is assigned based on the telephone numbers provided. A lot of the conditional payload elements are conditional on the basis of the port-type. Port-type can take on the following values: + + +## Modify a Portin Order + +Please refer to the matrix below to see which elements can be modified and replaced. + +| Payload Field | Manual Off-Net | Manual On-Net | Manual Toll Free | Automated On-Net | Automated Off-Net Pre FOC | Automated Off-Net Post FOC | Internal | +|----------------------------------------------------------|----------------|---------------|------------------|-------------------|---------------------------|----------------------------|----------| +| billingTelephoneNumber | Editable | Editable | Disabled | Editable | Editable | Disabled | Editable | +| newBillingTelephoneNumber | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | +| partialPort | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | +| subscriber.subscriberType | Editable | Editable | Editable | Editable | Editable | Disabled | Editable | +| subscriber.businessName/firstName/middleInitial/lastName | Editable | Editable | Editable | Editable | Editable | Disabled | Editable | +| loaAuthorizingPerson | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | +| wirelessInfo.accountNumber | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | +| wirelessInfo.pinNumber | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | +| subscriber.serviceAddress | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | +| requestedFocDate | Editable | Editable | Editable | Editable | Editable | Editable | Editable | +| listOfPhoneNumbers | Disabled | Disabled | Disabled | Editable | Disabled | Disabled | Disabled | +| siteId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | +| peerId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | +| customerOrderId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | +| TnAttributes elements | Editable | Editable | Editable | Editable | Editable | Editable | Editable | +| Immediately | Disabled | Disabled | Disabled | Disabled | Disabled | Disabled | Editable | + +### SUPP Order Field Notes + +* `AccountNumber` - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both. +* `AlternateSpid` - Not applicable to toll free port-ins. Can only be modified in DRAFT state. Can only be modified if it is not configured at the system level. +* `BillingTelephoneNumber` - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. +* `BusinessName` - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. +* `CustomerOrderId` - Can always be updated. This field is removed from the order if not provided in the PUT payload. +* `Immediately` - Only applicable to Internal port-in orders. May be included in the PUT payload, but cannot be changed in a SUPP. +* `ListOfPhoneNumbers` - Can be SUPPed only for Automated on-net port-ins and toll free port-ins. For toll free port-ins, may be SUPPed only in draft states (i.e. DRAFT, VALIDATE_DRAFT_TFNS, VALID_DRAFT_TFNS, or INVALID_DRAFT_TFNS). +* `LoaAuthorizingPerson` - Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. +* `NewBillingTelephoneNumber` - Not applicable to toll free port-ins or Automated off-net port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins. +* `OverrideValidation` - Applies only to internal ports. This Bandwidth internal flag forces port-out to bypass validity checking (if there are no terminal errors). This flag can be SUPPed only for orders in EXCEPTION status. +* `PartialPort` - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. +* `PeerId` - Can always be updated. +* `PinNumber` - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both. +* `ProcessingStatus` - May only be SUPPed for port-in orders in draft state. The only valid value is “SUBMITTED” (not case sensitive). +* `RequestedFocDate` - Can always be updated, but subject to blackout windows if the current date is too close to an assigned FOC date. +* `ResetAddressFields` - Not applicable to toll free port-ins. If included with a value of true, any Subscriber elements, including subscriber type, subscriber/business name elements, and service address elements, NOT included in the PUT payload will be removed from the order. +* `ServiceAddress` - Element of Subscriber. Includes all address fields. ServiceAddress elements cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. See also, ResetAddressFields. +* `SiteId` - Can always be updated. +* `SubscriberName` - Element of Subscriber. Includes FirstName, MiddleInitial, and LastName. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. +* `SubscriberType` - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. If SubscriberType is set to BUSINESS, a BusinessName must be provided. If SubscriberType is set to RESIDENTIAL, a FirstName and LastName must be provided. +* `TnAttributes` - Can be SUPPed prior to completion of the port-in request. +* `Triggered` - May be included in the PUT payload, but cannot be changed in a SUPP. + diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx new file mode 100644 index 000000000..2f860ee39 --- /dev/null +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -0,0 +1,187 @@ +--- +id: updatePortin +title: Update Portin +slug: /numbers/guides/updatePortin +description: How to port numbers using the Bandwidth API +keywords: + - bandwidth + - numbers + - porting + - portin + - lnp + - port + - update + - supp +image: ../../../static/img/bandwidth-logo.png +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const accountId = "{accountId}"; +export const orderId = "{orderId}"; + +export const Highlight = ({children, color}) => ( + + {children} + + ); + +The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. + +## Modify a Portin Order + +The API allows a user to modify an existing LNP order, called a SUPP request. Modifications are only allowed for orders that are not yet complete or cancelled. LNP orders can be modified with a PUT to `accounts/{accountId}/portins/{orderId}`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. + +Items that can be included in a SUPP request include: + +* CustomerOrderId +* RequestedFocDate +* BillingTelephoneNumber +* NewBillingTelephoneNumber +* AccountNumber +* PinNumber +* TnAttributes elements +* Subscriber elements +* SiteId +* PeerId +* PartialPort +* LoaAuthorizingPerson +* ListOfPhoneNumbers +* Triggered +* Immediately + +If the order ProcessingStatus is DRAFT, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from DRAFT to SUBMITTED. The AltSpid element can be modified if it is not configured at the system level. + +`ProcessingStatus` - you can only provide this field with a value of SUBMITTED if the current ProcessingStatus of the port-in is DRAFT. + +When a port-in is being processed by off-net partner Level 3 (you can retrieve this information using a GET request to `/portins/{orderId}` indicates a Port Type of AUTOMATEDOFFNET and a VendorName of "Level 3"), the rules for what can be changed in a SUPP operation are more restrictive. If the order has NOT yet received FOC, you may change the following: + +* RequestedFocDate +* BillingTelephoneNumber +* SubscriberType +* Subscriber name elements or BusinessName, provided that SubscriberType is provided + +After the FOC date has been received, the billing telephone number and subscriber information cannot be modified, only the FOC date/time can be updated. + +The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. Please refer to the matrix below to see which elements can be modified and replaced. + +| Payload Field | Manual Off-Net | Manual On-Net | Manual Toll Free | Automated On-Net | Automated Off-Net Pre FOC | Automated Off-Net Post FOC | Internal | +|----------------------------------------------------------|----------------|---------------|------------------|-------------------|---------------------------|----------------------------|----------| +| billingTelephoneNumber | Editable | Editable | Disabled | Editable | Editable | Disabled | Editable | +| newBillingTelephoneNumber | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | +| partialPort | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | +| subscriber.subscriberType | Editable | Editable | Editable | Editable | Editable | Disabled | Editable | +| subscriber.businessName/firstName/middleInitial/lastName | Editable | Editable | Editable | Editable | Editable | Disabled | Editable | +| loaAuthorizingPerson | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | +| wirelessInfo.accountNumber | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | +| wirelessInfo.pinNumber | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | +| subscriber.serviceAddress | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | +| requestedFocDate | Editable | Editable | Editable | Editable | Editable | Editable | Editable | +| listOfPhoneNumbers | Disabled | Disabled | Disabled | Editable | Disabled | Disabled | Disabled | +| siteId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | +| peerId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | +| customerOrderId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | +| TnAttributes elements | Editable | Editable | Editable | Editable | Editable | Editable | Editable | +| Immediately | Disabled | Disabled | Disabled | Disabled | Disabled | Disabled | Editable | + +### SUPP Order Field Notes + +* `AccountNumber` - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both. +* `AlternateSpid` - Not applicable to toll free port-ins. Can only be modified in DRAFT state. Can only be modified if it is not configured at the system level. +* `BillingTelephoneNumber` - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. +* `BusinessName` - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. +* `CustomerOrderId` - Can always be updated. This field is removed from the order if not provided in the PUT payload. +* `Immediately` - Only applicable to Internal port-in orders. May be included in the PUT payload, but cannot be changed in a SUPP. +* `ListOfPhoneNumbers` - Can be SUPPed only for Automated on-net port-ins and toll free port-ins. For toll free port-ins, may be SUPPed only in draft states (i.e. DRAFT, VALIDATE_DRAFT_TFNS, VALID_DRAFT_TFNS, or INVALID_DRAFT_TFNS). +* `LoaAuthorizingPerson` - Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. +* `NewBillingTelephoneNumber` - Not applicable to toll free port-ins or Automated off-net port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins. +* `OverrideValidation` - Applies only to internal ports. This Bandwidth internal flag forces port-out to bypass validity checking (if there are no terminal errors). This flag can be SUPPed only for orders in EXCEPTION status. +* `PartialPort` - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. +* `PeerId` - Can always be updated. +* `PinNumber` - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both. +* `ProcessingStatus` - May only be SUPPed for port-in orders in draft state. The only valid value is “SUBMITTED” (not case sensitive). +* `RequestedFocDate` - Can always be updated, but subject to blackout windows if the current date is too close to an assigned FOC date. +* `ResetAddressFields` - Not applicable to toll free port-ins. If included with a value of true, any Subscriber elements, including subscriber type, subscriber/business name elements, and service address elements, NOT included in the PUT payload will be removed from the order. +* `ServiceAddress` - Element of Subscriber. Includes all address fields. ServiceAddress elements cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. See also, ResetAddressFields. +* `SiteId` - Can always be updated. +* `SubscriberName` - Element of Subscriber. Includes FirstName, MiddleInitial, and LastName. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. +* `SubscriberType` - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. If SubscriberType is set to BUSINESS, a BusinessName must be provided. If SubscriberType is set to RESIDENTIAL, a FirstName and LastName must be provided. +* `TnAttributes` - Can be SUPPed prior to completion of the port-in request. +* `Triggered` - May be included in the PUT payload, but cannot be changed in a SUPP. + +### Request URL + +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} + +### Examples + +> Request + +```xml +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 +Content-Type: application/xml; charset=utf-8 +Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= + + + + SJM00002 + 2014-12-04T13:00:00.000Z + 8045030092 + 9175131245 + + 23453245 + 1111 + + + RESIDENTIAL + Steve + McKinnon + + + true + 115 + Monarch Way + Cary + NC + 27518 + + + 743 + true + + 2019721004 + 2019721005 + + Steve McKinnon + Foo + +``` + +> Response + +```xml +HTTP 200 OK +Content-Type: application/xml; charset=utf-8 + + + b6080e4c-7ddf-4faa-bbd8-328a72de9297 + + 200 + Supp request received. Please use the order id to check the status of your order later. + + REQUESTED_SUPP + 2014-12-04T13:00:00Z + 8045030092 + 9175131245 + false + +``` diff --git a/site/docs/numbers/portingNumbers.mdx b/site/docs/numbers/portingNumbers.mdx deleted file mode 100644 index 1a7a15051..000000000 --- a/site/docs/numbers/portingNumbers.mdx +++ /dev/null @@ -1,583 +0,0 @@ ---- -id: portingNumbers -title: Porting Numbers -slug: /numbers/guides/portingNumbers -description: How to port numbers using the Bandwidth API -keywords: - - bandwidth - - numbers - - porting - - port -image: ../../static/img/bandwidth-logo.png ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -export const accountId = "{accountId}"; -export const orderId = "{orderId}"; - -export const Highlight = ({children, color}) => ( - - {children} - - ); - -The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. - -Bandwidth supports two APIs for porting numbers to Bandwidth: -- /portins -- /bulkPortins - -The `/portins` API allows a set of TNs to be ported in, provided that the set of TNs meets the criteria below. -TNs can be ported in a single `/portins` request if all of the following are true: - -1. They all have the same Port Type -2. They all have the same losing carrier -3. They are all associated with the same billing TN and Service Address - -There are also a number of reasons why a TN may not be able to be ported in: - -* The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. -* The TN is an off-net TN and the account is configured to support tier zero (on-net) only. -* The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with. -* The TN is already being processed in another active port-in order. -* The Bandwidth account has not been enabled for porting. -Otherwise the user must separate the TNs into individual `/portins` requests. - -The `/lnpchecker` API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs. -The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. -Terminology - - -| Term | Description | | -|:----------------------------------|:-------------------------------------------------------| -| Port Type | A categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. See the POST operation for more information | -| On-Net | TNs that belong to a rate center covered by Bandwidth are referred to as on-net TNs | -| Off-Net | TNs that belong to a rate center covered by a Bandwidth partner are refered to as off-net TNs | -| Automated | If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention | -| Manual | If the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team | -| Internal | TNs that are being moved from one Bandwidth account to another Bandwidth account are referred to as internal ports. Internal ports are handled automatically | -| Losing carrier | The carrier from which the TN(s) is being ported | - - -## Checking for Portability - -A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the `/accounts/{accountId}/lnpChecker` API endpoint. - -The `fullcheck` query parameter values control the components of the response payload that is returned. - -### Request URL -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker - -### Request Query Parameter - -| `fullcheck` value | Description | -|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `false` (default) | Return only rate center information | -| `true` | Additional information will be provided on the losing carriers associated with the listed numbers | -| `onnetportability` | Provides rate center and losing carrier information for onnet tiers only | -| `offnetportabilty` | In addition to on-net information return off-net port information in `` element with Partner/Vendor that the port will be supported on. Contains a list of the TNs that are supported in partner rate centers, and for which we will manually execute a port if requested for help. | - -### Response Parameters - -| Element | Description | -|:----------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SupportedRateCenters`
`PartnerSupportedRateCenters`
`UnsupportedRateCenters` | Rate Center information for the indicated set of ratecenters, containing City, State, LATA and the list of TNs for which that Rate Center applies.
The Tier information is provided for offnet rate centers. | -| `SupportedLosingCarriers`
`UnsupportedLosingCarriers` | Details on the Losing Carrier including name, SPID, whether or not the carrier is a wireless carrier, whether or not account number is required as part of the CSR check, and the anticipated minimum number of days before a FoC date will be granted. | - -### Examples - -> Request - -```xml -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker?fullcheck=true HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= - - - - 9195551234 - 9198675309 - - -``` - -> Response - -```xml -HTTP 200 OK -Content-Type: application/xml; charset=utf-8 - - - - MIXED - - 9198675309 - - - - RALEIGH - RALEIGH - NC - 426 - - 0 - - - 9198675309 - - - - - - DIR ASST - CUSTOMER DIRECTORY ASSISTANCE - NC - 99999 - - 9195551234 - - - - - - 979E - BANDWIDTH.COM:979E -NSR/1 - false - false - 3 - - 9198675309 - - - - - Unknown - false - false - 10 - - 9195551234 - - - - -``` - -## Create a Portin Order - -The API allows a user to create a new LNP order. An order number will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. - -As in other asynchronous workflows, the request to port in a number is created by a POST to a resource dedicated to the purpose to tracking requests – the `accounts/{accountId}/portins` resource. - -The portins endpoint is used to manage requests to port both toll free and non-toll free telephone numbers into Bandwidth. Like many other requests, the /portins endpoint causes the creation of an order that is used to manage the porting event throughout the lifecycle of the request. The various sub-resources and methods are covered in greater detail below. -When a port-in is created, a port-type is assigned based on the telephone numbers provided. A lot of the conditional payload elements are conditional on the basis of the port-type. Port-type can take on the following values: - -* MANUALOFFNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Off-net port-ins are processed manually when the Bandwidth partner does not have APIs by which the port-in can be automated, or Bandwidth has not implemented those APIs. Orders may also be processed manually if there are more numbers in the port-in than the partner’s interface supports. -* MANUALONNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. On-net port-ins are processed manually only when there are more numbers in the port-in than the porting vendor’s interface supports. -* MANUALTOLLFREE - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Currently all toll free port-ins are handled manually by Bandwidth’s Local Number Portability team. But Bandwidth is in the process of automating portions of toll free porting, with a goal of eventually automating the entire process. -* AUTOMATED - Automated means that the port-in will be processed automatically using interfaces to our porting vendors. There are several sub-types of AUTOMATED as follows: -* ON-NET - On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. There are differences in on-net port-in rules depending on whether the order is for wireless to wireless vs. one of the other 3 combinations. -* OFF-NET - Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Currently only numbers in the U.S. are automated. There are differences in port-in rules depending on whether the order has achieved FOC status. -* INTERNAL - Internal means that the telephone number is being moved from one Bandwidth account to another Bandwidth account. Internal port-in may involve on-net, off-net, or toll free telephone numbers. - -### Polling vs. Webhooks - -Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP "order". The orders are then processed and the order status is updated asynchronously. Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. - -Order processing times can vary and are not guaranteed, so bandwidth recommends relying on a webhook update from an portins subscription. - -### Request URL - -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins - -### Request Parameters - -The table column labeled `M/O/C` is used to indicate if the element is Mandatory, Optional, or Conditional. Conditional elements are mandatory under certain conditions described in the Description column for that element. Mandatory elements are mandatory for all port-types and conditions, and Optional elements are optional for all port-types and conditions. - -| Parameter | M/O/C | Description | -|:----------------------------------|:-----:|:------------| -| AlternateSpid | O | Even though the telephone numbers are being ported into Bandwidth’s SPID, some of Bandwidth’s wholesale customers have an alternate SPID that is used to identify the telephone number with that customer. This element is not applicable for toll free port-ins. | -| BillingTelephoneNumber | C | The `BillingTelephoneNumber` is the primary telephone number associated with the invoice that the subscriber gets from the losing carrier. For wireline port-in, the BillingTelephoneNumber is typically the telephone number being ported in. This element is not applicable for toll free port-ins, but mandatory for non-toll free port-ins. | -| BusinessName | C | The `BusinessName` is mandatory for non-toll free port-ins for which the SubscriberType is set to `BUSINESS`. The `BusinessName` may be up to 50 characters in length. This element is not applicable for toll free port-ins. | -| CustomerOrderId | O | The `CustomerOrderId` is an optional field that may be provided by the customer and will remain with the order.

Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters. The value is opaque to Bandwidth. | -| Immediately | O | Including `Immediately` with a value of `true` will cause an Internal port-in to complete as soon as possible, without requiring a scheduled activation time.

`Immediately` has no meaning for port types other than Internal. | -| LoaAuthorizingPerson | M | The `LoaAuthorizingPerson` is mandatory for all port-types. This is the first and last names of the person that has authorized the port. The `LoaAuthorizingPerson` value may be up to 15 characters in length. | -| ListOfPhoneNumbers | M | `ListOfPhoneNumbers` is an array of `PhoneNumber`. At least one `PhoneNumber` must be provided for all port-types. -| ListOfPhoneNumbers.PhoneNumber | M | Ten digit phone number with no dots or dashes. One or more is required.
Use a `` tag for each phone number in the `` list. | -| NewBillingTelephoneNumber | O | This field is used to specify a new billing telephone number on the losing carrier account.

Cannot be the same as `BillingTelephoneNumber` or be present in the list of ported numbers. This element is not applicable to toll free or off-net port-in orders. | -| PartialPort | O | The `PartialPort` must be set to `true` if the intent is to **NOT** port all of the telephone numbers associated with the `BillingTelephoneNumber`.

If PartialPort is omitted or false, and the `ListOfPhoneNumbers` does not include all of the telephone numbers associated with the `BillingTelephoneNumber`, the port-in will be rejected.

PartialPort is applicable only to on-net port-types. This element is not applicable to toll free or off-net port-in orders. | -| PeerId | O | `PeerId` specifies the numeric identifier of the SIP-peer (Location) that the telephone numbers will be ported into.

You can find the identifier for a SIP-peer (location) by using `GET /accounts/id/sites/id/sippeers`, or by clicking on 'Accounts' on the upper right of the [Bandwidth Dashboard](Https://dashboard.bandwidth.com), then clicking 'Locations' on the navigation bar. The SIP-peer (location) identifiers are listed next to each location name. If `PeerId` is omitted, the SIP-peer (location) designated as the 'default location' for that site (sub-account) will be used. | -| ProcessingStatus | O | Including `ProcessingStatus` with a value of DRAFT allows you to create a port-in request, but not process the request. Omitting `ProcessingStatus` causes the port-in to be validated and, if correct, processed right away.

Be aware, however, that validation of the port-in payload occurs when the request is actually submitted by performing a PUT on the order with `ProcessingStatus` set to SUBMITTED. | -| RequestedFocDate | O | Format: ISO8601 encoding such as “2013-05-10T15:14:22Z”, or "2019-10-31T17:15:00+04:00".

For all ports, if `RequestedFocDate` is specified, the date portion must be:
- in the future
- after the losing carrier's minimum number of days to port-out
- not on a weekend or U.S. holiday

If `RequestedFocDate` is not specified, the next available FOC date meeting the criteria above will be used. If the Time portion of the `RequestedFocDate` is omitted the port-in order will be activated at the default activation time of 11:30 AM ET. If an activation time other than 11:30 AM ET is desired, that activation time should be included in the `RequestedFocDate`. | -| ResetAddressFields | O | The `ResetAddressFields` may be specified in a `PUT` request for a non-toll free port-in order if you would like to remove `ServiceAddress` elements that are not specified in the PUT payload. Default value is `false`. | -| ServiceAddress | C | The `ServiceAddress` is mandatory for all non-toll free port-ins. See sub-fields for additional details. | -| ServiceAddress.AddressDetail1 - 3 | O | `AddressDetail1` may be used to specify Secondary Address Unit Designators, as defined by the Postal Addressing Standards, Publication 28. Generally, `AddressDetail1` would be accompanied by `AddressValue1`.

`AddressDetail1`, `AddressDetail2`, and `AddressDetail3` are all available parameters. | -| ServiceAddress.AddressLine2 | O | `AddressLine2` is used to specify Unit, Suite, Floor, etc. in the Service Address. `AddressLine2` is optional when not needed to fully specify the `ServiceAddress`. | -| ServiceAddress.AddressValue1 - 3 | O | `AddressValue1` may be used to specify Secondary Address Unit Designators, as defined by the Postal Addressing Standards, Publication 28. Generally, `AddressDetail1` would be accompanied by `AddressValue1`

`AddressValue1`, `AddressValue2`, and `AddressValue3` are all available parameters. | -| ServiceAddress.City | C | `City` is mandatory in cases where the `ServiceAddress` is mandatory. | -| ServiceAddress.Country | O | `Country` is the country of the `ServiceAddress`. This value will be derived from the `StateCode`, so it should generally be omitted. | -| ServiceAddress.HouseNumber | C | The `HouseNumber` is the street address number of the `ServiceAddress`. `HouseNumber` is mandatory for port-in orders in which the `ServiceAddress` is mandatory. | -| ServiceAddress.HousePrefix | O | The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`. | -| ServiceAddress.HouseSuffix | O | The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`. | -| ServiceAddress.PlusFour | O | `PlusFour` is the 4 digits that are sometimes suffixed to the Zip Code. | -| ServiceAddress.PostDirectional | O | The `PostDirectional` is the street name post directional of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`. | -| ServiceAddress.PreDirectional | O | The `PreDirectional` is the non-numeric street name prefix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`. | -| ServiceAddress.StateCode | C | `StateCode` is the 2-letter abbreviation of the state of the `ServiceAddress`. `StateCode` is mandatory in cases where the `ServiceAddress` is mandatory. ex: `NC`, `NY`, or `AK` | -| ServiceAddress.StreetName | C | The `StreetName` is mandatory in cases where the `ServiceAddress` is mandatory. | -| ServiceAddress.StreetSuffix | O | The `StreetSuffix` is the street suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`. | -| SiteId | M | `SiteId` is mandatory for all port-types. It specifies the identifier of the site (sub-account) that the telephone numbers will be ported into.

You can find the identifier for a site (sub-account) by using `GET /accounts/id/sites`, or by clicking on 'Manage sub-account' for the desired sub-account on the main page of the Bandwidth Dashboard. | -| Subscriber | C | The `Subscriber` is mandatory for all non-toll free port-in orders. See sub-fields for details. | -| Subscriber.FirstName | O | The `FirstName` value is applicable to non-toll free port-in orders in which the `SubscriberType` is set to RESIDENTIAL. The `FirstName` is always optional. The `FirstName` may be up to 50 characters in length. | -| Subscriber.LastName | C | The `LastName` value is mandatory for non-toll free port-in orders in which the `SubscriberType` is set to RESIDENTIAL. The `LastName` may be up to 50 characters in length. | -| Subscriber.MiddleInitial | O | The `MiddleInitial` value is applicable to non-toll free port-in orders in which the SubscriberType is set to RESIDENTIAL. The `MiddleInitial` is always optional. The `MiddleInitial` is 1 character in length. | -| Subscriber.SubscriberType | C | The `SubscriberType` is mandatory for all non-toll free port-in orders.

The `SubscriberType` field may have values: `BUSINESS` or `RESIDENTIAL`. | -| TnAttributes | O | The `TnAttributes` field specifies line attributes that will apply to the ported in telephone numbers. If present, `TnAttributes` may have a value of `PROTECTED`. This element is not applicable for off-net or toll free port-types. | -| Triggered | O | The `Triggered` field must be set to `true` if you want an activation time other than the 11:30 AM ET default. The desired activation time can then be specified in the time portion of the `RequestedFocDate`. Triggered activation is not yet supported for toll free port-in orders. | -| WirelessInfo | O | Most common for telephone numbers that were formerly wireless. This element is not applicable for toll free port-ins. | -| WirelessInfo.AccountNumber | O | The `AccountNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless. | -| WirelessInfo.PinNumber | O | The `PinNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless. | -| Zip | C | `Zip` is the Zip Code of the `ServiceAddress`. `Zip` is mandatory in cases where the `ServiceAddress` is mandatory. | - -### Examples - -> Request - -```xml -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= - - - 2016-03-25T21:15:00.000Z - X455 - 9195551234 - 9175131245 - 12345 - 660123 - - BUSINESS - First - Last - - 11235 - Back - Denver - CO - 27541 - Canyon - - - The Authguy - - 771297665AABC - 1234 - - - 9195551234 - 9195554321 - - true - -``` - -> Response - -```xml -HTTP 201 Created -Content-Type: application/xml; charset=utf-8 - - - - 03f194d5-3932-4e9f-8ba1-03ef767985e5 - - 201 - Order request received. Please use the order id to check the status of your order later. - - PENDING_DOCUMENTS - 2016-03-25T21:15:00.000Z - The Authguy - - BUSINESS - First - Last - - 11235 - Back - Denver - CO - 27541 - Canyon - United States - - - - 771297665AABC - 1234 - - 9195551234 - 9175131245 - - 9195551234 - 9195554321 - - true - -``` - -## Upload Letter of Authorization (LOA) - -After successfully submitting the Create LNP Order request, an LOA may be uploaded using our LOA API. - -The following MIME types are supported for the LOA upload file: - -* PDF(“application/pdf”) -* PLAIN(“text/plain”) -* JPG(“image/jpeg”) -* TIFF(“image/tiff”) -* CSV(“text/csv”) -* XML(“application/xml”) -* WAV(“audio/x-wav”) -* ZIP(“application/zip”) - -### Request URL -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas - -### Examples - - - - -> Request - -```http -POST /api/accounts/9900778/portins/{orderId}/loas HTTP/1.1 -Host: dashboard.bandwidth.com -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -Content-Type: application/pdf -documentType: LOA -Accept: / -Accept-Encoding: gzip, deflate -Accept-Language: en-US,en;q=0.8 -Cache-Control: no-cache - -----WebKitFormBoundaryE19zNvXGzXaLvS5C -Content-Disposition: form-data; name="george"; filename="Bandwidth Dashboard.pdf" -Content-Type: application/pdf -----WebKitFormBoundaryE19zNvXGzXaLvS5C -``` - -> Response - -```xml -HTTP 201 Created -Content-Type: application/xml; charset=utf-8 - - - - 63097af1-37ae-432f-8a0d-9b0e6517a35b-1429550165581.pdf - 0 - LOA file uploaded successfully for order 63097af1-37ae-432f-8a0d-9b0e6517a35b - -``` - - - - -> Request - -```cURL -curl -H 'Content-Type: application/pdf' --data-binary "@Test_LOA.pdf" -iv https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{order-id}/loas -``` - - - - -## Modify a Portin Order - -The API allows a user to modify an existing LNP order, called a SUPP request. Modifications are only allowed for orders that are not yet complete or cancelled. LNP orders can be modified with a PUT to `accounts/{accountId}/portins/{orderId}`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. - -Items that can be included in a SUPP request include: - -* CustomerOrderId -* RequestedFocDate -* BillingTelephoneNumber -* NewBillingTelephoneNumber -* AccountNumber -* PinNumber -* TnAttributes elements -* Subscriber elements -* SiteId -* PeerId -* PartialPort -* LoaAuthorizingPerson -* ListOfPhoneNumbers -* Triggered -* Immediately - -If the order ProcessingStatus is DRAFT, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from DRAFT to SUBMITTED. The AltSpid element can be modified if it is not configured at the system level. - -`ProcessingStatus` - you can only provide this field with a value of SUBMITTED if the current ProcessingStatus of the port-in is DRAFT. - -When a port-in is being processed by off-net partner Level 3 (you can retrieve this information using a GET request to `/portins/{orderId}` indicates a Port Type of AUTOMATEDOFFNET and a VendorName of "Level 3"), the rules for what can be changed in a SUPP operation are more restrictive. If the order has NOT yet received FOC, you may change the following: - -* RequestedFocDate -* BillingTelephoneNumber -* SubscriberType -* Subscriber name elements or BusinessName, provided that SubscriberType is provided - -After the FOC date has been received, the billing telephone number and subscriber information cannot be modified, only the FOC date/time can be updated. - -The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. Please refer to the matrix below to see which elements can be modified and replaced. - -| Payload Field | Manual Off-Net | Manual On-Net | Manual Toll Free | Automated On-Net | Automated Off-Net Pre FOC | Automated Off-Net Post FOC | Internal | -|----------------------------------------------------------|----------------|---------------|------------------|-------------------|---------------------------|----------------------------|----------| -| billingTelephoneNumber | Editable | Editable | Disabled | Editable | Editable | Disabled | Editable | -| newBillingTelephoneNumber | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | -| partialPort | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | -| subscriber.subscriberType | Editable | Editable | Editable | Editable | Editable | Disabled | Editable | -| subscriber.businessName/firstName/middleInitial/lastName | Editable | Editable | Editable | Editable | Editable | Disabled | Editable | -| loaAuthorizingPerson | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | -| wirelessInfo.accountNumber | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | -| wirelessInfo.pinNumber | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | -| subscriber.serviceAddress | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | -| requestedFocDate | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| listOfPhoneNumbers | Disabled | Disabled | Disabled | Editable | Disabled | Disabled | Disabled | -| siteId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| peerId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| customerOrderId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| TnAttributes elements | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| Immediately | Disabled | Disabled | Disabled | Disabled | Disabled | Disabled | Editable | - -### SUPP Order Field Notes - -* `AccountNumber` - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both. -* `AlternateSpid` - Not applicable to toll free port-ins. Can only be modified in DRAFT state. Can only be modified if it is not configured at the system level. -* `BillingTelephoneNumber` - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. -* `BusinessName` - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. -* `CustomerOrderId` - Can always be updated. This field is removed from the order if not provided in the PUT payload. -* `Immediately` - Only applicable to Internal port-in orders. May be included in the PUT payload, but cannot be changed in a SUPP. -* `ListOfPhoneNumbers` - Can be SUPPed only for Automated on-net port-ins and toll free port-ins. For toll free port-ins, may be SUPPed only in draft states (i.e. DRAFT, VALIDATE_DRAFT_TFNS, VALID_DRAFT_TFNS, or INVALID_DRAFT_TFNS). -* `LoaAuthorizingPerson` - Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. -* `NewBillingTelephoneNumber` - Not applicable to toll free port-ins or Automated off-net port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins. -* `OverrideValidation` - Applies only to internal ports. This Bandwidth internal flag forces port-out to bypass validity checking (if there are no terminal errors). This flag can be SUPPed only for orders in EXCEPTION status. -* `PartialPort` - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. -* `PeerId` - Can always be updated. -* `PinNumber` - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both. -* `ProcessingStatus` - May only be SUPPed for port-in orders in draft state. The only valid value is “SUBMITTED” (not case sensitive). -* `RequestedFocDate` - Can always be updated, but subject to blackout windows if the current date is too close to an assigned FOC date. -* `ResetAddressFields` - Not applicable to toll free port-ins. If included with a value of true, any Subscriber elements, including subscriber type, subscriber/business name elements, and service address elements, NOT included in the PUT payload will be removed from the order. -* `ServiceAddress` - Element of Subscriber. Includes all address fields. ServiceAddress elements cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. See also, ResetAddressFields. -* `SiteId` - Can always be updated. -* `SubscriberName` - Element of Subscriber. Includes FirstName, MiddleInitial, and LastName. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. -* `SubscriberType` - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. If SubscriberType is set to BUSINESS, a BusinessName must be provided. If SubscriberType is set to RESIDENTIAL, a FirstName and LastName must be provided. -* `TnAttributes` - Can be SUPPed prior to completion of the port-in request. -* `Triggered` - May be included in the PUT payload, but cannot be changed in a SUPP. - -### Request URL - -PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} - -### Examples - -> Request - -```xml -PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= - - - - SJM00002 - 2014-12-04T13:00:00.000Z - 8045030092 - 9175131245 - - 23453245 - 1111 - - - RESIDENTIAL - Steve - McKinnon - - - true - 115 - Monarch Way - Cary - NC - 27518 - - - 743 - true - - 2019721004 - 2019721005 - - Steve McKinnon - Foo - -``` - -> Response - -```xml -HTTP 200 OK -Content-Type: application/xml; charset=utf-8 - - - b6080e4c-7ddf-4faa-bbd8-328a72de9297 - - 200 - Supp request received. Please use the order id to check the status of your order later. - - REQUESTED_SUPP - 2014-12-04T13:00:00Z - 8045030092 - 9175131245 - false - -``` - -## Cancel a Portin Order - -The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and dhe status of the order shall not be marked as `COMPLETE`. The DELETE method is used for this purpose. - -### Request URL - -DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} - -### Examples - -> Request - -```http -DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -``` - -> Response - -```http -HTTP 200 OK -``` diff --git a/site/sidebar.js b/site/sidebar.js index 58ba2a224..d63961f65 100644 --- a/site/sidebar.js +++ b/site/sidebar.js @@ -46,13 +46,24 @@ module.exports = { items: [ "numbers/searchingNumbers", "numbers/orderingNumbers", - "numbers/portingNumbers", + { + type: "category", + label: "Porting numbers", + items: [ + "numbers/porting/portingNumbers", + "numbers/porting/lnpChecker", + "numbers/porting/loaUpload", + "numbers/porting/updatePortin", + "numbers/porting/cancelPortin", + "numbers/porting/portingTypes", + "numbers/porting/bulkportins", + ], + }, "numbers/csrLookupTool", "numbers/hostingNumbers", "numbers/manageNumberFeatures", "numbers/searchNumbers", "numbers/disconnectNumbers", - "numbers/bulkportins", "numbers/lookupNumbers", "numbers/downloadingReports", "numbers/e911s", diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index 4fa9be11a..b1bffa318 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -10190,7 +10190,7 @@ "/accounts", "Porting" ], - "description": "Creates a port-in order for the specified telephone number(s) and account number.\nWhen the order is successfully created, the 201 response will include a unique orderId that\nis used to manage the order.

\n

Note that you can create a 'draft' order by including ProcessingStatus with a value of 'draft'\nwhen you create the order. A draft order is not submitted to the porting vendor until you\nrequest that it be submitted by using PUT to update the ProcessingStatus to 'submitted'.\nThis is useful if you wish to add items to the order over a period of time and submit once\nyou have the order setup the way you want. Note, however, that draft orders that have not\nbeen updated in a couple of days are automatically deleted. Removal of stagnant draft orders\nis performed so that telephone numbers are not tied up in these orders, preventing them from\nbeing included in other orders. Very little validation is performed while an order is in\ndraft state. It is only when you change the ProcessingStatus to 'submitted' that full\nvalidation is performed on the order.

If you are creating a port-in order for toll free telephone numbers, you can create the order\nwith far fewer fields. The only mandatory fields for toll free port-in orders are:

\n\n
  • URI parameter, accountId
    • \n
  • A ListOfPhoneNumbers with at least one toll free PhoneNumber
    • \n
  • The SiteId that will serve as the destination of you toll free number on completion of the\nport-in
    • \n
  • The LoaAuthorizingPerson name
\n\n

But you may also want to include optional toll free fields: RequestedFocDate, CustomerOrderId,\nPeerId, and ProcessingStatus. All other port-in fields are not applicable for toll free\nport-ins.

\n\n

All toll free telephone numbers provided will be validated (even in draft state) to ensure\nthat they are portable, and to allow you to separate telephone numbers into separate port-ins\nbased on the RespOrg that they are being ported from.

\n", + "description": "Creates a port-in order for the specified telephone number(s) and account number.", "operationId": "CreatePortin", "summary": "Create port-in order", "parameters": [ @@ -11779,7 +11779,7 @@ "content": { "application/xml": { "schema": { - "$ref": "#/components/schemas/LnpOrderResponse" + "$ref": "#/components/schemas/LnpOrderPortoutResponse" }, "examples": { "example": { @@ -13487,10 +13487,10 @@ "description": "Successful retrieval of report output. Link to download the file provided in the Location header", "headers": { "Location": { - "description": "The URL for downloading the file", - "schema": { - "type": "string" - } + "description": "The URL for downloading the file", + "schema": { + "type": "string" + } } } }, @@ -20107,7 +20107,7 @@ "type": "string", "maxLength": 255 }, - "LnpOrderResponse": { + "LnpOrderPortoutResponse": { "type": "object", "properties": { "LnpOrderResponse": { @@ -22522,79 +22522,220 @@ "type": "object", "properties": { "LnpOrder": { - "$ref": "#/components/schemas/LnpOrder" + "type": "object", + "properties": { + "CustomerOrderId": { + "type": "string", + "description": "The `CustomerOrderId` is an optional field that may be provided by the customer and will remain with the order.

Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters. The value is opaque to Bandwidth." + }, + "ProcessingStatus": { + "type": "string", + "enum": [ + "DRAFT" + ], + "description": "Including `ProcessingStatus` with a value of DRAFT allows you to create a port-in request, but not process the request. This is useful if you wish to add items to the order over a period of time and submit once you have the order setup the way you want. Note, however, that draft orders that have not been updated in a couple of days are automatically deleted. Removal of stagnant draft orders is performed so that telephone numbers are not tied up in these orders, preventing them from being included in other orders.

Very little validation is performed while an order is in draft state. Omitting `ProcessingStatus` causes the port-in to be validated and, if correct, processed right away. The full validation is performed on the order when you change the ProcessingStatus to 'SUBMITTED' by performing a PUT request on the order.

All toll free telephone numbers provided will be validated (even in draft state) to ensure\nthat they are portable, and to allow you to separate telephone numbers into separate port-ins\nbased on the RespOrg that they are being ported from.

" + }, + "BillingTelephoneNumber": { + "type": "string", + "description": "The `BillingTelephoneNumber` is the primary telephone number associated with the invoice that the subscriber gets from the losing carrier. For wireline port-in, the BillingTelephoneNumber is typically the telephone number being ported in. This element is not applicable for toll free port-ins, but mandatory for non-toll free port-ins." + }, + "NewBillingTelephoneNumber": { + "type": "string", + "description": "This field is used to specify a new billing telephone number on the losing carrier account.

Cannot be the same as `BillingTelephoneNumber` or be present in the list of ported numbers. This element is not applicable to toll free or off-net port-in orders." + }, + "WirelessInfo": { + "$ref": "#/components/schemas/WirelessInfoPortinRequestPayload" + }, + "RequestedFocDate": { + "type": "string", + "description": "Format: ISO8601 encoding such as “2013-05-10T15:14:22Z”, or \"2019-10-31T17:15:00+04:00\".

For all ports, if `RequestedFocDate` is specified, the date portion must be:
- in the future
- after the losing carrier's minimum number of days to port-out
- not on a weekend or U.S. holiday

If `RequestedFocDate` is not specified, the next available FOC date meeting the criteria above will be used. If the Time portion of the `RequestedFocDate` is omitted the port-in order will be activated at the default activation time of 11:30 AM ET. If an activation time other than 11:30 AM ET is desired, that activation time should be included in the `RequestedFocDate`." + }, + "Subscriber": { + "$ref": "#/components/schemas/SubscriberPortinPayload" + }, + "PeerId": { + "type": "string", + "description": "`PeerId` specifies the numeric identifier of the SIP-peer (Location) that the telephone numbers will be ported into.

You can find the identifier for a SIP-peer (location) by using `GET /accounts/id/sites/id/sippeers`, or by clicking on 'Accounts' on the upper right of the [Bandwidth Dashboard](Https://dashboard.bandwidth.com), then clicking 'Locations' on the navigation bar. The SIP-peer (location) identifiers are listed next to each location name. If `PeerId` is omitted, the SIP-peer (location) designated as the 'default location' for that site (sub-account) will be used." + }, + "PartialPort": { + "type": "string", + "description": "The `PartialPort` must be set to `true` if the intent is to **NOT** port all of the telephone numbers associated with the `BillingTelephoneNumber`.

If PartialPort is omitted or false, and the `ListOfPhoneNumbers` does not include all of the telephone numbers associated with the `BillingTelephoneNumber`, the port-in will be rejected.

PartialPort is applicable only to on-net port-types. This element is not applicable to toll free or off-net port-in orders." + }, + "LoaAuthorizingPerson": { + "type": "string", + "description": "The `LoaAuthorizingPerson` is mandatory for all port-types. This is the first and last names of the person that has authorized the port. The `LoaAuthorizingPerson` value may be up to 15 characters in length." + }, + "Immediately": { + "type": "boolean", + "description": "Including `Immediately` with a value of `true` will cause an Internal port-in to complete as soon as possible, without requiring a scheduled activation time.

`Immediately` has no meaning for port types other than Internal." + }, + "Triggered": { + "type": "boolean", + "description": "The `Triggered` field must be set to `true` if you want an activation time other than the 11:30 AM ET default. The desired activation time can then be specified in the time portion of the `RequestedFocDate`. Triggered activation is not yet supported for toll free port-in orders." + }, + "BillingType": { + "type": "string", + "description": "" + }, + "AutoActivation": { + "type": "string", + "description": "" + }, + "TnAttributes": { + "type": "array", + "description": "The `TnAttributes` field specifies line attributes that will apply to the ported in telephone numbers. If present, `TnAttributes` may have a value of `PROTECTED`. This element is not applicable for off-net or toll free port-types.", + "items": { + "$ref": "#/components/schemas/TnAttribute" + } + }, + "AlternateSpid": { + "type": "string", + "description": "Even though the telephone numbers are being ported into Bandwidth’s SPID, some of Bandwidth’s wholesale customers have an alternate SPID that is used to identify the telephone number with that customer. This element is not applicable for toll free port-ins." + }, + "ListOfPhoneNumbers": { + "type": "array", + "description": "`ListOfPhoneNumbers` is an array of `PhoneNumber`. At least one `PhoneNumber` must be provided for all port-types.", + "items": { + "type": "object", + "properties": { + "PhoneNumber": { + "description": "Ten digit phone number with no dots or dashes. One or more is required.
Use a `` tag for each phone number in the `` list.", + "type": "string" + } + } + } + }, + "SiteId": { + "type": "integer", + "format": "int32", + "description": "`SiteId` is mandatory for all port-types. It specifies the identifier of the site (sub-account) that the telephone numbers will be ported into.

You can find the identifier for a site (sub-account) by using `GET /accounts/id/sites`, or by clicking on 'Manage sub-account' for the desired sub-account on the main page of the Bandwidth Dashboard." + } + } } } }, - "LnpOrder": { + "SubscriberPortinPayload": { "type": "object", + "title": "Subscriber", + "description": "The `Subscriber` is mandatory for all non-toll free port-in orders. See sub-fields for details.", "properties": { - "CustomerOrderId": { - "type": "string" - }, - "ProcessingStatus": { + "SubscriberType": { "type": "string", + "description": "The `SubscriberType` is mandatory for all non-toll free port-in orders.

The `SubscriberType` field may have values: `BUSINESS` or `RESIDENTIAL`.", "enum": [ - "DRAFT" + "business", + "residential", + "generic" ] }, - "BillingTelephoneNumber": { - "type": "string" + "BusinessName": { + "type": "string", + "description": "The `BusinessName` is mandatory for non-toll free port-ins for which the SubscriberType is set to `BUSINESS`. The `BusinessName` may be up to 25 characters in length. This element is not applicable for toll free port-ins." }, - "NewBillingTelephoneNumber": { - "type": "string" + "FirstName": { + "type": "string", + "description": "The `FirstName` value is applicable to non-toll free port-in orders in which the `SubscriberType` is set to RESIDENTIAL. The `FirstName` is always optional. The `FirstName` may be up to 25 characters in length." }, - "WirelessInfo": { - "$ref": "#/components/schemas/WirelessInfo" + "MiddleInitial": { + "type": "string", + "description": "The `MiddleInitial` value is applicable to non-toll free port-in orders in which the SubscriberType is set to RESIDENTIAL. The `MiddleInitial` is always optional. The `MiddleInitial` is 1 character in length." }, - "RequestedFocDate": { - "type": "string" + "LastName": { + "type": "string", + "description": "The `LastName` value is mandatory for non-toll free port-in orders in which the `SubscriberType` is set to RESIDENTIAL. The `LastName` may be up to 25 characters in length." }, - "Subscriber": { - "$ref": "#/components/schemas/Subscriber" + "Name": { + "type": "string", + "description": "" }, - "PeerId": { - "type": "string" + "AccountNumber": { + "type": "string", + "description": "" }, - "PartialPort": { - "type": "string" + "PinNumber": { + "type": "string", + "description": "" }, - "LoaAuthorizingPerson": { - "type": "string" + "ServiceAddress": { + "$ref": "#/components/schemas/PortinSubscriberAddress" + } + } + }, + "PortinSubscriberAddress": { + "type": "object", + "title": "ServiceAddress", + "description": "The `ServiceAddress` is mandatory for all non-toll free port-ins. See sub-fields for additional details.", + "properties": { + "HousePrefix": { + "type": "string", + "description": "The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." }, - "Immediately": { - "type": "boolean" + "HouseNumber": { + "type": "string", + "description": "The `HouseNumber` is the street address number of the `ServiceAddress`. `HouseNumber` is mandatory for port-in orders in which the `ServiceAddress` is mandatory." }, - "Triggered": { - "type": "boolean" + "HouseSuffix": { + "type": "string", + "description": "The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." }, - "BillingType": { - "type": "string" + "PreDirectional": { + "type": "string", + "description": "The `PreDirectional` is the non-numeric street name prefix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." }, - "AutoActivation": { - "type": "string" + "StreetName": { + "type": "string", + "description": "The `StreetName` is mandatory in cases where the `ServiceAddress` is mandatory." }, - "TnAttributes": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TnAttribute" - } + "StreetSuffix": { + "type": "string", + "description": "The `StreetSuffix` is the street suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." }, - "OverrideValidation": { - "type": "boolean" + "PostDirectional": { + "type": "string", + "description": "The `PostDirectional` is the street name post directional of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." }, - "AlternateSpid": { - "type": "string" + "AddressLine2": { + "type": "string", + "description": "`AddressLine2` is used to specify Unit, Suite, Floor, etc. in the Service Address. `AddressLine2` is optional when not needed to fully specify the `ServiceAddress`." }, - "ListOfPhoneNumbers": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PhoneNumber" - } + "City": { + "type": "string", + "description": "`City` is mandatory in cases where the `ServiceAddress` is mandatory." }, - "SiteId": { - "type": "integer", - "format": "int32" + "StateCode": { + "type": "string", + "description": "`StateCode` is the 2-letter abbreviation of the state of the `ServiceAddress`. `StateCode` is mandatory in cases where the `ServiceAddress` is mandatory. ex: `NC`, `NY`, or `AK`" + }, + "Zip": { + "type": "string", + "description": "`Zip` is the Zip Code of the `ServiceAddress`. `Zip` is mandatory in cases where the `ServiceAddress` is mandatory." + }, + "PlusFour": { + "type": "string", + "description": "`PlusFour` is the 4 digits that are sometimes suffixed to the Zip Code." + }, + "Country": { + "type": "string", + "description": "`Country` is the country of the `ServiceAddress`. This value will be derived from the `StateCode`, so it should generally be omitted." + }, + "ResetAddressFields": { + "type": "boolean", + "description": "The `ResetAddressFields` may be specified in a `PUT` request for a non-toll free port-in order if you would like to remove `ServiceAddress` elements that are not specified in the PUT payload. Default value is `false`." + } + } + }, + "WirelessInfoPortinRequestPayload": { + "type": "object", + "title": "WirelessInfo", + "description": "Most common for telephone numbers that were formerly wireless. This element is not applicable for toll free port-ins.", + "properties": { + "AccountNumber": { + "type": "string", + "description": "The `AccountNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless." + }, + "PinNumber": { + "type": "string", + "description": "The `PinNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless." } } }, @@ -28927,6 +29068,10 @@ "LnpOrderResponse": { "type": "object", "properties": { + "OrderId": { + "type": "string", + "description": "Unique orderId that is used to manage the order" + }, "Status": { "type": "object", "properties": { From 80155ea97be3aa300672faddd295e9888c19f71a Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Thu, 30 Jun 2022 14:47:31 +0300 Subject: [PATCH 02/20] Porting - refined request schema --- site/specs-temp/numbers.json | 263 ++++++++++++++++++----------------- 1 file changed, 134 insertions(+), 129 deletions(-) diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index b1bffa318..172e45091 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -22526,7 +22526,9 @@ "properties": { "CustomerOrderId": { "type": "string", - "description": "The `CustomerOrderId` is an optional field that may be provided by the customer and will remain with the order.

Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters. The value is opaque to Bandwidth." + "description": "The `CustomerOrderId` is an optional field that may be provided by the customer and will remain with the order. The value is opaque to Bandwidth.", + "format": "Only alphanumeric values, dashes and spaces are allowed", + "maxLength": 40 }, "ProcessingStatus": { "type": "string", @@ -22544,14 +22546,134 @@ "description": "This field is used to specify a new billing telephone number on the losing carrier account.

Cannot be the same as `BillingTelephoneNumber` or be present in the list of ported numbers. This element is not applicable to toll free or off-net port-in orders." }, "WirelessInfo": { - "$ref": "#/components/schemas/WirelessInfoPortinRequestPayload" + "type": "object", + "title": "WirelessInfo", + "description": "Most common for telephone numbers that were formerly wireless. This element is not applicable for toll free port-ins.", + "properties": { + "AccountNumber": { + "type": "string", + "description": "The `AccountNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless." + }, + "PinNumber": { + "type": "string", + "description": "The `PinNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless." + } + } }, "RequestedFocDate": { "type": "string", "description": "Format: ISO8601 encoding such as “2013-05-10T15:14:22Z”, or \"2019-10-31T17:15:00+04:00\".

For all ports, if `RequestedFocDate` is specified, the date portion must be:
- in the future
- after the losing carrier's minimum number of days to port-out
- not on a weekend or U.S. holiday

If `RequestedFocDate` is not specified, the next available FOC date meeting the criteria above will be used. If the Time portion of the `RequestedFocDate` is omitted the port-in order will be activated at the default activation time of 11:30 AM ET. If an activation time other than 11:30 AM ET is desired, that activation time should be included in the `RequestedFocDate`." }, "Subscriber": { - "$ref": "#/components/schemas/SubscriberPortinPayload" + "type": "object", + "title": "Subscriber", + "description": "The `Subscriber` is mandatory for all non-toll free port-in orders. See sub-fields for details.", + "properties": { + "SubscriberType": { + "type": "string", + "description": "The `SubscriberType` is mandatory for all non-toll free port-in orders.", + "enum": [ + "BUSINESS", + "RESIDENTIAL" + ] + }, + "BusinessName": { + "type": "string", + "description": "The `BusinessName` is mandatory for non-toll free port-ins for which the SubscriberType is set to `BUSINESS`. This element is not applicable for toll free port-ins.", + "maxLength": 25 + }, + "FirstName": { + "type": "string", + "description": "The `FirstName` value is applicable to non-toll free port-in orders in which the `SubscriberType` is set to RESIDENTIAL.", + "maxLength": 25 + }, + "MiddleInitial": { + "type": "string", + "description": "The `MiddleInitial` value is applicable to non-toll free port-in orders in which the SubscriberType is set to RESIDENTIAL.", + "maxLength": 1 + }, + "LastName": { + "type": "string", + "description": "The `LastName` value is mandatory for non-toll free port-in orders in which the `SubscriberType` is set to RESIDENTIAL.", + "maxLength": 25 + }, + "ServiceAddress": { + "type": "object", + "title": "ServiceAddress", + "description": "The `ServiceAddress` is mandatory for all non-toll free port-ins.", + "properties": { + "HousePrefix": { + "type": "string", + "description": "The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." + }, + "HouseNumber": { + "type": "string", + "description": "The `HouseNumber` is the street address number of the `ServiceAddress`. `HouseNumber` is mandatory for port-in orders in which the `ServiceAddress` is mandatory." + }, + "HouseSuffix": { + "type": "string", + "description": "The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." + }, + "PreDirectional": { + "type": "string", + "description": "The `PreDirectional` is the non-numeric street name prefix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." + }, + "StreetName": { + "type": "string", + "description": "The `StreetName` is mandatory in cases where the `ServiceAddress` is mandatory." + }, + "StreetSuffix": { + "type": "string", + "description": "The `StreetSuffix` is the street suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." + }, + "PostDirectional": { + "type": "string", + "description": "The `PostDirectional` is the street name post directional of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." + }, + "AddressLine2": { + "type": "string", + "description": "`AddressLine2` is used to specify Unit, Suite, Floor, etc. in the Service Address. `AddressLine2` is optional when not needed to fully specify the `ServiceAddress`." + }, + "City": { + "type": "string", + "description": "`City` is mandatory in cases where the `ServiceAddress` is mandatory." + }, + "StateCode": { + "type": "string", + "description": "`StateCode` is the 2-letter abbreviation of the state of the `ServiceAddress`. `StateCode` is mandatory in cases where the `ServiceAddress` is mandatory. ex: `NC`, `NY`, or `AK`", + "maxLength": 2 + }, + "Zip": { + "type": "string", + "description": "`Zip` is the Zip Code of the `ServiceAddress`. `Zip` is mandatory in cases where the `ServiceAddress` is mandatory." + }, + "PlusFour": { + "type": "string", + "description": "`PlusFour` is the 4 digits that are sometimes suffixed to the Zip Code.", + "maxLength": 4 + }, + "Country": { + "type": "string", + "description": "`Country` is the country of the `ServiceAddress`. This value will be derived from the `StateCode`, so it should generally be omitted." + }, + "ResetAddressFields": { + "type": "boolean", + "description": "The `ResetAddressFields` may be specified in a `PUT` request for a non-toll free port-in order if you would like to remove `ServiceAddress` elements that are not specified in the PUT payload. Default value is `false`." + } + }, + "required": [ + "HouseNumber", + "StreetName", + "City", + "StateCode", + "Zip" + ] + } + }, + "required": [ + "SubscriberType", + "ServiceAddress" + ] }, "PeerId": { "type": "string", @@ -22563,7 +22685,8 @@ }, "LoaAuthorizingPerson": { "type": "string", - "description": "The `LoaAuthorizingPerson` is mandatory for all port-types. This is the first and last names of the person that has authorized the port. The `LoaAuthorizingPerson` value may be up to 15 characters in length." + "description": "The `LoaAuthorizingPerson` is mandatory for all port-types. This is the first and last names of the person that has authorized the port.", + "maxLength": 15 }, "Immediately": { "type": "boolean", @@ -22610,132 +22733,14 @@ "format": "int32", "description": "`SiteId` is mandatory for all port-types. It specifies the identifier of the site (sub-account) that the telephone numbers will be ported into.

You can find the identifier for a site (sub-account) by using `GET /accounts/id/sites`, or by clicking on 'Manage sub-account' for the desired sub-account on the main page of the Bandwidth Dashboard." } - } - } - } - }, - "SubscriberPortinPayload": { - "type": "object", - "title": "Subscriber", - "description": "The `Subscriber` is mandatory for all non-toll free port-in orders. See sub-fields for details.", - "properties": { - "SubscriberType": { - "type": "string", - "description": "The `SubscriberType` is mandatory for all non-toll free port-in orders.

The `SubscriberType` field may have values: `BUSINESS` or `RESIDENTIAL`.", - "enum": [ - "business", - "residential", - "generic" + }, + "required": [ + "BillingTelephoneNumber", + "SiteId", + "ListOfPhoneNumbers", + "LoaAuthorizingPerson", + "Subscriber" ] - }, - "BusinessName": { - "type": "string", - "description": "The `BusinessName` is mandatory for non-toll free port-ins for which the SubscriberType is set to `BUSINESS`. The `BusinessName` may be up to 25 characters in length. This element is not applicable for toll free port-ins." - }, - "FirstName": { - "type": "string", - "description": "The `FirstName` value is applicable to non-toll free port-in orders in which the `SubscriberType` is set to RESIDENTIAL. The `FirstName` is always optional. The `FirstName` may be up to 25 characters in length." - }, - "MiddleInitial": { - "type": "string", - "description": "The `MiddleInitial` value is applicable to non-toll free port-in orders in which the SubscriberType is set to RESIDENTIAL. The `MiddleInitial` is always optional. The `MiddleInitial` is 1 character in length." - }, - "LastName": { - "type": "string", - "description": "The `LastName` value is mandatory for non-toll free port-in orders in which the `SubscriberType` is set to RESIDENTIAL. The `LastName` may be up to 25 characters in length." - }, - "Name": { - "type": "string", - "description": "" - }, - "AccountNumber": { - "type": "string", - "description": "" - }, - "PinNumber": { - "type": "string", - "description": "" - }, - "ServiceAddress": { - "$ref": "#/components/schemas/PortinSubscriberAddress" - } - } - }, - "PortinSubscriberAddress": { - "type": "object", - "title": "ServiceAddress", - "description": "The `ServiceAddress` is mandatory for all non-toll free port-ins. See sub-fields for additional details.", - "properties": { - "HousePrefix": { - "type": "string", - "description": "The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." - }, - "HouseNumber": { - "type": "string", - "description": "The `HouseNumber` is the street address number of the `ServiceAddress`. `HouseNumber` is mandatory for port-in orders in which the `ServiceAddress` is mandatory." - }, - "HouseSuffix": { - "type": "string", - "description": "The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." - }, - "PreDirectional": { - "type": "string", - "description": "The `PreDirectional` is the non-numeric street name prefix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." - }, - "StreetName": { - "type": "string", - "description": "The `StreetName` is mandatory in cases where the `ServiceAddress` is mandatory." - }, - "StreetSuffix": { - "type": "string", - "description": "The `StreetSuffix` is the street suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." - }, - "PostDirectional": { - "type": "string", - "description": "The `PostDirectional` is the street name post directional of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." - }, - "AddressLine2": { - "type": "string", - "description": "`AddressLine2` is used to specify Unit, Suite, Floor, etc. in the Service Address. `AddressLine2` is optional when not needed to fully specify the `ServiceAddress`." - }, - "City": { - "type": "string", - "description": "`City` is mandatory in cases where the `ServiceAddress` is mandatory." - }, - "StateCode": { - "type": "string", - "description": "`StateCode` is the 2-letter abbreviation of the state of the `ServiceAddress`. `StateCode` is mandatory in cases where the `ServiceAddress` is mandatory. ex: `NC`, `NY`, or `AK`" - }, - "Zip": { - "type": "string", - "description": "`Zip` is the Zip Code of the `ServiceAddress`. `Zip` is mandatory in cases where the `ServiceAddress` is mandatory." - }, - "PlusFour": { - "type": "string", - "description": "`PlusFour` is the 4 digits that are sometimes suffixed to the Zip Code." - }, - "Country": { - "type": "string", - "description": "`Country` is the country of the `ServiceAddress`. This value will be derived from the `StateCode`, so it should generally be omitted." - }, - "ResetAddressFields": { - "type": "boolean", - "description": "The `ResetAddressFields` may be specified in a `PUT` request for a non-toll free port-in order if you would like to remove `ServiceAddress` elements that are not specified in the PUT payload. Default value is `false`." - } - } - }, - "WirelessInfoPortinRequestPayload": { - "type": "object", - "title": "WirelessInfo", - "description": "Most common for telephone numbers that were formerly wireless. This element is not applicable for toll free port-ins.", - "properties": { - "AccountNumber": { - "type": "string", - "description": "The `AccountNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless." - }, - "PinNumber": { - "type": "string", - "description": "The `PinNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless." } } }, From 08a000975ef235d7ad22e7f6d05723a34cfcfe69 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Sat, 2 Jul 2022 21:58:27 +0300 Subject: [PATCH 03/20] Porting - split request schema to 4 types --- site/specs-temp/numbers.json | 631 +++++++++++++++++++++-------------- 1 file changed, 384 insertions(+), 247 deletions(-) diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index 172e45091..6fc94a21d 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -2920,7 +2920,7 @@ } } }, - "post" : { + "post": { "tags": [ "/accounts", "Porting" @@ -3038,7 +3038,7 @@ } } }, - "put" : { + "put": { "tags": [ "/accounts", "Porting" @@ -3106,8 +3106,7 @@ } } }, - - "/accounts/{accountId}/csrs/{csrsId}/notes": { + "/accounts/{accountId}/csrs/{csrsId}/notes": { "get": { "tags": [ "/accounts" @@ -3295,7 +3294,6 @@ } } }, - "/accounts/{accountId}/discnumbers": { "get": { "tags": [ @@ -10215,7 +10213,20 @@ } }, "schema": { - "$ref": "#/components/schemas/LnpOrderRequest" + "oneOf": [ + { + "$ref": "#/components/schemas/OnNetLnpOrderRequest" + }, + { + "$ref": "#/components/schemas/TollFreeLnpOrderRequest" + }, + { + "$ref": "#/components/schemas/OffNetLnpOrderRequest" + }, + { + "$ref": "#/components/schemas/InternalLnpOrderRequest" + } + ] } } } @@ -22518,228 +22529,217 @@ } } }, - "LnpOrderRequest": { + "LnpOrderBasic": { "type": "object", "properties": { - "LnpOrder": { + "CustomerOrderId": { + "type": "string", + "description": "The `CustomerOrderId` is an optional field that may be provided by the customer and will remain with the order. The value is opaque to Bandwidth.", + "format": "Only alphanumeric values, dashes and spaces", + "maxLength": 40 + }, + "ProcessingStatus": { + "type": "string", + "enum": [ + "DRAFT" + ], + "description": "Including `ProcessingStatus` with a value of DRAFT allows you to create a port-in request, but not process the request. This is useful if you wish to add items to the order over a period of time and submit once you have the order setup the way you want. Note, however, that draft orders that have not been updated in a couple of days are automatically deleted. Removal of stagnant draft orders is performed so that telephone numbers are not tied up in these orders, preventing them from being included in other orders.

Very little validation is performed while an order is in draft state. Omitting `ProcessingStatus` causes the port-in to be validated and, if correct, processed right away. The full validation is performed on the order when you change the ProcessingStatus to 'SUBMITTED' by performing a PUT request on the order.

All toll free telephone numbers provided will be validated (even in draft state) to ensure\nthat they are portable, and to allow you to separate telephone numbers into separate port-ins\nbased on the RespOrg that they are being ported from.

" + }, + "RequestedFocDate": { + "type": "string", + "description": "Format: ISO8601 encoding such as “2013-05-10T15:14:22Z”, or \"2019-10-31T17:15:00+04:00\".

For all ports, if `RequestedFocDate` is specified, the date portion must be:
- in the future
- after the losing carrier's minimum number of days to port-out
- not on a weekend or U.S. holiday

If `RequestedFocDate` is not specified, the next available FOC date meeting the criteria above will be used. If the Time portion of the `RequestedFocDate` is omitted the port-in order will be activated at the default activation time of 11:30 AM ET. If an activation time other than 11:30 AM ET is desired, that activation time should be included in the `RequestedFocDate`." + }, + "PeerId": { + "type": "string", + "description": "`PeerId` specifies the numeric identifier of the SIP-peer (Location) that the telephone numbers will be ported into.

You can find the identifier for a SIP-peer (location) by using `GET /accounts/id/sites/id/sippeers`, or by clicking on 'Accounts' on the upper right of the [Bandwidth Dashboard](Https://dashboard.bandwidth.com), then clicking 'Locations' on the navigation bar. The SIP-peer (location) identifiers are listed next to each location name. If `PeerId` is omitted, the SIP-peer (location) designated as the 'default location' for that site (sub-account) will be used." + }, + "LoaAuthorizingPerson": { + "type": "string", + "description": "This is the first and last names of the person that has authorized the port.", + "maxLength": 15 + }, + "ListOfPhoneNumbers": { + "type": "array", + "description": "`ListOfPhoneNumbers` is an array of `PhoneNumber`. At least one `PhoneNumber` must be provided.", + "items": { + "type": "object", + "properties": { + "PhoneNumber": { + "description": "One or more phone numbers is required.
Use a `` tag for each phone number in the `` list.", + "format": "Ten digit phone number with no dots or dashes", + "type": "string" + } + } + } + }, + "SiteId": { + "type": "integer", + "format": "int32", + "description": "`SiteId` specifies the identifier of the site (sub-account) that the telephone numbers will be ported into.

You can find the identifier for a site (sub-account) by using `GET /accounts/id/sites`, or by clicking on 'Manage sub-account' for the desired sub-account on the main page of the Bandwidth Dashboard." + } + }, + "required": [ + "SiteId", + "ListOfPhoneNumbers", + "LoaAuthorizingPerson" + ] + }, + "LnpOrderAdditionalFields": { + "type": "object", + "properties": { + "BillingTelephoneNumber": { + "type": "string", + "description": "The `BillingTelephoneNumber` is the primary telephone number associated with the invoice that the subscriber gets from the losing carrier. For wireline port-in, the BillingTelephoneNumber is typically the telephone number being ported in." + }, + "WirelessInfo": { "type": "object", + "title": "WirelessInfo", + "description": "Most common for telephone numbers that were formerly wireless.", "properties": { - "CustomerOrderId": { + "AccountNumber": { "type": "string", - "description": "The `CustomerOrderId` is an optional field that may be provided by the customer and will remain with the order. The value is opaque to Bandwidth.", - "format": "Only alphanumeric values, dashes and spaces are allowed", - "maxLength": 40 + "description": "The `AccountNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless." }, - "ProcessingStatus": { + "PinNumber": { "type": "string", - "enum": [ - "DRAFT" - ], - "description": "Including `ProcessingStatus` with a value of DRAFT allows you to create a port-in request, but not process the request. This is useful if you wish to add items to the order over a period of time and submit once you have the order setup the way you want. Note, however, that draft orders that have not been updated in a couple of days are automatically deleted. Removal of stagnant draft orders is performed so that telephone numbers are not tied up in these orders, preventing them from being included in other orders.

Very little validation is performed while an order is in draft state. Omitting `ProcessingStatus` causes the port-in to be validated and, if correct, processed right away. The full validation is performed on the order when you change the ProcessingStatus to 'SUBMITTED' by performing a PUT request on the order.

All toll free telephone numbers provided will be validated (even in draft state) to ensure\nthat they are portable, and to allow you to separate telephone numbers into separate port-ins\nbased on the RespOrg that they are being ported from.

" + "description": "The `PinNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless." + } + } + }, + "Subscriber": { + "oneOf": [ + { + "$ref": "#/components/schemas/SubscriberBusiness" }, - "BillingTelephoneNumber": { - "type": "string", - "description": "The `BillingTelephoneNumber` is the primary telephone number associated with the invoice that the subscriber gets from the losing carrier. For wireline port-in, the BillingTelephoneNumber is typically the telephone number being ported in. This element is not applicable for toll free port-ins, but mandatory for non-toll free port-ins." + { + "$ref": "#/components/schemas/SubscriberResidential" + } + ] + }, + "Triggered": { + "type": "boolean", + "description": "The `Triggered` field must be set to `true` if you want an activation time other than the 11:30 AM ET default. The desired activation time can then be specified in the time portion of the `RequestedFocDate`." + }, + "AlternateSpid": { + "type": "string", + "description": "Even though the telephone numbers are being ported into Bandwidth’s SPID, some of Bandwidth’s wholesale customers have an alternate SPID that is used to identify the telephone number with that customer." + } + }, + "required": [ + "BillingTelephoneNumber", + "Subscriber" + ] + }, + "TollFreeLnpOrderRequest": { + "type": "object", + "title": "Toll free Lnp request", + "description": "Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Currently all toll free port-ins are handled manually by Bandwidth’s Local Number Portability team. But Bandwidth is in the process of automating portions of toll free porting, with a goal of eventually automating the entire process.", + "properties": { + "LnpOrder": { + "allOf": [ + { + "$ref": "#/components/schemas/LnpOrderBasic" + } + ] + } + } + }, + "OnNetLnpOrderRequest": { + "type": "object", + "title": "On-net Lnp request", + "properties": { + "LnpOrder": { + "allOf": [ + { + "$ref": "#/components/schemas/LnpOrderBasic" }, - "NewBillingTelephoneNumber": { - "type": "string", - "description": "This field is used to specify a new billing telephone number on the losing carrier account.

Cannot be the same as `BillingTelephoneNumber` or be present in the list of ported numbers. This element is not applicable to toll free or off-net port-in orders." + { + "$ref": "#/components/schemas/LnpOrderAdditionalFields" }, - "WirelessInfo": { + { "type": "object", - "title": "WirelessInfo", - "description": "Most common for telephone numbers that were formerly wireless. This element is not applicable for toll free port-ins.", "properties": { - "AccountNumber": { + "NewBillingTelephoneNumber": { "type": "string", - "description": "The `AccountNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless." + "description": "This field is used to specify a new billing telephone number on the losing carrier account.

Cannot be the same as `BillingTelephoneNumber` or be present in the list of ported numbers." }, - "PinNumber": { + "PartialPort": { "type": "string", - "description": "The `PinNumber` is sometimes required to authorize the port-out from the losing carrier. This is most common for telephone numbers that were formerly wireless." + "description": "The `PartialPort` must be set to `true` if the intent is to **NOT** port all of the telephone numbers associated with the `BillingTelephoneNumber`.

If PartialPort is omitted or false, and the `ListOfPhoneNumbers` does not include all of the telephone numbers associated with the `BillingTelephoneNumber`, the port-in will be rejected.

PartialPort is applicable only to on-net port-types." + }, + "BillingType": { + "type": "string", + "description": "" + }, + "AutoActivation": { + "type": "string", + "description": "" + }, + "TnAttributes": { + "type": "array", + "description": "The `TnAttributes` field specifies line attributes that will apply to the ported in telephone numbers. If present, `TnAttributes` may have a value of `PROTECTED`.", + "items": { + "$ref": "#/components/schemas/TnAttribute" + } } } + } + ] + } + } + }, + "InternalLnpOrderRequest": { + "type": "object", + "title": "On-net Lnp request", + "properties": { + "LnpOrder": { + "allOf": [ + { + "$ref": "#/components/schemas/LnpOrderBasic" }, - "RequestedFocDate": { - "type": "string", - "description": "Format: ISO8601 encoding such as “2013-05-10T15:14:22Z”, or \"2019-10-31T17:15:00+04:00\".

For all ports, if `RequestedFocDate` is specified, the date portion must be:
- in the future
- after the losing carrier's minimum number of days to port-out
- not on a weekend or U.S. holiday

If `RequestedFocDate` is not specified, the next available FOC date meeting the criteria above will be used. If the Time portion of the `RequestedFocDate` is omitted the port-in order will be activated at the default activation time of 11:30 AM ET. If an activation time other than 11:30 AM ET is desired, that activation time should be included in the `RequestedFocDate`." + { + "$ref": "#/components/schemas/LnpOrderAdditionalFields" }, - "Subscriber": { + { "type": "object", - "title": "Subscriber", - "description": "The `Subscriber` is mandatory for all non-toll free port-in orders. See sub-fields for details.", "properties": { - "SubscriberType": { + "NewBillingTelephoneNumber": { "type": "string", - "description": "The `SubscriberType` is mandatory for all non-toll free port-in orders.", - "enum": [ - "BUSINESS", - "RESIDENTIAL" - ] - }, - "BusinessName": { - "type": "string", - "description": "The `BusinessName` is mandatory for non-toll free port-ins for which the SubscriberType is set to `BUSINESS`. This element is not applicable for toll free port-ins.", - "maxLength": 25 + "description": "This field is used to specify a new billing telephone number on the losing carrier account.

Cannot be the same as `BillingTelephoneNumber` or be present in the list of ported numbers." }, - "FirstName": { + "PartialPort": { "type": "string", - "description": "The `FirstName` value is applicable to non-toll free port-in orders in which the `SubscriberType` is set to RESIDENTIAL.", - "maxLength": 25 + "description": "The `PartialPort` must be set to `true` if the intent is to **NOT** port all of the telephone numbers associated with the `BillingTelephoneNumber`.

If PartialPort is omitted or false, and the `ListOfPhoneNumbers` does not include all of the telephone numbers associated with the `BillingTelephoneNumber`, the port-in will be rejected.

PartialPort is applicable only to on-net port-types." }, - "MiddleInitial": { - "type": "string", - "description": "The `MiddleInitial` value is applicable to non-toll free port-in orders in which the SubscriberType is set to RESIDENTIAL.", - "maxLength": 1 - }, - "LastName": { - "type": "string", - "description": "The `LastName` value is mandatory for non-toll free port-in orders in which the `SubscriberType` is set to RESIDENTIAL.", - "maxLength": 25 + "Immediately": { + "type": "boolean", + "description": "Including `Immediately` with a value of `true` will cause an Internal port-in to complete as soon as possible, without requiring a scheduled activation time.

`Immediately` has no meaning for port types other than Internal." }, - "ServiceAddress": { - "type": "object", - "title": "ServiceAddress", - "description": "The `ServiceAddress` is mandatory for all non-toll free port-ins.", - "properties": { - "HousePrefix": { - "type": "string", - "description": "The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." - }, - "HouseNumber": { - "type": "string", - "description": "The `HouseNumber` is the street address number of the `ServiceAddress`. `HouseNumber` is mandatory for port-in orders in which the `ServiceAddress` is mandatory." - }, - "HouseSuffix": { - "type": "string", - "description": "The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." - }, - "PreDirectional": { - "type": "string", - "description": "The `PreDirectional` is the non-numeric street name prefix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." - }, - "StreetName": { - "type": "string", - "description": "The `StreetName` is mandatory in cases where the `ServiceAddress` is mandatory." - }, - "StreetSuffix": { - "type": "string", - "description": "The `StreetSuffix` is the street suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." - }, - "PostDirectional": { - "type": "string", - "description": "The `PostDirectional` is the street name post directional of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." - }, - "AddressLine2": { - "type": "string", - "description": "`AddressLine2` is used to specify Unit, Suite, Floor, etc. in the Service Address. `AddressLine2` is optional when not needed to fully specify the `ServiceAddress`." - }, - "City": { - "type": "string", - "description": "`City` is mandatory in cases where the `ServiceAddress` is mandatory." - }, - "StateCode": { - "type": "string", - "description": "`StateCode` is the 2-letter abbreviation of the state of the `ServiceAddress`. `StateCode` is mandatory in cases where the `ServiceAddress` is mandatory. ex: `NC`, `NY`, or `AK`", - "maxLength": 2 - }, - "Zip": { - "type": "string", - "description": "`Zip` is the Zip Code of the `ServiceAddress`. `Zip` is mandatory in cases where the `ServiceAddress` is mandatory." - }, - "PlusFour": { - "type": "string", - "description": "`PlusFour` is the 4 digits that are sometimes suffixed to the Zip Code.", - "maxLength": 4 - }, - "Country": { - "type": "string", - "description": "`Country` is the country of the `ServiceAddress`. This value will be derived from the `StateCode`, so it should generally be omitted." - }, - "ResetAddressFields": { - "type": "boolean", - "description": "The `ResetAddressFields` may be specified in a `PUT` request for a non-toll free port-in order if you would like to remove `ServiceAddress` elements that are not specified in the PUT payload. Default value is `false`." - } - }, - "required": [ - "HouseNumber", - "StreetName", - "City", - "StateCode", - "Zip" - ] - } - }, - "required": [ - "SubscriberType", - "ServiceAddress" - ] - }, - "PeerId": { - "type": "string", - "description": "`PeerId` specifies the numeric identifier of the SIP-peer (Location) that the telephone numbers will be ported into.

You can find the identifier for a SIP-peer (location) by using `GET /accounts/id/sites/id/sippeers`, or by clicking on 'Accounts' on the upper right of the [Bandwidth Dashboard](Https://dashboard.bandwidth.com), then clicking 'Locations' on the navigation bar. The SIP-peer (location) identifiers are listed next to each location name. If `PeerId` is omitted, the SIP-peer (location) designated as the 'default location' for that site (sub-account) will be used." - }, - "PartialPort": { - "type": "string", - "description": "The `PartialPort` must be set to `true` if the intent is to **NOT** port all of the telephone numbers associated with the `BillingTelephoneNumber`.

If PartialPort is omitted or false, and the `ListOfPhoneNumbers` does not include all of the telephone numbers associated with the `BillingTelephoneNumber`, the port-in will be rejected.

PartialPort is applicable only to on-net port-types. This element is not applicable to toll free or off-net port-in orders." - }, - "LoaAuthorizingPerson": { - "type": "string", - "description": "The `LoaAuthorizingPerson` is mandatory for all port-types. This is the first and last names of the person that has authorized the port.", - "maxLength": 15 - }, - "Immediately": { - "type": "boolean", - "description": "Including `Immediately` with a value of `true` will cause an Internal port-in to complete as soon as possible, without requiring a scheduled activation time.

`Immediately` has no meaning for port types other than Internal." - }, - "Triggered": { - "type": "boolean", - "description": "The `Triggered` field must be set to `true` if you want an activation time other than the 11:30 AM ET default. The desired activation time can then be specified in the time portion of the `RequestedFocDate`. Triggered activation is not yet supported for toll free port-in orders." - }, - "BillingType": { - "type": "string", - "description": "" - }, - "AutoActivation": { - "type": "string", - "description": "" - }, - "TnAttributes": { - "type": "array", - "description": "The `TnAttributes` field specifies line attributes that will apply to the ported in telephone numbers. If present, `TnAttributes` may have a value of `PROTECTED`. This element is not applicable for off-net or toll free port-types.", - "items": { - "$ref": "#/components/schemas/TnAttribute" - } - }, - "AlternateSpid": { - "type": "string", - "description": "Even though the telephone numbers are being ported into Bandwidth’s SPID, some of Bandwidth’s wholesale customers have an alternate SPID that is used to identify the telephone number with that customer. This element is not applicable for toll free port-ins." - }, - "ListOfPhoneNumbers": { - "type": "array", - "description": "`ListOfPhoneNumbers` is an array of `PhoneNumber`. At least one `PhoneNumber` must be provided for all port-types.", - "items": { - "type": "object", - "properties": { - "PhoneNumber": { - "description": "Ten digit phone number with no dots or dashes. One or more is required.
Use a `` tag for each phone number in the `` list.", - "type": "string" + "TnAttributes": { + "type": "array", + "description": "The `TnAttributes` field specifies line attributes that will apply to the ported in telephone numbers. If present, `TnAttributes` may have a value of `PROTECTED`.", + "items": { + "$ref": "#/components/schemas/TnAttribute" } } } + } + ] + } + } + }, + "OffNetLnpOrderRequest": { + "type": "object", + "title": "Off-net Lnp request", + "properties": { + "LnpOrder": { + "allOf": [ + { + "$ref": "#/components/schemas/LnpOrderBasic" }, - "SiteId": { - "type": "integer", - "format": "int32", - "description": "`SiteId` is mandatory for all port-types. It specifies the identifier of the site (sub-account) that the telephone numbers will be ported into.

You can find the identifier for a site (sub-account) by using `GET /accounts/id/sites`, or by clicking on 'Manage sub-account' for the desired sub-account on the main page of the Bandwidth Dashboard." + { + "$ref": "#/components/schemas/LnpOrderAdditionalFields" } - }, - "required": [ - "BillingTelephoneNumber", - "SiteId", - "ListOfPhoneNumbers", - "LoaAuthorizingPerson", - "Subscriber" ] } } @@ -22755,6 +22755,145 @@ } } }, + "SubscriberBusiness": { + "type": "object", + "title": "BUSINESS", + "properties": { + "SubscriberType": { + "type": "string", + "enum": [ + "BUSINESS" + ] + }, + "BusinessName": { + "type": "string", + "maxLength": 25 + }, + "ServiceAddress": { + "$ref": "#/components/schemas/PortinSubscriberServiceAddress" + } + }, + "required": [ + "SubscriberType", + "ServiceAddress", + "BusinessName" + ] + }, + "SubscriberResidential": { + "type": "object", + "title": "RESIDENTIAL", + "properties": { + "SubscriberType": { + "type": "string", + "enum": [ + "RESIDENTIAL" + ] + }, + "FirstName": { + "type": "string", + "maxLength": 25 + }, + "MiddleInitial": { + "type": "string", + "maxLength": 1 + }, + "LastName": { + "type": "string", + "maxLength": 25 + }, + "ServiceAddress": { + "$ref": "#/components/schemas/PortinSubscriberServiceAddress" + } + }, + "required": [ + "SubscriberType", + "ServiceAddress", + "FirstName", + "LastName" + ] + }, + "PortinSubscriberServiceAddress": { + "type": "object", + "title": "ServiceAddress", + "properties": { + "HousePrefix": { + "type": "string", + "description": "The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." + }, + "HouseNumber": { + "type": "string", + "description": "The `HouseNumber` is the street address number of the `ServiceAddress`. `HouseNumber` is mandatory for port-in orders in which the `ServiceAddress` is mandatory." + }, + "HouseSuffix": { + "type": "string", + "description": "The `HouseSuffix` is the non-numeric address number suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." + }, + "PreDirectional": { + "type": "string", + "description": "The `PreDirectional` is the non-numeric street name prefix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." + }, + "StreetName": { + "type": "string", + "description": "The `StreetName` is mandatory in cases where the `ServiceAddress` is mandatory." + }, + "StreetSuffix": { + "type": "string", + "description": "The `StreetSuffix` is the street suffix of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." + }, + "PostDirectional": { + "type": "string", + "description": "The `PostDirectional` is the street name post directional of the `ServiceAddress`. This element is optional when not needed to fully specify the `ServiceAddress`." + }, + "AddressLine2": { + "type": "string", + "description": "`AddressLine2` is used to specify Unit, Suite, Floor, etc. in the Service Address. `AddressLine2` is optional when not needed to fully specify the `ServiceAddress`." + }, + "City": { + "type": "string", + "description": "`City` is mandatory in cases where the `ServiceAddress` is mandatory." + }, + "StateCode": { + "type": "string", + "description": "`StateCode` is the 2-letter abbreviation of the state of the `ServiceAddress`. `StateCode` is mandatory in cases where the `ServiceAddress` is mandatory. ex: `NC`, `NY`, or `AK`", + "maxLength": 2 + }, + "Zip": { + "type": "string", + "description": "`Zip` is the Zip Code of the `ServiceAddress`. `Zip` is mandatory in cases where the `ServiceAddress` is mandatory." + }, + "PlusFour": { + "type": "string", + "description": "`PlusFour` is the 4 digits that are sometimes suffixed to the Zip Code.", + "maxLength": 4 + }, + "Country": { + "type": "string", + "description": "`Country` is the country of the `ServiceAddress`. This value will be derived from the `StateCode`, so it should generally be omitted." + } + }, + "required": [ + "HouseNumber", + "StreetName", + "City", + "StateCode", + "Zip" + ] + }, + "PortinPutSubscriberServiceAddress": { + "allOf": [ + { + "$ref": "#/components/schemas/PortinSubscriberServiceAddress" + } + ], + "type": "object", + "title": "ServiceAddress", + "properties": { + "ResetAddressFields": { + "type": "boolean", + "description": "The `ResetAddressFields` may be specified in a `PUT` request for a non-toll free port-in order if you would like to remove `ServiceAddress` elements that are not specified in the PUT payload. Default value is `false`." + } + } + }, "FileMetaData": { "type": "object", "properties": { @@ -24393,156 +24532,154 @@ "CsrGetResponse": { "type": "object", "properties": { - "CustomerOrderId" : { + "CustomerOrderId": { "type": "string" }, - "LastModifiedBy" : { + "LastModifiedBy": { "type": "string" }, - "OrderCreateDate" : { + "OrderCreateDate": { "type": "string" }, - "OrderId" : { + "OrderId": { "type": "string" }, - "LastModifiedDate" : { + "LastModifiedDate": { "type": "string" }, - "WorkingOrBillingTelephoneNumber" : { + "WorkingOrBillingTelephoneNumber": { "type": "string" }, - "WorkingTelephoneNumber" : { + "WorkingTelephoneNumber": { "type": "string" }, - "BillingTelephoneNumber" : { + "BillingTelephoneNumber": { "type": "string" }, - "CustomerName" : { + "CustomerName": { "type": "string" }, - "AuthorizingPersonName" : { + "AuthorizingPersonName": { "type": "string" }, - "AccountNumber" : { + "AccountNumber": { "type": "string" }, - "WorkingTelephoneNumbersOnAccount" : { + "WorkingTelephoneNumbersOnAccount": { "type": "object", "properties": { - "TelephoneNumber" : { + "TelephoneNumber": { "type": "array" } } }, - "CsrServiceAddress" : { + "CsrServiceAddress": { "$ref": "#/components/schemas/Address" }, - "AccountTelephoneNumber" : { + "AccountTelephoneNumber": { "type": "string" }, - "EndUserName" : { + "EndUserName": { "type": "string" }, - "AuthorizingUserName" : { + "AuthorizingUserName": { "type": "string" }, - "CustomerCode" : { + "CustomerCode": { "type": "string" }, - "EndUserPIN" : { + "EndUserPIN": { "type": "string" }, - "EndUserPassword" : { + "EndUserPassword": { "type": "string" }, - "AddressLine1" : { + "AddressLine1": { "type": "string" }, - "City" : { + "City": { "type": "string" }, - "State" : { + "State": { "type": "string" }, - "ZIPCode" : { + "ZIPCode": { "type": "string" }, - "TypeOfService" : { + "TypeOfService": { "type": "string" }, - "Status" : { + "Status": { "type": "string" } } }, - - - "Csr": { + "Csr": { "type": "object", "properties": { - "WorkingOrBillingTelephoneNumber" : { + "WorkingOrBillingTelephoneNumber": { "type": "string" }, - "WorkingTelephoneNumber" : { + "WorkingTelephoneNumber": { "type": "string" }, - "BillingTelephoneNumber" : { + "BillingTelephoneNumber": { "type": "string" }, - "CustomerName" : { + "CustomerName": { "type": "string" }, - "AuthorizingPersonName" : { + "AuthorizingPersonName": { "type": "string" }, - "AccountNumber" : { + "AccountNumber": { "type": "string" }, - "WorkingTelephoneNumbersOnAccount" : { + "WorkingTelephoneNumbersOnAccount": { "type": "object", "properties": { - "TelephoneNumber" : { + "TelephoneNumber": { "type": "array" } } }, - "CsrServiceAddress" : { + "CsrServiceAddress": { "$ref": "#/components/schemas/Address" }, - "AccountTelephoneNumber" : { + "AccountTelephoneNumber": { "type": "string" }, - "EndUserName" : { + "EndUserName": { "type": "string" }, - "AuthorizingUserName" : { + "AuthorizingUserName": { "type": "string" }, - "CustomerCode" : { + "CustomerCode": { "type": "string" }, - "EndUserPIN" : { + "EndUserPIN": { "type": "string" }, - "EndUserPassword" : { + "EndUserPassword": { "type": "string" }, - "AddressLine1" : { + "AddressLine1": { "type": "string" }, - "City" : { + "City": { "type": "string" }, - "State" : { + "State": { "type": "string" }, - "ZIPCode" : { + "ZIPCode": { "type": "string" }, - "TypeOfService" : { + "TypeOfService": { "type": "string" }, - "Status" : { + "Status": { "type": "string" } } From 2ada46da17bd2a06f77ab03706584446ad1fa183 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Mon, 4 Jul 2022 17:37:48 +0300 Subject: [PATCH 04/20] Porting - bulk portins updates * add reference to bulk portins and lnp checker * move schema descriptions from the guide to api reference * uniform guides ids for porting --- site/docs/numbers/porting/bulkportins.mdx | 37 +--- site/docs/numbers/porting/cancelPortin.mdx | 6 +- site/docs/numbers/porting/lnpChecker.mdx | 42 +--- site/docs/numbers/porting/loaUpload.mdx | 4 +- site/docs/numbers/porting/portingNumbers.mdx | 21 +- site/docs/numbers/porting/portingTypes.mdx | 4 +- site/docs/numbers/porting/updatePortin.mdx | 4 +- site/sidebar.js | 2 +- site/specs-temp/numbers.json | 203 +++++++++++++++++-- 9 files changed, 207 insertions(+), 116 deletions(-) diff --git a/site/docs/numbers/porting/bulkportins.mdx b/site/docs/numbers/porting/bulkportins.mdx index 59c38e39b..afa536f5e 100644 --- a/site/docs/numbers/porting/bulkportins.mdx +++ b/site/docs/numbers/porting/bulkportins.mdx @@ -1,7 +1,7 @@ --- -id: bulkportins +id: bulkPortins title: Manage bulk port-in orders -slug: /numbers/guides/bulkportins +slug: /numbers/guides/porting/bulkPortins description: How to manage bulk port-in order using the Bandwidth API keywords: - bandwidth @@ -49,36 +49,3 @@ telephone numbers are portable, child port-in orders are created to handle the a A bulk port-in order may have one of 3 terminal processing statuses: COMPLETED, CANCELLED, or PARTIAL, which are just an aggregation of the child order statuses. An order in a “terminal” state will never transition to any other processing status (terminal or not). A bulk port-in order goes to a terminal status automatically as soon as the last of its associated child port-ins transfers to terminal status (COMPLETE or CANCELLED). The resulting terminal processing status of the bulk port-in order depends on statuses of associated child port-ins: COMPLETED - when all child port-ins are in COMPLETE status, CANCELLED - when all child port-ins are in CANCELLED status, PARTIAL - when there is a mix of CANCELLED and COMPLETE child port-in statuses. The following table describes parameters for the bulk port-in API. All parameters except for the URL parameter "accountId" are optional in the bulk port-in, although the rules for individual child port-ins described in the [/portins](/apis/numbers/#operation/ListPortins) API still apply to the child port-ins that make up the bulk port-in. Enforcement of required fields in the child port-ins occurs when the bulk port-in is submitted (i.e. changed from a DRAFT status to IN_PROGRESS). Only fields that you wish to use as defaults for all of the child port-in orders should be included in the bulk port-in order. The child port-ins are also created in DRAFT status, allowing you to update fields that need to be different for each child order before the child orders are submitted. - - -| Parameter | Description | -|:----------------------------|:----------------------------------------| -| `accountId (URL Parameter)` | The account ID for porting the numbers. | -| `CustomerOrderId` | Internal customer order id for tracking the order. This can be any alphanumeric string. | -| `RequestedFocDate` | If present this will specify the date and time that the port-in is requested to happen. The actual time and date is subject to negotiation with the losing carriers. Format is ISO8601 encoding of ZULU/UTC/GMT such as “2013-05-10T15:14:22Z”.| -| `AlternateSpid` | Unique customer AltSPID to be applied to the port-in requests. Can be changed only for DRAFT bulk port-in. | -| `BillingTelephoneNumber (BTN)` | Account or Billing telephone number for order. This will be unusual for bulk port-in requests that are expected to decompose into port-in requests from multiple carriers, because the value will be different for each losing carrier. | -| `SubscriberType` | (BUSINESS, RESIDENTIAL) If residential, order will be rejected if a BusinessName is entered. | -| `BusinessName` | Subscriber business name. | -| `FirstName` | Subscriber first name. | -| `MiddleInitial` | Subscriber middle initial. | -| `LastName` | Subscriber last name. | -| `HouseNumber` | Street address number. | -| `HousePrefix` | Street address number prefix. | -| `HouseSuffix` | Street address number suffix. | -| `PreDirectional` | Street address pre-directional. | -| `StreetName` | Street name. | -| `StreetSuffix` | Street suffix. | -| `PostDirectional` | Street address post directional. | -| `AddressLine2` | Put unit, suite, floor, etc. here. | -| `City` | City. | -| `StateCode` | Two letter state code. | -| `Zip` | Zip code. | -| `PlusFour` | Zip + 4 value.| -| `Country` | 3 letter country code. | -| `LoaAuthorizingPerson` | First and last name of person who authorized LOA. | -| `AccountNumber` | Account number associated with the account on the losing carrier, often required for wireless ports, or enterprise ports. This will be unusual for bulk port-in requests that are expected to decompose into port-in requests from multiple carriers. | -| `PinNumber` | PIN Number, often required for wireless ports. | -| `siteid` | This is the Site / Sub-Account ID made visible in the /accounts/{accountId}/sites API call | -| `PeerId` | This is the SIP Peer / Location ID made visible in the /accounts/{accountId}/sites/{siteId}/sipPeers API call | -| `TnAttributes` | Attributes to be assigned to the telephone number. Optional parameter. Possible values - "Protected" | \ No newline at end of file diff --git a/site/docs/numbers/porting/cancelPortin.mdx b/site/docs/numbers/porting/cancelPortin.mdx index 5cfb37683..ff7324f30 100644 --- a/site/docs/numbers/porting/cancelPortin.mdx +++ b/site/docs/numbers/porting/cancelPortin.mdx @@ -1,8 +1,8 @@ --- id: cancelPortin -title: Porting Numbers -slug: /numbers/guides/portcancelPortiningNumbers -description: How to port numbers using the Bandwidth API +title: Cancel Portin +slug: /numbers/guides/porting/cancelPortin +description: How to cancel portin request keywords: - bandwidth - numbers diff --git a/site/docs/numbers/porting/lnpChecker.mdx b/site/docs/numbers/porting/lnpChecker.mdx index 84f454780..287f7d220 100644 --- a/site/docs/numbers/porting/lnpChecker.mdx +++ b/site/docs/numbers/porting/lnpChecker.mdx @@ -1,8 +1,8 @@ --- id: lnpChecker title: Lnp Checker -slug: /numbers/porting/lnpChecker -description: How to port numbers using the Bandwidth API +slug: /numbers/guides/porting/lnpChecker +description: How to check number(s) portability keywords: - bandwidth - numbers @@ -34,44 +34,6 @@ export const Highlight = ({children, color}) => ( ); -The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. - -Bandwidth supports two APIs for porting numbers to Bandwidth: -- /portins -- /bulkPortins - -The `/portins` API allows a set of TNs to be ported in, provided that the set of TNs meets the criteria below. -TNs can be ported in a single `/portins` request if all of the following are true: - -1. They all have the same Port Type -2. They all have the same losing carrier -3. They are all associated with the same billing TN and Service Address - -There are also a number of reasons why a TN may not be able to be ported in: - -* The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. -* The TN is an off-net TN and the account is configured to support tier zero (on-net) only. -* The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with. -* The TN is already being processed in another active port-in order. -* The Bandwidth account has not been enabled for porting. -Otherwise the user must separate the TNs into individual `/portins` requests. - -The `/lnpchecker` API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs. -The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. -Terminology - - -| Term | Description | | -|:----------------------------------|:-------------------------------------------------------| -| Port Type | A categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. See the POST operation for more information | -| On-Net | TNs that belong to a rate center covered by Bandwidth are referred to as on-net TNs | -| Off-Net | TNs that belong to a rate center covered by a Bandwidth partner are refered to as off-net TNs | -| Automated | If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention | -| Manual | If the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team | -| Internal | TNs that are being moved from one Bandwidth account to another Bandwidth account are referred to as internal ports. Internal ports are handled automatically | -| Losing carrier | The carrier from which the TN(s) is being ported | - - ## Checking for Portability A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the `/accounts/{accountId}/lnpChecker` API endpoint. diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx index b657a1e8e..a62bdcced 100644 --- a/site/docs/numbers/porting/loaUpload.mdx +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -1,8 +1,8 @@ --- id: loaUpload title: LOA Upload -slug: /numbers/guides/loaUpload -description: How to port numbers using the Bandwidth API +slug: /numbers/guides/porting/loaUpload +description: How to upload Letter of Authorization (LOA) for portin request keywords: - bandwidth - numbers diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 94f39824d..f68eef6d5 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -1,7 +1,7 @@ --- id: portingNumbers title: Create Portin -slug: /numbers/guides/portingNumbers +slug: /numbers/guides/porting/portingNumbers description: How to port numbers using the Bandwidth API keywords: - bandwidth @@ -33,10 +33,6 @@ export const Highlight = ({children, color}) => ( The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. -Bandwidth supports two APIs for porting numbers to Bandwidth: -- /portins -- /bulkPortins - The `/portins` API allows a set of TNs to be ported in, provided that the set of TNs meets the criteria below. TNs can be ported in a single `/portins` request if all of the following are true: @@ -53,8 +49,15 @@ There are also a number of reasons why a TN may not be able to be ported in: * The Bandwidth account has not been enabled for porting. Otherwise the user must separate the TNs into individual `/portins` requests. -The `/lnpchecker` API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs. -The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. +### Checking for Portability + +A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the `/accounts/{accountId}/lnpChecker` API endpoint. This API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs. Here you can check out [How to check number portability](/docs/numbers/guides/porting/lnpChecker). + +### Bulk Portin + +Bandwidth supports an alternative way to port numbers to Bandwidth. +The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/bulkPortins). + Terminology @@ -69,10 +72,6 @@ Terminology | Losing carrier | The carrier from which the TN(s) is being ported | -## Checking for Portability - -A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the `/accounts/{accountId}/lnpChecker` API endpoint. - ## Create a Portin Order The API allows a user to create a new LNP order. An order number will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. diff --git a/site/docs/numbers/porting/portingTypes.mdx b/site/docs/numbers/porting/portingTypes.mdx index 69d868810..122a7c0db 100644 --- a/site/docs/numbers/porting/portingTypes.mdx +++ b/site/docs/numbers/porting/portingTypes.mdx @@ -1,8 +1,8 @@ --- id: portingTypes title: Porting Types -slug: /numbers/guides/portingTypes -description: How to port numbers using the Bandwidth API +slug: /numbers/guides/porting/portingTypes +description: What is Port Type keywords: - bandwidth - numbers diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx index 2f860ee39..8772dd689 100644 --- a/site/docs/numbers/porting/updatePortin.mdx +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -1,8 +1,8 @@ --- id: updatePortin title: Update Portin -slug: /numbers/guides/updatePortin -description: How to port numbers using the Bandwidth API +slug: /numbers/guides/porting/updatePortin +description: How to update your portin request keywords: - bandwidth - numbers diff --git a/site/sidebar.js b/site/sidebar.js index d63961f65..6b5457b34 100644 --- a/site/sidebar.js +++ b/site/sidebar.js @@ -56,7 +56,7 @@ module.exports = { "numbers/porting/updatePortin", "numbers/porting/cancelPortin", "numbers/porting/portingTypes", - "numbers/porting/bulkportins", + "numbers/porting/bulkPortins", ], }, "numbers/csrLookupTool", diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index 6fc94a21d..817215afa 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -1548,7 +1548,8 @@ "/accounts/{accountId}/bulkPortins": { "get": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "Retrieves bulk port-in orders for the specified accountId.\nA maximum of 1,000 orders can be retrieved per request. If no date range or specific query parameter is provided, the order results will be limited to the last two years. Please visit Guides and Tutorials", "operationId": "ListBulkPortins", @@ -1610,7 +1611,8 @@ "in": "query", "required": false, "schema": { - "type": "date" + "format": "date", + "type": "string" }, "example": "2021-06-21T18:45:00.000Z" }, @@ -1620,7 +1622,8 @@ "in": "query", "required": false, "schema": { - "type": "date" + "format": "date", + "type": "string" }, "example": "2021-06-21T18:45:00.000Z" }, @@ -1630,7 +1633,8 @@ "in": "query", "required": false, "schema": { - "type": "date" + "format": "date", + "type": "string" }, "example": "2021-06-21T18:45:00.000Z" }, @@ -1672,7 +1676,8 @@ }, "post": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "

Creates a bulk port-in order to be used as a template for a collection of child port-in orders. The template values will be cascaded to child port-ins that result from decomposing a collection of Telephone Numbers that span carriers, RespOrgs, or have attributes that drive the decomposition into a number of individual port-in orders.

Upon a successfully-submitted payload, the order will have a status of \"DRAFT\", denoting that further modification to the template is expected. For example, the next step is to use the /tnList endpoint to add a collection of telephone numbers to the bulk port-in order. The only valid value for the ProcessingStatus element in a POST is 'DRAFT', which is the default value.

Please visit Guides and Tutorials

", "operationId": "CreateBulkOrder", @@ -1740,7 +1745,8 @@ "/accounts/{accountId}/bulkPortins/{orderid}": { "get": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "Retrieves information associated with the bulk port-in order specified by the orderId URI parameter. Please visit Guides and Tutorials", "operationId": "RetrieveBulkOrder", @@ -1790,7 +1796,8 @@ }, "put": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "The PUT operation is available only for bulk port-in orders that are not yet associated with subtending orders. Since this only occurs for bulk port-in orders that are in one of the draft states, there are few restrictions on what may be included. As with the POST, any data associated with the bulk port-in will cascade to subtending orders when they are created. (Subtending orders are created after telephone numbers are added to the bulk port-in using the /tnList endpoint.) The PUT completely replaces the existing Bulk Portin order with the payload of the PUT. Please visit Guides and Tutorials.

The following element may appear only in PUT or PATCH operations on a bulk port-in order.
  • RetryValidation - When toll free numbers are included in a port-in order, Bandwidth accesses a vendor to determine if the numbers are portable, and if so, from which RespOrg. In the event that we do not receive a response from our vendor after a number of retries, we give up and place the order in the INVALID_DRAFT_TNS state. This scenario can occur if our toll free porting vendor is performing maintenance, for example. Including RetryValidation with a value of true will cause the order to return to VALIDATE_DRAFT_TNS and we will repeat our attempts to retrieve the portability data from the vendor. This element is included in the synchronous response to the PUT or PATCH, when included in the request, but is not included in subsequent GET requests for the order.
", "operationId": "PutBulkOrder", @@ -1865,7 +1872,8 @@ }, "delete": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "Delete a bulk port-in order with child port-ins. Deleting a bulk port-in is allowed for 'DRAFT' state only. Deleting a bulk port-in will delete all DRAFT child port-ins associated with the bulk port-in. When the bulk port-in is deleted, any child port-in orders that are not in a draft status are dissociated from the bulk port-in, but not deleted. Please visit Guides and Tutorials", "operationId": "DeleteBulkOrder", @@ -1915,7 +1923,8 @@ }, "patch": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing Bulk Port-in order. This is done via a PUT or PATCH on the existing order-id. Since the Bulk Port-in\n order acts as a template for port-in orders in DRAFT status, any record can be changed at any time. The PATCH replaces elements of the referenced Bulk Portin order, but it replaces only the records included in the request payload. Other elements will remain untouched.

Changing the fields in a Bulk Port-in order causes the system to reapply all changed values to the child port-ins contained in the list of subtending port-in orders. Note that if the port-in orders contained within the Bulk Port are in DRAFT state, any field can be modified. If any child port-in order in the Bulk Port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller.

Changing the ProcessingStatus to 'IN_PROGRESS' causes all child port-ins to begin processing. This is only valid if child port-ins exist for the bulk port-in.

Please visit Guides and Tutorials

", "operationId": "PatchBulkOrder", @@ -1992,7 +2001,8 @@ "/accounts/{accountId}/bulkPortins/{orderid}/portinList": { "get": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "Retrieves a list of Port-in Orders that are all associated with the identified Bulk Port-in. This response is not paginated due to its inherently limited size. Please visit Guides and Tutorials", "operationId": "ListBulkChildOrders", @@ -2039,7 +2049,8 @@ }, "put": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "

A PUT on a PortinList resource will cause replacement of the list of port-in orders associated with the specified bulk port-in.

This PUT will completely replace the existing list of port-in orders associated with the bulk port-in. If all port-in orders in the list are not valid, the PUT request will fail, due to the potential for losing the port-in to bulk port-in relationships.

Only port-in orders in a draft status may be associated with a bulk port-in order. And port-in orders may only be added to a bulk port-in order while that bulk port-in order is still in a draft state.

Child port-in orders may be dissociated from the bulk port-in at any time.

Please visit Guides and Tutorials

", "operationId": "UpdateBulkChildList", @@ -2106,7 +2117,8 @@ "/accounts/{accountId}/bulkPortins/{orderid}/notes": { "get": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "Retrieve all notes associated with the order. Please visit Guides and Tutorials", "operationId": "ListBulkNotes", @@ -2156,7 +2168,8 @@ }, "post": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "Updates the Notes resource by adding a note. Adding a note to a port-in order causes a notification to be sent to Bandwidth Operations, so that they may assist as necessary. A note may be up to 500 characters in length. Please visit Guides and Tutorials", "operationId": "CreateBulkNote", @@ -2223,7 +2236,8 @@ "/accounts/{accountId}/bulkPortins/{orderid}/notes/{noteId}": { "put": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "Update a specified note. Notes may only be updated, not deleted. Please visit Guides and Tutorials", "operationId": "UpdateBulkNote", @@ -2300,7 +2314,8 @@ "/accounts/{accountId}/bulkPortins/{orderid}/tnList": { "get": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "

The information returned in the GET /tnList response payload depends on the ProcessingStatus of the bulk port-in order. See the Responses tab for examples of each response payload.

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

\n ProcessingStatus\n

\n 		\n

\n Information Returned\n

\n
\n

\n DRAFT\n

\n 		\n

\n In this state, no tnList has been provided, so the response\n includes empty portable and non-portable telephone number lists.\n

\n
\n

\n VALIDATE_DRAFT_TNS\n

\n 		\n

\n In this state, validation of the tnList is still in progress,\n so the response includes all of the tnList telephone numbers\n in a `not validated` list. This is a temporary state until\n the validation completes. Validation takes longer when toll\n free numbers are included in the tnList.\n

\n
\n

\n VALID_DRAFT_TNS\n

\n 		\n

\n In this state, all of the telephone numbers in the tnList have\n been determined to be portable. The response payload includes\n a list of the child port-in orders and shows which telephone\n numbers are assigned to each child port-in order.\n

\n
\n

\n INVALID_DRAFT_TNS\n

\n 		\n

\n In this state, at least one of the telephone numbers in the tnList\n has been determined to be non-portable. The response payload includes\n a list of portable numbers (if any) and a list of errors showing which\n telephone numbers are non-portable as well as the reasons why they\n cannot be ported. Or, if communication errors prevented us from\n determining telephone number portability, those errors will be included.\n

\n
\n

Please visit Guides and Tutorials

", "operationId": "ListBulkTns", @@ -2347,7 +2362,8 @@ }, "put": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "

This operation is used to add telephone numbers to a draft bulk port-in order.\n The telephone numbers may be a mix of toll free and non-toll free. Once the\n telephone numbers are added, they will be checked for portability, and if\n portable, decomposed into individual child port-in orders. Both the bulk\n port-in order and the child port-in orders remain in draft status until you\n explicitly submit them.

\n\n

After submitting a tnList with the PUT operation, you will need to poll for\n completion of the validation and decomposition using the GET /tnList operation\n or the GET /bulkPortins/orderId operation (both include the order ProcessingStatus).\n The basic ProcessingStatus flow is as follows:

\n\n
  • On submission of the tnList, the bulk port-in order transitions from DRAFT\n status to VALIDATE_DRAFT_TNS. The order will remain in this state until validation\n is complete. For a tnList that does not contain any toll free telephone numbers, the\n validation step is very fast. When the tnList does contain toll free telephone\n numbers, the time it takes to validate the toll free numbers is roughly proportional\n to the number of toll free telephone numbers. If you PUT a new tnList while validation\n is in progress for a previous tnList, the validation of the previous tnList will be\n abandoned and replaced by validation of the new tnList.
    • \n
  • If all of the telephone numbers in the tnList are portable, the bulk port-in\n transitions to the VALID_DRAFT_TNS state. At this point, child port-in orders have\n been created in DRAFT status to meet requirements about which telephone numbers can\n be ported together in the same port-in order. The bulk port-in will remain in this\n state until you use the PATCH operation on the bulk port-in order to change the\n ProcessingStatus to IN_PROGRESS. If you PUT an updated tnList, all draft child\n port-in orders are removed, and the validation process begins again with the new\n tnList.
    • \n
  • If at least one of the telephone numbers in the tnList is not portable, the bulk\n port-in transitions to the INVALID_DRAFT_TNS state. When this happens, no child\n port-in orders are created. You can use the GET operation on /tnList to see reasons\n why telephone numbers are non-portable. You’ll need to update the tnList to remove\n non-portable telephone numbers and PUT the tnList again to restart the validation\n step. The goal is to get to the VALID_DRAFT_TNS state, from which you can submit\n the bulk port-in order.
\n

Please visit Guides and Tutorials

", "operationId": "UpdateBulkTnList", @@ -2427,7 +2443,8 @@ "/accounts/{accountId}/bulkPortins/{orderid}/history": { "get": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "Retrieves the history of the specified bulk port-in order. Obtaining history for a draft bulk port-in is not supported.

Please visit Guides and Tutorials

", "operationId": "GetBulkHistory", @@ -2492,7 +2509,8 @@ "/accounts/{accountId}/bulkPortins/{orderid}/loas": { "get": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "Retrieves the list of the loa (and other) files associated with the order.", "operationId": "ListBulkLoas", @@ -2550,7 +2568,8 @@ }, "post": { "tags": [ - "/accounts" + "/accounts", + "Porting" ], "description": "

POSTing to the /loas resource will enable the upload of the file. The key attribute to the POST is ensuring that the headers are correctly set to support the file upload.
\nQuery parameter or header documentType can be used to specify type of document on upload. Possible values are: LOA, INVOICE, CSR, OTHER.\n
\nHeader settings typical of a valid upload are...
\n
\n\nHost: dashboard.bandwidth.com
\nAuthorization: Basic xxxxxxxxxxxxxxxxxxxx==
\nContent-Type: application/pdf
\ndocumentType: [LOA | INVOICE | CSR | OTHER]
\nAccept: /
\nAccept-Encoding: gzip, deflate
\nAccept-Language: en-US,en;q=0.8
\nCache-Control: no-cache
\n
\n----WebKitFormBoundaryE19zNvXGzXaLvS5C
\nContent-Disposition: form-data; name=\"george\"; filename=\"Bandwidth Dashboard.pdf\"
\nContent-Type: application/pdf
\n
\n
\n----WebKitFormBoundaryE19zNvXGzXaLvS5C
\n

", "operationId": "UploadBulkLoa", @@ -21094,7 +21113,151 @@ "type": "object", "properties": { "BulkPortin": { - "$ref": "#/components/schemas/BulkPortin" + "type": "object", + "properties": { + "CustomerOrderId": { + "type": "string", + "description": "Internal customer order id for tracking the order.", + "format": "alphanumeric" + }, + "RequestedFocDate": { + "type": "string", + "format": "ISO8601 date-time encoding of ZULU/UTC/GMT", + "description": "If present this will specify the date and time that the port-in is requested to happen. The actual time and date is subject to negotiation with the losing carriers.", + "example": "2013-05-10T15:14:22Z" + }, + "AlternateSpid": { + "type": "string", + "description": "Unique customer AltSPID to be applied to the port-in requests. Can be changed only for DRAFT bulk port-in." + }, + "BillingTelephoneNumber": { + "type": "string", + "description": "Account or Billing telephone number for order. This will be unusual for bulk port-in requests that are expected to decompose into port-in requests from multiple carriers, because the value will be different for each losing carrier." + }, + "Subscriber": { + "type": "object", + "properties": { + "SubscriberType": { + "type": "string", + "enum": [ + "BUSINESS", + "RESIDENTIAL", + "GENERIC" + ], + "description": "If residential, order will be rejected if a BusinessName is entered." + }, + "BusinessName": { + "type": "string", + "description": "Subscriber business name." + }, + "FirstName": { + "type": "string", + "description": "Subscriber first name." + }, + "MiddleInitial": { + "type": "string", + "description": "Subscriber middle initial." + }, + "LastName": { + "type": "string", + "description": "Subscriber last name." + }, + "Name": { + "type": "string", + "description": "" + }, + "ServiceAddress": { + "type": "object", + "properties": { + "HousePrefix": { + "type": "string", + "description": "Street address number prefix." + }, + "HouseNumber": { + "type": "string", + "description": "Street address number." + }, + "HouseSuffix": { + "type": "string", + "description": "Street address number suffix." + }, + "PreDirectional": { + "type": "string", + "description": "Street address pre-directional." + }, + "StreetName": { + "type": "string", + "description": "Street name." + }, + "StreetSuffix": { + "type": "string", + "description": "Street suffix." + }, + "PostDirectional": { + "type": "string", + "description": "Street address post directional." + }, + "AddressLine2": { + "type": "string", + "description": "Put unit, suite, floor, etc. here." + }, + "City": { + "type": "string", + "description": "City." + }, + "StateCode": { + "type": "string", + "description": "Two letter state code." + }, + "Zip": { + "type": "string", + "description": "Zip code." + }, + "PlusFour": { + "type": "string", + "description": "Zip + 4 value." + }, + "Country": { + "type": "string", + "description": "3 letter country code." + } + } + } + } + }, + "LoaAuthorizingPerson": { + "type": "string", + "description": "First and last name of person who authorized LOA." + }, + "AccountNumber": { + "type": "string", + "description": "Account number associated with the account on the losing carrier, often required for wireless ports, or enterprise ports. This will be unusual for bulk port-in requests that are expected to decompose into port-in requests from multiple carriers." + }, + "PinNumber": { + "type": "string", + "description": "PIN Number, often required for wireless ports." + }, + "SiteId": { + "type": "integer", + "format": "int32", + "description": "This is the Site / Sub-Account ID made visible in the /accounts/{accountId}/sites API call" + }, + "PeerId": { + "type": "integer", + "format": "int32", + "description": "This is the SIP Peer / Location ID made visible in the /accounts/{accountId}/sites/{siteId}/sipPeers API call" + }, + "TnAttributes": { + "type": "array", + "description": "Attributes to be assigned to the telephone number. Optional parameter. Possible values - `Protected`", + "items": { + "$ref": "#/components/schemas/TnAttribute" + } + }, + "RetryValidation": { + "type": "boolean" + } + } } } }, From 655c14f9b4b3765215fd935d779030bbadf5ba58 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Thu, 7 Jul 2022 20:14:32 +0300 Subject: [PATCH 05/20] Porting - port types * merge port type info from 3 sources * remove dedicated port type page --- site/docs/numbers/porting/bulkportins.mdx | 5 +- site/docs/numbers/porting/lnpChecker.mdx | 46 +++--- site/docs/numbers/porting/portingNumbers.mdx | 52 +------ site/docs/numbers/porting/portingTypes.mdx | 139 ------------------- site/docs/numbers/porting/updatePortin.mdx | 6 +- site/sidebar.js | 3 +- site/specs-temp/numbers.json | 16 +-- 7 files changed, 48 insertions(+), 219 deletions(-) delete mode 100644 site/docs/numbers/porting/portingTypes.mdx diff --git a/site/docs/numbers/porting/bulkportins.mdx b/site/docs/numbers/porting/bulkportins.mdx index afa536f5e..f9122fae2 100644 --- a/site/docs/numbers/porting/bulkportins.mdx +++ b/site/docs/numbers/porting/bulkportins.mdx @@ -1,6 +1,6 @@ --- id: bulkPortins -title: Manage bulk port-in orders +title: Create Bulk Portin slug: /numbers/guides/porting/bulkPortins description: How to manage bulk port-in order using the Bandwidth API keywords: @@ -29,8 +29,11 @@ export const Highlight = ({children, color}) => ( ); + [The bulkPortins endpoint](/apis/numbers#operation/ListBulkPortins) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. Like many other requests, the bulkPortins endpoint causes the creation of a Bulk Portins order that is used to manage the porting event throughout the lifecycle of the request. +The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. + When a bulk port-in is created successfully, it will have one or more child port-in orders that satisfy the following industry port-in rules: * Telephone numbers in a child port-in order all have the same port-type (e.g. toll free, automated on-net, automated off-net, internal, etc.). diff --git a/site/docs/numbers/porting/lnpChecker.mdx b/site/docs/numbers/porting/lnpChecker.mdx index 287f7d220..564f5ceb3 100644 --- a/site/docs/numbers/porting/lnpChecker.mdx +++ b/site/docs/numbers/porting/lnpChecker.mdx @@ -1,6 +1,6 @@ --- id: lnpChecker -title: Lnp Checker +title: Checking number portability slug: /numbers/guides/porting/lnpChecker description: How to check number(s) portability keywords: @@ -34,30 +34,40 @@ export const Highlight = ({children, color}) => ( ); -## Checking for Portability +A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the [`/accounts/{accountId}/lnpChecker`](/apis/numbers#operation/RequestPortabilityInfo) API endpoint. -A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the `/accounts/{accountId}/lnpChecker` API endpoint. +### Portability criteria -The `fullcheck` query parameter values control the components of the response payload that is returned. +TNs can be ported in a single `/portins` request if all the following are true: -### Request URL -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker +1. They all have the same Port Type (see the `Port Types` section below) +2. They all have the same losing carrier +3. They are all associated with the same billing TN and Service Address + +There are also a number of reasons why a TN may not be able to be ported in: -### Request Query Parameter +* The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. +* The TN is an off-net TN, and the account is configured to support tier zero (on-net) only. +* The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with. +* The TN is already being processed in another active port-in order. +* The Bandwidth account has not been enabled for porting. +Otherwise, the user must separate the TNs into individual `/portins` requests. -| `fullcheck` value | Description | -|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `false` (default) | Return only rate center information | -| `true` | Additional information will be provided on the losing carriers associated with the listed numbers | -| `onnetportability` | Provides rate center and losing carrier information for onnet tiers only | -| `offnetportabilty` | In addition to on-net information return off-net port information in `` element with Partner/Vendor that the port will be supported on. Contains a list of the TNs that are supported in partner rate centers, and for which we will manually execute a port if requested for help. | +### Port Types -### Response Parameters +Port Type - is a categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. -| Element | Description | -|:----------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SupportedRateCenters`
`PartnerSupportedRateCenters`
`UnsupportedRateCenters` | Rate Center information for the indicated set of ratecenters, containing City, State, LATA and the list of TNs for which that Rate Center applies.
The Tier information is provided for offnet rate centers. | -| `SupportedLosingCarriers`
`UnsupportedLosingCarriers` | Details on the Losing Carrier including name, SPID, whether or not the carrier is a wireless carrier, whether or not account number is required as part of the CSR check, and the anticipated minimum number of days before a FoC date will be granted. | +| Port Type | Description | | +|:----------------------------------|:-------------------------------------------------------| +| MANUAL | `MANUAL` (for all port types starting with `MANUAL`) indicates that if the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team. | +| MANUALOFFNET | `Off-net` means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Off-net port-ins are processed manually when the Bandwidth partner does not have APIs by which the port-in can be automated, or Bandwidth has not implemented those APIs. Orders may also be processed manually if there are more numbers in the port-in than the partner’s interface supports, e.g. off-net ports with vendor Level 3 and with more than 49 TNs are automatically submitted as manual ports.| +| MANUALONNET | `On-net` means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. On-net port-ins are processed manually only when there are more numbers in the port-in than the porting vendor’s interface supports (e.g more than 999 TNs). | +| MANUALTOLLFREE | Currently all toll free port-ins are handled manually by Bandwidth’s LNP team. But Bandwidth is in the process of automating portions of toll free porting, with a goal of eventually automating the entire process. | +| AUTOMATED | If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention using interfaces to our porting vendors. There are several sub-types of `AUTOMATED` as follows:
  • `AUTOMATED` - means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth (On-net tns). There are differences in on-net port-in rules depending on whether the order is for wireless to wireless vs. one of the other 3 combinations.
  • `AUTOMATEDOFFNET` - Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Currently, only numbers in the U.S. are automated. There are differences in port-in rules depending on whether the order has achieved FOC status.
  • `INTERNAL` - Internal means that the telephone number is being moved from one Bandwidth account to another Bandwidth account. Internal port-in may involve on-net, off-net, or toll free telephone numbers.
| +| MIXED | If the list of TNs supplied to /lnpchecker includes TNs that are categorized as more than one of the above Port Types, the resulting Port Type will be `MIXED`. If you plan to use /portins to port the TNs, you must break the TN list into separate /portins requests for each Port Type. | + +### Request URL +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker ### Examples diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index f68eef6d5..0018c734a 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -33,44 +33,10 @@ export const Highlight = ({children, color}) => ( The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. -The `/portins` API allows a set of TNs to be ported in, provided that the set of TNs meets the criteria below. -TNs can be ported in a single `/portins` request if all of the following are true: - -1. They all have the same Port Type -2. They all have the same losing carrier -3. They are all associated with the same billing TN and Service Address - -There are also a number of reasons why a TN may not be able to be ported in: - -* The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. -* The TN is an off-net TN and the account is configured to support tier zero (on-net) only. -* The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with. -* The TN is already being processed in another active port-in order. -* The Bandwidth account has not been enabled for porting. -Otherwise the user must separate the TNs into individual `/portins` requests. - -### Checking for Portability - -A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the `/accounts/{accountId}/lnpChecker` API endpoint. This API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs. Here you can check out [How to check number portability](/docs/numbers/guides/porting/lnpChecker). - -### Bulk Portin - -Bandwidth supports an alternative way to port numbers to Bandwidth. -The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/bulkPortins). - -Terminology - - -| Term | Description | | -|:----------------------------------|:-------------------------------------------------------| -| Port Type | A categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. See the POST operation for more information | -| On-Net | TNs that belong to a rate center covered by Bandwidth are referred to as on-net TNs | -| Off-Net | TNs that belong to a rate center covered by a Bandwidth partner are refered to as off-net TNs | -| Automated | If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention | -| Manual | If the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team | -| Internal | TNs that are being moved from one Bandwidth account to another Bandwidth account are referred to as internal ports. Internal ports are handled automatically | -| Losing carrier | The carrier from which the TN(s) is being ported | +The `/portins` API accepts Port-In requests. On order to successfully port telephone numbers they need to correspond to a set of criteria. To learn more follow the [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) guide. +Bandwidth also supports an alternative way to port in numbers. +The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/bulkPortins). ## Create a Portin Order @@ -78,17 +44,6 @@ The API allows a user to create a new LNP order. An order number will be auto-ge As in other asynchronous workflows, the request to port in a number is created by a POST to a resource dedicated to the purpose to tracking requests – the `accounts/{accountId}/portins` resource. -The portins endpoint is used to manage requests to port both toll free and non-toll free telephone numbers into Bandwidth. Like many other requests, the /portins endpoint causes the creation of an order that is used to manage the porting event throughout the lifecycle of the request. The various sub-resources and methods are covered in greater detail below. -When a port-in is created, a port-type is assigned based on the telephone numbers provided. A lot of the conditional payload elements are conditional on the basis of the port-type. Port-type can take on the following values: - -* MANUALOFFNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Off-net port-ins are processed manually when the Bandwidth partner does not have APIs by which the port-in can be automated, or Bandwidth has not implemented those APIs. Orders may also be processed manually if there are more numbers in the port-in than the partner’s interface supports. -* MANUALONNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. On-net port-ins are processed manually only when there are more numbers in the port-in than the porting vendor’s interface supports. -* MANUALTOLLFREE - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Currently all toll free port-ins are handled manually by Bandwidth’s Local Number Portability team. But Bandwidth is in the process of automating portions of toll free porting, with a goal of eventually automating the entire process. -* AUTOMATED - Automated means that the port-in will be processed automatically using interfaces to our porting vendors. There are several sub-types of AUTOMATED as follows: -* ON-NET - On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. There are differences in on-net port-in rules depending on whether the order is for wireless to wireless vs. one of the other 3 combinations. -* OFF-NET - Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Currently only numbers in the U.S. are automated. There are differences in port-in rules depending on whether the order has achieved FOC status. -* INTERNAL - Internal means that the telephone number is being moved from one Bandwidth account to another Bandwidth account. Internal port-in may involve on-net, off-net, or toll free telephone numbers. - ### Polling vs. Webhooks Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP "order". The orders are then processed and the order status is updated asynchronously. Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. @@ -184,6 +139,7 @@ Content-Type: application/xml; charset=utf-8 true ``` +You can retrieve an information about your Port in using a GET request to `/accounts/{accountId}/portins/{orderId}` ## Modify a Portin Order diff --git a/site/docs/numbers/porting/portingTypes.mdx b/site/docs/numbers/porting/portingTypes.mdx deleted file mode 100644 index 122a7c0db..000000000 --- a/site/docs/numbers/porting/portingTypes.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -id: portingTypes -title: Porting Types -slug: /numbers/guides/porting/portingTypes -description: What is Port Type -keywords: - - bandwidth - - numbers - - porting - - portin - - lnp - - port - - port type - - types -image: ../../../static/img/bandwidth-logo.png ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -export const accountId = "{accountId}"; -export const orderId = "{orderId}"; - -export const Highlight = ({children, color}) => ( - - {children} - - ); - -The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. - -Bandwidth supports two APIs for porting numbers to Bandwidth: -- /portins -- /bulkPortins - -The `/portins` API allows a set of TNs to be ported in, provided that the set of TNs meets the criteria below. -TNs can be ported in a single `/portins` request if all of the following are true: - -1. They all have the same Port Type -2. They all have the same losing carrier -3. They are all associated with the same billing TN and Service Address - -There are also a number of reasons why a TN may not be able to be ported in: - -* The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. -* The TN is an off-net TN and the account is configured to support tier zero (on-net) only. -* The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with. -* The TN is already being processed in another active port-in order. -* The Bandwidth account has not been enabled for porting. -Otherwise the user must separate the TNs into individual `/portins` requests. - -The `/lnpchecker` API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs. -The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. -Terminology - - -| Term | Description | | -|:----------------------------------|:-------------------------------------------------------| -| Port Type | A categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. See the POST operation for more information | -| On-Net | TNs that belong to a rate center covered by Bandwidth are referred to as on-net TNs | -| Off-Net | TNs that belong to a rate center covered by a Bandwidth partner are refered to as off-net TNs | -| Automated | If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention | -| Manual | If the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team | -| Internal | TNs that are being moved from one Bandwidth account to another Bandwidth account are referred to as internal ports. Internal ports are handled automatically | -| Losing carrier | The carrier from which the TN(s) is being ported | - -* MANUALOFFNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Off-net port-ins are processed manually when the Bandwidth partner does not have APIs by which the port-in can be automated, or Bandwidth has not implemented those APIs. Orders may also be processed manually if there are more numbers in the port-in than the partner’s interface supports. -* MANUALONNET - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. On-net port-ins are processed manually only when there are more numbers in the port-in than the porting vendor’s interface supports. -* MANUALTOLLFREE - Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Currently all toll free port-ins are handled manually by Bandwidth’s Local Number Portability team. But Bandwidth is in the process of automating portions of toll free porting, with a goal of eventually automating the entire process. -* AUTOMATED - Automated means that the port-in will be processed automatically using interfaces to our porting vendors. There are several sub-types of AUTOMATED as follows: -* ON-NET - On-net means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. There are differences in on-net port-in rules depending on whether the order is for wireless to wireless vs. one of the other 3 combinations. -* OFF-NET - Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Currently only numbers in the U.S. are automated. There are differences in port-in rules depending on whether the order has achieved FOC status. -* INTERNAL - Internal means that the telephone number is being moved from one Bandwidth account to another Bandwidth account. Internal port-in may involve on-net, off-net, or toll free telephone numbers. - - -## Create a Portin Order - -The API allows a user to create a new LNP order. An order number will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. - -As in other asynchronous workflows, the request to port in a number is created by a POST to a resource dedicated to the purpose to tracking requests – the `accounts/{accountId}/portins` resource. - -The portins endpoint is used to manage requests to port both toll free and non-toll free telephone numbers into Bandwidth. Like many other requests, the /portins endpoint causes the creation of an order that is used to manage the porting event throughout the lifecycle of the request. The various sub-resources and methods are covered in greater detail below. -When a port-in is created, a port-type is assigned based on the telephone numbers provided. A lot of the conditional payload elements are conditional on the basis of the port-type. Port-type can take on the following values: - - -## Modify a Portin Order - -Please refer to the matrix below to see which elements can be modified and replaced. - -| Payload Field | Manual Off-Net | Manual On-Net | Manual Toll Free | Automated On-Net | Automated Off-Net Pre FOC | Automated Off-Net Post FOC | Internal | -|----------------------------------------------------------|----------------|---------------|------------------|-------------------|---------------------------|----------------------------|----------| -| billingTelephoneNumber | Editable | Editable | Disabled | Editable | Editable | Disabled | Editable | -| newBillingTelephoneNumber | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | -| partialPort | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | -| subscriber.subscriberType | Editable | Editable | Editable | Editable | Editable | Disabled | Editable | -| subscriber.businessName/firstName/middleInitial/lastName | Editable | Editable | Editable | Editable | Editable | Disabled | Editable | -| loaAuthorizingPerson | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | -| wirelessInfo.accountNumber | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | -| wirelessInfo.pinNumber | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | -| subscriber.serviceAddress | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | -| requestedFocDate | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| listOfPhoneNumbers | Disabled | Disabled | Disabled | Editable | Disabled | Disabled | Disabled | -| siteId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| peerId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| customerOrderId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| TnAttributes elements | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| Immediately | Disabled | Disabled | Disabled | Disabled | Disabled | Disabled | Editable | - -### SUPP Order Field Notes - -* `AccountNumber` - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both. -* `AlternateSpid` - Not applicable to toll free port-ins. Can only be modified in DRAFT state. Can only be modified if it is not configured at the system level. -* `BillingTelephoneNumber` - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. -* `BusinessName` - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. -* `CustomerOrderId` - Can always be updated. This field is removed from the order if not provided in the PUT payload. -* `Immediately` - Only applicable to Internal port-in orders. May be included in the PUT payload, but cannot be changed in a SUPP. -* `ListOfPhoneNumbers` - Can be SUPPed only for Automated on-net port-ins and toll free port-ins. For toll free port-ins, may be SUPPed only in draft states (i.e. DRAFT, VALIDATE_DRAFT_TFNS, VALID_DRAFT_TFNS, or INVALID_DRAFT_TFNS). -* `LoaAuthorizingPerson` - Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. -* `NewBillingTelephoneNumber` - Not applicable to toll free port-ins or Automated off-net port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins. -* `OverrideValidation` - Applies only to internal ports. This Bandwidth internal flag forces port-out to bypass validity checking (if there are no terminal errors). This flag can be SUPPed only for orders in EXCEPTION status. -* `PartialPort` - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. -* `PeerId` - Can always be updated. -* `PinNumber` - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both. -* `ProcessingStatus` - May only be SUPPed for port-in orders in draft state. The only valid value is “SUBMITTED” (not case sensitive). -* `RequestedFocDate` - Can always be updated, but subject to blackout windows if the current date is too close to an assigned FOC date. -* `ResetAddressFields` - Not applicable to toll free port-ins. If included with a value of true, any Subscriber elements, including subscriber type, subscriber/business name elements, and service address elements, NOT included in the PUT payload will be removed from the order. -* `ServiceAddress` - Element of Subscriber. Includes all address fields. ServiceAddress elements cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. See also, ResetAddressFields. -* `SiteId` - Can always be updated. -* `SubscriberName` - Element of Subscriber. Includes FirstName, MiddleInitial, and LastName. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. -* `SubscriberType` - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. If SubscriberType is set to BUSINESS, a BusinessName must be provided. If SubscriberType is set to RESIDENTIAL, a FirstName and LastName must be provided. -* `TnAttributes` - Can be SUPPed prior to completion of the port-in request. -* `Triggered` - May be included in the PUT payload, but cannot be changed in a SUPP. - diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx index 8772dd689..5cad35e38 100644 --- a/site/docs/numbers/porting/updatePortin.mdx +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -33,11 +33,11 @@ export const Highlight = ({children, color}) => ( ); -The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. +In this guide we will show you how to manage your Port in order. Please ensure you have followed our earlier guide on [How to create Port in order](/docs/numbers/guides/porting/updatePortin) with Bandwidth. ## Modify a Portin Order -The API allows a user to modify an existing LNP order, called a SUPP request. Modifications are only allowed for orders that are not yet complete or cancelled. LNP orders can be modified with a PUT to `accounts/{accountId}/portins/{orderId}`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. +The PUT to `accounts/{accountId}/portins/{orderId}` API allows a user to modify an existing LNP order, by sending a so-called a SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. Items that can be included in a SUPP request include: @@ -57,7 +57,7 @@ Items that can be included in a SUPP request include: * Triggered * Immediately -If the order ProcessingStatus is DRAFT, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from DRAFT to SUBMITTED. The AltSpid element can be modified if it is not configured at the system level. +If the order ProcessingStatus is `DRAFT`, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from `DRAFT` to `SUBMITTED`. The AltSpid element can be modified if it is not configured at the system level. `ProcessingStatus` - you can only provide this field with a value of SUBMITTED if the current ProcessingStatus of the port-in is DRAFT. diff --git a/site/sidebar.js b/site/sidebar.js index 6b5457b34..ba40230a2 100644 --- a/site/sidebar.js +++ b/site/sidebar.js @@ -51,12 +51,11 @@ module.exports = { label: "Porting numbers", items: [ "numbers/porting/portingNumbers", + "numbers/porting/bulkPortins", "numbers/porting/lnpChecker", "numbers/porting/loaUpload", "numbers/porting/updatePortin", "numbers/porting/cancelPortin", - "numbers/porting/portingTypes", - "numbers/porting/bulkPortins", ], }, "numbers/csrLookupTool", diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index 817215afa..a6457968d 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -7981,7 +7981,7 @@ "/accounts", "Porting" ], - "description": "

\n Bandwidth supports two APIs for porting numbers to Bandwidth: /portins and /bulkPortins.
\n The /portins API allows a set of TNs to be ported in, provided that the set of TNs meets the criteria below.
\n TNs can be ported in a single /portins request if all of the following are true:\n

\n
    \n
  • They all have the same Port Type.
    • \n
  • They all have the same losing carrier.
    • \n
  • They are all associated with the same billing TN and Service Address.
    • \n
\n

There are also a number of reasons why a TN may not be able to be ported in:

\n
    \n
  • The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners.
    • \n
  • The TN is an off-net TN and the account is configured to support tier zero (on-net) only.
    • \n
  • The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with.
    • \n
  • The TN is already being processed in another active port-in order.
    • \n
  • The Bandwidth account has not been enabled for porting.
    • \n
\n

\n Otherwise the user must separate the TNs into individual /portins requests.
\n The /lnpchecker API is used to determine the Port Type(s) and losing carrier(s) for a set of TNs.
\n The /bulkPortins API eliminates the need for the /lnpchecker API by sorting the list of TNs automatically into a set of port-in requests by Port Type. The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves.\n

\nTerminology\n
    \n
  • Port Type - A categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. See the POST operation for more information.
    • \n
  • On-Net - TNs that belong to a rate center covered by Bandwidth are referred to as on-net TNs.
    • \n
  • Off-Net - TNs that belong to a rate center covered by a Bandwidth partner are refered to as off-net TNs.
    • \n
  • Automated - If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention.
    • \n
  • Manual - If the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team.
    • \n
  • Internal - TNs that are being moved from one Bandwidth account to another Bandwidth account are referred to as internal ports. Internal ports are handled automatically.
    • \n
  • Losing carrier - The carrier from which the TN(s) is being ported.
    • \n
\n

Please visit Guides and Tutorials to learn more.

", + "description": "This API endpoint is used to check whether a number or set of numbers can be ported into the Bandwidth Network.\nThe fullcheck query parameter values control the components of the response payload that is returned.\n

Please visit Guides and Tutorials to learn more.

", "operationId": "RequestPortabilityInfo", "summary": "Request portability information for a set of TNs", "parameters": [ @@ -7997,7 +7997,7 @@ }, { "name": "fullCheck", - "description": "\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Parameter ValueDescription
trueadditional information will be provided on the losing carriers associated with the listed numbers
falsereturn only rate center information
onnetportabilityidentical in meaning to "true" value
offnetportabilityin addition to on-net information return off-net port information in <PartnerSupportedRateCenters> element with Partner/Vendor that the port will be supported on. \n Contains a list of the TNs that are supported in partner rate centers, and for which we will execute a port if requested\n
\nIMPORTANT: If your account supports off-net telephone numbers (tiers other than tier zero), you MUST include query parameter fullCheck=offnetportability in your /lnpchecker request. Failure to do so will cause off-net telephone numbers to appear as though they are not portable.", + "description": "

`fullCheck` controls the components of the response payload that is returned

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
Parameter ValueDescription
trueadditional information will be provided on the losing carriers associated with the listed numbers
falsereturn only rate center information
onnetportabilityProvides rate center and losing carrier information for onnet tiers only
offnetportabilityin addition to on-net information return off-net port information in <PartnerSupportedRateCenters> element with Partner/Vendor that the port will be supported on. \n Contains a list of the TNs that are supported in partner rate centers, and for which we will execute a port if requested\n
\nIMPORTANT: If your account supports off-net telephone numbers (tiers other than tier zero), you MUST include query parameter fullCheck=offnetportability in your /lnpchecker request. Failure to do so will cause off-net telephone numbers to appear as though they are not portable.", "in": "query", "required": false, "schema": { @@ -8024,7 +8024,7 @@ }, "responses": { "200": { - "description": "A successful check has been performed. Note: For users of Enterprise Telephony accounts SupportedLosingCarriers\nand UnsupportedLosingCarriers will be omitted from the success output even when query parameter\nfullCheck has values of true, onnetportability, or offnetportability.\n\n\n \n \n \n \n \n \n \n \n
TagValues
PortType AUTOMATED, AUTOMATEDOFFNET, INTERNAL, MANUAL_ON_NET, MANUALOFFNET, MANUAL_TOLLFREE, MIXED
\n\n
\n\n
    \n
  • AUTOMATED - A properly formatted /portins request with these TNs will be processed by Bandwidth and our porting vendor without requiring human intervention.
    • \n
  • AUTOMATEDOFFNET - A properly formatted /portins request with these TNs will be processed by Bandwidth and our off-net porting vendor without requiring human intervention.
    • \n
  • INTERNAL - The TNs will be moved from one Bandwidth account to another Bandwidth account. Internal ports are handled automatically, without human intervention.
    • \n
  • MANUAL_ON_NET - On-net ports, if they include more than 999 TNs, must be handled manually by creating a ticket.
    • \n
  • MANUALOFFNET - Ports for off-net vendors that do not support a porting API, or have a porting API that Bandwidth does not support, or off-net ports with vendor Level 3 and with more than 49 TNs, are automatically submitted as manual ports.
    • \n
  • MANUAL_TOLLFREE - All toll-free port-ins are handled manually.
    • \n
  • MIXED - If the list of TNs supplied to /lnpchecker includes TNs that are categorized as more than one of the above Port Types, the resulting Port Type will be MIXED. If you plan to use /portins to port the TNs, you must break the TN list into separate /portins requests for each Port Type.
    • \n
", + "description": "A successful check has been performed. Note: For users of Enterprise Telephony accounts SupportedLosingCarriers\nand UnsupportedLosingCarriers will be omitted from the success output even when query parameter\nfullCheck has values of true, onnetportability, or offnetportability.", "content": { "application/xml": { "schema": { @@ -20268,7 +20268,7 @@ "type": "string" }, "SupportedRateCenters": { - "description": "Supported Rate Centers", + "description": "Supported Rate Center information for the indicated set of ratecenters, containing City, State, LATA and the list of TNs for which that Rate Center applies. \nThe Tier information is provided for offnet rate centers.", "type": "object", "properties": { "RateCenterGroup": { @@ -20277,7 +20277,7 @@ } }, "UnsupportedRateCenters": { - "description": "Unsupported Rate Centers", + "description": "Unsupported Rate Center information for the indicated set of ratecenters, containing City, State, LATA and the list of TNs for which that Rate Center applies. \nThe Tier information is provided for offnet rate centers.", "type": "object", "properties": { "RateCenterGroup": { @@ -20286,7 +20286,7 @@ } }, "PartnerSupportedRateCenters": { - "description": "Partner Supported Rate Centers", + "description": "Partner Supported Rate Center information for the indicated set of ratecenters, containing City, State, LATA and the list of TNs for which that Rate Center applies. \nThe Tier information is provided for offnet rate centers.", "type": "object", "properties": { "RateCenterGroup": { @@ -20295,7 +20295,7 @@ } }, "SupportedLosingCarriers": { - "description": "Supported Losing Carriers (unavailable for Enterprise Telephony users)", + "description": "Details on Supported Losing Carriers (unavailable for Enterprise Telephony users) including name, SPID, whether or not the carrier is a wireless carrier, whether or not account number is required as part of the CSR check, and the anticipated minimum number of days before a FoC date will be granted.", "type": "object", "properties": { "LosingCarrierTnList": { @@ -20304,7 +20304,7 @@ } }, "UnsupportedLosingCarriers": { - "description": "Unsupported Losing Carriers (unavailable for Enterprise Telephony users)", + "description": "Unsupported Losing Carriers (unavailable for Enterprise Telephony users) including name, SPID, whether or not the carrier is a wireless carrier, whether or not account number is required as part of the CSR check, and the anticipated minimum number of days before a FoC date will be granted.", "type": "object", "properties": { "LosingCarrierTnList": { From adb39411253182ee94db0cb65fc38f57ec791c11 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Fri, 8 Jul 2022 18:43:11 +0300 Subject: [PATCH 06/20] Porting - add code examples --- site/docs/numbers/porting/portingNumbers.mdx | 420 +++++++++++++++---- 1 file changed, 334 insertions(+), 86 deletions(-) diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 0018c734a..084680a20 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -1,6 +1,6 @@ --- id: portingNumbers -title: Create Portin +title: Port-in numbers slug: /numbers/guides/porting/portingNumbers description: How to port numbers using the Bandwidth API keywords: @@ -42,103 +42,351 @@ The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting The API allows a user to create a new LNP order. An order number will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. -As in other asynchronous workflows, the request to port in a number is created by a POST to a resource dedicated to the purpose to tracking requests – the `accounts/{accountId}/portins` resource. - -### Polling vs. Webhooks - -Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP "order". The orders are then processed and the order status is updated asynchronously. Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. - -Order processing times can vary and are not guaranteed, so bandwidth recommends relying on a webhook update from an portins subscription. - ### Request URL POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins ### Examples -> Request + + ```xml -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= - - - 2016-03-25T21:15:00.000Z - X455 - 9195551234 - 9175131245 - 12345 - 660123 - - BUSINESS - First - Last - - 11235 - Back - Denver - CO - 27541 - Canyon - - - The Authguy - - 771297665AABC - 1234 - - - 9195551234 - 9195554321 - - true - + Note: Remember to add authentication for your application if needed! + + https://dashboard.bandwidth.com/api/accounts/{accountId}/portins + //Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + + 2016-03-25T21:15:00.000Z + X455 + 9195551234 + 9175131245 + 12345 + 660123 + + BUSINESS + First + Last + + 11235 + Back + Denver + CO + 27541 + Canyon + + + The Authguy + + 771297665AABC + 1234 + + + 9195551234 + 9195554321 + + true + ``` -> Response + + -```xml -HTTP 201 Created -Content-Type: application/xml; charset=utf-8 - - - - 03f194d5-3932-4e9f-8ba1-03ef767985e5 - - 201 - Order request received. Please use the order id to check the status of your order later. - - PENDING_DOCUMENTS - 2016-03-25T21:15:00.000Z - The Authguy - - BUSINESS - First - Last - - 11235 - Back - Denver - CO - 27541 - Canyon - United States - - - - 771297665AABC - 1234 - - 9195551234 - 9175131245 - - 9195551234 - 9195554321 - - true - +```cURL + Note: Remember to add authentication for your application if needed! + + curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ + -X POST \ + -U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ + -H 'Content-Type: application/xml' \ + -d ' + 2016-03-25T21:15:00.000Z + X455 + 9195551234 + 9175131245 + 12345 + 660123 + + BUSINESS + First + Last + + 11235 + Back + Denver + CO + 27541 + Canyon + + + The Authguy + + 771297665AABC + 1234 + + + 9195551234 + 9195554321 + + true + ' +``` + + + + +```java +import com.bandwidth.BandwidthClient; +import com.bandwidth.http.response.ApiResponse; +import com.bandwidth.voice.models.CreateCallRequest; +import com.bandwidth.voice.models.CreateCallResponse; + +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ExecutionException; + +public class Sample { + + public static void main(String[] args) { + String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); + String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); + String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); + String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); + + IrisClient client = new IrisClient(accountId, username, password); + + Subscriber s = new Subscriber(); + s.setSubscriberType("BUSINESS"); + s.setBusinessName("Company"); + ServiceAddress serviceAddress = new ServiceAddress(); + serviceAddress.setHouseNumber("123"); + serviceAddress.setStreetName("Anywhere St"); + serviceAddress.setCity("Raleigh"); + serviceAddress.setStateCode("NC"); + serviceAddress.setZip("27609"); + s.setServiceAddress(serviceAddress); + + LnpOrder order = new LnpOrder(); + order.setSiteId(getFirstSite().getId()); + order.setPeerId(getFirstSipPeer().getPeerId()); + order.setBillingTelephoneNumber("9195551212"); + order.setSubscriber(s); + order.setLoaAuthorizingPerson("Joe Blow"); + order.getListOfPhoneNumbers().add("9195551212"); + + try { + order = LnpOrder.create(client, order); + System.out.println(order); + } catch (InterruptedException | ExecutionException e) { + System.out.println(e.getMessage()); + } + } +} +``` + + + + +```csharp +using System; +using System.Threading.Tasks; +using Bandwidth.Standard; +using Bandwidth.Standard.Exceptions; +using Bandwidth.Standard.Voice.Models; + +class Program +{ + static async Task Main(string[] args) + { + var accountId = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ACCOUNT_ID"); + var username = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_USERNAME"); + var password = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_PASSWORD"); + var apiEndpoint = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ENDPOINT"); + + var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") + + var data = new PortIn + { + BillingTelephoneNumber = "+1-202-555-0158", + Subscriber = new Subscriber + { + SubscriberType = "BUSINESS", + BusinessName = "Company", + FirstName = "John", + LastName = "Doe", + ServiceAddress = new Address + { + City = "City", + StateCode = "State", + Country = "Country" + } + }, + PeerId = sipPeer.Id, + SiteId = site.Id + }; + try + { + var order = await PortIn.Create(_client, data); + } + catch (Bandwidth.Iris.BandwidthIrisException error) + { + Console.WriteLine(error.Message); + } + catch (Exception e) + { + Exception innerEx = e; + + while(innerEx != null) + { + string msg = innerEx.Message; + Console.WriteLine(msg); + innerEx = innerEx.InnerException; + } + } + } +} ``` + + + + +```ruby + require 'ruby-bandwidth-iris' + + BandwidthIris::Client.global_options = { + :account_id => 'accountId', + :username => 'userName', + :password => 'password' + } + + data = { + :site_id =>1234, + :peer_id => 5678, + :billing_telephone_number => "9195551212", + :subscriber => { + :subscriber_type => "BUSINESS", + :business_name => "Company", + :service_address => { + :house_number => "123", + :street_name => "EZ Street", + :city => "Raleigh", + :state_code => "NC", + :county => "Wake" + } + }, + :loa_authorizing_person => "Joe Blow", + :list_of_phone_numbers => { + :phone_number => ["9195551212"] + }, + :billing_type => "PORTIN" + } + + portin_response = BandwidthIris::PortIn.create(data) +``` + + + + +```js + var numbers = require("@bandwidth/numbers"); + + var data = { + siteId: 1234, + peerId: 5678, + billingTelephoneNumber: "9195551212", + subscriber: { + subscriberType: "BUSINESS", + businessName: "Company", + serviceAddress: { + houseNumber: "123", + streetName: "EZ Street", + city: "Raleigh", + stateCode: "NC", + county: "Wake" + } + }, + loaAuthorizingPerson: "Joe Blow", + listOfPhoneNumbers: { + phoneNumber: ["9195551212"] + }, + billingType: "PORTIN" + }; + + //Using client directly + var client = new numbers.Client("accountId", "userName", "password"); + numbers.PortIn.create(client, function(err, response){...}); + + //Or you can use default client instance (do this only once) + numbers.Client.globalOptions.accountId = "accountId"; + numbers.Client.globalOptions.userName = "userName"; + numbers.Client.globalOptions.password = "password"; + + //Default client will be used to do this call + numbers.PortIn.create(data, callback); + + numbers.PortIn.create(data, callback); +``` + + + + +```php + $accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); + $username = getenv("BANDWIDTH_API_USERNAME"); + $password = getenv("BANDWIDTH_API_PASSWORD"); + $apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); + + $client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); + $account = new \Iris\Account($accountId, $client); + + try { + $portin = $account->portins()->create(array( + "BillingTelephoneNumber" => "6882015002", + "Subscriber" => array( + "SubscriberType" => "BUSINESS", + "BusinessName" => "Acme Corporation", + "ServiceAddress" => array( + "HouseNumber" => "1623", + "StreetName" => "Brockton Ave", + "City" => "Los Angeles", + "StateCode" => "CA", + "Zip" => "90025", + "Country" => "USA" + ) + ), + "LoaAuthorizingPerson" => "John Doe", + "ListOfPhoneNumbers" => array( + "PhoneNumber" => array("9882015025", "9882015026") + ), + "SiteId" => "365", + "Triggered" => "false" + )); + print_r($response->getResult()->callId); + } catch (BandwidthLib\APIException $e) { + print_r($e->getResponseCode()); + } +``` + + + + +### Polling vs. Webhooks + +Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP "order". The orders are then processed and the order status is updated asynchronously. Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. + +Order processing times can vary and are not guaranteed, so bandwidth recommends relying on a webhook update from an portins subscription. + You can retrieve an information about your Port in using a GET request to `/accounts/{accountId}/portins/{orderId}` ## Modify a Portin Order From 1115ef27c266360327455407c9c7afc115c00749 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Fri, 8 Jul 2022 19:47:07 +0300 Subject: [PATCH 07/20] Porting - add GET code examples --- site/docs/numbers/porting/portingNumbers.mdx | 164 ++++++++++++++++++- 1 file changed, 157 insertions(+), 7 deletions(-) diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 084680a20..393230680 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -237,7 +237,7 @@ class Program }; try { - var order = await PortIn.Create(_client, data); + var order = await PortIn.Create(client, data); } catch (Bandwidth.Iris.BandwidthIrisException error) { @@ -323,9 +323,9 @@ class Program billingType: "PORTIN" }; - //Using client directly - var client = new numbers.Client("accountId", "userName", "password"); - numbers.PortIn.create(client, function(err, response){...}); + // Using client directly + // var client = new numbers.Client("accountId", "userName", "password"); + // numbers.PortIn.create(client, function(err, response){...}); //Or you can use default client instance (do this only once) numbers.Client.globalOptions.accountId = "accountId"; @@ -334,8 +334,6 @@ class Program //Default client will be used to do this call numbers.PortIn.create(data, callback); - - numbers.PortIn.create(data, callback); ``` @@ -372,7 +370,6 @@ class Program "SiteId" => "365", "Triggered" => "false" )); - print_r($response->getResult()->callId); } catch (BandwidthLib\APIException $e) { print_r($e->getResponseCode()); } @@ -388,6 +385,159 @@ Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP Order processing times can vary and are not guaranteed, so bandwidth recommends relying on a webhook update from an portins subscription. You can retrieve an information about your Port in using a GET request to `/accounts/{accountId}/portins/{orderId}` + + + +```cURL +curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ +-X GET \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-H 'Accept: application/xml' +``` + + + + +```java +import com.bandwidth.BandwidthClient; +import com.bandwidth.http.response.ApiResponse; +import com.bandwidth.voice.models.CreateCallRequest; +import com.bandwidth.voice.models.CreateCallResponse; + +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ExecutionException; + +public class Sample { + + public static void main(String[] args) { + String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); + String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); + String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); + String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); + + IrisClient client = new IrisClient(accountId, username, password); + + try { + LnpOrder order = LnpOrder.get(client, "orderId"); + System.out.println(order); + } catch (InterruptedException | ExecutionException e) { + System.out.println(e.getMessage()); + } + } +} +``` + + + + +```csharp +using System; +using System.Threading.Tasks; +using Bandwidth.Standard; +using Bandwidth.Standard.Exceptions; +using Bandwidth.Standard.Voice.Models; + +class Program +{ + static async Task Main(string[] args) + { + var accountId = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ACCOUNT_ID"); + var username = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_USERNAME"); + var password = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_PASSWORD"); + var apiEndpoint = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ENDPOINT"); + + var client = Client.GetInstance(accountId, username, password, apiEndpoint) + + try + { + var portInOrder = PortIn.Get(client, "orderId"); + } + catch (Bandwidth.Iris.BandwidthIrisException error) + { + Console.WriteLine(error.Message); + } + catch (Exception e) + { + Exception innerEx = e; + + while(innerEx != null) + { + string msg = innerEx.Message; + Console.WriteLine(msg); + innerEx = innerEx.InnerException; + } + } + } +} +``` + + + + +```ruby +require 'ruby-bandwidth-iris' + +BandwidthIris::Client.global_options = { + :account_id => 'accountId', + :username => 'userName', + :password => 'password' +} +portIn = BandwidthIris::PortIn.get("portin_id", callback) +``` + + + + +```js +var numbers = require("@bandwidth/numbers"); + +// Using client directly +// var client = new numbers.Client("accountId", "userName", "password"); +// numbers.PortIn.create(client, function(err, response){...}); + +//Or you can use default client instance (do this only once) +numbers.Client.globalOptions.accountId = "accountId"; +numbers.Client.globalOptions.userName = "userName"; +numbers.Client.globalOptions.password = "password"; + +var orderId = "..."; +//Default client will be used to do this call +numbers.PortIn.get(orderId, callback) +``` + + + + +```php +$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); +$username = getenv("BANDWIDTH_API_USERNAME"); +$password = getenv("BANDWIDTH_API_PASSWORD"); +$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); + +$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); +$account = new \Iris\Account($accountId, $client); + +try { + $portin = $account->portins()->portin("d28b36f7-fa96-49eb-9556-a40fca49f7c6")); +} catch (BandwidthLib\APIException $e) { + print_r($e->getResponseCode()); +} +``` + + + ## Modify a Portin Order From ecc7aa3a6f0f7194108f58b0d9a305f4c00b51d2 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Fri, 8 Jul 2022 20:02:36 +0300 Subject: [PATCH 08/20] Porting - add PUT code examples --- site/docs/numbers/porting/portingNumbers.mdx | 260 ++++++++++++++++++- 1 file changed, 258 insertions(+), 2 deletions(-) diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 393230680..0ed8460d7 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -49,7 +49,7 @@ The API allows a user to create a new LNP order. An order number will be auto-ge ### Examples GET request to `/accounts/{accountId}/portins/{orderId}` PUT to `accounts/{accountId}/portins/{orderId}`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. For more details follow ....TODO + + + +```xml +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 +Content-Type: application/xml; charset=utf-8 +Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= + + + + SJM00002 + 2014-12-04T13:00:00.000Z + 8045030092 + 9175131245 + + 23453245 + 1111 + + + RESIDENTIAL + Steve + McKinnon + + + true + 115 + Monarch Way + Cary + NC + 27518 + + + 743 + true + + 2019721004 + 2019721005 + + Steve McKinnon + Foo + +``` + + + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + SJM00002 + 2014-12-04T13:00:00.000Z + 8045030092 + 9175131245 + + 23453245 + 1111 + + + RESIDENTIAL + Steve + McKinnon + + + true + 115 + Monarch Way + Cary + NC + 27518 + + + 743 + true + + 2019721004 + 2019721005 + + Steve McKinnon + Foo +' +``` + + + + +```java +import com.bandwidth.BandwidthClient; +import com.bandwidth.http.response.ApiResponse; +import com.bandwidth.voice.models.CreateCallRequest; +import com.bandwidth.voice.models.CreateCallResponse; + +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ExecutionException; + +public class Sample { + + public static void main(String[] args) { + String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); + String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); + String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); + String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); + + IrisClient client = new IrisClient(accountId, username, password); + + LnpOrderSupp order = new LnpOrderSupp(); + order.setSiteId(getFirstSite().getId()); + order.setPeerId(getFirstSipPeer().getPeerId()); + // ... + + try { + portIn = BandwidthIris::PortIn.get("portin_id", callback) + order.update(client, LnpOrderSupp supp); + System.out.println(order); + } catch (InterruptedException | ExecutionException e) { + System.out.println(e.getMessage()); + } + } +} +``` + + + + +```csharp +using System; +using System.Threading.Tasks; +using Bandwidth.Standard; +using Bandwidth.Standard.Exceptions; +using Bandwidth.Standard.Voice.Models; + +class Program +{ + static async Task Main(string[] args) + { + var accountId = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ACCOUNT_ID"); + var username = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_USERNAME"); + var password = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_PASSWORD"); + var apiEndpoint = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ENDPOINT"); + + var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") + + var data = new PortIn + { + // ... + PeerId = sipPeer.Id, + SiteId = site.Id + }; + try + { + var portInOrder = PortIn.Get("orderId"); + portInOrder.Update(data); + } + catch (Bandwidth.Iris.BandwidthIrisException error) + { + Console.WriteLine(error.Message); + } + catch (Exception e) + { + Exception innerEx = e; + + while(innerEx != null) + { + string msg = innerEx.Message; + Console.WriteLine(msg); + innerEx = innerEx.InnerException; + } + } + } +} +``` + + + + +```ruby +require 'ruby-bandwidth-iris' + +BandwidthIris::Client.global_options = { +:account_id => 'accountId', +:username => 'userName', +:password => 'password' +} + +data = { + //... +} + +portIn = BandwidthIris::PortIn.get("portin_id", callback) +portIn.update(data) +``` + + + + +```js +var numbers = require("@bandwidth/numbers"); + +var data = { + // ... +}; + +numbers.Client.globalOptions.accountId = "accountId"; +numbers.Client.globalOptions.userName = "userName"; +numbers.Client.globalOptions.password = "password"; + +portIn.update(data, callback);; +``` + + + + +```php +$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); +$username = getenv("BANDWIDTH_API_USERNAME"); +$password = getenv("BANDWIDTH_API_PASSWORD"); +$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); + +$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); +$account = new \Iris\Account($accountId, $client); + +try { + $portin = $account->portins()->portin("d28b36f7-fa96-49eb-9556-a40fca49f7c6")); + $portin->update(array( + "BillingTelephoneNumber" => "6882015002", + "SiteId" => "365", + // ... + )); +} catch (BandwidthLib\APIException $e) { + print_r($e->getResponseCode()); +} +``` + + + + ## Cancel a Portin Order The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and dhe status of the order shall not be marked as `COMPLETE`. The DELETE method is used for this purpose. From a236db556bf59ecbbe58a7135611e0541bb61aec Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Wed, 13 Jul 2022 22:40:10 +0300 Subject: [PATCH 09/20] Porting - SUPP schemas --- site/docs/numbers/porting/portingNumbers.mdx | 595 ++++++++----------- site/docs/numbers/porting/updatePortin.mdx | 238 ++++++-- site/specs-temp/numbers.json | 434 +++++++++++--- 3 files changed, 764 insertions(+), 503 deletions(-) diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 0ed8460d7..242cf2892 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -31,17 +31,20 @@ export const Highlight = ({children, color}) => ( ); -The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. +The Bandwidth Phone Number `/portins` API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. -The `/portins` API accepts Port-In requests. On order to successfully port telephone numbers they need to correspond to a set of criteria. To learn more follow the [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) guide. +## Create a Portin Order -Bandwidth also supports an alternative way to port in numbers. -The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/bulkPortins). +In order to successfully port telephone numbers they need to correspond to a set of criteria. All these are listed in [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) guide. -## Create a Portin Order +:::info +As an alternative to current feature the `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/bulkPortins). +::: The API allows a user to create a new LNP order. An order number will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. +To create Port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. + ### Request URL POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins @@ -64,107 +67,105 @@ The API allows a user to create a new LNP order. An order number will be auto-ge ```xml - Note: Remember to add authentication for your application if needed! - - https://dashboard.bandwidth.com/api/accounts/{accountId}/portins - //Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD - - 2016-03-25T21:15:00.000Z - X455 - 9195551234 - 9175131245 - 12345 - 660123 - - BUSINESS - First - Last - - 11235 - Back - Denver - CO - 27541 - Canyon - - - The Authguy - - 771297665AABC - 1234 - - - 9195551234 - 9195554321 - - true - +Note: Remember to add authentication for your application if needed! + +https://dashboard.bandwidth.com/api/accounts/{accountId}/portins +//Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + + 2016-03-25T21:15:00.000Z + X455 + 9195551234 + 9175131245 + 12345 + 660123 + + BUSINESS + First + Last + + 11235 + Back + Denver + CO + 27541 + Canyon + + + The Authguy + + 771297665AABC + 1234 + + + 9195551234 + 9195554321 + + true + ``` ```cURL - Note: Remember to add authentication for your application if needed! - - curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ - -X POST \ - -U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ - -H 'Content-Type: application/xml' \ - -d ' - 2016-03-25T21:15:00.000Z - X455 - 9195551234 - 9175131245 - 12345 - 660123 - - BUSINESS - First - Last - - 11235 - Back - Denver - CO - 27541 - Canyon - - - The Authguy - - 771297665AABC - 1234 - - - 9195551234 - 9195554321 - - true - ' +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + 2016-03-25T21:15:00.000Z + X455 + 9195551234 + 9175131245 + 12345 + 660123 + + BUSINESS + First + Last + + 11235 + Back + Denver + CO + 27541 + Canyon + + + The Authguy + + 771297665AABC + 1234 + + + 9195551234 + 9195554321 + + true +' ``` ```java -import com.bandwidth.BandwidthClient; -import com.bandwidth.http.response.ApiResponse; -import com.bandwidth.voice.models.CreateCallRequest; -import com.bandwidth.voice.models.CreateCallResponse; - -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.ExecutionException; +import com.bandwidth.iris.sdk.IrisClient; +import com.bandwidth.iris.sdk.model.LnpOrder; +import com.bandwidth.iris.sdk.model.ServiceAddress; +import com.bandwidth.iris.sdk.model.Subscriber; -public class Sample { +public class Main { public static void main(String[] args) { String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); + String version = System.getenv("BANDWIDTH_IRIS_URL"); - IrisClient client = new IrisClient(accountId, username, password); + IrisClient client = new IrisClient(irisUrl, accountId, username, password, version); Subscriber s = new Subscriber(); s.setSubscriberType("BUSINESS"); @@ -178,8 +179,8 @@ public class Sample { s.setServiceAddress(serviceAddress); LnpOrder order = new LnpOrder(); - order.setSiteId(getFirstSite().getId()); - order.setPeerId(getFirstSipPeer().getPeerId()); + order.setSiteId("123"); + order.setPeerId("12345"); order.setBillingTelephoneNumber("9195551212"); order.setSubscriber(s); order.setLoaAuthorizingPerson("Joe Blow"); @@ -188,7 +189,7 @@ public class Sample { try { order = LnpOrder.create(client, order); System.out.println(order); - } catch (InterruptedException | ExecutionException e) { + } catch (Exception e) { System.out.println(e.getMessage()); } } @@ -199,180 +200,150 @@ public class Sample { ```csharp -using System; -using System.Threading.Tasks; -using Bandwidth.Standard; -using Bandwidth.Standard.Exceptions; -using Bandwidth.Standard.Voice.Models; +var accountId = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ACCOUNT_ID"); +var username = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_USERNAME"); +var password = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_PASSWORD"); +var apiEndpoint = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ENDPOINT"); + +var client = Client.GetInstance(accountId, username, password, apiEndpoint) -class Program +var data = new PortIn { - static async Task Main(string[] args) + BillingTelephoneNumber = "+1-202-555-0158", + Subscriber = new Subscriber { - var accountId = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ACCOUNT_ID"); - var username = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_USERNAME"); - var password = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_PASSWORD"); - var apiEndpoint = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ENDPOINT"); - - var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") - - var data = new PortIn - { - BillingTelephoneNumber = "+1-202-555-0158", - Subscriber = new Subscriber - { - SubscriberType = "BUSINESS", - BusinessName = "Company", - FirstName = "John", - LastName = "Doe", - ServiceAddress = new Address - { - City = "City", - StateCode = "State", - Country = "Country" - } - }, - PeerId = sipPeer.Id, - SiteId = site.Id - }; - try - { - var order = await PortIn.Create(client, data); - } - catch (Bandwidth.Iris.BandwidthIrisException error) - { - Console.WriteLine(error.Message); - } - catch (Exception e) + SubscriberType = "BUSINESS", + BusinessName = "Company", + FirstName = "John", + LastName = "Doe", + ServiceAddress = new Address { - Exception innerEx = e; - - while(innerEx != null) - { - string msg = innerEx.Message; - Console.WriteLine(msg); - innerEx = innerEx.InnerException; - } + City = "City", + StateCode = "State", + Country = "Country" } - } -} + }, + PeerId = "12345", + SiteId = "123" +}; +var order = await PortIn.Create(client, data); ``` ```ruby - require 'ruby-bandwidth-iris' +require 'ruby-bandwidth-iris' - BandwidthIris::Client.global_options = { - :account_id => 'accountId', - :username => 'userName', - :password => 'password' - } +BandwidthIris::Client.global_options = { + :account_id => 'accountId', + :username => 'userName', + :password => 'password' +} - data = { - :site_id =>1234, - :peer_id => 5678, - :billing_telephone_number => "9195551212", - :subscriber => { - :subscriber_type => "BUSINESS", - :business_name => "Company", - :service_address => { - :house_number => "123", - :street_name => "EZ Street", - :city => "Raleigh", - :state_code => "NC", - :county => "Wake" - } - }, - :loa_authorizing_person => "Joe Blow", - :list_of_phone_numbers => { - :phone_number => ["9195551212"] - }, - :billing_type => "PORTIN" - } +data = { + :site_id =>1234, + :peer_id => 5678, + :billing_telephone_number => "9195551212", + :subscriber => { + :subscriber_type => "BUSINESS", + :business_name => "Company", + :service_address => { + :house_number => "123", + :street_name => "EZ Street", + :city => "Raleigh", + :state_code => "NC", + :county => "Wake" + } + }, + :loa_authorizing_person => "Joe Blow", + :list_of_phone_numbers => { + :phone_number => ["9195551212"] + }, + :billing_type => "PORTIN" +} - portin_response = BandwidthIris::PortIn.create(data) +portin_response = BandwidthIris::PortIn.create(data) ``` ```js - var numbers = require("@bandwidth/numbers"); - - var data = { - siteId: 1234, - peerId: 5678, - billingTelephoneNumber: "9195551212", - subscriber: { - subscriberType: "BUSINESS", - businessName: "Company", - serviceAddress: { - houseNumber: "123", - streetName: "EZ Street", - city: "Raleigh", - stateCode: "NC", - county: "Wake" - } - }, - loaAuthorizingPerson: "Joe Blow", - listOfPhoneNumbers: { - phoneNumber: ["9195551212"] - }, - billingType: "PORTIN" - }; - - // Using client directly - // var client = new numbers.Client("accountId", "userName", "password"); - // numbers.PortIn.create(client, function(err, response){...}); - - //Or you can use default client instance (do this only once) - numbers.Client.globalOptions.accountId = "accountId"; - numbers.Client.globalOptions.userName = "userName"; - numbers.Client.globalOptions.password = "password"; - - //Default client will be used to do this call - numbers.PortIn.create(data, callback); +var numbers = require("@bandwidth/numbers"); + +var data = { + siteId: 1234, + peerId: 5678, + billingTelephoneNumber: "9195551212", + subscriber: { + subscriberType: "BUSINESS", + businessName: "Company", + serviceAddress: { + houseNumber: "123", + streetName: "EZ Street", + city: "Raleigh", + stateCode: "NC", + county: "Wake" + } + }, + loaAuthorizingPerson: "Joe Blow", + listOfPhoneNumbers: { + phoneNumber: ["9195551212"] + }, + billingType: "PORTIN" +}; + +// Using client directly +// var client = new numbers.Client("accountId", "userName", "password"); +// numbers.PortIn.create(client, function(err, response){...}); + +//Or you can use default client instance (do this only once) +numbers.Client.globalOptions.accountId = "accountId"; +numbers.Client.globalOptions.userName = "userName"; +numbers.Client.globalOptions.password = "password"; + +//Default client will be used to do this call +numbers.PortIn.create(data, callback); ``` ```php - $accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); - $username = getenv("BANDWIDTH_API_USERNAME"); - $password = getenv("BANDWIDTH_API_PASSWORD"); - $apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); - - $client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); - $account = new \Iris\Account($accountId, $client); - - try { - $portin = $account->portins()->create(array( - "BillingTelephoneNumber" => "6882015002", - "Subscriber" => array( - "SubscriberType" => "BUSINESS", - "BusinessName" => "Acme Corporation", - "ServiceAddress" => array( - "HouseNumber" => "1623", - "StreetName" => "Brockton Ave", - "City" => "Los Angeles", - "StateCode" => "CA", - "Zip" => "90025", - "Country" => "USA" - ) - ), - "LoaAuthorizingPerson" => "John Doe", - "ListOfPhoneNumbers" => array( - "PhoneNumber" => array("9882015025", "9882015026") - ), - "SiteId" => "365", - "Triggered" => "false" - )); - } catch (BandwidthLib\APIException $e) { - print_r($e->getResponseCode()); - } +$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); +$username = getenv("BANDWIDTH_API_USERNAME"); +$password = getenv("BANDWIDTH_API_PASSWORD"); +$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); + +$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); +$account = new \Iris\Account($accountId, $client); + +try { + $portin = $account->portins()->create(array( + "BillingTelephoneNumber" => "6882015002", + "Subscriber" => array( + "SubscriberType" => "BUSINESS", + "BusinessName" => "Acme Corporation", + "ServiceAddress" => array( + "HouseNumber" => "1623", + "StreetName" => "Brockton Ave", + "City" => "Los Angeles", + "StateCode" => "CA", + "Zip" => "90025", + "Country" => "USA" + ) + ), + "LoaAuthorizingPerson" => "John Doe", + "ListOfPhoneNumbers" => array( + "PhoneNumber" => array("9882015025", "9882015026") + ), + "SiteId" => "365", + "Triggered" => "false" + )); +} catch (BandwidthLib\APIException $e) { + print_r($e->getResponseCode()); +} ``` @@ -380,11 +351,9 @@ class Program ### Polling vs. Webhooks -Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP "order". The orders are then processed and the order status is updated asynchronously. Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. +Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP "order". The orders are then processed and the order status is updated asynchronously. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. Please follow the [How to setup Notification Webhook](/numbers/webhooks/orderWebhook/orderWebhook) guide. -Order processing times can vary and are not guaranteed, so bandwidth recommends relying on a webhook update from an portins subscription. - -You can retrieve an information about your Port in using a GET request to `/accounts/{accountId}/portins/{orderId}` +To poll an information about your Port in using a GET request to `/accounts/{accountId}/portins/{orderId}` ```csharp -using System; -using System.Threading.Tasks; -using Bandwidth.Standard; -using Bandwidth.Standard.Exceptions; -using Bandwidth.Standard.Voice.Models; - -class Program -{ - static async Task Main(string[] args) - { - var accountId = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ACCOUNT_ID"); - var username = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_USERNAME"); - var password = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_PASSWORD"); - var apiEndpoint = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ENDPOINT"); - - var client = Client.GetInstance(accountId, username, password, apiEndpoint) - - try - { - var portInOrder = PortIn.Get(client, "orderId"); - } - catch (Bandwidth.Iris.BandwidthIrisException error) - { - Console.WriteLine(error.Message); - } - catch (Exception e) - { - Exception innerEx = e; - - while(innerEx != null) - { - string msg = innerEx.Message; - Console.WriteLine(msg); - innerEx = innerEx.InnerException; - } - } - } -} +var client = Client.GetInstance(accountId, username, password, apiEndpoint) +var portInOrder = PortIn.Get(client, "orderId"); ``` @@ -541,8 +475,8 @@ try { ## Modify a Portin Order -The API allows a user to modify an existing LNP order, called a SUPP request. Modifications are only allowed for orders that are not yet complete or cancelled. LNP orders can be modified with a PUT to `accounts/{accountId}/portins/{orderId}`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. -For more details follow ....TODO +The API allows a user to modify an existing LNP order, called a SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. LNP orders can be modified with a PUT to `accounts/{accountId}/portins/{orderId}`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. +For more details check our [PUT /portins](/apis/numbers/#operation/UpdatePortin) endpoint ```java -import com.bandwidth.BandwidthClient; -import com.bandwidth.http.response.ApiResponse; -import com.bandwidth.voice.models.CreateCallRequest; -import com.bandwidth.voice.models.CreateCallResponse; - -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.ExecutionException; - -public class Sample { +String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); +String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); +String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); +String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); +String version = System.getenv("BANDWIDTH_IRIS_URL"); - public static void main(String[] args) { - String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); - String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); - String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); - String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); +IrisClient client = new IrisClient(accountId, username, password, irisUrl, version); - IrisClient client = new IrisClient(accountId, username, password); +LnpOrderSupp supp = new LnpOrderSupp(); +supp.setSiteId("123"); +supp.setPeerId("12345"); +// ... - LnpOrderSupp order = new LnpOrderSupp(); - order.setSiteId(getFirstSite().getId()); - order.setPeerId(getFirstSipPeer().getPeerId()); - // ... - - try { - portIn = BandwidthIris::PortIn.get("portin_id", callback) - order.update(client, LnpOrderSupp supp); - System.out.println(order); - } catch (InterruptedException | ExecutionException e) { - System.out.println(e.getMessage()); - } - } +try { + LnpOrder order = LnpOrder.get(client, "orderId"); + order.update(supp); + System.out.println(order); +} catch (Exception e) { + System.out.println(e.getMessage()); } ``` @@ -689,51 +611,16 @@ public class Sample { ```csharp -using System; -using System.Threading.Tasks; -using Bandwidth.Standard; -using Bandwidth.Standard.Exceptions; -using Bandwidth.Standard.Voice.Models; +var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") -class Program +var data = new PortIn { - static async Task Main(string[] args) - { - var accountId = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ACCOUNT_ID"); - var username = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_USERNAME"); - var password = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_PASSWORD"); - var apiEndpoint = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ENDPOINT"); - - var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") - - var data = new PortIn - { - // ... - PeerId = sipPeer.Id, - SiteId = site.Id - }; - try - { - var portInOrder = PortIn.Get("orderId"); - portInOrder.Update(data); - } - catch (Bandwidth.Iris.BandwidthIrisException error) - { - Console.WriteLine(error.Message); - } - catch (Exception e) - { - Exception innerEx = e; - - while(innerEx != null) - { - string msg = innerEx.Message; - Console.WriteLine(msg); - innerEx = innerEx.InnerException; - } - } - } -} + // ... + PeerId = "12345", + SiteId = "123" +}; +var portInOrder = PortIn.Get("orderId"); +portInOrder.Update(data); ``` diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx index 5cad35e38..643c60995 100644 --- a/site/docs/numbers/porting/updatePortin.mdx +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -35,41 +35,10 @@ export const Highlight = ({children, color}) => ( In this guide we will show you how to manage your Port in order. Please ensure you have followed our earlier guide on [How to create Port in order](/docs/numbers/guides/porting/updatePortin) with Bandwidth. -## Modify a Portin Order - -The PUT to `accounts/{accountId}/portins/{orderId}` API allows a user to modify an existing LNP order, by sending a so-called a SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. - -Items that can be included in a SUPP request include: - -* CustomerOrderId -* RequestedFocDate -* BillingTelephoneNumber -* NewBillingTelephoneNumber -* AccountNumber -* PinNumber -* TnAttributes elements -* Subscriber elements -* SiteId -* PeerId -* PartialPort -* LoaAuthorizingPerson -* ListOfPhoneNumbers -* Triggered -* Immediately +The PUT to `accounts/{accountId}/portins/{orderId}` API allows a user to modify an existing LNP order, by sending a so-called SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. If the order ProcessingStatus is `DRAFT`, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from `DRAFT` to `SUBMITTED`. The AltSpid element can be modified if it is not configured at the system level. -`ProcessingStatus` - you can only provide this field with a value of SUBMITTED if the current ProcessingStatus of the port-in is DRAFT. - -When a port-in is being processed by off-net partner Level 3 (you can retrieve this information using a GET request to `/portins/{orderId}` indicates a Port Type of AUTOMATEDOFFNET and a VendorName of "Level 3"), the rules for what can be changed in a SUPP operation are more restrictive. If the order has NOT yet received FOC, you may change the following: - -* RequestedFocDate -* BillingTelephoneNumber -* SubscriberType -* Subscriber name elements or BusinessName, provided that SubscriberType is provided - -After the FOC date has been received, the billing telephone number and subscriber information cannot be modified, only the FOC date/time can be updated. - The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. Please refer to the matrix below to see which elements can be modified and replaced. | Payload Field | Manual Off-Net | Manual On-Net | Manual Toll Free | Automated On-Net | Automated Off-Net Pre FOC | Automated Off-Net Post FOC | Internal | @@ -91,38 +60,35 @@ The general approach to handling this API call is to replace the elements includ | TnAttributes elements | Editable | Editable | Editable | Editable | Editable | Editable | Editable | | Immediately | Disabled | Disabled | Disabled | Disabled | Disabled | Disabled | Editable | -### SUPP Order Field Notes - -* `AccountNumber` - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both. -* `AlternateSpid` - Not applicable to toll free port-ins. Can only be modified in DRAFT state. Can only be modified if it is not configured at the system level. -* `BillingTelephoneNumber` - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. -* `BusinessName` - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. -* `CustomerOrderId` - Can always be updated. This field is removed from the order if not provided in the PUT payload. -* `Immediately` - Only applicable to Internal port-in orders. May be included in the PUT payload, but cannot be changed in a SUPP. -* `ListOfPhoneNumbers` - Can be SUPPed only for Automated on-net port-ins and toll free port-ins. For toll free port-ins, may be SUPPed only in draft states (i.e. DRAFT, VALIDATE_DRAFT_TFNS, VALID_DRAFT_TFNS, or INVALID_DRAFT_TFNS). -* `LoaAuthorizingPerson` - Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. -* `NewBillingTelephoneNumber` - Not applicable to toll free port-ins or Automated off-net port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins. -* `OverrideValidation` - Applies only to internal ports. This Bandwidth internal flag forces port-out to bypass validity checking (if there are no terminal errors). This flag can be SUPPed only for orders in EXCEPTION status. -* `PartialPort` - Not applicable to toll free port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. -* `PeerId` - Can always be updated. -* `PinNumber` - Element of WirelessInfo. Not applicable to toll free port-ins. Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both. -* `ProcessingStatus` - May only be SUPPed for port-in orders in draft state. The only valid value is “SUBMITTED” (not case sensitive). -* `RequestedFocDate` - Can always be updated, but subject to blackout windows if the current date is too close to an assigned FOC date. -* `ResetAddressFields` - Not applicable to toll free port-ins. If included with a value of true, any Subscriber elements, including subscriber type, subscriber/business name elements, and service address elements, NOT included in the PUT payload will be removed from the order. -* `ServiceAddress` - Element of Subscriber. Includes all address fields. ServiceAddress elements cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins. See also, ResetAddressFields. -* `SiteId` - Can always be updated. -* `SubscriberName` - Element of Subscriber. Includes FirstName, MiddleInitial, and LastName. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. -* `SubscriberType` - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received. If SubscriberType is set to BUSINESS, a BusinessName must be provided. If SubscriberType is set to RESIDENTIAL, a FirstName and LastName must be provided. -* `TnAttributes` - Can be SUPPed prior to completion of the port-in request. -* `Triggered` - May be included in the PUT payload, but cannot be changed in a SUPP. +### Level3 Portin + +When a port-in is being processed by off-net partner Level 3 (you can retrieve this information using a GET request to `/portins/{orderId}` indicates a Port Type of AUTOMATEDOFFNET and a VendorName of "Level 3"), the rules for what can be changed in a SUPP operation are more restrictive. If the order has NOT yet received FOC, you may change the following: + +* RequestedFocDate +* BillingTelephoneNumber +* SubscriberType +* Subscriber name elements or BusinessName, provided that SubscriberType is provided + +After the FOC date has been received, the billing telephone number and subscriber information cannot be modified, only the FOC date/time can be updated. ### Request URL PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} -### Examples - -> Request + + ```xml PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 @@ -166,7 +132,159 @@ Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= ``` -> Response + + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' +SJM00002 +2014-12-04T13:00:00.000Z +8045030092 +9175131245 + + 23453245 + 1111 + + + RESIDENTIAL + Steve + McKinnon + + + true + 115 + Monarch Way + Cary + NC + 27518 + + +743 +true + + 2019721004 + 2019721005 + +Steve McKinnon +Foo +' +``` + + + + +```java +String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); +String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); +String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); +String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); +String version = System.getenv("BANDWIDTH_IRIS_URL"); + +IrisClient client = new IrisClient(accountId, username, password, irisUrl, version); + +LnpOrderSupp supp = new LnpOrderSupp(); +supp.setSiteId("123"); +supp.setPeerId("12345"); +// ... + +try { + LnpOrder order = LnpOrder.get(client, "orderId"); + order.update(supp); + System.out.println(order); +} catch (Exception e) { + System.out.println(e.getMessage()); +} +``` + + + + +```csharp +var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") + +var data = new PortIn +{ + // ... + PeerId = "12345", + SiteId = "123" +}; +var portInOrder = PortIn.Get("orderId"); +portInOrder.Update(data); +``` + + + + +```ruby +require 'ruby-bandwidth-iris' + +BandwidthIris::Client.global_options = { +:account_id => 'accountId', +:username => 'userName', +:password => 'password' +} + +data = { +//... +} + +portIn = BandwidthIris::PortIn.get("portin_id", callback) +portIn.update(data) +``` + + + + +```js +var numbers = require("@bandwidth/numbers"); + +var data = { +// ... +}; + +numbers.Client.globalOptions.accountId = "accountId"; +numbers.Client.globalOptions.userName = "userName"; +numbers.Client.globalOptions.password = "password"; + +portIn.update(data, callback);; +``` + + + + +```php +$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); +$username = getenv("BANDWIDTH_API_USERNAME"); +$password = getenv("BANDWIDTH_API_PASSWORD"); +$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); + +$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); +$account = new \Iris\Account($accountId, $client); + +try { + $portin = $account->portins()->portin("d28b36f7-fa96-49eb-9556-a40fca49f7c6")); + $portin->update(array( + "BillingTelephoneNumber" => "6882015002", + "SiteId" => "365", + // ... + )); +} catch (BandwidthLib\APIException $e) { + print_r($e->getResponseCode()); +} +``` + + + + +> Postman/cURL Response Example ```xml HTTP 200 OK diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index a6457968d..e37eab632 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -10339,7 +10339,7 @@ "/accounts", "Porting" ], - "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing LNP order. This is done via a PUT on the existing order-id. If a field is present in the PUT /portins/{orderId} payload, the value of the field will be updated for the order, subject to existing rules about the field. If a field is NOT present in the PUT /portins/{orderId} payload, behavior varies as to whether the missing field is removed from the port-in, set to a default value, or left unchanged. As a result, we STRONGLY RECOMMEND performing a GET on the order and copying those element values to the PUT for any elements you are not explicitly trying to change the value of.

Note:

  • If the order ProcessingStatus is DRAFT, the rules about what can be changed are much more relaxed. Most of the validation is performed when the ProcessingStatus is changed from DRAFT to SUBMITTED. If SUPP is performed on a draft portin, no validations are applied except validation of the ListOfPhoneNumbers, if at least 1 PhoneNumber is provided.
  • If the port-in order is associated with a bulk port-in which is in DRAFT state, it is not possible to change its state from DRAFT to SUBMITTED without detaching it from the bulk port-in. Alternatively, submitting the parent bulk port-in will trigger the submission of child port-in orders.

Per-field notes about SUPP:

\n\n
    \n
  • AccountNumber - Element of WirelessInfo. Not applicable to toll free port-ins.\n Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo, you must\n include both AccountNumber and PinNumber in the payload, even if you are not
    • \n
  • BillingTelephoneNumber - Not applicable to toll free port-ins. Cannot be SUPPed for\n Automated on-net wireless to wireless port-ins or Automated off-net port-ins after FOC received.
    • \n
  • BusinessName - Element of Subscriber. Cannot be SUPPed for Automated on-net wireless\n to wireless port-ins or Automated off-net port-ins after FOC received.
    • \n
  • CustomerOrderId - Can always be updated. This field is removed from the order if\n not provided in the PUT payload.
    • \n
  • Immediately - Only applicable to Internal port-in orders. May be included in the\n PUT payload, but cannot be changed in a SUPP.
    • \n
  • ListOfPhoneNumbers - Can be SUPPed only for Automated on-net port-ins and toll free port-ins.\n For toll free port-ins, may be SUPPed only in draft states (i.e. DRAFT, VALIDATE_DRAFT_TFNS, VALID_DRAFT_TFNS, or INVALID_DRAFT_TFNS).
    • \n
  • LoaAuthorizingPerson - Cannot be SUPPed for Automated on-net wireless to wireless\n port-ins or Automated off-net port-ins.
    • \n
  • NewBillingTelephoneNumber - Not applicable to toll free port-ins or Automated\n off-net port-ins. Cannot be SUPPed for Automated on-net wireless to wireless port-ins.
    • \n
  • PartialPort - Not applicable to toll free port-ins. Cannot be SUPPed for Automated\n on-net wireless to wireless port-ins or Automated off-net port-ins.
    • \n
  • PeerId - Can always be updated.
    • \n
  • PinNumber - Element of WirelessInfo. Not applicable to toll free port-ins.\n Cannot be SUPPed for Automated off-net port-ins. If you want to SUPP WirelessInfo,\n you must include both AccountNumber and PinNumber in the payload, even if you are not\n changing both.
    • \n
  • RequestedFocDate - Can always be updated, but subject to blackout windows\n if the current date is too close to an assigned FOC date.
    • \n
  • ResetAddressFields - Not applicable to toll free port-ins. If included with a\n value of true, any Subscriber elements, including subscriber type, subscriber/business name\n elements, and service address elements, NOT included in the PUT payload will be removed from\n the order.
    • \n
  • RetryValidation - When toll free numbers are included in a port-in order,\n Bandwidth accesses a vendor to determine if the numbers are portable, and if so, from\n which RespOrg. In the event that we do not receive a response from our vendor after a\n number of retries, we give up and place the order in the INVALID_TFNS or\n INVALID_DRAFT_TFNS state. This scenario can occur if our toll free porting vendor is\n performing maintenance, for example. Including RetryValidation with a value of true will\n cause the order to return to VALIDATE_TFNS or VALIDATE_DRAFT_TFNS and we will repeat our\n attempts to retrieve the portability data from the vendor. This element is included in\n the synchronous response to the PUT, when included in the request, but is not included\n in subsequent GET requests for the order.
    • \n
  • ServiceAddress - Element of Subscriber. Includes all address fields.\n ServiceAddress elements cannot be SUPPed for Automated on-net wireless to wireless port-ins\n or Automated off-net port-ins. See also, ResetAddressFields.
    • \n
  • SiteId - Can always be updated.
    • \n
  • Subscriber Name - Element of Subscriber. Includes FirstName,\n MiddleInitial, and LastName. Cannot be SUPPed for Automated on-net wireless to\n wireless port-ins or Automated off-net port-ins after FOC received.
    • \n
  • SubscriberType - Element of Subscriber. Cannot be SUPPed for Automated on-net\n wireless to wireless port-ins or Automated off-net port-ins after FOC received. If SubscriberType\n is set to BUSINESS, a BusinessName must be provided. If SubscriberType is set to RESIDENTIAL, a\n FirstName and LastName must be provided.
    • \n
  • TnAttributes - Attributes to be assigned to the telephone number. Possible values - \"Protected\".
    • \n
\n", + "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing LNP order. This is done via a PUT on the existing order-id. If a field is present in the PUT /portins/{orderId} payload, the value of the field will be updated for the order, subject to existing rules about the field. If a field is NOT present in the PUT /portins/{orderId} payload, behavior varies as to whether the missing field is removed from the port-in, set to a default value, or left unchanged. As a result, we STRONGLY RECOMMEND performing a GET on the order and copying those element values to the PUT for any elements you are not explicitly trying to change the value of.

Note:

  • If the order ProcessingStatus is DRAFT, the rules about what can be changed are much more relaxed. Most of the validation is performed when the ProcessingStatus is changed from DRAFT to SUBMITTED. If SUPP is performed on a draft portin, no validations are applied except validation of the ListOfPhoneNumbers, if at least 1 PhoneNumber is provided.
  • If the port-in order is associated with a bulk port-in which is in DRAFT state, it is not possible to change its state from DRAFT to SUBMITTED without detaching it from the bulk port-in. Alternatively, submitting the parent bulk port-in will trigger the submission of child port-in orders.

\n", "operationId": "UpdatePortin", "summary": "Update port-in order", "parameters": [ @@ -10373,7 +10373,62 @@ } }, "schema": { - "$ref": "#/components/schemas/LnpOrderSuppRequest" + "oneOf": [ + { + "type": "object", + "title": "Automated Off-Net", + "properties": { + "LnpOrderSupp": { + "$ref": "#/components/schemas/LnpOrderSuppAutomatedOffNet" + } + } + }, + { + "type": "object", + "title": "Toll-Free", + "properties": { + "LnpOrderSupp": { + "$ref": "#/components/schemas/LnpOrderSuppManualTollFree" + } + } + }, + { + "type": "object", + "title": "Manual Off/On Net", + "properties": { + "LnpOrderSupp": { + "$ref": "#/components/schemas/LnpOrderSuppManualOnNetOffNet" + } + } + }, + { + "type": "object", + "title": "Automated On-Net", + "properties": { + "LnpOrderSupp": { + "$ref": "#/components/schemas/LnpOrderSuppAutomatedOnNet" + } + } + }, + { + "type": "object", + "title": "Automated On-Net wireless to wireless", + "properties": { + "LnpOrderSupp": { + "$ref": "#/components/schemas/LnpOrderSuppAutomatedOnNetWireless" + } + } + }, + { + "type": "object", + "title": "Internal", + "properties": { + "LnpOrderSupp": { + "$ref": "#/components/schemas/LnpOrderSuppInternal" + } + } + } + ] } } } @@ -21162,10 +21217,6 @@ "type": "string", "description": "Subscriber last name." }, - "Name": { - "type": "string", - "description": "" - }, "ServiceAddress": { "type": "object", "properties": { @@ -22692,6 +22743,53 @@ } } }, + "FileMetaData": { + "type": "object", + "properties": { + "DocumentName": { + "type": "string" + }, + "DocumentType": { + "type": "string", + "enum": [ + "LOA", + "INVOICE", + "CSR", + "OTHER" + ] + } + } + }, + "FileMetaDataRequest": { + "type": "object", + "properties": { + "FileMetaData": { + "type": "object", + "properties": { + "DocumentName": { + "type": "string" + }, + "DocumentType": { + "type": "string", + "enum": [ + "LOA", + "INVOICE", + "CSR", + "OTHER" + ] + } + } + } + } + }, + "PhoneNumber": { + "type": "object", + "properties": { + "PhoneNumber": { + "type": "string" + } + } + }, "LnpOrderBasic": { "type": "object", "properties": { @@ -22795,7 +22893,7 @@ }, "TollFreeLnpOrderRequest": { "type": "object", - "title": "Toll free Lnp request", + "title": "Toll free", "description": "Manual indicates that the port-in will be processed manually by Bandwidth’s Local Number Portability team. Currently all toll free port-ins are handled manually by Bandwidth’s Local Number Portability team. But Bandwidth is in the process of automating portions of toll free porting, with a goal of eventually automating the entire process.", "properties": { "LnpOrder": { @@ -22809,7 +22907,7 @@ }, "OnNetLnpOrderRequest": { "type": "object", - "title": "On-net Lnp request", + "title": "On-net", "properties": { "LnpOrder": { "allOf": [ @@ -22853,7 +22951,7 @@ }, "InternalLnpOrderRequest": { "type": "object", - "title": "On-net Lnp request", + "title": "Internal", "properties": { "LnpOrder": { "allOf": [ @@ -22893,7 +22991,7 @@ }, "OffNetLnpOrderRequest": { "type": "object", - "title": "Off-net Lnp request", + "title": "Off-net", "properties": { "LnpOrder": { "allOf": [ @@ -22933,7 +23031,7 @@ "maxLength": 25 }, "ServiceAddress": { - "$ref": "#/components/schemas/PortinSubscriberServiceAddress" + "$ref": "#/components/schemas/PortinCreateSubscriberServiceAddress" } }, "required": [ @@ -22965,7 +23063,7 @@ "maxLength": 25 }, "ServiceAddress": { - "$ref": "#/components/schemas/PortinSubscriberServiceAddress" + "$ref": "#/components/schemas/PortinCreateSubscriberServiceAddress" } }, "required": [ @@ -22975,7 +23073,50 @@ "LastName" ] }, - "PortinSubscriberServiceAddress": { + "PortinSubscriberSupp": { + "type": "object", + "title": "Subscriber", + "properties": { + "SubscriberType": { + "type": "string", + "description": "If SubscriberType is set to BUSINESS, a BusinessName must be provided. If SubscriberType is set to RESIDENTIAL, a FirstName and LastName must be provided.", + "enum": [ + "business", + "residential", + "generic" + ] + }, + "BusinessName": { + "type": "string" + }, + "FirstName": { + "type": "string" + }, + "MiddleInitial": { + "type": "string" + }, + "LastName": { + "type": "string" + }, + "ServiceAddress": { + "$ref": "#/components/schemas/PortinPutSubscriberServiceAddress" + } + } + }, + "WirelessInfoSupp": { + "type": "object", + "title": "WirelessInfo", + "description": "If you want to SUPP WirelessInfo, you must include both AccountNumber and PinNumber in the payload, even if you are not changing both.", + "properties": { + "AccountNumber": { + "type": "string" + }, + "PinNumber": { + "type": "string" + } + } + }, + "PortinSubscriberBasicServiceAddress": { "type": "object", "title": "ServiceAddress", "properties": { @@ -23033,7 +23174,15 @@ "type": "string", "description": "`Country` is the country of the `ServiceAddress`. This value will be derived from the `StateCode`, so it should generally be omitted." } - }, + } + }, + "PortinCreateSubscriberServiceAddress": { + "allOf": [ + { + "$ref": "#/components/schemas/PortinSubscriberBasicServiceAddress" + } + ], + "title": "ServiceAddress", "required": [ "HouseNumber", "StreetName", @@ -23045,11 +23194,12 @@ "PortinPutSubscriberServiceAddress": { "allOf": [ { - "$ref": "#/components/schemas/PortinSubscriberServiceAddress" + "$ref": "#/components/schemas/PortinSubscriberBasicServiceAddress" } ], "type": "object", "title": "ServiceAddress", + "description": "Includes all address fields. ServiceAddress elements cannot be SUPPed for Automated on-net wireless to wireless port-ins. See also, ResetAddressFields.", "properties": { "ResetAddressFields": { "type": "boolean", @@ -23057,131 +23207,236 @@ } } }, - "FileMetaData": { + "LnpOrderBasicModifiableFields": { "type": "object", "properties": { - "DocumentName": { + "CustomerOrderId": { + "type": "string", + "description": "This field is removed from the order if not provided in the PUT payload." + }, + "PeerId": { "type": "string" }, - "DocumentType": { + "SiteId": { + "type": "integer", + "format": "int32" + }, + "RequestedFocDate": { "type": "string", - "enum": [ - "LOA", - "INVOICE", - "CSR", - "OTHER" - ] + "description": "Is a subject to blackout windows if the current date is too close to an assigned FOC date." + }, + "Triggered": { + "type": "boolean", + "description": "May be included in the PUT payload as is, but cannot be changed." + }, + "TnAttributes": { + "type": "array", + "description": "Can be SUPPed prior to completion of the port-in request.", + "items": { + "$ref": "#/components/schemas/TnAttribute" + } + }, + "ProcessingStatus": { + "type": "string", + "description": "May only be SUPPed for port-in orders in draft state. The only valid value is “SUBMITTED” (not case sensitive)." } } }, - "FileMetaDataRequest": { + "LnpOrderAdditionalModifiableFields": { "type": "object", "properties": { - "FileMetaData": { + "BillingTelephoneNumber": { + "type": "string" + }, + "Subscriber": { + "$ref": "#/components/schemas/PortinSubscriberSupp" + }, + "AlternateSpid": { + "type": "string", + "description": "Can only be modified in DRAFT state. Can only be modified if it is not configured at the system level." + } + } + }, + "LnpOrderSuppManualTollFree": { + "allOf": [ + { + "$ref": "#/components/schemas/LnpOrderBasicModifiableFields" + } + ], + "type": "object", + "title": "LnpOrderSupp", + "properties": { + "Subscriber": { "type": "object", + "title": "Subscriber", "properties": { - "DocumentName": { - "type": "string" - }, - "DocumentType": { + "SubscriberType": { "type": "string", "enum": [ - "LOA", - "INVOICE", - "CSR", - "OTHER" + "BUSINESS" ] + }, + "BusinessName": { + "type": "string", + "maxLength": 25 + }, + "ServiceAddress": { + "$ref": "#/components/schemas/PortinSubscriberBasicServiceAddress" } } - } - } - }, - "PhoneNumber": { - "type": "object", - "properties": { - "PhoneNumber": { + }, + "LoaAuthorizingPerson": { "type": "string" + }, + "RetryValidation": { + "type": "boolean", + "description": "If 'TOLL_FREE_PORT_INS_PHASE_1' feature is enabled for account, Bandwidth accesses a vendor to determine if the numbers are portable, and if so, from which RespOrg. In the event that we do not receive a response from our vendor after a number of retries, we give up and place the order in the INVALID_TFNS or INVALID_DRAFT_TFNS state. This scenario can occur if our toll free porting vendor is performing maintenance, for example. Including RetryValidation with a value of true will cause the order to return to VALIDATE_TFNS or VALIDATE_DRAFT_TFNS and we will repeat our attempts to retrieve the portability data from the vendor. This element is included in the synchronous response to the PUT, when included in the request, but is not included in subsequent GET requests for the order." + }, + "ListOfPhoneNumbers": { + "type": "array", + "description": "May be SUPPed only in draft states (i.e. DRAFT, VALIDATE_DRAFT_TFNS, VALID_DRAFT_TFNS, or INVALID_DRAFT_TFNS)", + "items": { + "$ref": "#/components/schemas/PhoneNumber" + } } } }, - "LnpOrderSuppRequest": { - "type": "object", - "properties": { - "LnpOrderSupp": { - "$ref": "#/components/schemas/LnpOrderSupp" + "LnpOrderSuppManualOnNetOffNet": { + "allOf": [ + { + "$ref": "#/components/schemas/LnpOrderBasicModifiableFields" + }, + { + "$ref": "#/components/schemas/LnpOrderAdditionalModifiableFields" } - } - }, - "LnpOrderSupp": { + ], "type": "object", + "title": "LnpOrderSupp", "properties": { - "CustomerOrderId": { - "type": "string" - }, - "BillingTelephoneNumber": { - "type": "string" - }, "NewBillingTelephoneNumber": { "type": "string" }, "WirelessInfo": { - "$ref": "#/components/schemas/WirelessInfo" + "$ref": "#/components/schemas/WirelessInfoSupp" }, - "RequestedFocDate": { + "PartialPort": { "type": "string" }, - "Subscriber": { - "$ref": "#/components/schemas/Subscriber" + "LoaAuthorizingPerson": { + "type": "string" + } + } + }, + "LnpOrderSuppAutomatedOnNet": { + "allOf": [ + { + "$ref": "#/components/schemas/LnpOrderBasicModifiableFields" }, - "PeerId": { + { + "$ref": "#/components/schemas/LnpOrderAdditionalModifiableFields" + } + ], + "type": "object", + "title": "LnpOrderSupp", + "properties": { + "NewBillingTelephoneNumber": { "type": "string" }, + "WirelessInfo": { + "$ref": "#/components/schemas/WirelessInfoSupp" + }, "PartialPort": { "type": "string" }, "LoaAuthorizingPerson": { "type": "string" }, - "Immediately": { - "type": "boolean" - }, - "Triggered": { - "type": "boolean" - }, - "BillingType": { - "type": "string" + "ListOfPhoneNumbers": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PhoneNumber" + } + } + } + }, + "LnpOrderSuppAutomatedOnNetWireless": { + "allOf": [ + { + "$ref": "#/components/schemas/LnpOrderBasicModifiableFields" }, - "AutoActivation": { - "type": "string" + { + "$ref": "#/components/schemas/LnpOrderAdditionalModifiableFields" + } + ], + "type": "object", + "title": "LnpOrderSupp", + "properties": { + "WirelessInfo": { + "$ref": "#/components/schemas/WirelessInfoSupp" }, - "TnAttributes": { + "ListOfPhoneNumbers": { "type": "array", "items": { - "$ref": "#/components/schemas/TnAttribute" + "$ref": "#/components/schemas/PhoneNumber" } + } + } + }, + "LnpOrderSuppAutomatedOffNet": { + "allOf": [ + { + "$ref": "#/components/schemas/LnpOrderBasicModifiableFields" }, - "OverrideValidation": { - "type": "boolean" + { + "$ref": "#/components/schemas/LnpOrderAdditionalModifiableFields" + } + ], + "type": "object", + "title": "LnpOrderSupp", + "properties": { + "Subscriber": { + "allOf": [ + { + "$ref": "#/components/schemas/PortinSubscriberSupp" + } + ], + "type": "object", + "title": "LnpOrderSupp", + "description": "Cannot be SUPPed after FOC received." + } + } + }, + "LnpOrderSuppInternal": { + "allOf": [ + { + "$ref": "#/components/schemas/LnpOrderBasicModifiableFields" }, - "AlternateSpid": { + { + "$ref": "#/components/schemas/LnpOrderAdditionalModifiableFields" + } + ], + "type": "object", + "title": "LnpOrderSupp", + "properties": { + "NewBillingTelephoneNumber": { "type": "string" }, - "SiteId": { - "type": "integer", - "format": "int32" + "WirelessInfo": { + "$ref": "#/components/schemas/WirelessInfoSupp" }, - "ActualFocDate": { - "type": "string", - "format": "date-time" + "PartialPort": { + "type": "string" }, - "RetryValidation": { - "type": "boolean" + "LoaAuthorizingPerson": { + "type": "string" }, - "ListOfPhoneNumbers": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PhoneNumber" - } + "Immediately": { + "type": "boolean", + "description": "May be included in the PUT payload as is, but cannot be changed." + }, + "OverrideValidation": { + "type": "boolean", + "description": "This Bandwidth internal flag forces port-out to bypass validity checking (if there are no terminal errors). This flag can be SUPPed only for orders in EXCEPTION status." } } }, @@ -25532,7 +25787,8 @@ "description": "Subscriber information.", "properties": { "Name": { - "description": "Subscriber business / customer name. Max length is 45 characters.", + "description": "Subscriber business / customer name.", + "maxLength": 45, "type": "string" }, "ServiceAddress": { From fec0b8afb918010023c872b9bd36055f3f8b8a22 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Thu, 14 Jul 2022 20:41:09 +0300 Subject: [PATCH 10/20] Porting - Reorganization and individual page crafting --- site/docs/numbers/porting/bulkportins.mdx | 309 ++++++++++++++++++- site/docs/numbers/porting/cancelPortin.mdx | 59 ---- site/docs/numbers/porting/lnpChecker.mdx | 133 +++++++- site/docs/numbers/porting/loaUpload.mdx | 212 +++++++++++-- site/docs/numbers/porting/portingNumbers.mdx | 254 +-------------- site/docs/numbers/porting/updatePortin.mdx | 54 ++-- site/sidebar.js | 3 +- site/specs-temp/numbers.json | 43 ++- 8 files changed, 694 insertions(+), 373 deletions(-) delete mode 100644 site/docs/numbers/porting/cancelPortin.mdx diff --git a/site/docs/numbers/porting/bulkportins.mdx b/site/docs/numbers/porting/bulkportins.mdx index f9122fae2..16debc363 100644 --- a/site/docs/numbers/porting/bulkportins.mdx +++ b/site/docs/numbers/porting/bulkportins.mdx @@ -30,7 +30,314 @@ export const Highlight = ({children, color}) => ( ); -[The bulkPortins endpoint](/apis/numbers#operation/ListBulkPortins) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. Like many other requests, the bulkPortins endpoint causes the creation of a Bulk Portins order that is used to manage the porting event throughout the lifecycle of the request. +[The bulkPortins endpoint](/apis/numbers#operation/ListBulkPortins) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. +:::info +If you want to create individual port-in you can use `/portins` API. For more details follow the [How to create Port in request](/docs/numbers/guides/porting/portingNumbers) guide. +::: + +Like many other requests, the bulkPortins endpoint causes the creation of a Bulk Portins order that is used to manage the porting event throughout the lifecycle of the request. + +To create Port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. + + +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins + + + +```xml +Note: Remember to add authentication for your application if needed! + +https://dashboard.bandwidth.com/api/accounts/{accountId}/portins +//Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + + 2016-03-25T21:15:00.000Z + X455 + 9195551234 + 9175131245 + 12345 + 660123 + + BUSINESS + First + Last + + 11235 + Back + Denver + CO + 27541 + Canyon + + + The Authguy + + 771297665AABC + 1234 + + + 9195551234 + 9195554321 + + true + +``` + + + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' +2016-03-25T21:15:00.000Z +X455 +9195551234 +9175131245 +12345 +660123 + + BUSINESS + First + Last + + 11235 + Back + Denver + CO + 27541 + Canyon + + +The Authguy + + 771297665AABC + 1234 + + + 9195551234 + 9195554321 + +true +' +``` + + + + +```java +import com.bandwidth.iris.sdk.IrisClient; +import com.bandwidth.iris.sdk.model.LnpOrder; +import com.bandwidth.iris.sdk.model.ServiceAddress; +import com.bandwidth.iris.sdk.model.Subscriber; + +public class Main { + +public static void main(String[] args) { +String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); +String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); +String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); +String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); +String version = System.getenv("BANDWIDTH_IRIS_URL"); + +IrisClient client = new IrisClient(irisUrl, accountId, username, password, version); + +Subscriber s = new Subscriber(); +s.setSubscriberType("BUSINESS"); +s.setBusinessName("Company"); +ServiceAddress serviceAddress = new ServiceAddress(); +serviceAddress.setHouseNumber("123"); +serviceAddress.setStreetName("Anywhere St"); +serviceAddress.setCity("Raleigh"); +serviceAddress.setStateCode("NC"); +serviceAddress.setZip("27609"); +s.setServiceAddress(serviceAddress); + +LnpOrder order = new LnpOrder(); +order.setSiteId("123"); +order.setPeerId("12345"); +order.setBillingTelephoneNumber("9195551212"); +order.setSubscriber(s); +order.setLoaAuthorizingPerson("Joe Blow"); +order.getListOfPhoneNumbers().add("9195551212"); + +try { +order = LnpOrder.create(client, order); +System.out.println(order); +} catch (Exception e) { +System.out.println(e.getMessage()); +} +} +} +``` + + + + +```csharp +var accountId = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ACCOUNT_ID"); +var username = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_USERNAME"); +var password = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_PASSWORD"); +var apiEndpoint = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ENDPOINT"); + +var client = Client.GetInstance(accountId, username, password, apiEndpoint) + +var data = new PortIn +{ + BillingTelephoneNumber = "+1-202-555-0158", + Subscriber = new Subscriber +{ + SubscriberType = "BUSINESS", + BusinessName = "Company", + FirstName = "John", + LastName = "Doe", + ServiceAddress = new Address +{ + City = "City", + StateCode = "State", + Country = "Country" +} +}, + PeerId = "12345", + SiteId = "123" +}; +var order = await PortIn.Create(client, data); +``` + + + + +```ruby +require 'ruby-bandwidth-iris' + +BandwidthIris::Client.global_options = { +:account_id => 'accountId', +:username => 'userName', +:password => 'password' +} + +data = { +:site_id =>1234, +:peer_id => 5678, +:billing_telephone_number => "9195551212", +:subscriber => { +:subscriber_type => "BUSINESS", +:business_name => "Company", +:service_address => { +:house_number => "123", +:street_name => "EZ Street", +:city => "Raleigh", +:state_code => "NC", +:county => "Wake" +} +}, +:loa_authorizing_person => "Joe Blow", +:list_of_phone_numbers => { +:phone_number => ["9195551212"] +}, +:billing_type => "PORTIN" +} + +portin_response = BandwidthIris::PortIn.create(data) +``` + + + + +```js +var numbers = require("@bandwidth/numbers"); + +var data = { +siteId: 1234, +peerId: 5678, +billingTelephoneNumber: "9195551212", +subscriber: { +subscriberType: "BUSINESS", +businessName: "Company", +serviceAddress: { +houseNumber: "123", +streetName: "EZ Street", +city: "Raleigh", +stateCode: "NC", +county: "Wake" +} +}, +loaAuthorizingPerson: "Joe Blow", +listOfPhoneNumbers: { +phoneNumber: ["9195551212"] +}, +billingType: "PORTIN" +}; + +// Using client directly +// var client = new numbers.Client("accountId", "userName", "password"); +// numbers.PortIn.create(client, function(err, response){...}); + +//Or you can use default client instance (do this only once) +numbers.Client.globalOptions.accountId = "accountId"; +numbers.Client.globalOptions.userName = "userName"; +numbers.Client.globalOptions.password = "password"; + +//Default client will be used to do this call +numbers.PortIn.create(data, callback); +``` + + + + +```php +$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); +$username = getenv("BANDWIDTH_API_USERNAME"); +$password = getenv("BANDWIDTH_API_PASSWORD"); +$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); + +$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); +$account = new \Iris\Account($accountId, $client); + +try { +$portin = $account->portins()->create(array( +"BillingTelephoneNumber" => "6882015002", +"Subscriber" => array( +"SubscriberType" => "BUSINESS", +"BusinessName" => "Acme Corporation", +"ServiceAddress" => array( +"HouseNumber" => "1623", +"StreetName" => "Brockton Ave", +"City" => "Los Angeles", +"StateCode" => "CA", +"Zip" => "90025", +"Country" => "USA" +) +), +"LoaAuthorizingPerson" => "John Doe", +"ListOfPhoneNumbers" => array( +"PhoneNumber" => array("9882015025", "9882015026") +), +"SiteId" => "365", +"Triggered" => "false" +)); +} catch (BandwidthLib\APIException $e) { +print_r($e->getResponseCode()); +} +``` + + + The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. diff --git a/site/docs/numbers/porting/cancelPortin.mdx b/site/docs/numbers/porting/cancelPortin.mdx deleted file mode 100644 index ff7324f30..000000000 --- a/site/docs/numbers/porting/cancelPortin.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -id: cancelPortin -title: Cancel Portin -slug: /numbers/guides/porting/cancelPortin -description: How to cancel portin request -keywords: - - bandwidth - - numbers - - porting - - portin - - port - - cancel - - lnp -image: ../../../static/img/bandwidth-logo.png ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -export const accountId = "{accountId}"; -export const orderId = "{orderId}"; - -export const Highlight = ({children, color}) => ( - - {children} - - ); - -The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. - -## Cancel a Portin Order - -The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and dhe status of the order shall not be marked as `COMPLETE`. The DELETE method is used for this purpose. - -### Request URL - -DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} - -### Examples - -> Request - -```http -DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= -``` - -> Response - -```http -HTTP 200 OK -``` diff --git a/site/docs/numbers/porting/lnpChecker.mdx b/site/docs/numbers/porting/lnpChecker.mdx index 564f5ceb3..e271935ac 100644 --- a/site/docs/numbers/porting/lnpChecker.mdx +++ b/site/docs/numbers/porting/lnpChecker.mdx @@ -1,6 +1,6 @@ --- id: lnpChecker -title: Checking number portability +title: Check number(s) portability slug: /numbers/guides/porting/lnpChecker description: How to check number(s) portability keywords: @@ -34,16 +34,13 @@ export const Highlight = ({children, color}) => ( ); -A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the [`/accounts/{accountId}/lnpChecker`](/apis/numbers#operation/RequestPortabilityInfo) API endpoint. - -### Portability criteria - -TNs can be ported in a single `/portins` request if all the following are true: +A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network. TNs can be ported in a single `/portins` request if all the following are true: 1. They all have the same Port Type (see the `Port Types` section below) 2. They all have the same losing carrier 3. They are all associated with the same billing TN and Service Address +:::info There are also a number of reasons why a TN may not be able to be ported in: * The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. @@ -52,6 +49,7 @@ There are also a number of reasons why a TN may not be able to be ported in: * The TN is already being processed in another active port-in order. * The Bandwidth account has not been enabled for porting. Otherwise, the user must separate the TNs into individual `/portins` requests. +::: ### Port Types @@ -66,12 +64,27 @@ Port Type - is a categorization of how the TNs submitted to the /lnpchecker API | AUTOMATED | If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention using interfaces to our porting vendors. There are several sub-types of `AUTOMATED` as follows:
  • `AUTOMATED` - means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth (On-net tns). There are differences in on-net port-in rules depending on whether the order is for wireless to wireless vs. one of the other 3 combinations.
  • `AUTOMATEDOFFNET` - Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Currently, only numbers in the U.S. are automated. There are differences in port-in rules depending on whether the order has achieved FOC status.
  • `INTERNAL` - Internal means that the telephone number is being moved from one Bandwidth account to another Bandwidth account. Internal port-in may involve on-net, off-net, or toll free telephone numbers.
| | MIXED | If the list of TNs supplied to /lnpchecker includes TNs that are categorized as more than one of the above Port Types, the resulting Port Type will be `MIXED`. If you plan to use /portins to port the TNs, you must break the TN list into separate /portins requests for each Port Type. | -### Request URL -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker +### Check number portability + +A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the POST request to [`/accounts/{accountId}/lnpChecker`](/apis/numbers#operation/RequestPortabilityInfo) API endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. ### Examples +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker -> Request + + ```xml POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker?fullcheck=true HTTP/1.1 @@ -86,7 +99,102 @@ Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= ``` -> Response + + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker?fullcheck=true' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + + 9195551234 + 9198675309 + +' +``` + + + + +```java +String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); +String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); +String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); +String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); +String version = System.getenv("BANDWIDTH_IRIS_URL"); +IrisClient client = new IrisClient(accountId, username, password, irisUrl, version); + +NumberPortabilityRequest request = new NumberPortabilityRequest(); +request.getTnList().add("9195551212"); +NumberPortabilityResponse response = LnpChecker.checkLnp(client, request, "true"); +System.out.println(response.getPortableNumbers().get(0)); +``` + + + + +```csharp +var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") +var result = await LnpChecker.Check(client, new string[] { "555555" }); +Console.WriteLine(result); +``` + + + + +```ruby +require 'ruby-bandwidth-iris' + +BandwidthIris::Client.global_options = { +:account_id => 'accountId', +:username => 'userName', +:password => 'password' +} + +numbers = ["9195551212", "9195551213"] +full_check = true +BandwidthIris::LnpChecker.check(numbers, full_check) +``` + + + + +```js +var numbers = require("@bandwidth/numbers"); + +numbers.Client.globalOptions.accountId = "accountId"; +numbers.Client.globalOptions.userName = "userName"; +numbers.Client.globalOptions.password = "password"; + +var numbersList = ["9195551212", "9195551213"]; +var fullCheck = true; +numbers.LnpChecker.check(numbersList, fullCheck, callback); +``` + + + + +```php +$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); +$username = getenv("BANDWIDTH_API_USERNAME"); +$password = getenv("BANDWIDTH_API_PASSWORD"); +$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); + +$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); +$account = new \Iris\Account($accountId, $client); + +$account->lnpChecker(["4109255199", "9196190594"], "true"); +``` + + + + + +Response ```xml HTTP 200 OK @@ -147,3 +255,8 @@ Content-Type: application/xml; charset=utf-8 ``` +## Where to next? + +Now that you have learnt how to check numbers portability, check out some of the available actions in the following guides: +- [How to create Port in request](/docs/numbers/guides/porting/portingNumbers) +- [How to create Bulk Port in](/docs/numbers/guides/porting/bulkPortins) \ No newline at end of file diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx index a62bdcced..996110ee6 100644 --- a/site/docs/numbers/porting/loaUpload.mdx +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -23,6 +23,7 @@ import TabItem from '@theme/TabItem'; export const accountId = "{accountId}"; export const orderId = "{orderId}"; +export const fileId = "{fileId}"; export const Highlight = ({children, color}) => ( ( ); -The Bandwidth Phone Number API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. -## Upload Letter of Authorization (LOA) - -After successfully submitting the Create LNP Order request, an LOA may be uploaded using our LOA API. +After successfully submitting the Create LNP Order request, an Letter of Authorization (LOA) may be uploaded using our LOA API. The following MIME types are supported for the LOA upload file: @@ -53,22 +51,27 @@ The following MIME types are supported for the LOA upload file: * WAV(“audio/x-wav”) * ZIP(“application/zip”) -### Request URL -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas -### Examples +To upload/manage the LOA you can use different requests to [/portins/{orderId}/loas API](/apis/numbers/#operation/UploadPortinLoaFile). This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. + +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas - + groupId="manageLoa" + defaultValue="http" + values={[ + { label: 'http', value: 'http', }, + { label: 'cURL', value: 'curl', }, + { label: 'Java', value: 'java', }, + { label: 'C#', value: 'csharp', }, + { label: 'Ruby', value: 'ruby', }, + { label: 'NodeJS', value: 'nodejs', }, + { label: 'PHP', value: 'php', }, + ] + }> + -> Request +> UPLOAD LOA ```http POST /api/accounts/9900778/portins/{orderId}/loas HTTP/1.1 @@ -101,15 +104,188 @@ Content-Type: application/xml; charset=utf-8 ``` +>UPDATE FILE METADATA + +```xml + + [string] + [LOA | INVOICE | CSR | OTHER] + +``` + - + > Request ```cURL -curl -H 'Content-Type: application/pdf' --data-binary "@Test_LOA.pdf" -iv https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{order-id}/loas +# UPLOAD LOA + +curl \ + -H 'Content-Type: application/pdf' \ + --data-binary "@Test_LOA.pdf" \ + -iv https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas + +# UPDATE FILE METADATA + +curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata' \ +-X PUT \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + [string] + [LOA | INVOICE | CSR | OTHER] +' +``` + + + + +```java +String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); +String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); +String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); +String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); +String version = System.getenv("BANDWIDTH_IRIS_URL"); + +IrisClient client = new IrisClient(accountId, username, password, irisUrl, version); + +try { + LnpOrder order = LnpOrder.get(client, "orderId"); + + String fileName = "myLoaFile.pdf"; + order.uploadLoa(new File("path_to_the_file/../myLoaFile.pdf"), LoaFileType.PDF); + order.updateLoa(new File("another_path_to_the_file"), LoaFileType.PDF); + order.deleteLoa(fileName); + order.getLoaMetaData(fileName); + + FileMetaData fileMetaData = new FileMetaData(); + fileMetaData.setDocumentName("myLoaFile.pdf"); + fileMetaData.setDocumentType("INVOICE"); + order.updateLoaMetaData(fileName, fileMetaData); + order.deleteLoaMetaData(fileName); +} catch (Exception e) { + System.out.println(e.getMessage()); +} +``` + + + + +```csharp +var client = Client.GetInstance(accountId, username, password, apiEndpoint) +var portInOrder = PortIn.Get(client, "orderId"); + +// Port In LOA Management +portInOrder.CreateFile(Stream s, string mediaType); +portInOrder.CreateFile(byte[] buffer, string mediaType); +portInOrder.UpdateFile(string fileName, Stream s, string mediaType); +portInOrder.UpdateFile(string fileName, byte[] buffer, string mediaType); +portInOrder.GetFileMetaData(string fileName); +PutFileMetadata(string fileName, FileMetadata fileMetadata); +portInOrder.DeleteFile(string fileName); +portInOrder.GetFiles(bool metaData); +portInOrder.GetFile(string fileName); +``` + + + + +```ruby +require 'ruby-bandwidth-iris' + +BandwidthIris::Client.global_options = { +:account_id => 'accountId', +:username => 'userName', +:password => 'password' +} +portIn = BandwidthIris::PortIn.get("portin_id", callback) + +# Add File +portIn.create_file(IO.read("myFile.txt")) + +# Update File +portIn.update_file("myFile.txt", IO.read("myFile.txt")) + +# Get File +portIn.get_file("myFile.txt") + +# Get File Metadata +portIn.get_file_metadata("myFile.txt") + +# Get Files +portIn.get_files() +``` + + + + +```js +var numbers = require("@bandwidth/numbers"); + +// Using client directly +// var client = new numbers.Client("accountId", "userName", "password"); +// numbers.PortIn.create(client, function(err, response){...}); + +//Or you can use default client instance (do this only once) +numbers.Client.globalOptions.accountId = "accountId"; +numbers.Client.globalOptions.userName = "userName"; +numbers.Client.globalOptions.password = "password"; + +var portinOrderId = "..."; +numbers.PortIn.get(portinOrderId, function(err, portIn){ +// Add File +portIn.createFile(fs.createReadStream("myFile.txt"), callback); + +// Update File +portIn.updateFile("myFile.txt", fs.createReadStream("myFile.txt"), callback); + +// Get File +portIn.getFile("myFile.txt", callback); + +// Get File Metadata +portIn.getFileMetadata("myFile.txt", callback); + +// Get Files +portIn.getFiles(callback); +}); +``` + + + + +```php +$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); +$username = getenv("BANDWIDTH_API_USERNAME"); +$password = getenv("BANDWIDTH_API_PASSWORD"); +$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); + +$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); +$account = new \Iris\Account($accountId, $client); + +try { + $portin = $account->portins()->portin("d28b36f7-fa96-49eb-9556-a40fca49f7c6")); + $portin->list_loas(true); // metadata = true + $portin->loas_send("./1.txt"); + $portin->loas_update("./1.txt", "1.txt"); + $portin->loas_delete("1.txt"); + $portin->get_metadata("1.txt"); + + $meta_new = array( + "DocumentName" => "text.txt", + "DocumentType" => "INVOICE" + ); + $portin->set_metadata('test.txt', $meta_new); + $portin->delete_metadata('test.txt'); +} catch (BandwidthLib\APIException $e) { + print_r($e->getResponseCode()); +} ``` +## Where to next? + +Now that you have learnt how to create a Port in order, check out some of the available actions in the following guides: +- [How to manage Port in](/docs/numbers/guides/porting/updatePortin) diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 242cf2892..7800117c3 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -1,6 +1,6 @@ --- id: portingNumbers -title: Port-in numbers +title: Create Port-in slug: /numbers/guides/porting/portingNumbers description: How to port numbers using the Bandwidth API keywords: @@ -33,24 +33,20 @@ export const Highlight = ({children, color}) => ( The Bandwidth Phone Number `/portins` API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. -## Create a Portin Order - -In order to successfully port telephone numbers they need to correspond to a set of criteria. All these are listed in [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) guide. +In order to successfully port telephone numbers they need to correspond to a set of criteria. To check them follow the [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) guide. :::info -As an alternative to current feature the `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/bulkPortins). +As an alternative to individual porting the `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/bulkPortins). ::: -The API allows a user to create a new LNP order. An order number will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. - -To create Port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +## Create a Portin Order -### Request URL +The API allows a user to create a new LNP order. An order id will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins +To create Port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. -### Examples +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins `. Please follow the [How to setup Notification Webhook](/numbers/webhooks/orderWebhook/orderWebhook) guide. +Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP "order". The orders are then processed and the order status is updated asynchronously. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. Please follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) guide. + +To poll an information about your Port in you can still use a GET request to [/portins API](/apis/numbers/#operation/GetPortin). This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. -To poll an information about your Port in using a GET request to `/accounts/{accountId}/portins/{orderId}` +GET https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} -## Modify a Portin Order - -The API allows a user to modify an existing LNP order, called a SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. LNP orders can be modified with a PUT to `accounts/{accountId}/portins/{orderId}`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. -For more details check our [PUT /portins](/apis/numbers/#operation/UpdatePortin) endpoint - - - - -```xml -PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= - - - - SJM00002 - 2014-12-04T13:00:00.000Z - 8045030092 - 9175131245 - - 23453245 - 1111 - - - RESIDENTIAL - Steve - McKinnon - - - true - 115 - Monarch Way - Cary - NC - 27518 - - - 743 - true - - 2019721004 - 2019721005 - - Steve McKinnon - Foo - -``` - - - - -```cURL -Note: Remember to add authentication for your application if needed! - -curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ --X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ --H 'Content-Type: application/xml' \ --d ' - SJM00002 - 2014-12-04T13:00:00.000Z - 8045030092 - 9175131245 - - 23453245 - 1111 - - - RESIDENTIAL - Steve - McKinnon - - - true - 115 - Monarch Way - Cary - NC - 27518 - - - 743 - true - - 2019721004 - 2019721005 - - Steve McKinnon - Foo -' -``` - - - - -```java -String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); -String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); -String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); -String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); -String version = System.getenv("BANDWIDTH_IRIS_URL"); - -IrisClient client = new IrisClient(accountId, username, password, irisUrl, version); - -LnpOrderSupp supp = new LnpOrderSupp(); -supp.setSiteId("123"); -supp.setPeerId("12345"); -// ... - -try { - LnpOrder order = LnpOrder.get(client, "orderId"); - order.update(supp); - System.out.println(order); -} catch (Exception e) { - System.out.println(e.getMessage()); -} -``` - - - - -```csharp -var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") - -var data = new PortIn -{ - // ... - PeerId = "12345", - SiteId = "123" -}; -var portInOrder = PortIn.Get("orderId"); -portInOrder.Update(data); -``` - - - - -```ruby -require 'ruby-bandwidth-iris' - -BandwidthIris::Client.global_options = { -:account_id => 'accountId', -:username => 'userName', -:password => 'password' -} - -data = { - //... -} - -portIn = BandwidthIris::PortIn.get("portin_id", callback) -portIn.update(data) -``` - - - - -```js -var numbers = require("@bandwidth/numbers"); - -var data = { - // ... -}; - -numbers.Client.globalOptions.accountId = "accountId"; -numbers.Client.globalOptions.userName = "userName"; -numbers.Client.globalOptions.password = "password"; - -portIn.update(data, callback);; -``` - - - - -```php -$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); -$username = getenv("BANDWIDTH_API_USERNAME"); -$password = getenv("BANDWIDTH_API_PASSWORD"); -$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); - -$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); -$account = new \Iris\Account($accountId, $client); - -try { - $portin = $account->portins()->portin("d28b36f7-fa96-49eb-9556-a40fca49f7c6")); - $portin->update(array( - "BillingTelephoneNumber" => "6882015002", - "SiteId" => "365", - // ... - )); -} catch (BandwidthLib\APIException $e) { - print_r($e->getResponseCode()); -} -``` - - - - -## Cancel a Portin Order +## Where to next? -The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and dhe status of the order shall not be marked as `COMPLETE`. The DELETE method is used for this purpose. - -TODO : reference to cancel portin - -> Response - -```http -HTTP 200 OK -``` +Now that you have learnt how to create a Port in order, check out some of the available actions in the following guides: +- [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) +- [How to upload LOA (Letter of authorization)](/docs/numbers/guides/porting/loaUpload) +- [How to manage Port in](/docs/numbers/guides/porting/updatePortin) +- [How to create Bulk Port in](/docs/numbers/guides/porting/bulkPortins) \ No newline at end of file diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx index 643c60995..0c04c9b80 100644 --- a/site/docs/numbers/porting/updatePortin.mdx +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -41,36 +41,6 @@ If the order ProcessingStatus is `DRAFT`, the rules about what can be changed ar The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. Please refer to the matrix below to see which elements can be modified and replaced. -| Payload Field | Manual Off-Net | Manual On-Net | Manual Toll Free | Automated On-Net | Automated Off-Net Pre FOC | Automated Off-Net Post FOC | Internal | -|----------------------------------------------------------|----------------|---------------|------------------|-------------------|---------------------------|----------------------------|----------| -| billingTelephoneNumber | Editable | Editable | Disabled | Editable | Editable | Disabled | Editable | -| newBillingTelephoneNumber | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | -| partialPort | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | -| subscriber.subscriberType | Editable | Editable | Editable | Editable | Editable | Disabled | Editable | -| subscriber.businessName/firstName/middleInitial/lastName | Editable | Editable | Editable | Editable | Editable | Disabled | Editable | -| loaAuthorizingPerson | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | -| wirelessInfo.accountNumber | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | -| wirelessInfo.pinNumber | Editable | Editable | Disabled | Editable | Disabled | Disabled | Editable | -| subscriber.serviceAddress | Editable | Editable | Editable | Editable | Disabled | Disabled | Editable | -| requestedFocDate | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| listOfPhoneNumbers | Disabled | Disabled | Disabled | Editable | Disabled | Disabled | Disabled | -| siteId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| peerId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| customerOrderId | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| TnAttributes elements | Editable | Editable | Editable | Editable | Editable | Editable | Editable | -| Immediately | Disabled | Disabled | Disabled | Disabled | Disabled | Disabled | Editable | - -### Level3 Portin - -When a port-in is being processed by off-net partner Level 3 (you can retrieve this information using a GET request to `/portins/{orderId}` indicates a Port Type of AUTOMATEDOFFNET and a VendorName of "Level 3"), the rules for what can be changed in a SUPP operation are more restrictive. If the order has NOT yet received FOC, you may change the following: - -* RequestedFocDate -* BillingTelephoneNumber -* SubscriberType -* Subscriber name elements or BusinessName, provided that SubscriberType is provided - -After the FOC date has been received, the billing telephone number and subscriber information cannot be modified, only the FOC date/time can be updated. - ### Request URL PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} @@ -303,3 +273,27 @@ Content-Type: application/xml; charset=utf-8 false ``` + +## Cancel a Portin Order + +The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and dhe status of the order shall not be marked as `COMPLETE`. The DELETE method is used for this purpose. + +### Request URL + +DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} + +### Examples + +> Request + +```http +DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 +Content-Type: application/xml; charset=utf-8 +Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= +``` + +> Response + +```http +HTTP 200 OK +``` \ No newline at end of file diff --git a/site/sidebar.js b/site/sidebar.js index ea30dab1e..11c29745d 100644 --- a/site/sidebar.js +++ b/site/sidebar.js @@ -51,11 +51,10 @@ module.exports = { label: "Porting numbers", items: [ "numbers/porting/portingNumbers", - "numbers/porting/bulkPortins", "numbers/porting/lnpChecker", "numbers/porting/loaUpload", "numbers/porting/updatePortin", - "numbers/porting/cancelPortin", + "numbers/porting/bulkPortins", ], }, "numbers/csrLookupTool", diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index a064beda7..fc4f68d22 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -1551,7 +1551,7 @@ "/accounts", "Porting" ], - "description": "Retrieves bulk port-in orders for the specified accountId.\nA maximum of 1,000 orders can be retrieved per request. If no date range or specific query parameter is provided, the order results will be limited to the last two years. Please visit Guides and Tutorials", + "description": "Retrieves bulk port-in orders for the specified accountId.\nA maximum of 1,000 orders can be retrieved per request. If no date range or specific query parameter is provided, the order results will be limited to the last two years. Please visit Guides and Tutorials", "operationId": "ListBulkPortins", "summary": "List bulk port-in orders", "parameters": [ @@ -1679,7 +1679,7 @@ "/accounts", "Porting" ], - "description": "

Creates a bulk port-in order to be used as a template for a collection of child port-in orders. The template values will be cascaded to child port-ins that result from decomposing a collection of Telephone Numbers that span carriers, RespOrgs, or have attributes that drive the decomposition into a number of individual port-in orders.

Upon a successfully-submitted payload, the order will have a status of \"DRAFT\", denoting that further modification to the template is expected. For example, the next step is to use the /tnList endpoint to add a collection of telephone numbers to the bulk port-in order. The only valid value for the ProcessingStatus element in a POST is 'DRAFT', which is the default value.

Please visit Guides and Tutorials

", + "description": "

Creates a bulk port-in order to be used as a template for a collection of child port-in orders. The template values will be cascaded to child port-ins that result from decomposing a collection of Telephone Numbers that span carriers, RespOrgs, or have attributes that drive the decomposition into a number of individual port-in orders.

Upon a successfully-submitted payload, the order will have a status of \"DRAFT\", denoting that further modification to the template is expected. For example, the next step is to use the /tnList endpoint to add a collection of telephone numbers to the bulk port-in order. The only valid value for the ProcessingStatus element in a POST is 'DRAFT', which is the default value.

Please visit Guides and Tutorials

", "operationId": "CreateBulkOrder", "summary": "Create bulk port-in order", "parameters": [ @@ -1748,7 +1748,7 @@ "/accounts", "Porting" ], - "description": "Retrieves information associated with the bulk port-in order specified by the orderId URI parameter. Please visit Guides and Tutorials", + "description": "Retrieves information associated with the bulk port-in order specified by the orderId URI parameter. Please visit Guides and Tutorials", "operationId": "RetrieveBulkOrder", "summary": "Retrieve bulk port-in order", "parameters": [ @@ -1799,7 +1799,7 @@ "/accounts", "Porting" ], - "description": "The PUT operation is available only for bulk port-in orders that are not yet associated with subtending orders. Since this only occurs for bulk port-in orders that are in one of the draft states, there are few restrictions on what may be included. As with the POST, any data associated with the bulk port-in will cascade to subtending orders when they are created. (Subtending orders are created after telephone numbers are added to the bulk port-in using the /tnList endpoint.) The PUT completely replaces the existing Bulk Portin order with the payload of the PUT. Please visit Guides and Tutorials.

The following element may appear only in PUT or PATCH operations on a bulk port-in order.
  • RetryValidation - When toll free numbers are included in a port-in order, Bandwidth accesses a vendor to determine if the numbers are portable, and if so, from which RespOrg. In the event that we do not receive a response from our vendor after a number of retries, we give up and place the order in the INVALID_DRAFT_TNS state. This scenario can occur if our toll free porting vendor is performing maintenance, for example. Including RetryValidation with a value of true will cause the order to return to VALIDATE_DRAFT_TNS and we will repeat our attempts to retrieve the portability data from the vendor. This element is included in the synchronous response to the PUT or PATCH, when included in the request, but is not included in subsequent GET requests for the order.
", + "description": "The PUT operation is available only for bulk port-in orders that are not yet associated with subtending orders. Since this only occurs for bulk port-in orders that are in one of the draft states, there are few restrictions on what may be included. As with the POST, any data associated with the bulk port-in will cascade to subtending orders when they are created. (Subtending orders are created after telephone numbers are added to the bulk port-in using the /tnList endpoint.) The PUT completely replaces the existing Bulk Portin order with the payload of the PUT. Please visit Guides and Tutorials.

The following element may appear only in PUT or PATCH operations on a bulk port-in order.
  • RetryValidation - When toll free numbers are included in a port-in order, Bandwidth accesses a vendor to determine if the numbers are portable, and if so, from which RespOrg. In the event that we do not receive a response from our vendor after a number of retries, we give up and place the order in the INVALID_DRAFT_TNS state. This scenario can occur if our toll free porting vendor is performing maintenance, for example. Including RetryValidation with a value of true will cause the order to return to VALIDATE_DRAFT_TNS and we will repeat our attempts to retrieve the portability data from the vendor. This element is included in the synchronous response to the PUT or PATCH, when included in the request, but is not included in subsequent GET requests for the order.
", "operationId": "PutBulkOrder", "summary": "Update bulk port-in order", "parameters": [ @@ -1875,7 +1875,7 @@ "/accounts", "Porting" ], - "description": "Delete a bulk port-in order with child port-ins. Deleting a bulk port-in is allowed for 'DRAFT' state only. Deleting a bulk port-in will delete all DRAFT child port-ins associated with the bulk port-in. When the bulk port-in is deleted, any child port-in orders that are not in a draft status are dissociated from the bulk port-in, but not deleted. Please visit Guides and Tutorials", + "description": "Delete a bulk port-in order with child port-ins. Deleting a bulk port-in is allowed for 'DRAFT' state only. Deleting a bulk port-in will delete all DRAFT child port-ins associated with the bulk port-in. When the bulk port-in is deleted, any child port-in orders that are not in a draft status are dissociated from the bulk port-in, but not deleted. Please visit Guides and Tutorials", "operationId": "DeleteBulkOrder", "summary": "Delete bulk port-in order", "parameters": [ @@ -1926,7 +1926,7 @@ "/accounts", "Porting" ], - "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing Bulk Port-in order. This is done via a PUT or PATCH on the existing order-id. Since the Bulk Port-in\n order acts as a template for port-in orders in DRAFT status, any record can be changed at any time. The PATCH replaces elements of the referenced Bulk Portin order, but it replaces only the records included in the request payload. Other elements will remain untouched.

Changing the fields in a Bulk Port-in order causes the system to reapply all changed values to the child port-ins contained in the list of subtending port-in orders. Note that if the port-in orders contained within the Bulk Port are in DRAFT state, any field can be modified. If any child port-in order in the Bulk Port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller.

Changing the ProcessingStatus to 'IN_PROGRESS' causes all child port-ins to begin processing. This is only valid if child port-ins exist for the bulk port-in.

Please visit Guides and Tutorials

", + "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing Bulk Port-in order. This is done via a PUT or PATCH on the existing order-id. Since the Bulk Port-in\n order acts as a template for port-in orders in DRAFT status, any record can be changed at any time. The PATCH replaces elements of the referenced Bulk Portin order, but it replaces only the records included in the request payload. Other elements will remain untouched.

Changing the fields in a Bulk Port-in order causes the system to reapply all changed values to the child port-ins contained in the list of subtending port-in orders. Note that if the port-in orders contained within the Bulk Port are in DRAFT state, any field can be modified. If any child port-in order in the Bulk Port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller.

Changing the ProcessingStatus to 'IN_PROGRESS' causes all child port-ins to begin processing. This is only valid if child port-ins exist for the bulk port-in.

Please visit Guides and Tutorials

", "operationId": "PatchBulkOrder", "summary": "Patch bulk port-in order", "parameters": [ @@ -2004,7 +2004,7 @@ "/accounts", "Porting" ], - "description": "Retrieves a list of Port-in Orders that are all associated with the identified Bulk Port-in. This response is not paginated due to its inherently limited size. Please visit Guides and Tutorials", + "description": "Retrieves a list of Port-in Orders that are all associated with the identified Bulk Port-in. This response is not paginated due to its inherently limited size. Please visit Guides and Tutorials", "operationId": "ListBulkChildOrders", "summary": "List bulk port-in child orders", "parameters": [ @@ -2052,7 +2052,7 @@ "/accounts", "Porting" ], - "description": "

A PUT on a PortinList resource will cause replacement of the list of port-in orders associated with the specified bulk port-in.

This PUT will completely replace the existing list of port-in orders associated with the bulk port-in. If all port-in orders in the list are not valid, the PUT request will fail, due to the potential for losing the port-in to bulk port-in relationships.

Only port-in orders in a draft status may be associated with a bulk port-in order. And port-in orders may only be added to a bulk port-in order while that bulk port-in order is still in a draft state.

Child port-in orders may be dissociated from the bulk port-in at any time.

Please visit Guides and Tutorials

", + "description": "

A PUT on a PortinList resource will cause replacement of the list of port-in orders associated with the specified bulk port-in.

This PUT will completely replace the existing list of port-in orders associated with the bulk port-in. If all port-in orders in the list are not valid, the PUT request will fail, due to the potential for losing the port-in to bulk port-in relationships.

Only port-in orders in a draft status may be associated with a bulk port-in order. And port-in orders may only be added to a bulk port-in order while that bulk port-in order is still in a draft state.

Child port-in orders may be dissociated from the bulk port-in at any time.

Please visit Guides and Tutorials

", "operationId": "UpdateBulkChildList", "summary": "Update list of bulk port-in child orders", "parameters": [ @@ -2120,7 +2120,7 @@ "/accounts", "Porting" ], - "description": "Retrieve all notes associated with the order. Please visit Guides and Tutorials", + "description": "Retrieve all notes associated with the order. Please visit Guides and Tutorials", "operationId": "ListBulkNotes", "summary": "List bulk port-in order notes", "parameters": [ @@ -2171,7 +2171,7 @@ "/accounts", "Porting" ], - "description": "Updates the Notes resource by adding a note. Adding a note to a port-in order causes a notification to be sent to Bandwidth Operations, so that they may assist as necessary. A note may be up to 500 characters in length. Please visit Guides and Tutorials", + "description": "Updates the Notes resource by adding a note. Adding a note to a port-in order causes a notification to be sent to Bandwidth Operations, so that they may assist as necessary. A note may be up to 500 characters in length. Please visit Guides and Tutorials", "operationId": "CreateBulkNote", "summary": "Create bulk port-in order note", "parameters": [ @@ -2239,7 +2239,7 @@ "/accounts", "Porting" ], - "description": "Update a specified note. Notes may only be updated, not deleted. Please visit Guides and Tutorials", + "description": "Update a specified note. Notes may only be updated, not deleted. Please visit Guides and Tutorials", "operationId": "UpdateBulkNote", "summary": "Update bulk port-in order note", "parameters": [ @@ -2317,7 +2317,7 @@ "/accounts", "Porting" ], - "description": "

The information returned in the GET /tnList response payload depends on the ProcessingStatus of the bulk port-in order. See the Responses tab for examples of each response payload.

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

\n ProcessingStatus\n

\n 		\n

\n Information Returned\n

\n
\n

\n DRAFT\n

\n 		\n

\n In this state, no tnList has been provided, so the response\n includes empty portable and non-portable telephone number lists.\n

\n
\n

\n VALIDATE_DRAFT_TNS\n

\n 		\n

\n In this state, validation of the tnList is still in progress,\n so the response includes all of the tnList telephone numbers\n in a `not validated` list. This is a temporary state until\n the validation completes. Validation takes longer when toll\n free numbers are included in the tnList.\n

\n
\n

\n VALID_DRAFT_TNS\n

\n 		\n

\n In this state, all of the telephone numbers in the tnList have\n been determined to be portable. The response payload includes\n a list of the child port-in orders and shows which telephone\n numbers are assigned to each child port-in order.\n

\n
\n

\n INVALID_DRAFT_TNS\n

\n 		\n

\n In this state, at least one of the telephone numbers in the tnList\n has been determined to be non-portable. The response payload includes\n a list of portable numbers (if any) and a list of errors showing which\n telephone numbers are non-portable as well as the reasons why they\n cannot be ported. Or, if communication errors prevented us from\n determining telephone number portability, those errors will be included.\n

\n
\n

Please visit Guides and Tutorials

", + "description": "

The information returned in the GET /tnList response payload depends on the ProcessingStatus of the bulk port-in order. See the Responses tab for examples of each response payload.

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

\n ProcessingStatus\n

\n 		\n

\n Information Returned\n

\n
\n

\n DRAFT\n

\n 		\n

\n In this state, no tnList has been provided, so the response\n includes empty portable and non-portable telephone number lists.\n

\n
\n

\n VALIDATE_DRAFT_TNS\n

\n 		\n

\n In this state, validation of the tnList is still in progress,\n so the response includes all of the tnList telephone numbers\n in a `not validated` list. This is a temporary state until\n the validation completes. Validation takes longer when toll\n free numbers are included in the tnList.\n

\n
\n

\n VALID_DRAFT_TNS\n

\n 		\n

\n In this state, all of the telephone numbers in the tnList have\n been determined to be portable. The response payload includes\n a list of the child port-in orders and shows which telephone\n numbers are assigned to each child port-in order.\n

\n
\n

\n INVALID_DRAFT_TNS\n

\n 		\n

\n In this state, at least one of the telephone numbers in the tnList\n has been determined to be non-portable. The response payload includes\n a list of portable numbers (if any) and a list of errors showing which\n telephone numbers are non-portable as well as the reasons why they\n cannot be ported. Or, if communication errors prevented us from\n determining telephone number portability, those errors will be included.\n

\n
\n

Please visit Guides and Tutorials

", "operationId": "ListBulkTns", "summary": "List bulk port-in order tns", "parameters": [ @@ -2365,7 +2365,7 @@ "/accounts", "Porting" ], - "description": "

This operation is used to add telephone numbers to a draft bulk port-in order.\n The telephone numbers may be a mix of toll free and non-toll free. Once the\n telephone numbers are added, they will be checked for portability, and if\n portable, decomposed into individual child port-in orders. Both the bulk\n port-in order and the child port-in orders remain in draft status until you\n explicitly submit them.

\n\n

After submitting a tnList with the PUT operation, you will need to poll for\n completion of the validation and decomposition using the GET /tnList operation\n or the GET /bulkPortins/orderId operation (both include the order ProcessingStatus).\n The basic ProcessingStatus flow is as follows:

\n\n
  • On submission of the tnList, the bulk port-in order transitions from DRAFT\n status to VALIDATE_DRAFT_TNS. The order will remain in this state until validation\n is complete. For a tnList that does not contain any toll free telephone numbers, the\n validation step is very fast. When the tnList does contain toll free telephone\n numbers, the time it takes to validate the toll free numbers is roughly proportional\n to the number of toll free telephone numbers. If you PUT a new tnList while validation\n is in progress for a previous tnList, the validation of the previous tnList will be\n abandoned and replaced by validation of the new tnList.
    • \n
  • If all of the telephone numbers in the tnList are portable, the bulk port-in\n transitions to the VALID_DRAFT_TNS state. At this point, child port-in orders have\n been created in DRAFT status to meet requirements about which telephone numbers can\n be ported together in the same port-in order. The bulk port-in will remain in this\n state until you use the PATCH operation on the bulk port-in order to change the\n ProcessingStatus to IN_PROGRESS. If you PUT an updated tnList, all draft child\n port-in orders are removed, and the validation process begins again with the new\n tnList.
    • \n
  • If at least one of the telephone numbers in the tnList is not portable, the bulk\n port-in transitions to the INVALID_DRAFT_TNS state. When this happens, no child\n port-in orders are created. You can use the GET operation on /tnList to see reasons\n why telephone numbers are non-portable. You’ll need to update the tnList to remove\n non-portable telephone numbers and PUT the tnList again to restart the validation\n step. The goal is to get to the VALID_DRAFT_TNS state, from which you can submit\n the bulk port-in order.
\n

Please visit Guides and Tutorials

", + "description": "

This operation is used to add telephone numbers to a draft bulk port-in order.\n The telephone numbers may be a mix of toll free and non-toll free. Once the\n telephone numbers are added, they will be checked for portability, and if\n portable, decomposed into individual child port-in orders. Both the bulk\n port-in order and the child port-in orders remain in draft status until you\n explicitly submit them.

\n\n

After submitting a tnList with the PUT operation, you will need to poll for\n completion of the validation and decomposition using the GET /tnList operation\n or the GET /bulkPortins/orderId operation (both include the order ProcessingStatus).\n The basic ProcessingStatus flow is as follows:

\n\n
  • On submission of the tnList, the bulk port-in order transitions from DRAFT\n status to VALIDATE_DRAFT_TNS. The order will remain in this state until validation\n is complete. For a tnList that does not contain any toll free telephone numbers, the\n validation step is very fast. When the tnList does contain toll free telephone\n numbers, the time it takes to validate the toll free numbers is roughly proportional\n to the number of toll free telephone numbers. If you PUT a new tnList while validation\n is in progress for a previous tnList, the validation of the previous tnList will be\n abandoned and replaced by validation of the new tnList.
    • \n
  • If all of the telephone numbers in the tnList are portable, the bulk port-in\n transitions to the VALID_DRAFT_TNS state. At this point, child port-in orders have\n been created in DRAFT status to meet requirements about which telephone numbers can\n be ported together in the same port-in order. The bulk port-in will remain in this\n state until you use the PATCH operation on the bulk port-in order to change the\n ProcessingStatus to IN_PROGRESS. If you PUT an updated tnList, all draft child\n port-in orders are removed, and the validation process begins again with the new\n tnList.
    • \n
  • If at least one of the telephone numbers in the tnList is not portable, the bulk\n port-in transitions to the INVALID_DRAFT_TNS state. When this happens, no child\n port-in orders are created. You can use the GET operation on /tnList to see reasons\n why telephone numbers are non-portable. You’ll need to update the tnList to remove\n non-portable telephone numbers and PUT the tnList again to restart the validation\n step. The goal is to get to the VALID_DRAFT_TNS state, from which you can submit\n the bulk port-in order.
\n

Please visit Guides and Tutorials

", "operationId": "UpdateBulkTnList", "summary": "Update bulk port-in order tn list", "parameters": [ @@ -2446,7 +2446,7 @@ "/accounts", "Porting" ], - "description": "Retrieves the history of the specified bulk port-in order. Obtaining history for a draft bulk port-in is not supported.

Please visit Guides and Tutorials

", + "description": "Retrieves the history of the specified bulk port-in order. Obtaining history for a draft bulk port-in is not supported.

Please visit Guides and Tutorials

", "operationId": "GetBulkHistory", "summary": "Retrieve bulk port-in order history", "parameters": [ @@ -10521,7 +10521,7 @@ "/accounts", "Porting" ], - "description": "Creates a port-in order for the specified telephone number(s) and account number.", + "description": "Creates a port-in order for the specified telephone number(s) and account number.
Please visit How to Create Port in guide. Also you can find more information about port types and numbers portability on How to check numbers portability guide", "operationId": "CreatePortin", "summary": "Create port-in order", "parameters": [ @@ -24242,7 +24242,18 @@ { "$ref": "#/components/schemas/LnpOrderBasic" } - ] + ], + "type": "object", + "properties": { + "Subscriber": { + "type": "object", + "allOf": [ + { + "$ref": "#/components/schemas/SubscriberBusiness" + } + ] + } + } } } }, From 7a40f20a884e63c18290642a5a3ed997fd713739 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Tue, 19 Jul 2022 15:32:13 +0300 Subject: [PATCH 11/20] Porting - Fix some external and internal references --- .../campaign-management/csp/campaign-api.mdx | 2 +- .../imports/imports-api.mdx | 2 +- site/docs/numbers/porting/loaUpload.mdx | 4 +- site/docs/numbers/porting/portingNumbers.mdx | 4 +- site/docs/numbers/porting/updatePortin.mdx | 187 ++++++++++++++---- site/docs/voice/migrationGuide.mdx | 2 +- site/specs-temp/numbers.json | 2 +- 7 files changed, 158 insertions(+), 45 deletions(-) diff --git a/site/docs/messaging/campaign-management/csp/campaign-api.mdx b/site/docs/messaging/campaign-management/csp/campaign-api.mdx index 320950f90..67380e480 100644 --- a/site/docs/messaging/campaign-management/csp/campaign-api.mdx +++ b/site/docs/messaging/campaign-management/csp/campaign-api.mdx @@ -728,7 +728,7 @@ Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManag ## Update Campaign TN Relationship ### Assumption -This endpoint assumes that TN(s) have already been ordered or ported into our system. For more info, please see [our number ordering](/docs/numbers/guides/searchingForNumbers) or [number porting](/docs/numbers/guides/portingNumbers) guides. +This endpoint assumes that TN(s) have already been ordered or ported into our system. For more info, please see [our number ordering](/docs/numbers/guides/searchingForNumbers) or [number porting](/docs/numbers/guides/porting/portingNumbers) guides. ### Request URL POST https://dashboard.bandwidth.com/api/accounts/{accountId}/tnoptions diff --git a/site/docs/messaging/campaign-management/imports/imports-api.mdx b/site/docs/messaging/campaign-management/imports/imports-api.mdx index f6807c633..e54c1ef65 100644 --- a/site/docs/messaging/campaign-management/imports/imports-api.mdx +++ b/site/docs/messaging/campaign-management/imports/imports-api.mdx @@ -290,7 +290,7 @@ Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManag ## Update Campaign TN Relationship ### Assumption -This endpoint assumes that TN(s) have already been ordered or ported into our system. For more info, please see [our number ordering](/docs/numbers/guides/searchingForNumbers) or [number porting](/docs/numbers/guides/portingNumbers) guides. +This endpoint assumes that TN(s) have already been ordered or ported into our system. For more info, please see [our number ordering](/docs/numbers/guides/searchingForNumbers) or [number porting](/docs/numbers/guides/porting/portingNumbers) guides. #### Request URL POST https://dashboard.bandwidth.com/api/accounts/{accountId}/tnoptions diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx index 996110ee6..01b8ad10c 100644 --- a/site/docs/numbers/porting/loaUpload.mdx +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -38,7 +38,7 @@ export const Highlight = ({children, color}) => ( ); -After successfully submitting the Create LNP Order request, an Letter of Authorization (LOA) may be uploaded using our LOA API. +After successfully submitting the [Create LNP Order request](/docs/numbers/guides/porting/portingNumbers), an Letter of Authorization (LOA) may be uploaded using our LOA API. The following MIME types are supported for the LOA upload file: @@ -52,7 +52,7 @@ The following MIME types are supported for the LOA upload file: * ZIP(“application/zip”) -To upload/manage the LOA you can use different requests to [/portins/{orderId}/loas API](/apis/numbers/#operation/UploadPortinLoaFile). This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +To upload and manage the LOA you can use different requests to [/portins/{orderId}/loas API](/apis/numbers/#operation/UploadPortinLoaFile). This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 7800117c3..6c689a9b8 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -347,9 +347,9 @@ try { ### Polling vs. Webhooks -Porting numbers in the Bandwidth Dashboard is asynchronous when creating an LNP "order". The orders are then processed and the order status is updated asynchronously. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. Please follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) guide. +Porting numbers in the Bandwidth Dashboard is asynchronous which means the orders are processed and the order status is updated asynchronously. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. Please follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) guide. -To poll an information about your Port in you can still use a GET request to [/portins API](/apis/numbers/#operation/GetPortin). This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +To poll an information about your Port in you can still use a GET request to [accounts/{accountId}/portins API](/apis/numbers/#operation/GetPortin). This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. GET https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} ( In this guide we will show you how to manage your Port in order. Please ensure you have followed our earlier guide on [How to create Port in order](/docs/numbers/guides/porting/updatePortin) with Bandwidth. -The PUT to `accounts/{accountId}/portins/{orderId}` API allows a user to modify an existing LNP order, by sending a so-called SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. +The PUT to [accounts/{accountId}/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin) API allows a user to modify an existing LNP order, by sending a so-called SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. If the order ProcessingStatus is `DRAFT`, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from `DRAFT` to `SUBMITTED`. The AltSpid element can be modified if it is not configured at the system level. +Regarding the fields which can be updated for different port types check [request schema for PUT accounts/{accountId}/portins/{orderId}](/apis/numbers/#operation/UpdatePortin) guide. -The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. Please refer to the matrix below to see which elements can be modified and replaced. - -### Request URL +The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} @@ -61,7 +60,7 @@ The general approach to handling this API call is to replace the elements includ ```xml -PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/d28b36f7-fa96-49eb-9556-a40fca49f7c6 HTTP/1.1 Content-Type: application/xml; charset=utf-8 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= @@ -102,19 +101,39 @@ Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= ``` +> Response + +```xml +HTTP 200 OK +Content-Type: application/xml; charset=utf-8 + + + d28b36f7-fa96-49eb-9556-a40fca49f7c6 + + 200 + Supp request received. Please use the order id to check the status of your order later. + + REQUESTED_SUPP + 2022-06-04T13:00:00Z + 8045030092 + 9175131245 + false + +``` + ```cURL Note: Remember to add authentication for your application if needed! -curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ --X POST \ +curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins/d28b36f7-fa96-49eb-9556-a40fca49f7c6' \ +-X PUT \ -U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ -H 'Content-Type: application/xml' \ -d ' SJM00002 -2014-12-04T13:00:00.000Z +2022-06-04T13:00:00.000Z 8045030092 9175131245 @@ -148,6 +167,26 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ ' ``` +> Response + +```xml +HTTP 200 OK +Content-Type: application/xml; charset=utf-8 + + + d28b36f7-fa96-49eb-9556-a40fca49f7c6 + + 200 + Supp request received. Please use the order id to check the status of your order later. + + REQUESTED_SUPP + 2022-06-04T13:00:00Z + 8045030092 + 9175131245 + false + +``` + @@ -166,7 +205,7 @@ supp.setPeerId("12345"); // ... try { - LnpOrder order = LnpOrder.get(client, "orderId"); + LnpOrder order = LnpOrder.get(client, "d28b36f7-fa96-49eb-9556-a40fca49f7c6"); order.update(supp); System.out.println(order); } catch (Exception e) { @@ -186,7 +225,7 @@ var data = new PortIn PeerId = "12345", SiteId = "123" }; -var portInOrder = PortIn.Get("orderId"); +var portInOrder = PortIn.Get("d28b36f7-fa96-49eb-9556-a40fca49f7c6"); portInOrder.Update(data); ``` @@ -206,7 +245,7 @@ data = { //... } -portIn = BandwidthIris::PortIn.get("portin_id", callback) +portIn = BandwidthIris::PortIn.get("d28b36f7-fa96-49eb-9556-a40fca49f7c6", callback) portIn.update(data) ``` @@ -224,7 +263,9 @@ numbers.Client.globalOptions.accountId = "accountId"; numbers.Client.globalOptions.userName = "userName"; numbers.Client.globalOptions.password = "password"; -portIn.update(data, callback);; +numbers.PortIn.get("d28b36f7-fa96-49eb-9556-a40fca49f7c6", function(err, portIn){ + portIn.update(data, callback); +}); ``` @@ -254,40 +295,30 @@ try { -> Postman/cURL Response Example - -```xml -HTTP 200 OK -Content-Type: application/xml; charset=utf-8 - - - b6080e4c-7ddf-4faa-bbd8-328a72de9297 - - 200 - Supp request received. Please use the order id to check the status of your order later. - - REQUESTED_SUPP - 2014-12-04T13:00:00Z - 8045030092 - 9175131245 - false - -``` - ## Cancel a Portin Order The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and dhe status of the order shall not be marked as `COMPLETE`. The DELETE method is used for this purpose. -### Request URL - DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} -### Examples + + > Request ```http -DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} HTTP/1.1 +DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/d28b36f7-fa96-49eb-9556-a40fca49f7c6 HTTP/1.1 Content-Type: application/xml; charset=utf-8 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= ``` @@ -296,4 +327,86 @@ Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= ```http HTTP 200 OK -``` \ No newline at end of file +``` + + + + +```java +String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); +String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); +String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); +String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); +String version = System.getenv("BANDWIDTH_IRIS_URL"); + +IrisClient client = new IrisClient(accountId, username, password, irisUrl, version); + +LnpOrder order = LnpOrder.get(client, "d28b36f7-fa96-49eb-9556-a40fca49f7c6"); +order.delete(); +``` + + + + +```csharp +var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") + +var portInOrder = PortIn.Get("d28b36f7-fa96-49eb-9556-a40fca49f7c6"); +portInOrder.Delete(); +``` + + + + +```ruby +require 'ruby-bandwidth-iris' + +BandwidthIris::Client.global_options = { +:account_id => 'accountId', +:username => 'userName', +:password => 'password' +} + +portIn = BandwidthIris::PortIn.get("d28b36f7-fa96-49eb-9556-a40fca49f7c6", callback) +portIn.delete +``` + + + + +```js +var numbers = require("@bandwidth/numbers"); + +numbers.Client.globalOptions.accountId = "accountId"; +numbers.Client.globalOptions.userName = "userName"; +numbers.Client.globalOptions.password = "password"; + +numbers.PortIn.get("d28b36f7-fa96-49eb-9556-a40fca49f7c6", function(err, portIn){ + portIn.delete(callback); +}); +``` + + + + +```php +$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); +$username = getenv("BANDWIDTH_API_USERNAME"); +$password = getenv("BANDWIDTH_API_PASSWORD"); +$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); + +$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); +$account = new \Iris\Account($accountId, $client); + + +$portin = $account->portins()->portin("d28b36f7-fa96-49eb-9556-a40fca49f7c6")); +$portin->delete(); +``` + + + + +## Where to next? + +Now that you have learnt how to manage a Port in order, check out some of the available actions in the following guides: +- [How to manage Port in](/docs/numbers/guides/porting/updatePortin) \ No newline at end of file diff --git a/site/docs/voice/migrationGuide.mdx b/site/docs/voice/migrationGuide.mdx index c572973c3..581fcc458 100644 --- a/site/docs/voice/migrationGuide.mdx +++ b/site/docs/voice/migrationGuide.mdx @@ -1178,7 +1178,7 @@ Our Bandwidth Signature Support is included for free for every customer. Our sup Whether you are [purchasing new phone numbers](/docs/numbers/guides/orderingNumbers) to use with Bandwidth or looking to keep your existing phone numbers purchased from Twilio, the process couldn’t be easier. -You can port your numbers from Twilio to Bandwidth without devoting any downtime by following a few simple steps in our [Porting Numbers ](/docs/numbers/guides/portingNumbers) guide. +You can port your numbers from Twilio to Bandwidth without devoting any downtime by following a few simple steps in our [Porting Numbers ](/docs/numbers/guides/porting/portingNumbers) guide. ## Other API features diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index fc4f68d22..7ba5e962c 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -10653,7 +10653,7 @@ "/accounts", "Porting" ], - "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing LNP order. This is done via a PUT on the existing order-id. If a field is present in the PUT /portins/{orderId} payload, the value of the field will be updated for the order, subject to existing rules about the field. If a field is NOT present in the PUT /portins/{orderId} payload, behavior varies as to whether the missing field is removed from the port-in, set to a default value, or left unchanged. As a result, we STRONGLY RECOMMEND performing a GET on the order and copying those element values to the PUT for any elements you are not explicitly trying to change the value of.

Note:

  • If the order ProcessingStatus is DRAFT, the rules about what can be changed are much more relaxed. Most of the validation is performed when the ProcessingStatus is changed from DRAFT to SUBMITTED. If SUPP is performed on a draft portin, no validations are applied except validation of the ListOfPhoneNumbers, if at least 1 PhoneNumber is provided.
  • If the port-in order is associated with a bulk port-in which is in DRAFT state, it is not possible to change its state from DRAFT to SUBMITTED without detaching it from the bulk port-in. Alternatively, submitting the parent bulk port-in will trigger the submission of child port-in orders.

\n", + "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing LNP order. This is done via a PUT on the existing order-id. If a field is present in the PUT /portins/{orderId} payload, the value of the field will be updated for the order, subject to existing rules about the field. If a field is NOT present in the PUT /portins/{orderId} payload, behavior varies as to whether the missing field is removed from the port-in, set to a default value, or left unchanged. As a result, we STRONGLY RECOMMEND performing a GET on the order and copying those element values to the PUT for any elements you are not explicitly trying to change the value of.

Note:

  • If the order ProcessingStatus is DRAFT, the rules about what can be changed are much more relaxed. Most of the validation is performed when the ProcessingStatus is changed from DRAFT to SUBMITTED. If SUPP is performed on a draft portin, no validations are applied except validation of the ListOfPhoneNumbers, if at least 1 PhoneNumber is provided.
  • If the port-in order is associated with a bulk port-in which is in DRAFT state, it is not possible to change its state from DRAFT to SUBMITTED without detaching it from the bulk port-in. Alternatively, submitting the parent bulk port-in will trigger the submission of child port-in orders.

Please visit How to Manage Port in guide. Also you can find more information about port types on Port Types section of this guide\n", "operationId": "UpdatePortin", "summary": "Update port-in order", "parameters": [ From 5a4d6cf8c8aceef1047e1d5f4e22dac3a0e0fee5 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Mon, 25 Jul 2022 17:56:14 +0300 Subject: [PATCH 12/20] Porting - do bulk porting more cute --- site/docs/numbers/porting/bulkportins.mdx | 466 +++++++++------------- site/docs/numbers/porting/lnpChecker.mdx | 2 +- site/specs-temp/numbers.json | 11 +- 3 files changed, 192 insertions(+), 287 deletions(-) diff --git a/site/docs/numbers/porting/bulkportins.mdx b/site/docs/numbers/porting/bulkportins.mdx index 16debc363..ed9c68bd3 100644 --- a/site/docs/numbers/porting/bulkportins.mdx +++ b/site/docs/numbers/porting/bulkportins.mdx @@ -1,6 +1,6 @@ --- id: bulkPortins -title: Create Bulk Portin +title: Bulk Portins slug: /numbers/guides/porting/bulkPortins description: How to manage bulk port-in order using the Bandwidth API keywords: @@ -29,16 +29,17 @@ export const Highlight = ({children, color}) => ( ); +[The bulkPortins endpoint](/apis/numbers#operation/CreateBulkPortin) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. -[The bulkPortins endpoint](/apis/numbers#operation/ListBulkPortins) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. -:::info -If you want to create individual port-in you can use `/portins` API. For more details follow the [How to create Port in request](/docs/numbers/guides/porting/portingNumbers) guide. -::: +## Create Bulk Portin -Like many other requests, the bulkPortins endpoint causes the creation of a Bulk Portins order that is used to manage the porting event throughout the lifecycle of the request. +To create Bulk Port-in request order, you must make a POST request to our [API /bulkPortins](/apis/numbers/#operation/CreateBulkPortin) endpoint. This order is used to manage the porting event throughout the lifecycle of the request. This can be done through tools like [Postman](https://github.com/Bandwidth/postman), or in command line. Note the ```OrderId``` field in response. It will be used for the next steps. -To create Port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +:::info +Only fields that you wish to use as defaults for all of the child port-in orders should be included in the bulk port-in order. +::: +### Examples POST https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins POST +> Request + ```xml -Note: Remember to add authentication for your application if needed! +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + +https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins +\n + + Order Id for all child orders + 2021-06-30Z + 14020 + 521434 + +``` + +> Response -https://dashboard.bandwidth.com/api/accounts/{accountId}/portins -//Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD - - 2016-03-25T21:15:00.000Z - X455 - 9195551234 - 9175131245 - 12345 - 660123 - - BUSINESS - First - Last - - 11235 - Back - Denver - CO - 27541 - Canyon - - - The Authguy - - 771297665AABC - 1234 - - - 9195551234 - 9195554321 - - true - +``` + + + + Order Id for all child orders + 2021-06-30T00:00:00.000Z + 14020 + 521434 + DRAFT + 9900572 + jgilmore + jgilmore + 2021-06-21T19:42:34.760Z + 2021-06-21T19:42:34.760Z + 3233e096-1ce5-4a58-ba77-02a5ee1c0ef4 + + ``` @@ -100,262 +94,172 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/portins ```cURL Note: Remember to add authentication for your application if needed! -curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ +curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/bulkPortins' \ -X POST \ -U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ -H 'Content-Type: application/xml' \ --d ' -2016-03-25T21:15:00.000Z -X455 -9195551234 -9175131245 -12345 -660123 - - BUSINESS - First - Last - - 11235 - Back - Denver - CO - 27541 - Canyon - - -The Authguy - - 771297665AABC - 1234 - - - 9195551234 - 9195554321 - -true -' +-d ' + Order Id for all child orders + 2021-06-30Z + 14020 + 521434 +' ``` - - -```java -import com.bandwidth.iris.sdk.IrisClient; -import com.bandwidth.iris.sdk.model.LnpOrder; -import com.bandwidth.iris.sdk.model.ServiceAddress; -import com.bandwidth.iris.sdk.model.Subscriber; - -public class Main { - -public static void main(String[] args) { -String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); -String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); -String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); -String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); -String version = System.getenv("BANDWIDTH_IRIS_URL"); - -IrisClient client = new IrisClient(irisUrl, accountId, username, password, version); - -Subscriber s = new Subscriber(); -s.setSubscriberType("BUSINESS"); -s.setBusinessName("Company"); -ServiceAddress serviceAddress = new ServiceAddress(); -serviceAddress.setHouseNumber("123"); -serviceAddress.setStreetName("Anywhere St"); -serviceAddress.setCity("Raleigh"); -serviceAddress.setStateCode("NC"); -serviceAddress.setZip("27609"); -s.setServiceAddress(serviceAddress); - -LnpOrder order = new LnpOrder(); -order.setSiteId("123"); -order.setPeerId("12345"); -order.setBillingTelephoneNumber("9195551212"); -order.setSubscriber(s); -order.setLoaAuthorizingPerson("Joe Blow"); -order.getListOfPhoneNumbers().add("9195551212"); - -try { -order = LnpOrder.create(client, order); -System.out.println(order); -} catch (Exception e) { -System.out.println(e.getMessage()); -} -} -} -``` + - - - -```csharp -var accountId = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ACCOUNT_ID"); -var username = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_USERNAME"); -var password = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_PASSWORD"); -var apiEndpoint = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ENDPOINT"); - -var client = Client.GetInstance(accountId, username, password, apiEndpoint) - -var data = new PortIn -{ - BillingTelephoneNumber = "+1-202-555-0158", - Subscriber = new Subscriber -{ - SubscriberType = "BUSINESS", - BusinessName = "Company", - FirstName = "John", - LastName = "Doe", - ServiceAddress = new Address -{ - City = "City", - StateCode = "State", - Country = "Country" -} -}, - PeerId = "12345", - SiteId = "123" -}; -var order = await PortIn.Create(client, data); -``` +## Provide telephone number(s) to port - - - -```ruby -require 'ruby-bandwidth-iris' - -BandwidthIris::Client.global_options = { -:account_id => 'accountId', -:username => 'userName', -:password => 'password' -} - -data = { -:site_id =>1234, -:peer_id => 5678, -:billing_telephone_number => "9195551212", -:subscriber => { -:subscriber_type => "BUSINESS", -:business_name => "Company", -:service_address => { -:house_number => "123", -:street_name => "EZ Street", -:city => "Raleigh", -:state_code => "NC", -:county => "Wake" -} -}, -:loa_authorizing_person => "Joe Blow", -:list_of_phone_numbers => { -:phone_number => ["9195551212"] -}, -:billing_type => "PORTIN" -} - -portin_response = BandwidthIris::PortIn.create(data) +After Bulk Portin is created the next step is to add telephone numbers to the order. To do it you must send a PUT request to our [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/UpdateBulkTnList) endpoint. This can be done through tools like [Postman](https://github.com/Bandwidth/postman), or in command line. + +### Examples + +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList + + + +> Request + +```xml +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + +https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList +\n + + [telephone number] + [telephone number] + + [telephone number] + [telephone number] + ``` - - - -```js -var numbers = require("@bandwidth/numbers"); - -var data = { -siteId: 1234, -peerId: 5678, -billingTelephoneNumber: "9195551212", -subscriber: { -subscriberType: "BUSINESS", -businessName: "Company", -serviceAddress: { -houseNumber: "123", -streetName: "EZ Street", -city: "Raleigh", -stateCode: "NC", -county: "Wake" -} -}, -loaAuthorizingPerson: "Joe Blow", -listOfPhoneNumbers: { -phoneNumber: ["9195551212"] -}, -billingType: "PORTIN" -}; - -// Using client directly -// var client = new numbers.Client("accountId", "userName", "password"); -// numbers.PortIn.create(client, function(err, response){...}); - -//Or you can use default client instance (do this only once) -numbers.Client.globalOptions.accountId = "accountId"; -numbers.Client.globalOptions.userName = "userName"; -numbers.Client.globalOptions.password = "password"; - -//Default client will be used to do this call -numbers.PortIn.create(data, callback); +> Response + +``` + + + ac2c8ab2-7a63-44da-a307-edcabe0b6c81 + VALIDATE_DRAFT_TNS + ``` - - -```php -$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); -$username = getenv("BANDWIDTH_API_USERNAME"); -$password = getenv("BANDWIDTH_API_PASSWORD"); -$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); - -$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); -$account = new \Iris\Account($accountId, $client); - -try { -$portin = $account->portins()->create(array( -"BillingTelephoneNumber" => "6882015002", -"Subscriber" => array( -"SubscriberType" => "BUSINESS", -"BusinessName" => "Acme Corporation", -"ServiceAddress" => array( -"HouseNumber" => "1623", -"StreetName" => "Brockton Ave", -"City" => "Los Angeles", -"StateCode" => "CA", -"Zip" => "90025", -"Country" => "USA" -) -), -"LoaAuthorizingPerson" => "John Doe", -"ListOfPhoneNumbers" => array( -"PhoneNumber" => array("9882015025", "9882015026") -), -"SiteId" => "365", -"Triggered" => "false" -)); -} catch (BandwidthLib\APIException $e) { -print_r($e->getResponseCode()); -} + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/bulkPortins' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + [telephone number] + [telephone number] + + [telephone number] + [telephone number] +' ``` -The set of port-ins associated with the bulk port-in remain in a DRAFT state until you've had a chance to examine the breakdown. From that point, you can decide to submit all of the port-ins together under the umbrella of the bulk port-in, or you can separate out individual port-ins to submit by themselves. +After submitting a tnList with the ```PUT``` operation, you will need to poll for completion of the validation and decomposition using the GET [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/ListBulkTns). Check the ```ProcessingStatus``` field. If all the telephone numbers in the tnList are portable, the bulk port-in transitions to the ```VALID_DRAFT_TNS``` state. -When a bulk port-in is created successfully, it will have one or more child port-in orders that satisfy the following industry port-in rules: +:::caution +If at least one of the telephone numbers in the tnList is not portable, the bulk port-in transitions to the ```INVALID_DRAFT_TNS``` state. You will see reasons why telephone numbers are non-portable in response body. To fix it you’ll need to update the tnList to remove non-portable telephone numbers. +::: + +At this point, bulk port-in will have one or more child port-in orders that satisfy industry port-in rules (for more details on the rules check [Port Types](/docs/numbers/guides/porting/lnpChecker/#port-types) guide). + +## Submit Bulk Portin + +The bulk port-in and child port-in orders will remain in ```DRAFT``` state until you transit them to ```IN_PROGRESS``` state. The child port-ins are also created in DRAFT status, allowing you to update fields that need to be different for each child order before the child orders are submitted. +You can submit all the port-ins together under the umbrella of the bulk port-in. + +:::info +Regardless of bulk port-in You can still work with individual port-ins to submit by themselves through ```PUT``` request to [/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin). Check [Update Portin](/docs/numbers/guides/porting/updatePortin) guide to learn more. +::: + +To trigger Bulk Portin processing use the ```PATCH``` operation on the bulk port-in order to change the ```ProcessingStatus``` to ```IN_PROGRESS```. To do it you must send a PATCH request to our [API /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkPortin) endpoint. This can be done through tools like [Postman](https://github.com/Bandwidth/postman), or in command line. + +### Examples + +PATCH https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} + + + +> Request -* Telephone numbers in a child port-in order all have the same port-type (e.g. toll free, automated on-net, automated off-net, internal, etc.). -* Non-toll free telephone numbers in a child port-in order all have the same losing carrier. -* Toll free telephone numbers in a child port-in order all have the same losing RespOrg. +```xml +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + +https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} +\n + + IN_PROGRESS + +``` + +> Response + +``` + + + + Order Id for all child orders + 2021-06-30T00:00:00.000Z + 14020 + 521434 + IN_PROGRESS + 9900572 + jgilmore + jgilmore + 2021-06-21T19:42:34.760Z + 2021-06-21T19:42:34.760Z + 3233e096-1ce5-4a58-ba77-02a5ee1c0ef4 + + +``` -The elements used or supplied in the bulk port-in payload are described in the table below. The values supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. + + -All bulk port-ins start in a draft processing status and remain in a draft state until explicitly submitted -by setting the bulk port-in ProcessingStatus to IN_PROGRESS. The bulk order starts in “DRAFT” state until -telephone numbers are added using the /tnList endpoint. Once telephone numbers are added, the order -transitions to VALIDATE_DRAFT_TNS, and from there to either VALID_DRAFT_TNS, or INVALID_DRAFT_TNS. -If there are invalid, or non-portable telephone numbers, a GET on [/tnList](/apis/numbers/#operation/ListBulkTns) will show the errors. If all -telephone numbers are portable, child port-in orders are created to handle the actual port-ins. +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + IN_PROGRESS + ' +``` + + + -A bulk port-in order may have one of 3 terminal processing statuses: COMPLETED, CANCELLED, or PARTIAL, which are just an aggregation of the child order statuses. An order in a “terminal” state will never transition to any other processing status (terminal or not). A bulk port-in order goes to a terminal status automatically as soon as the last of its associated child port-ins transfers to terminal status (COMPLETE or CANCELLED). The resulting terminal processing status of the bulk port-in order depends on statuses of associated child port-ins: COMPLETED - when all child port-ins are in COMPLETE status, CANCELLED - when all child port-ins are in CANCELLED status, PARTIAL - when there is a mix of CANCELLED and COMPLETE child port-in statuses. +## Bulk Portin completion -The following table describes parameters for the bulk port-in API. All parameters except for the URL parameter "accountId" are optional in the bulk port-in, although the rules for individual child port-ins described in the [/portins](/apis/numbers/#operation/ListPortins) API still apply to the child port-ins that make up the bulk port-in. Enforcement of required fields in the child port-ins occurs when the bulk port-in is submitted (i.e. changed from a DRAFT status to IN_PROGRESS). Only fields that you wish to use as defaults for all of the child port-in orders should be included in the bulk port-in order. The child port-ins are also created in DRAFT status, allowing you to update fields that need to be different for each child order before the child orders are submitted. +A bulk port-in order may have one of 3 terminal processing statuses: ```COMPLETED```, ```CANCELLED```, or ```PARTIAL```, which are just an aggregation of the child order statuses. An order in a “terminal” state will never transition to any other processing status (terminal or not). A bulk port-in order goes to a terminal status automatically as soon as the last of its associated child port-ins transfers to terminal status (```COMPLETE``` or ```CANCELLED```). The resulting terminal processing status of the bulk port-in order depends on statuses of associated child port-ins: +* ```COMPLETED``` - when all child port-ins are in ```COMPLETE``` status +* ```CANCELLED``` - when all child port-ins are in ```CANCELLED``` status +* ```PARTIAL``` - when there is a mix of ```CANCELLED``` and ```COMPLETE``` child port-in statuses. \ No newline at end of file diff --git a/site/docs/numbers/porting/lnpChecker.mdx b/site/docs/numbers/porting/lnpChecker.mdx index e271935ac..270c1ff47 100644 --- a/site/docs/numbers/porting/lnpChecker.mdx +++ b/site/docs/numbers/porting/lnpChecker.mdx @@ -37,7 +37,7 @@ export const Highlight = ({children, color}) => ( A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network. TNs can be ported in a single `/portins` request if all the following are true: 1. They all have the same Port Type (see the `Port Types` section below) -2. They all have the same losing carrier +2. Telephone numbers all have the same losing carrier (toll free telephone numbers all have the same losing RespOrg) 3. They are all associated with the same billing TN and Service Address :::info diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index 594ffc95a..f612d60e2 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -1679,8 +1679,8 @@ "/accounts", "Porting" ], - "description": "

Creates a bulk port-in order to be used as a template for a collection of child port-in orders. The template values will be cascaded to child port-ins that result from decomposing a collection of Telephone Numbers that span carriers, RespOrgs, or have attributes that drive the decomposition into a number of individual port-in orders.

Upon a successfully-submitted payload, the order will have a status of \"DRAFT\", denoting that further modification to the template is expected. For example, the next step is to use the /tnList endpoint to add a collection of telephone numbers to the bulk port-in order. The only valid value for the ProcessingStatus element in a POST is 'DRAFT', which is the default value.

Please visit Guides and Tutorials

", - "operationId": "CreateBulkOrder", + "description": "

Creates a bulk port-in order to be used as a template for a collection of child port-in orders. The template values will be cascaded to child port-ins that result from decomposing a collection of Telephone Numbers that span carriers, RespOrgs, or have attributes that drive the decomposition into a number of individual port-in orders.

Upon a successfully-submitted payload, the order will have a status of \"DRAFT\", denoting that further modification to the template is expected. For example, the next step is to use the /tnList endpoint to add a collection of telephone numbers to the bulk port-in order. The only valid value for the ProcessingStatus element in a POST is 'DRAFT', which is the default value. All parameters except for the URL parameter \"accountId\" are optional in the bulk port-in, although the rules for individual child port-ins described in the POST /portins API still apply to the child port-ins that make up the bulk port-in. Enforcement of required fields in the child port-ins occurs when the bulk port-in is submitted (i.e. changed from a DRAFT status to IN_PROGRESS). Enforcement of required fields in the child port-ins occurs when the bulk port-in is submitted (i.e. changed from a DRAFT status to IN_PROGRESS).

Please visit Guides and Tutorials

", + "operationId": "CreateBulkPortin", "summary": "Create bulk port-in order", "parameters": [ { @@ -1799,7 +1799,7 @@ "/accounts", "Porting" ], - "description": "The PUT operation is available only for bulk port-in orders that are not yet associated with subtending orders. Since this only occurs for bulk port-in orders that are in one of the draft states, there are few restrictions on what may be included. As with the POST, any data associated with the bulk port-in will cascade to subtending orders when they are created. (Subtending orders are created after telephone numbers are added to the bulk port-in using the /tnList endpoint.) The PUT completely replaces the existing Bulk Portin order with the payload of the PUT. Please visit Guides and Tutorials.

The following element may appear only in PUT or PATCH operations on a bulk port-in order.
  • RetryValidation - When toll free numbers are included in a port-in order, Bandwidth accesses a vendor to determine if the numbers are portable, and if so, from which RespOrg. In the event that we do not receive a response from our vendor after a number of retries, we give up and place the order in the INVALID_DRAFT_TNS state. This scenario can occur if our toll free porting vendor is performing maintenance, for example. Including RetryValidation with a value of true will cause the order to return to VALIDATE_DRAFT_TNS and we will repeat our attempts to retrieve the portability data from the vendor. This element is included in the synchronous response to the PUT or PATCH, when included in the request, but is not included in subsequent GET requests for the order.
", + "description": "The PUT operation is available only for bulk port-in orders that are not yet associated with subtending orders. Since this only occurs for bulk port-in orders that are in one of the draft states, there are few restrictions on what may be included. As with the POST, any data associated with the bulk port-in will cascade to subtending orders when they are created. (Subtending orders are created after telephone numbers are added to the bulk port-in using the /tnList endpoint.) The PUT completely replaces the existing Bulk Portin order with the payload of the PUT. Please visit Guides and Tutorials.", "operationId": "PutBulkOrder", "summary": "Update bulk port-in order", "parameters": [ @@ -2317,7 +2317,7 @@ "/accounts", "Porting" ], - "description": "

The information returned in the GET /tnList response payload depends on the ProcessingStatus of the bulk port-in order. See the Responses tab for examples of each response payload.

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

\n ProcessingStatus\n

\n 		\n

\n Information Returned\n

\n
\n

\n DRAFT\n

\n 		\n

\n In this state, no tnList has been provided, so the response\n includes empty portable and non-portable telephone number lists.\n

\n
\n

\n VALIDATE_DRAFT_TNS\n

\n 		\n

\n In this state, validation of the tnList is still in progress,\n so the response includes all of the tnList telephone numbers\n in a `not validated` list. This is a temporary state until\n the validation completes. Validation takes longer when toll\n free numbers are included in the tnList.\n

\n
\n

\n VALID_DRAFT_TNS\n

\n 		\n

\n In this state, all of the telephone numbers in the tnList have\n been determined to be portable. The response payload includes\n a list of the child port-in orders and shows which telephone\n numbers are assigned to each child port-in order.\n

\n
\n

\n INVALID_DRAFT_TNS\n

\n 		\n

\n In this state, at least one of the telephone numbers in the tnList\n has been determined to be non-portable. The response payload includes\n a list of portable numbers (if any) and a list of errors showing which\n telephone numbers are non-portable as well as the reasons why they\n cannot be ported. Or, if communication errors prevented us from\n determining telephone number portability, those errors will be included.\n

\n
\n

Please visit Guides and Tutorials

", + "description": "

The information returned in the GET /tnList response payload depends on the ProcessingStatus of the bulk port-in order. See the Responses tab for examples of each response payload.

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

\n ProcessingStatus\n

\n 		\n

\n Information Returned\n

\n
\n

\n DRAFT\n

\n 		\n

\n In this state, no tnList has been provided, so the response\n includes empty portable and non-portable telephone number lists.\n

\n
\n

\n VALIDATE_DRAFT_TNS\n

\n 		\n

\n In this state, validation of the tnList is still in progress,\n so the response includes all of the tnList telephone numbers\n in a 'not validated' list. This is a temporary state until\n the validation completes. Validation takes longer when toll\n free numbers are included in the tnList.\n

\n
\n

\n VALID_DRAFT_TNS\n

\n 		\n

\n In this state, all of the telephone numbers in the tnList have\n been determined to be portable. The response payload includes\n a list of the child port-in orders and shows which telephone\n numbers are assigned to each child port-in order.\n

\n
\n

\n INVALID_DRAFT_TNS\n

\n 		\n

\n In this state, at least one of the telephone numbers in the tnList\n has been determined to be non-portable. The response payload includes\n a list of portable numbers (if any) and a list of errors showing which\n telephone numbers are non-portable as well as the reasons why they\n cannot be ported. Or, if communication errors prevented us from\n determining telephone number portability, those errors will be included.\n

\n
\n

Please visit Guides and Tutorials

", "operationId": "ListBulkTns", "summary": "List bulk port-in order tns", "parameters": [ @@ -21841,7 +21841,8 @@ } }, "RetryValidation": { - "type": "boolean" + "type": "boolean", + "description": "Only allowed for PUT and PATCH requests.\n\n When toll free numbers are included in a port-in order, Bandwidth accesses a vendor to determine if the numbers are portable, and if so, from which RespOrg. In the event that we do not receive a response from our vendor after a number of retries, we give up and place the order in the INVALID_DRAFT_TNS state. This scenario can occur if our toll free porting vendor is performing maintenance, for example. Including RetryValidation with a value of true will cause the order to return to VALIDATE_DRAFT_TNS and we will repeat our attempts to retrieve the portability data from the vendor. This element is included in the synchronous response to the PUT or PATCH, when included in the request, but is not included in subsequent GET requests for the order." } } } From e0b588dd1ce93b7b72d427e2f26a80b6cb655d3d Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Tue, 26 Jul 2022 16:43:23 +0300 Subject: [PATCH 13/20] Porting - make docs cleaner --- site/docs/numbers/porting/bulkportins.mdx | 63 +++++++++++++++++--- site/docs/numbers/porting/lnpChecker.mdx | 14 +++-- site/docs/numbers/porting/loaUpload.mdx | 21 ++++--- site/docs/numbers/porting/portingNumbers.mdx | 15 +++-- site/docs/numbers/porting/updatePortin.mdx | 26 ++++---- site/sidebar.js | 2 +- site/specs-temp/numbers.json | 2 +- 7 files changed, 101 insertions(+), 42 deletions(-) diff --git a/site/docs/numbers/porting/bulkportins.mdx b/site/docs/numbers/porting/bulkportins.mdx index ed9c68bd3..047c44d0d 100644 --- a/site/docs/numbers/porting/bulkportins.mdx +++ b/site/docs/numbers/porting/bulkportins.mdx @@ -15,7 +15,6 @@ import TabItem from '@theme/TabItem'; export const accountId = "{accountId}"; export const orderId = "{orderId}"; -export const disconnectId = "{bulkOrderId}"; export const Highlight = ({children, color}) => ( POST https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins +## Update Bulk Portin + +It is possible to update Bulk Port-in order using ```PUT``` or ```PATCH``` request to ```/bulkPortins/{orderId} API``` on the existing order-id: +* As with the ```POST```, any data associated with the bulk port-in will cascade to subtending orders when they are created +* If the port-in orders contained within the Bulk Port are in ```DRAFT``` state, any field can be modified +* If any child port-in order in the Bulk Port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller + +:::info +Subtending orders are created after tns are added to the bulk port-in using the /tnList endpoint, see the next section of this tutorial. +::: + +* The [```PUT``` /bulkPortins/{orderId}](/apis/numbers/#operation/PutBulkOrder) operation is available only for bulk port-in orders that are not yet associated with subtending orders +* The [```PATCH``` /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkOrder) replaces only the elements included in the request payload. Other elements will remain untouched + +### Example + +In the following example we are adding ```LoaAuthorizingPerson``` field to the bulk porting (to apply it to all future subtending port-in orders): +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} + +```xml +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + +https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins +\n + + Order Id for all child orders + 2021-06-30Z + 14020 + 521434 + The Guy + +``` + +Note that ```PUT``` completely replaces the existing Bulk Portin order with the given payload. In its turn ```PATCH``` replaces only the elements included in the request payload. + +PATCH https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} + +```xml +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + +https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins +\n + + The Guy + +``` + ## Provide telephone number(s) to port After Bulk Portin is created the next step is to add telephone numbers to the order. To do it you must send a PUT request to our [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/UpdateBulkTnList) endpoint. This can be done through tools like [Postman](https://github.com/Bandwidth/postman), or in command line. -### Examples - PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList PATCH request to our [API /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkPortin) endpoint. This can be done through tools like [Postman](https://github.com/Bandwidth/postman), or in command line. -### Examples - PATCH https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} ( ); -A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network. TNs can be ported in a single `/portins` request if all the following are true: +A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network. +:::info +As an alternative to individual porting the `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/bulkPortins). +::: + +TNs can be ported in a single `/portins` request if all the following are true: 1. They all have the same Port Type (see the `Port Types` section below) 2. Telephone numbers all have the same losing carrier (toll free telephone numbers all have the same losing RespOrg) 3. They are all associated with the same billing TN and Service Address -:::info +:::caution There are also a number of reasons why a TN may not be able to be ported in: * The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. @@ -64,7 +69,7 @@ Port Type - is a categorization of how the TNs submitted to the /lnpchecker API | AUTOMATED | If the TNs are on-net, or off-net and covered by a Bandwidth partner that supports automated ports, then the port-in of these TNs will be handled with no human intervention using interfaces to our porting vendors. There are several sub-types of `AUTOMATED` as follows:
  • `AUTOMATED` - means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth (On-net tns). There are differences in on-net port-in rules depending on whether the order is for wireless to wireless vs. one of the other 3 combinations.
  • `AUTOMATEDOFFNET` - Off-net means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Currently, only numbers in the U.S. are automated. There are differences in port-in rules depending on whether the order has achieved FOC status.
  • `INTERNAL` - Internal means that the telephone number is being moved from one Bandwidth account to another Bandwidth account. Internal port-in may involve on-net, off-net, or toll free telephone numbers.
| | MIXED | If the list of TNs supplied to /lnpchecker includes TNs that are categorized as more than one of the above Port Types, the resulting Port Type will be `MIXED`. If you plan to use /portins to port the TNs, you must break the TN list into separate /portins requests for each Port Type. | -### Check number portability +### Check number(s) portability A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the POST request to [`/accounts/{accountId}/lnpChecker`](/apis/numbers#operation/RequestPortabilityInfo) API endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. @@ -258,5 +263,4 @@ Content-Type: application/xml; charset=utf-8 ## Where to next? Now that you have learnt how to check numbers portability, check out some of the available actions in the following guides: -- [How to create Port in request](/docs/numbers/guides/porting/portingNumbers) -- [How to create Bulk Port in](/docs/numbers/guides/porting/bulkPortins) \ No newline at end of file +- [How to create Port in request →](/docs/numbers/guides/porting/portingNumbers) diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx index 01b8ad10c..1d7951984 100644 --- a/site/docs/numbers/porting/loaUpload.mdx +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -40,20 +40,25 @@ export const Highlight = ({children, color}) => ( After successfully submitting the [Create LNP Order request](/docs/numbers/guides/porting/portingNumbers), an Letter of Authorization (LOA) may be uploaded using our LOA API. +:::caution +If your port-on order has a ```PENDING_DOCUMENTS``` status then LOA upload is a required action. +::: + The following MIME types are supported for the LOA upload file: -* PDF(“application/pdf”) -* PLAIN(“text/plain”) -* JPG(“image/jpeg”) -* TIFF(“image/tiff”) -* CSV(“text/csv”) -* XML(“application/xml”) -* WAV(“audio/x-wav”) -* ZIP(“application/zip”) +* PDF (“application/pdf”) +* PLAIN (“text/plain”) +* JPG (“image/jpeg”) +* TIFF (“image/tiff”) +* CSV (“text/csv”) +* XML (“application/xml”) +* WAV (“audio/x-wav”) +* ZIP (“application/zip”) To upload and manage the LOA you can use different requests to [/portins/{orderId}/loas API](/apis/numbers/#operation/UploadPortinLoaFile). This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +### Examples POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. - +### Examples POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins +:::info +If your port-on order stuck in a ```PENDING_DOCUMENTS``` status then [LOA (Letter of authorization) upload](/docs/numbers/guides/porting/loaUpload) is required action. +::: + ## Where to next? Now that you have learnt how to create a Port in order, check out some of the available actions in the following guides: -- [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) -- [How to upload LOA (Letter of authorization)](/docs/numbers/guides/porting/loaUpload) -- [How to manage Port in](/docs/numbers/guides/porting/updatePortin) -- [How to create Bulk Port in](/docs/numbers/guides/porting/bulkPortins) \ No newline at end of file + +- [How to check numbers portability ←](/docs/numbers/guides/porting/lnpChecker) +- [How to upload LOA (Letter of authorization) →](/docs/numbers/guides/porting/loaUpload) +- [How to manage Port in →](/docs/numbers/guides/porting/updatePortin) +- [How to create Bulk Port in →](/docs/numbers/guides/porting/bulkPortins) diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx index b8feacd36..45e3ec3a2 100644 --- a/site/docs/numbers/porting/updatePortin.mdx +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -1,6 +1,6 @@ --- id: updatePortin -title: Update Portin +title: Manage Portin slug: /numbers/guides/porting/updatePortin description: How to update your portin request keywords: @@ -33,16 +33,20 @@ export const Highlight = ({children, color}) => ( ); -In this guide we will show you how to manage your Port in order. Please ensure you have followed our earlier guide on [How to create Port in order](/docs/numbers/guides/porting/updatePortin) with Bandwidth. +In this guide we will show you how to manage your Port in order. We assume that you have [created Port in order](/docs/numbers/guides/porting/updatePortin) first. -The PUT to [accounts/{accountId}/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin) API allows a user to modify an existing LNP order, by sending a so-called SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. +## Update Port-in Order + +The PUT to [/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin) API allows a user to modify an existing LNP order, by sending a so-called SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. If the order ProcessingStatus is `DRAFT`, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from `DRAFT` to `SUBMITTED`. The AltSpid element can be modified if it is not configured at the system level. -Regarding the fields which can be updated for different port types check [request schema for PUT accounts/{accountId}/portins/{orderId}](/apis/numbers/#operation/UpdatePortin) guide. +Regarding the fields which can be updated for different port types check the request schema section of [PUT /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) specification. -The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. +The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. -PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} +### Examples +To update Port-in request, you must make a PUT request to our [API /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} -## Cancel a Portin Order +## Cancel a Port-in Order -The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and dhe status of the order shall not be marked as `COMPLETE`. The DELETE method is used for this purpose. +The API allows a user to cancel an existing LNP order. The order number that was generated in the create request must be provided, and the status of the order should not be ```COMPLETE```. The DELETE method is used for this purpose. +### Examples DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} delete(); - -## Where to next? - -Now that you have learnt how to manage a Port in order, check out some of the available actions in the following guides: -- [How to manage Port in](/docs/numbers/guides/porting/updatePortin) \ No newline at end of file diff --git a/site/sidebar.js b/site/sidebar.js index 11c29745d..40b917499 100644 --- a/site/sidebar.js +++ b/site/sidebar.js @@ -50,8 +50,8 @@ module.exports = { type: "category", label: "Porting numbers", items: [ - "numbers/porting/portingNumbers", "numbers/porting/lnpChecker", + "numbers/porting/portingNumbers", "numbers/porting/loaUpload", "numbers/porting/updatePortin", "numbers/porting/bulkPortins", diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index f612d60e2..2ec7b04ad 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -10653,7 +10653,7 @@ "/accounts", "Porting" ], - "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing LNP order. This is done via a PUT on the existing order-id. If a field is present in the PUT /portins/{orderId} payload, the value of the field will be updated for the order, subject to existing rules about the field. If a field is NOT present in the PUT /portins/{orderId} payload, behavior varies as to whether the missing field is removed from the port-in, set to a default value, or left unchanged. As a result, we STRONGLY RECOMMEND performing a GET on the order and copying those element values to the PUT for any elements you are not explicitly trying to change the value of.

Note:

  • If the order ProcessingStatus is DRAFT, the rules about what can be changed are much more relaxed. Most of the validation is performed when the ProcessingStatus is changed from DRAFT to SUBMITTED. If SUPP is performed on a draft portin, no validations are applied except validation of the ListOfPhoneNumbers, if at least 1 PhoneNumber is provided.
  • If the port-in order is associated with a bulk port-in which is in DRAFT state, it is not possible to change its state from DRAFT to SUBMITTED without detaching it from the bulk port-in. Alternatively, submitting the parent bulk port-in will trigger the submission of child port-in orders.

Please visit How to Manage Port in guide. Also you can find more information about port types on Port Types section of this guide\n", + "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing LNP order. This is done via a PUT on the existing order-id. If a field is present in the PUT /portins/{orderId} payload, the value of the field will be updated for the order, subject to existing rules about the field. If a field is NOT present in the PUT /portins/{orderId} payload, behavior varies as to whether the missing field is removed from the port-in, set to a default value, or left unchanged. As a result, we STRONGLY RECOMMEND performing a GET on the order and copying those element values to the PUT for any elements you are not explicitly trying to change the value of.

Note:

  • If the order ProcessingStatus is DRAFT, the rules about what can be changed are much more relaxed. Most of the validation is performed when the ProcessingStatus is changed from DRAFT to SUBMITTED. If SUPP is performed on a draft portin, no validations are applied except validation of the ListOfPhoneNumbers, if at least 1 PhoneNumber is provided.
  • Submitting the parent bulk port-in will trigger the submission of child port-in orders.

Please visit How to Manage Port in guide. Also you can find more information about port types on Port Types section of this guide\n", "operationId": "UpdatePortin", "summary": "Update port-in order", "parameters": [ From 3cd07fbc2769f7149dba5f07df3451419cc99b45 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Wed, 27 Jul 2022 17:16:06 +0300 Subject: [PATCH 14/20] Porting - split bulk porting --- site/docs/numbers/porting/bulkportins.mdx | 310 --------------- .../numbers/porting/createBulkPortins.mdx | 190 +++++++++ site/docs/numbers/porting/lnpChecker.mdx | 131 ++----- site/docs/numbers/porting/loaUpload.mdx | 204 ++-------- site/docs/numbers/porting/portingNumbers.mdx | 360 +++--------------- .../docs/numbers/porting/submitBulkportin.mdx | 123 ++++++ .../numbers/porting/updateBulkPortins.mdx | 220 +++++++++++ site/docs/numbers/porting/updatePortin.mdx | 211 +--------- site/sidebar.js | 4 +- site/specs-temp/numbers.json | 28 +- 10 files changed, 682 insertions(+), 1099 deletions(-) delete mode 100644 site/docs/numbers/porting/bulkportins.mdx create mode 100644 site/docs/numbers/porting/createBulkPortins.mdx create mode 100644 site/docs/numbers/porting/submitBulkportin.mdx create mode 100644 site/docs/numbers/porting/updateBulkPortins.mdx diff --git a/site/docs/numbers/porting/bulkportins.mdx b/site/docs/numbers/porting/bulkportins.mdx deleted file mode 100644 index 047c44d0d..000000000 --- a/site/docs/numbers/porting/bulkportins.mdx +++ /dev/null @@ -1,310 +0,0 @@ ---- -id: bulkPortins -title: Bulk Portins -slug: /numbers/guides/porting/bulkPortins -description: How to manage bulk port-in order using the Bandwidth API -keywords: - - bandwidth - - bulkportins - - portin -image: ../../static/img/bandwidth-logo.png ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -export const accountId = "{accountId}"; -export const orderId = "{orderId}"; - -export const Highlight = ({children, color}) => ( - - {children} - - ); - -[The bulkPortins endpoint](/apis/numbers#operation/CreateBulkPortin) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. - -## Create Bulk Portin - -To create Bulk Port-in request order, you must make a POST request to our [API /bulkPortins](/apis/numbers/#operation/CreateBulkPortin) endpoint. This order is used to manage the porting event throughout the lifecycle of the request. This can be done through tools like [Postman](https://github.com/Bandwidth/postman), or in command line. Note the ```OrderId``` field in response. It will be used for the next steps. - -:::info -Only fields that you wish to use as defaults for all of the child port-in orders should be included in the bulk port-in order. -::: - -POST https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins - - - -> Request - -```xml -Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD - -https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins -\n - - Order Id for all child orders - 2021-06-30Z - 14020 - 521434 - -``` - -> Response - -``` - - - - Order Id for all child orders - 2021-06-30T00:00:00.000Z - 14020 - 521434 - DRAFT - 9900572 - jgilmore - jgilmore - 2021-06-21T19:42:34.760Z - 2021-06-21T19:42:34.760Z - 3233e096-1ce5-4a58-ba77-02a5ee1c0ef4 - - -``` - - - - -```cURL -Note: Remember to add authentication for your application if needed! - -curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/bulkPortins' \ --X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ --H 'Content-Type: application/xml' \ --d ' - Order Id for all child orders - 2021-06-30Z - 14020 - 521434 -' -``` - - - - -## Update Bulk Portin - -It is possible to update Bulk Port-in order using ```PUT``` or ```PATCH``` request to ```/bulkPortins/{orderId} API``` on the existing order-id: -* As with the ```POST```, any data associated with the bulk port-in will cascade to subtending orders when they are created -* If the port-in orders contained within the Bulk Port are in ```DRAFT``` state, any field can be modified -* If any child port-in order in the Bulk Port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller - -:::info -Subtending orders are created after tns are added to the bulk port-in using the /tnList endpoint, see the next section of this tutorial. -::: - -* The [```PUT``` /bulkPortins/{orderId}](/apis/numbers/#operation/PutBulkOrder) operation is available only for bulk port-in orders that are not yet associated with subtending orders -* The [```PATCH``` /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkOrder) replaces only the elements included in the request payload. Other elements will remain untouched - -### Example - -In the following example we are adding ```LoaAuthorizingPerson``` field to the bulk porting (to apply it to all future subtending port-in orders): -PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} - -```xml -Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD - -https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins -\n - - Order Id for all child orders - 2021-06-30Z - 14020 - 521434 - The Guy - -``` - -Note that ```PUT``` completely replaces the existing Bulk Portin order with the given payload. In its turn ```PATCH``` replaces only the elements included in the request payload. - -PATCH https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} - -```xml -Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD - -https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins -\n - - The Guy - -``` - -## Provide telephone number(s) to port - -After Bulk Portin is created the next step is to add telephone numbers to the order. To do it you must send a PUT request to our [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/UpdateBulkTnList) endpoint. This can be done through tools like [Postman](https://github.com/Bandwidth/postman), or in command line. - -PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList - - - -> Request - -```xml -Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD - -https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList -\n - - [telephone number] - [telephone number] - - [telephone number] - [telephone number] - -``` - -> Response - -``` - - - ac2c8ab2-7a63-44da-a307-edcabe0b6c81 - VALIDATE_DRAFT_TNS - -``` - - - - -```cURL -Note: Remember to add authentication for your application if needed! - -curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/bulkPortins' \ --X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ --H 'Content-Type: application/xml' \ --d ' - [telephone number] - [telephone number] - - [telephone number] - [telephone number] -' -``` - - - - -After submitting a tnList with the ```PUT``` operation, you will need to poll for completion of the validation and decomposition using the GET [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/ListBulkTns). Check the ```ProcessingStatus``` field. If all the telephone numbers in the tnList are portable, the bulk port-in transitions to the ```VALID_DRAFT_TNS``` state. - -:::caution -If at least one of the telephone numbers in the tnList is not portable, the bulk port-in transitions to the ```INVALID_DRAFT_TNS``` state. You will see reasons why telephone numbers are non-portable in response body. To fix it you’ll need to update the tnList to remove non-portable telephone numbers. -::: - -At this point, bulk port-in will have one or more child port-in orders that satisfy industry port-in rules (for more details on the rules check [Port Types](/docs/numbers/guides/porting/lnpChecker/#port-types) guide). - -## Submit Bulk Portin - -The bulk port-in and child port-in orders will remain in ```DRAFT``` state until you transit them to ```IN_PROGRESS``` state. The child port-ins are also created in ```DRAFT``` status, allowing you to update fields that need to be different for each child order before the child orders are submitted. - -:::caution -Changing the ProcessingStatus to 'IN_PROGRESS' is only valid if child port-ins exist for the bulk port-in. -::: - -You can submit all the port-ins together under the umbrella of the bulk port-in. - -:::info -You can still work with individual port-ins to submit by themselves through ```PUT``` request to [/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin). Check [Update Portin](/docs/numbers/guides/porting/updatePortin) guide to learn more. -::: - -To trigger Bulk Portin processing use the ```PATCH``` operation on the bulk port-in order to change the ```ProcessingStatus``` to ```IN_PROGRESS```. To do it you must send a PATCH request to our [API /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkPortin) endpoint. This can be done through tools like [Postman](https://github.com/Bandwidth/postman), or in command line. - -PATCH https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} - - - -> Request - -```xml -Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD - -https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} -\n - - IN_PROGRESS - -``` - -> Response - -``` - - - - Order Id for all child orders - 2021-06-30T00:00:00.000Z - 14020 - 521434 - IN_PROGRESS - 9900572 - jgilmore - jgilmore - 2021-06-21T19:42:34.760Z - 2021-06-21T19:42:34.760Z - 3233e096-1ce5-4a58-ba77-02a5ee1c0ef4 - - -``` - - - - -```cURL -Note: Remember to add authentication for your application if needed! - -curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ --X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ --H 'Content-Type: application/xml' \ --d ' - IN_PROGRESS - ' -``` - - - - -## Bulk Portin completion - -A bulk port-in order may have one of 3 terminal processing statuses: ```COMPLETED```, ```CANCELLED```, or ```PARTIAL```, which are just an aggregation of the child order statuses. An order in a “terminal” state will never transition to any other processing status (terminal or not). A bulk port-in order goes to a terminal status automatically as soon as the last of its associated child port-ins transfers to terminal status (```COMPLETE``` or ```CANCELLED```). The resulting terminal processing status of the bulk port-in order depends on statuses of associated child port-ins: -* ```COMPLETED``` - when all child port-ins are in ```COMPLETE``` status -* ```CANCELLED``` - when all child port-ins are in ```CANCELLED``` status -* ```PARTIAL``` - when there is a mix of ```CANCELLED``` and ```COMPLETE``` child port-in statuses. \ No newline at end of file diff --git a/site/docs/numbers/porting/createBulkPortins.mdx b/site/docs/numbers/porting/createBulkPortins.mdx new file mode 100644 index 000000000..4ad113b77 --- /dev/null +++ b/site/docs/numbers/porting/createBulkPortins.mdx @@ -0,0 +1,190 @@ +--- +id: createBulkPortins +title: Bulk Port-ins +slug: /numbers/guides/porting/createBulkPortins +description: How to create bulk port-in order using the Bandwidth API +keywords: + - bandwidth + - bulkportins + - portin + - port-in +image: ../../static/img/bandwidth-logo.png +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const accountId = "{accountId}"; +export const orderId = "{orderId}"; + +export const Highlight = ({children, color}) => ( + + {children} + + ); + +[The bulkPortins endpoint](/apis/numbers#operation/CreateBulkPortin) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. + +## Create Bulk Port-in Draft + +To create Bulk Port-in request order, you must make a POST request to our [API /bulkPortins](/apis/numbers/#operation/CreateBulkPortin) endpoint. This order is used to manage the porting event throughout the lifecycle of the request. This can be done through tools like Postman, or in command line. Note the ```OrderId``` field in response. It will be used for the next steps. + +:::info +Only fields that you wish to use as defaults for all of the child port-in orders should be included in the bulk port-in order. +::: + +POST https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins + + + +> Request + +```xml +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + +https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins +\n + + Order Id for all child orders + 2021-06-30Z + 14020 + 521434 + +``` + +> Response + +``` + + + + Order Id for all child orders + 2021-06-30T00:00:00.000Z + 14020 + 521434 + DRAFT + 9900572 + jgilmore + jgilmore + 2021-06-21T19:42:34.760Z + 2021-06-21T19:42:34.760Z + ac2c8ab2-7a63-44da-a307-edcabe0b6c81 + + +``` + + + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/bulkPortins' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + Order Id for all child orders + 2021-06-30Z + 14020 + 521434 +' +``` + + + + +When bulk port-in is created, it has ```DRAFT``` status, which means it has not been processed yet. +If you want to update your bulk port-in (either in ```DRAFT``` or other further state) follow the [How to update Bulk Port-in](/docs/numbers/guides/porting/updateBulkPortins) guide. + +## Provide telephone number(s) to port + +After Bulk Port-in is created the next step is to add telephone numbers to the order. To do it you must send a PUT request to our [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/UpdateBulkTnList) endpoint. This can be done through tools like Postman, or in command line. + +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList + + + +> Request + +```xml +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + +https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList +\n + + [telephone number] + [telephone number] + + [telephone number] + [telephone number] + +``` + +> Response + +``` + + + ac2c8ab2-7a63-44da-a307-edcabe0b6c81 + VALIDATE_DRAFT_TNS + +``` + + + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + [telephone number] + [telephone number] + + [telephone number] + [telephone number] +' +``` + + + + +After submitting a tnList with the ```PUT``` operation, you will need to poll for completion of the validation and decomposition using the GET [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/ListBulkTns). Check the ```ProcessingStatus``` field. If all the telephone numbers in the tnList are portable, the bulk port-in transitions to the ```VALID_DRAFT_TNS``` state. + +:::caution +If at least one of the telephone numbers in the tnList is not portable, the bulk port-in transitions to the ```INVALID_DRAFT_TNS``` state. You will see reasons why telephone numbers are non-portable in response body. To fix it you’ll need to update the tnList to remove non-portable telephone numbers. +::: + +At this point, bulk port-in will have one or more child port-in orders that satisfy industry port-in rules (for more details on the rules check [Port Types](/docs/numbers/guides/porting/lnpChecker/#port-types) guide). +The child port-ins as a bulk port are also created in ```DRAFT``` status, allowing you to update fields that need to be different for each child order before the child orders are submitted. + +## Where to next? + +Now that you have learnt how to create a Bulk Port-in order, check out some of the available actions in the following guides: + +- [How to submit Bulk Port-in →](/docs/numbers/guides/porting/submitBulkPortins) +- [How to update Bulk Port-in →](/docs/numbers/guides/porting/updateBulkPortins) \ No newline at end of file diff --git a/site/docs/numbers/porting/lnpChecker.mdx b/site/docs/numbers/porting/lnpChecker.mdx index 5ce96bfc1..5615c6bef 100644 --- a/site/docs/numbers/porting/lnpChecker.mdx +++ b/site/docs/numbers/porting/lnpChecker.mdx @@ -8,6 +8,7 @@ keywords: - numbers - porting - portin + - port-in - port - lnp - portability @@ -36,7 +37,7 @@ export const Highlight = ({children, color}) => ( A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network. :::info -As an alternative to individual porting the `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/bulkPortins). +As an alternative to individual porting the `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/createBulkPortins). ::: TNs can be ported in a single `/portins` request if all the following are true: @@ -71,7 +72,7 @@ Port Type - is a categorization of how the TNs submitted to the /lnpchecker API ### Check number(s) portability -A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the POST request to [`/accounts/{accountId}/lnpChecker`](/apis/numbers#operation/RequestPortabilityInfo) API endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the POST request to [`/accounts/{accountId}/lnpChecker`](/apis/numbers#operation/RequestPortabilityInfo) API endpoint. This can be done using tools like Postman, or in command line. ### Examples POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker @@ -82,15 +83,12 @@ A number or set of numbers can be checked to see if they can be ported into the values={[ { label: 'Request Payload', value: 'payload', }, { label: 'cURL', value: 'curl', }, - { label: 'Java', value: 'java', }, - { label: 'C#', value: 'csharp', }, - { label: 'Ruby', value: 'ruby', }, - { label: 'NodeJS', value: 'nodejs', }, - { label: 'PHP', value: 'php', }, ] }> +>Request + ```xml POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker?fullcheck=true HTTP/1.1 Content-Type: application/xml; charset=utf-8 @@ -104,102 +102,7 @@ Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= ``` - - - -```cURL -Note: Remember to add authentication for your application if needed! - -curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker?fullcheck=true' \ --X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ --H 'Content-Type: application/xml' \ --d ' - - 9195551234 - 9198675309 - -' -``` - - - - -```java -String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); -String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); -String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); -String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); -String version = System.getenv("BANDWIDTH_IRIS_URL"); -IrisClient client = new IrisClient(accountId, username, password, irisUrl, version); - -NumberPortabilityRequest request = new NumberPortabilityRequest(); -request.getTnList().add("9195551212"); -NumberPortabilityResponse response = LnpChecker.checkLnp(client, request, "true"); -System.out.println(response.getPortableNumbers().get(0)); -``` - - - - -```csharp -var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") -var result = await LnpChecker.Check(client, new string[] { "555555" }); -Console.WriteLine(result); -``` - - - - -```ruby -require 'ruby-bandwidth-iris' - -BandwidthIris::Client.global_options = { -:account_id => 'accountId', -:username => 'userName', -:password => 'password' -} - -numbers = ["9195551212", "9195551213"] -full_check = true -BandwidthIris::LnpChecker.check(numbers, full_check) -``` - - - - -```js -var numbers = require("@bandwidth/numbers"); - -numbers.Client.globalOptions.accountId = "accountId"; -numbers.Client.globalOptions.userName = "userName"; -numbers.Client.globalOptions.password = "password"; - -var numbersList = ["9195551212", "9195551213"]; -var fullCheck = true; -numbers.LnpChecker.check(numbersList, fullCheck, callback); -``` - - - - -```php -$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); -$username = getenv("BANDWIDTH_API_USERNAME"); -$password = getenv("BANDWIDTH_API_PASSWORD"); -$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); - -$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); -$account = new \Iris\Account($accountId, $client); - -$account->lnpChecker(["4109255199", "9196190594"], "true"); -``` - - - - - -Response +> Response ```xml HTTP 200 OK @@ -260,6 +163,28 @@ Content-Type: application/xml; charset=utf-8 ``` + + + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker?fullcheck=true' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + + 9195551234 + 9198675309 + +' +``` + + + + ## Where to next? Now that you have learnt how to check numbers portability, check out some of the available actions in the following guides: diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx index 1d7951984..7375b6779 100644 --- a/site/docs/numbers/porting/loaUpload.mdx +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -2,12 +2,13 @@ id: loaUpload title: LOA Upload slug: /numbers/guides/porting/loaUpload -description: How to upload Letter of Authorization (LOA) for portin request +description: How to upload Letter of Authorization (LOA) for port-in request keywords: - bandwidth - numbers - porting - portin + - port-in - lnp - port - loa @@ -56,27 +57,22 @@ The following MIME types are supported for the LOA upload file: * ZIP (“application/zip”) -To upload and manage the LOA you can use different requests to [/portins/{orderId}/loas API](/apis/numbers/#operation/UploadPortinLoaFile). This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +To upload and manage the LOA you can use different requests to [/portins/{orderId}/loas API](/apis/numbers/#operation/UploadPortinLoaFile). This can be done using tools like Postman, or in command line. ### Examples POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas - + -> UPLOAD LOA +> Upload LOA ```http POST /api/accounts/9900778/portins/{orderId}/loas HTTP/1.1 @@ -109,20 +105,9 @@ Content-Type: application/xml; charset=utf-8 ``` ->UPDATE FILE METADATA - -```xml - - [string] - [LOA | INVOICE | CSR | OTHER] - -``` - -> Request - ```cURL # UPLOAD LOA @@ -130,161 +115,46 @@ curl \ -H 'Content-Type: application/pdf' \ --data-binary "@Test_LOA.pdf" \ -iv https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas - -# UPDATE FILE METADATA - -curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata' \ --X PUT \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ --H 'Content-Type: application/xml' \ --d ' - [string] - [LOA | INVOICE | CSR | OTHER] -' ``` - - -```java -String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); -String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); -String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); -String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); -String version = System.getenv("BANDWIDTH_IRIS_URL"); - -IrisClient client = new IrisClient(accountId, username, password, irisUrl, version); - -try { - LnpOrder order = LnpOrder.get(client, "orderId"); - - String fileName = "myLoaFile.pdf"; - order.uploadLoa(new File("path_to_the_file/../myLoaFile.pdf"), LoaFileType.PDF); - order.updateLoa(new File("another_path_to_the_file"), LoaFileType.PDF); - order.deleteLoa(fileName); - order.getLoaMetaData(fileName); - - FileMetaData fileMetaData = new FileMetaData(); - fileMetaData.setDocumentName("myLoaFile.pdf"); - fileMetaData.setDocumentType("INVOICE"); - order.updateLoaMetaData(fileName, fileMetaData); - order.deleteLoaMetaData(fileName); -} catch (Exception e) { - System.out.println(e.getMessage()); -} -``` - - - - -```csharp -var client = Client.GetInstance(accountId, username, password, apiEndpoint) -var portInOrder = PortIn.Get(client, "orderId"); - -// Port In LOA Management -portInOrder.CreateFile(Stream s, string mediaType); -portInOrder.CreateFile(byte[] buffer, string mediaType); -portInOrder.UpdateFile(string fileName, Stream s, string mediaType); -portInOrder.UpdateFile(string fileName, byte[] buffer, string mediaType); -portInOrder.GetFileMetaData(string fileName); -PutFileMetadata(string fileName, FileMetadata fileMetadata); -portInOrder.DeleteFile(string fileName); -portInOrder.GetFiles(bool metaData); -portInOrder.GetFile(string fileName); -``` - - - - -```ruby -require 'ruby-bandwidth-iris' - -BandwidthIris::Client.global_options = { -:account_id => 'accountId', -:username => 'userName', -:password => 'password' -} -portIn = BandwidthIris::PortIn.get("portin_id", callback) - -# Add File -portIn.create_file(IO.read("myFile.txt")) + -# Update File -portIn.update_file("myFile.txt", IO.read("myFile.txt")) +To manage your LOA files use our APIs like [/portins/{orderid}/loas/{fileId}](/apis/numbers/#operation/UpdatePortinLoaFile) and [/portins/{orderid}/loas/{fileId}/metadata](/apis/numbers/#operation/UpdatePortinLoadMetadata). -# Get File -portIn.get_file("myFile.txt") +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata -# Get File Metadata -portIn.get_file_metadata("myFile.txt") + + -# Get Files -portIn.get_files() +```xml + + [string] + [LOA | INVOICE | CSR | OTHER] + ``` - - -```js -var numbers = require("@bandwidth/numbers"); - -// Using client directly -// var client = new numbers.Client("accountId", "userName", "password"); -// numbers.PortIn.create(client, function(err, response){...}); - -//Or you can use default client instance (do this only once) -numbers.Client.globalOptions.accountId = "accountId"; -numbers.Client.globalOptions.userName = "userName"; -numbers.Client.globalOptions.password = "password"; - -var portinOrderId = "..."; -numbers.PortIn.get(portinOrderId, function(err, portIn){ -// Add File -portIn.createFile(fs.createReadStream("myFile.txt"), callback); - -// Update File -portIn.updateFile("myFile.txt", fs.createReadStream("myFile.txt"), callback); - -// Get File -portIn.getFile("myFile.txt", callback); - -// Get File Metadata -portIn.getFileMetadata("myFile.txt", callback); + -// Get Files -portIn.getFiles(callback); -}); -``` +> Request - - - -```php -$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); -$username = getenv("BANDWIDTH_API_USERNAME"); -$password = getenv("BANDWIDTH_API_PASSWORD"); -$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); - -$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); -$account = new \Iris\Account($accountId, $client); - -try { - $portin = $account->portins()->portin("d28b36f7-fa96-49eb-9556-a40fca49f7c6")); - $portin->list_loas(true); // metadata = true - $portin->loas_send("./1.txt"); - $portin->loas_update("./1.txt", "1.txt"); - $portin->loas_delete("1.txt"); - $portin->get_metadata("1.txt"); - - $meta_new = array( - "DocumentName" => "text.txt", - "DocumentType" => "INVOICE" - ); - $portin->set_metadata('test.txt', $meta_new); - $portin->delete_metadata('test.txt'); -} catch (BandwidthLib\APIException $e) { - print_r($e->getResponseCode()); -} +```cURL +curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata' \ +-X PUT \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + [string] + [LOA | INVOICE | CSR | OTHER] +' ``` @@ -293,4 +163,4 @@ try { ## Where to next? Now that you have learnt how to create a Port in order, check out some of the available actions in the following guides: -- [How to manage Port in](/docs/numbers/guides/porting/updatePortin) +- [How to manage Port in →](/docs/numbers/guides/porting/updatePortin) diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 96593d8ea..1b4f1dc2c 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -8,6 +8,7 @@ keywords: - numbers - porting - portin + - port-in - lnp - port image: ../../../static/img/bandwidth-logo.png @@ -36,14 +37,14 @@ The Bandwidth Phone Number `/portins` API is used to submit Port-In requests. Th In order to successfully port telephone numbers they need to correspond to a set of criteria. To check them follow the [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) guide. :::info -As an alternative to individual porting the `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/bulkPortins). +As an alternative to individual porting the `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/createBulkPortins). ::: -## Create a Portin Order +## Create a Port-in Order The API allows a user to create a new LNP order. An order id will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. -To create Port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +To create Port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done using tools like Postman, or in command line. ### Examples POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins @@ -53,15 +54,12 @@ To create Port-in request, you must make a POST +>Request + ```xml Note: Remember to add authentication for your application if needed! @@ -100,6 +98,48 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/portins ``` +>Response + +```xml + + d28b36f7-fa96-49eb-9556-a40fca49f7c6 + + 201 + Order request received. Please use the order id to check the status of your order later. + + PENDING_DOCUMENTS + 2016-03-25T21:15:00.000Z + X455 + 9195551234 + 9175131245 + 12345 + 660123 + + BUSINESS + First + Last + + 11235 + Back + Denver + CO + 27541 + Canyon + + + The Authguy + + 771297665AABC + 1234 + + + 9195551234 + 9195554321 + + true + +``` + @@ -143,205 +183,6 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ ' ``` - - - -```java -import com.bandwidth.iris.sdk.IrisClient; -import com.bandwidth.iris.sdk.model.LnpOrder; -import com.bandwidth.iris.sdk.model.ServiceAddress; -import com.bandwidth.iris.sdk.model.Subscriber; - -public class Main { - - public static void main(String[] args) { - String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); - String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); - String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); - String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); - String version = System.getenv("BANDWIDTH_IRIS_URL"); - - IrisClient client = new IrisClient(irisUrl, accountId, username, password, version); - - Subscriber s = new Subscriber(); - s.setSubscriberType("BUSINESS"); - s.setBusinessName("Company"); - ServiceAddress serviceAddress = new ServiceAddress(); - serviceAddress.setHouseNumber("123"); - serviceAddress.setStreetName("Anywhere St"); - serviceAddress.setCity("Raleigh"); - serviceAddress.setStateCode("NC"); - serviceAddress.setZip("27609"); - s.setServiceAddress(serviceAddress); - - LnpOrder order = new LnpOrder(); - order.setSiteId("123"); - order.setPeerId("12345"); - order.setBillingTelephoneNumber("9195551212"); - order.setSubscriber(s); - order.setLoaAuthorizingPerson("Joe Blow"); - order.getListOfPhoneNumbers().add("9195551212"); - - try { - order = LnpOrder.create(client, order); - System.out.println(order); - } catch (Exception e) { - System.out.println(e.getMessage()); - } - } -} -``` - - - - -```csharp -var accountId = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ACCOUNT_ID"); -var username = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_USERNAME"); -var password = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_PASSWORD"); -var apiEndpoint = System.Environment.GetEnvironmentVariable("BANDWIDTH_API_ENDPOINT"); - -var client = Client.GetInstance(accountId, username, password, apiEndpoint) - -var data = new PortIn -{ - BillingTelephoneNumber = "+1-202-555-0158", - Subscriber = new Subscriber - { - SubscriberType = "BUSINESS", - BusinessName = "Company", - FirstName = "John", - LastName = "Doe", - ServiceAddress = new Address - { - City = "City", - StateCode = "State", - Country = "Country" - } - }, - PeerId = "12345", - SiteId = "123" -}; -var order = await PortIn.Create(client, data); -``` - - - - -```ruby -require 'ruby-bandwidth-iris' - -BandwidthIris::Client.global_options = { - :account_id => 'accountId', - :username => 'userName', - :password => 'password' -} - -data = { - :site_id =>1234, - :peer_id => 5678, - :billing_telephone_number => "9195551212", - :subscriber => { - :subscriber_type => "BUSINESS", - :business_name => "Company", - :service_address => { - :house_number => "123", - :street_name => "EZ Street", - :city => "Raleigh", - :state_code => "NC", - :county => "Wake" - } - }, - :loa_authorizing_person => "Joe Blow", - :list_of_phone_numbers => { - :phone_number => ["9195551212"] - }, - :billing_type => "PORTIN" -} - -portin_response = BandwidthIris::PortIn.create(data) -``` - - - - -```js -var numbers = require("@bandwidth/numbers"); - -var data = { - siteId: 1234, - peerId: 5678, - billingTelephoneNumber: "9195551212", - subscriber: { - subscriberType: "BUSINESS", - businessName: "Company", - serviceAddress: { - houseNumber: "123", - streetName: "EZ Street", - city: "Raleigh", - stateCode: "NC", - county: "Wake" - } - }, - loaAuthorizingPerson: "Joe Blow", - listOfPhoneNumbers: { - phoneNumber: ["9195551212"] - }, - billingType: "PORTIN" -}; - -// Using client directly -// var client = new numbers.Client("accountId", "userName", "password"); -// numbers.PortIn.create(client, function(err, response){...}); - -//Or you can use default client instance (do this only once) -numbers.Client.globalOptions.accountId = "accountId"; -numbers.Client.globalOptions.userName = "userName"; -numbers.Client.globalOptions.password = "password"; - -//Default client will be used to do this call -numbers.PortIn.create(data, callback); -``` - - - - -```php -$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); -$username = getenv("BANDWIDTH_API_USERNAME"); -$password = getenv("BANDWIDTH_API_PASSWORD"); -$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); - -$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); -$account = new \Iris\Account($accountId, $client); - -try { - $portin = $account->portins()->create(array( - "BillingTelephoneNumber" => "6882015002", - "Subscriber" => array( - "SubscriberType" => "BUSINESS", - "BusinessName" => "Acme Corporation", - "ServiceAddress" => array( - "HouseNumber" => "1623", - "StreetName" => "Brockton Ave", - "City" => "Los Angeles", - "StateCode" => "CA", - "Zip" => "90025", - "Country" => "USA" - ) - ), - "LoaAuthorizingPerson" => "John Doe", - "ListOfPhoneNumbers" => array( - "PhoneNumber" => array("9882015025", "9882015026") - ), - "SiteId" => "365", - "Triggered" => "false" - )); -} catch (BandwidthLib\APIException $e) { - print_r($e->getResponseCode()); -} -``` - @@ -349,7 +190,7 @@ try { Porting numbers in the Bandwidth Dashboard is asynchronous which means the orders are processed and the order status is updated asynchronously. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. Please follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) guide. -To poll an information about your Port in you can still use a GET request to [accounts/{accountId}/portins API](/apis/numbers/#operation/GetPortin). This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +To poll an information about your Port in you can still use a GET request to [accounts/{accountId}/portins API](/apis/numbers/#operation/GetPortin). This can be done using tools like Postman, or in command line. GET https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} @@ -374,105 +210,11 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ -H 'Accept: application/xml' ``` - - - -```java -import com.bandwidth.BandwidthClient; -import com.bandwidth.http.response.ApiResponse; -import com.bandwidth.voice.models.CreateCallRequest; -import com.bandwidth.voice.models.CreateCallResponse; - -import java.util.concurrent.CompletableFuture; -import java.util.concurrent.ExecutionException; - -public class Sample { - - public static void main(String[] args) { - String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); - String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); - String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); - String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); - String version = System.getenv("BANDWIDTH_IRIS_URL"); - - IrisClient client = new IrisClient(irisUrl, accountId, username, password, version); - - try { - LnpOrder order = LnpOrder.get(client, "orderId"); - System.out.println(order); - } catch (Exception e) { - System.out.println(e.getMessage()); - } - } -} -``` - - - - -```csharp -var client = Client.GetInstance(accountId, username, password, apiEndpoint) -var portInOrder = PortIn.Get(client, "orderId"); -``` - - - - -```ruby -require 'ruby-bandwidth-iris' - -BandwidthIris::Client.global_options = { - :account_id => 'accountId', - :username => 'userName', - :password => 'password' -} -portIn = BandwidthIris::PortIn.get("portin_id", callback) -``` - - - - -```js -var numbers = require("@bandwidth/numbers"); - -// Using client directly -// var client = new numbers.Client("accountId", "userName", "password"); -// numbers.PortIn.create(client, function(err, response){...}); - -//Or you can use default client instance (do this only once) -numbers.Client.globalOptions.accountId = "accountId"; -numbers.Client.globalOptions.userName = "userName"; -numbers.Client.globalOptions.password = "password"; - -var orderId = "..."; -//Default client will be used to do this call -numbers.PortIn.get(orderId, callback) -``` - - - - -```php -$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); -$username = getenv("BANDWIDTH_API_USERNAME"); -$password = getenv("BANDWIDTH_API_PASSWORD"); -$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); - -$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); -$account = new \Iris\Account($accountId, $client); - -try { - $portin = $account->portins()->portin("d28b36f7-fa96-49eb-9556-a40fca49f7c6")); -} catch (BandwidthLib\APIException $e) { - print_r($e->getResponseCode()); -} -``` - :::info -If your port-on order stuck in a ```PENDING_DOCUMENTS``` status then [LOA (Letter of authorization) upload](/docs/numbers/guides/porting/loaUpload) is required action. +If your port-on order stuck in a ```PENDING_DOCUMENTS``` status and does not transit to ```SUBMITTED``` then [LOA (Letter of authorization) upload](/docs/numbers/guides/porting/loaUpload) is required action. ::: ## Where to next? @@ -482,4 +224,4 @@ Now that you have learnt how to create a Port in order, check out some of the av - [How to check numbers portability ←](/docs/numbers/guides/porting/lnpChecker) - [How to upload LOA (Letter of authorization) →](/docs/numbers/guides/porting/loaUpload) - [How to manage Port in →](/docs/numbers/guides/porting/updatePortin) -- [How to create Bulk Port in →](/docs/numbers/guides/porting/bulkPortins) +- [How to create Bulk Port in →](/docs/numbers/guides/porting/createBulkPortins) diff --git a/site/docs/numbers/porting/submitBulkportin.mdx b/site/docs/numbers/porting/submitBulkportin.mdx new file mode 100644 index 000000000..caabdd9a5 --- /dev/null +++ b/site/docs/numbers/porting/submitBulkportin.mdx @@ -0,0 +1,123 @@ +--- +id: submitBulkPortins +title: Submit Bulk Port-in +slug: /numbers/guides/porting/submitBulkPortins +description: How to trigger bulk port-in order processing +keywords: + - bandwidth + - bulkportins + - portin + - port-in +image: ../../static/img/bandwidth-logo.png +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const accountId = "{accountId}"; +export const orderId = "{orderId}"; + +export const Highlight = ({children, color}) => ( + + {children} + + ); + +[The bulkPortins endpoint](/apis/numbers#operation/CreateBulkPortin) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. + +## Submit Bulk Port-in + +On this step we assume that you have created your bulk port-in and added telephone numbers which you wanted to port into the Bandwidth Dashboard. If not, follow the [How to create Bulk Port in](/docs/numbers/guides/porting/createBulkPortins) guide. + +The bulk port-in and child port-in orders will remain in draft states until you submit them. You can submit all the port-ins together under the umbrella of the bulk port-in by changing bulk port-in status to ```IN_PROGRESS```. + +:::info +If for any reason you want to work with individual port-ins you still can submit them separately through ```PUT``` request to [/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin). Check [Update Port-in](/docs/numbers/guides/porting/updatePortin) guide to learn more. +::: + +To trigger Bulk Port-in processing use the ```PATCH``` operation on the bulk port-in order to change the ```ProcessingStatus``` to ```IN_PROGRESS```. To do it you must send a PATCH request to our [API /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkPortin) endpoint. This can be done through tools like Postman, or in command line. + +:::caution +Changing the ProcessingStatus to 'IN_PROGRESS' is only valid if child port-ins exist for the bulk port-in. Check [How to Provide telephone number(s) to port](/docs/numbers/guides/porting/createBulkPortins/#provide-telephone-numbers-to-port) guide. +::: + +PATCH https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} + + + +> Request + +```xml +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + +https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} +\n + + IN_PROGRESS + +``` + +> Response + +``` + + + + Order Id for all child orders + 2021-06-30T00:00:00.000Z + 14020 + 521434 + IN_PROGRESS + 9900572 + jgilmore + jgilmore + 2021-06-21T19:42:34.760Z + 2021-06-21T19:42:34.760Z + ac2c8ab2-7a63-44da-a307-edcabe0b6c81 + + +``` + + + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + IN_PROGRESS + ' +``` + + + + +## Bulk Port-in completion + +A bulk port-in order may have one of 3 terminal processing statuses: ```COMPLETED```, ```CANCELLED```, or ```PARTIAL```, which are just an aggregation of the child order statuses. An order in a “terminal” state will never transition to any other processing status (terminal or not). A bulk port-in order goes to a terminal status automatically as soon as the last of its associated child port-ins transfers to terminal status (```COMPLETE``` or ```CANCELLED```). The resulting terminal processing status of the bulk port-in order depends on statuses of associated child port-ins: +* ```COMPLETED``` - when all child port-ins are in ```COMPLETE``` status +* ```CANCELLED``` - when all child port-ins are in ```CANCELLED``` status +* ```PARTIAL``` - when there is a mix of ```CANCELLED``` and ```COMPLETE``` child port-in statuses. + +## Where to next? + +- [How to create Bulk Port-in ←](/docs/numbers/guides/porting/updateBulkPortins) +- [How to update Bulk Port-in →](/docs/numbers/guides/porting/updateBulkPortins) +- [How to manage Port in →](/docs/numbers/guides/porting/updatePortin) \ No newline at end of file diff --git a/site/docs/numbers/porting/updateBulkPortins.mdx b/site/docs/numbers/porting/updateBulkPortins.mdx new file mode 100644 index 000000000..cc85b219a --- /dev/null +++ b/site/docs/numbers/porting/updateBulkPortins.mdx @@ -0,0 +1,220 @@ +--- +id: updateBulkPortins +title: Update Bulk Port-in +slug: /numbers/guides/porting/updateBulkPortins +description: How to update bulk port-in order using the Bandwidth API +keywords: + - bandwidth + - bulkportins + - portin +image: ../../static/img/bandwidth-logo.png +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +export const accountId = "{accountId}"; +export const orderId = "{orderId}"; + +export const Highlight = ({children, color}) => ( + + {children} + + ); + +[The bulkPortins endpoint](/apis/numbers#operation/CreateBulkPortin) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. + +## Update Bulk Port-in + +It is possible to update Bulk Port-in order using ```PUT``` or ```PATCH``` request to ```/bulkPortins/{orderId} API``` on the existing order-id: +* If Bulk Port-in is not in terminal (```COMPLETED```, ```CANCELLED```, or ```PARTIAL```) status +* As with the ```POST```, any data associated with the bulk port-in will cascade to subtending orders when they are created +* If the port-in orders contained within the Bulk Port are in ```DRAFT``` state, any field can be modified +* If any child port-in order in the Bulk Port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller + +:::info +Subtending orders are created after tns are added to the bulk port-in using the /tnList endpoint, see the next section of this tutorial. +::: + +* The [```PUT``` /bulkPortins/{orderId}](/apis/numbers/#operation/PutBulkOrder) operation is available only for bulk port-in orders that are not yet associated with subtending orders +* The [```PATCH``` /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkOrder) replaces only the elements included in the request payload. Other elements will remain untouched + +### Example + +In the following example we are adding ```LoaAuthorizingPerson``` field to the bulk porting (to apply it to all future subtending port-in orders): +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} + + + +> Request + +```xml +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + +https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} + + Order Id for all child orders + 2021-06-30Z + 14020 + 521434 + The Guy + +``` + +> Response + +``` + + + + Order Id for all child orders + 2021-06-30T00:00:00.000Z + The Guy + 14020 + 521434 + DRAFT + 9900572 + myUser + myUser + 2021-06-21T19:42:34.760Z + 2021-06-21T19:42:34.760Z + ac2c8ab2-7a63-44da-a307-edcabe0b6c81 + + +``` + + + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + Order Id for all child orders + 2021-06-30Z + 14020 + 521434 + The Guy +' +``` + + + + +Note that ```PUT``` completely replaces the existing Bulk Port-in order with the given payload while ```PATCH``` replaces only the elements included in the request payload. + +PATCH https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} + + + + +> Request + +```xml +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD + +https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} + + The Guy + +``` + +> Response + +``` + + + + Order Id for all child orders + 2021-06-30T00:00:00.000Z + The Guy + 14020 + 521434 + DRAFT + 9900572 + myUser + myUser + 2021-06-21T19:42:34.760Z + 2021-06-21T19:42:34.760Z + ac2c8ab2-7a63-44da-a307-edcabe0b6c81 + + +``` + + + + +```cURL +Note: Remember to add authentication for your application if needed! + +curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ +-X POST \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' \ +-d ' + The Guy + ' +``` + + + + +## Delete Bulk Port-in + +You can delete a bulk port-in order with child port-ins. Deleting a bulk port-in is allowed for ```DRAFT``` state only. Deleting a bulk port-in will delete all ```DRAFT``` child port-ins associated with the bulk port-in. When the bulk port-in is deleted, any child port-in orders that are not in a ```DRAFT``` status are dissociated from the bulk port-in, but not deleted. + +### Examples +DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} + + + + +```http +curl -X DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}} \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-H 'Content-Type: application/xml' +``` + +> Response + +```http +HTTP 200 OK +``` + + + + +## Where to next? + +- [How to create Bulk Port-in ←](/docs/numbers/guides/porting/createBulkPortins) +- [How to submit Bulk Port-in →](/docs/numbers/guides/porting/submitBulkPortins) \ No newline at end of file diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx index 45e3ec3a2..5337c28aa 100644 --- a/site/docs/numbers/porting/updatePortin.mdx +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -1,13 +1,14 @@ --- id: updatePortin -title: Manage Portin +title: Manage Port-in slug: /numbers/guides/porting/updatePortin -description: How to update your portin request +description: How to update your port-in request keywords: - bandwidth - numbers - porting - portin + - port-in - lnp - port - update @@ -33,11 +34,11 @@ export const Highlight = ({children, color}) => ( ); -In this guide we will show you how to manage your Port in order. We assume that you have [created Port in order](/docs/numbers/guides/porting/updatePortin) first. +In this guide we will show you how to manage your Port in order. We assume that you have [created Port in order](/docs/numbers/guides/porting/updatePortin). ## Update Port-in Order -The PUT to [/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin) API allows a user to modify an existing LNP order, by sending a so-called SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the PUT on a porting order-id does not require that the full order payload is included. +The PUT to [/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin) API allows a user to modify an existing LNP order, by sending a so-called SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the ```PUT``` on a porting order-id does not require that the full order payload is included. If the order ProcessingStatus is `DRAFT`, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from `DRAFT` to `SUBMITTED`. The AltSpid element can be modified if it is not configured at the system level. Regarding the fields which can be updated for different port types check the request schema section of [PUT /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) specification. @@ -45,7 +46,7 @@ Regarding the fields which can be updated for different port types check the req The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. ### Examples -To update Port-in request, you must make a PUT request to our [API /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) endpoint. This can be done through our [SDKs](/sdks), using tools like [Postman](https://github.com/Bandwidth/postman), or in command line. +To update Port-in request, you must make a PUT request to our [API /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) endpoint. This can be done using tools like Postman, or in command line. PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} PUT @@ -191,111 +187,6 @@ Content-Type: application/xml; charset=utf-8 ``` - - - -```java -String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); -String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); -String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); -String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); -String version = System.getenv("BANDWIDTH_IRIS_URL"); - -IrisClient client = new IrisClient(accountId, username, password, irisUrl, version); - -LnpOrderSupp supp = new LnpOrderSupp(); -supp.setSiteId("123"); -supp.setPeerId("12345"); -// ... - -try { - LnpOrder order = LnpOrder.get(client, "d28b36f7-fa96-49eb-9556-a40fca49f7c6"); - order.update(supp); - System.out.println(order); -} catch (Exception e) { - System.out.println(e.getMessage()); -} -``` - - - - -```csharp -var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") - -var data = new PortIn -{ - // ... - PeerId = "12345", - SiteId = "123" -}; -var portInOrder = PortIn.Get("d28b36f7-fa96-49eb-9556-a40fca49f7c6"); -portInOrder.Update(data); -``` - - - - -```ruby -require 'ruby-bandwidth-iris' - -BandwidthIris::Client.global_options = { -:account_id => 'accountId', -:username => 'userName', -:password => 'password' -} - -data = { -//... -} - -portIn = BandwidthIris::PortIn.get("d28b36f7-fa96-49eb-9556-a40fca49f7c6", callback) -portIn.update(data) -``` - - - - -```js -var numbers = require("@bandwidth/numbers"); - -var data = { -// ... -}; - -numbers.Client.globalOptions.accountId = "accountId"; -numbers.Client.globalOptions.userName = "userName"; -numbers.Client.globalOptions.password = "password"; - -numbers.PortIn.get("d28b36f7-fa96-49eb-9556-a40fca49f7c6", function(err, portIn){ - portIn.update(data, callback); -}); -``` - - - - -```php -$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); -$username = getenv("BANDWIDTH_API_USERNAME"); -$password = getenv("BANDWIDTH_API_PASSWORD"); -$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); - -$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); -$account = new \Iris\Account($accountId, $client); - -try { - $portin = $account->portins()->portin("d28b36f7-fa96-49eb-9556-a40fca49f7c6")); - $portin->update(array( - "BillingTelephoneNumber" => "6882015002", - "SiteId" => "365", - // ... - )); -} catch (BandwidthLib\APIException $e) { - print_r($e->getResponseCode()); -} -``` - @@ -311,21 +202,14 @@ The API allows a user to cancel an existing LNP order. The order number that was defaultValue="cURL" values={[ { label: 'cURL', value: 'cURL', }, - { label: 'Java', value: 'java', }, - { label: 'C#', value: 'csharp', }, - { label: 'Ruby', value: 'ruby', }, - { label: 'NodeJS', value: 'nodejs', }, - { label: 'PHP', value: 'php', }, ] }> -> Request - ```http -DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/d28b36f7-fa96-49eb-9556-a40fca49f7c6 HTTP/1.1 -Content-Type: application/xml; charset=utf-8 -Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= +curl -X DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/d28b36f7-fa96-49eb-9556-a40fca49f7c6 \ + -U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ + -H 'Content-Type: application/xml' ``` > Response @@ -335,78 +219,15 @@ HTTP 200 OK ``` - - -```java -String accountId = System.getenv("BANDWIDTH_IRIS_ACCOUNTID"); -String username = System.getenv("BANDWIDTH_IRIS_USERNAME"); -String password = System.getenv("BANDWIDTH_IRIS_PASSWORD"); -String irisUrl = System.getenv("BANDWIDTH_IRIS_URL"); -String version = System.getenv("BANDWIDTH_IRIS_URL"); - -IrisClient client = new IrisClient(accountId, username, password, irisUrl, version); - -LnpOrder order = LnpOrder.get(client, "d28b36f7-fa96-49eb-9556-a40fca49f7c6"); -order.delete(); -``` - - - - -```csharp -var client = Client.GetInstance("accountId", "username", "password", "apiEndpoint") - -var portInOrder = PortIn.Get("d28b36f7-fa96-49eb-9556-a40fca49f7c6"); -portInOrder.Delete(); -``` - - - - -```ruby -require 'ruby-bandwidth-iris' - -BandwidthIris::Client.global_options = { -:account_id => 'accountId', -:username => 'userName', -:password => 'password' -} - -portIn = BandwidthIris::PortIn.get("d28b36f7-fa96-49eb-9556-a40fca49f7c6", callback) -portIn.delete -``` - - - - -```js -var numbers = require("@bandwidth/numbers"); - -numbers.Client.globalOptions.accountId = "accountId"; -numbers.Client.globalOptions.userName = "userName"; -numbers.Client.globalOptions.password = "password"; - -numbers.PortIn.get("d28b36f7-fa96-49eb-9556-a40fca49f7c6", function(err, portIn){ - portIn.delete(callback); -}); -``` - - - + -```php -$accountId = getenv("BANDWIDTH_API_ACCOUNT_ID"); -$username = getenv("BANDWIDTH_API_USERNAME"); -$password = getenv("BANDWIDTH_API_PASSWORD"); -$apiEndpoint = getenv("BANDWIDTH_API_ENDPOINT"); +## Port-in completion -$client = new \Iris\Client($username, $password, ['url' => $apiEndpoint]); -$account = new \Iris\Account($accountId, $client); +A port-in order may have one of 2 terminal processing statuses: ```COMPLETED``` (successful completion) or ```CANCELLED``` (cancelled by user or because of critical error). An order in a “terminal” state will never transition to any other processing status (terminal or not). +## Where to next? -$portin = $account->portins()->portin("d28b36f7-fa96-49eb-9556-a40fca49f7c6")); -$portin->delete(); -``` +- [How to check numbers portability ←](/docs/numbers/guides/porting/lnpChecker) +- [How to upload LOA (Letter of authorization) ←](/docs/numbers/guides/porting/loaUpload) +- [How to create Port in request ←](/docs/numbers/guides/porting/portingNumbers) - - diff --git a/site/sidebar.js b/site/sidebar.js index 40b917499..e6ec4262a 100644 --- a/site/sidebar.js +++ b/site/sidebar.js @@ -54,7 +54,9 @@ module.exports = { "numbers/porting/portingNumbers", "numbers/porting/loaUpload", "numbers/porting/updatePortin", - "numbers/porting/bulkPortins", + "numbers/porting/createBulkPortins", + "numbers/porting/updateBulkPortins", + "numbers/porting/submitBulkPortins", ], }, "numbers/csrLookupTool", diff --git a/site/specs-temp/numbers.json b/site/specs-temp/numbers.json index 6df17002f..4cdf2e700 100644 --- a/site/specs-temp/numbers.json +++ b/site/specs-temp/numbers.json @@ -1700,7 +1700,7 @@ "/accounts", "Porting" ], - "description": "Retrieves bulk port-in orders for the specified accountId.\nA maximum of 1,000 orders can be retrieved per request. If no date range or specific query parameter is provided, the order results will be limited to the last two years. Please visit Guides and Tutorials", + "description": "Retrieves bulk port-in orders for the specified accountId.\nA maximum of 1,000 orders can be retrieved per request. If no date range or specific query parameter is provided, the order results will be limited to the last two years. Please visit Guides and Tutorials", "operationId": "ListBulkPortins", "summary": "List bulk port-in orders", "parameters": [ @@ -1828,7 +1828,7 @@ "/accounts", "Porting" ], - "description": "

Creates a bulk port-in order to be used as a template for a collection of child port-in orders. The template values will be cascaded to child port-ins that result from decomposing a collection of Telephone Numbers that span carriers, RespOrgs, or have attributes that drive the decomposition into a number of individual port-in orders.

Upon a successfully-submitted payload, the order will have a status of \"DRAFT\", denoting that further modification to the template is expected. For example, the next step is to use the /tnList endpoint to add a collection of telephone numbers to the bulk port-in order. The only valid value for the ProcessingStatus element in a POST is 'DRAFT', which is the default value. All parameters except for the URL parameter \"accountId\" are optional in the bulk port-in, although the rules for individual child port-ins described in the POST /portins API still apply to the child port-ins that make up the bulk port-in. Enforcement of required fields in the child port-ins occurs when the bulk port-in is submitted (i.e. changed from a DRAFT status to IN_PROGRESS). Enforcement of required fields in the child port-ins occurs when the bulk port-in is submitted (i.e. changed from a DRAFT status to IN_PROGRESS).

Please visit Guides and Tutorials

", + "description": "

Creates a bulk port-in order to be used as a template for a collection of child port-in orders. The template values will be cascaded to child port-ins that result from decomposing a collection of Telephone Numbers that span carriers, RespOrgs, or have attributes that drive the decomposition into a number of individual port-in orders.

Upon a successfully-submitted payload, the order will have a status of \"DRAFT\", denoting that further modification to the template is expected. For example, the next step is to use the /tnList endpoint to add a collection of telephone numbers to the bulk port-in order. The only valid value for the ProcessingStatus element in a POST is 'DRAFT', which is the default value. All parameters except for the URL parameter \"accountId\" are optional in the bulk port-in, although the rules for individual child port-ins described in the POST /portins API still apply to the child port-ins that make up the bulk port-in. Enforcement of required fields in the child port-ins occurs when the bulk port-in is submitted (i.e. changed from a DRAFT status to IN_PROGRESS). Enforcement of required fields in the child port-ins occurs when the bulk port-in is submitted (i.e. changed from a DRAFT status to IN_PROGRESS).

Please visit Guides and Tutorials

", "operationId": "CreateBulkPortin", "summary": "Create bulk port-in order", "parameters": [ @@ -1897,7 +1897,7 @@ "/accounts", "Porting" ], - "description": "Retrieves information associated with the bulk port-in order specified by the orderId URI parameter. Please visit Guides and Tutorials", + "description": "Retrieves information associated with the bulk port-in order specified by the orderId URI parameter. Please visit Guides and Tutorials", "operationId": "RetrieveBulkOrder", "summary": "Retrieve bulk port-in order", "parameters": [ @@ -1948,7 +1948,7 @@ "/accounts", "Porting" ], - "description": "The PUT operation is available only for bulk port-in orders that are not yet associated with subtending orders. Since this only occurs for bulk port-in orders that are in one of the draft states, there are few restrictions on what may be included. As with the POST, any data associated with the bulk port-in will cascade to subtending orders when they are created. (Subtending orders are created after telephone numbers are added to the bulk port-in using the /tnList endpoint.) The PUT completely replaces the existing Bulk Portin order with the payload of the PUT. Please visit Guides and Tutorials.", + "description": "The PUT operation is available only for bulk port-in orders that are not yet associated with subtending orders. Since this only occurs for bulk port-in orders that are in one of the draft states, there are few restrictions on what may be included. As with the POST, any data associated with the bulk port-in will cascade to subtending orders when they are created. (Subtending orders are created after telephone numbers are added to the bulk port-in using the /tnList endpoint.) The PUT completely replaces the existing Bulk Portin order with the payload of the PUT. Please visit Guides and Tutorials.", "operationId": "PutBulkOrder", "summary": "Update bulk port-in order", "parameters": [ @@ -2024,7 +2024,7 @@ "/accounts", "Porting" ], - "description": "Delete a bulk port-in order with child port-ins. Deleting a bulk port-in is allowed for 'DRAFT' state only. Deleting a bulk port-in will delete all DRAFT child port-ins associated with the bulk port-in. When the bulk port-in is deleted, any child port-in orders that are not in a draft status are dissociated from the bulk port-in, but not deleted. Please visit Guides and Tutorials", + "description": "Delete a bulk port-in order with child port-ins. Deleting a bulk port-in is allowed for 'DRAFT' state only. Deleting a bulk port-in will delete all DRAFT child port-ins associated with the bulk port-in. When the bulk port-in is deleted, any child port-in orders that are not in a draft status are dissociated from the bulk port-in, but not deleted. Please visit Guides and Tutorials", "operationId": "DeleteBulkOrder", "summary": "Delete bulk port-in order", "parameters": [ @@ -2075,7 +2075,7 @@ "/accounts", "Porting" ], - "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing Bulk Port-in order. This is done via a PUT or PATCH on the existing order-id. Since the Bulk Port-in\n order acts as a template for port-in orders in DRAFT status, any record can be changed at any time. The PATCH replaces elements of the referenced Bulk Portin order, but it replaces only the records included in the request payload. Other elements will remain untouched.

Changing the fields in a Bulk Port-in order causes the system to reapply all changed values to the child port-ins contained in the list of subtending port-in orders. Note that if the port-in orders contained within the Bulk Port are in DRAFT state, any field can be modified. If any child port-in order in the Bulk Port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller.

Changing the ProcessingStatus to 'IN_PROGRESS' causes all child port-ins to begin processing. This is only valid if child port-ins exist for the bulk port-in.

Please visit Guides and Tutorials

", + "description": "

It is possible to change (\"SUPP\" in LNP terms) an existing Bulk Port-in order. This is done via a PUT or PATCH on the existing order-id. Since the Bulk Port-in\n order acts as a template for port-in orders in DRAFT status, any record can be changed at any time. The PATCH replaces elements of the referenced Bulk Portin order, but it replaces only the records included in the request payload. Other elements will remain untouched.

Changing the fields in a Bulk Port-in order causes the system to reapply all changed values to the child port-ins contained in the list of subtending port-in orders. Note that if the port-in orders contained within the Bulk Port are in DRAFT state, any field can be modified. If any child port-in order in the Bulk Port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller.

Changing the ProcessingStatus to 'IN_PROGRESS' causes all child port-ins to begin processing. This is only valid if child port-ins exist for the bulk port-in.

Please visit Guides and Tutorials

", "operationId": "PatchBulkOrder", "summary": "Patch bulk port-in order", "parameters": [ @@ -2153,7 +2153,7 @@ "/accounts", "Porting" ], - "description": "Retrieves a list of Port-in Orders that are all associated with the identified Bulk Port-in. This response is not paginated due to its inherently limited size. Please visit Guides and Tutorials", + "description": "Retrieves a list of Port-in Orders that are all associated with the identified Bulk Port-in. This response is not paginated due to its inherently limited size. Please visit Guides and Tutorials", "operationId": "ListBulkChildOrders", "summary": "List bulk port-in child orders", "parameters": [ @@ -2201,7 +2201,7 @@ "/accounts", "Porting" ], - "description": "

A PUT on a PortinList resource will cause replacement of the list of port-in orders associated with the specified bulk port-in.

This PUT will completely replace the existing list of port-in orders associated with the bulk port-in. If all port-in orders in the list are not valid, the PUT request will fail, due to the potential for losing the port-in to bulk port-in relationships.

Only port-in orders in a draft status may be associated with a bulk port-in order. And port-in orders may only be added to a bulk port-in order while that bulk port-in order is still in a draft state.

Child port-in orders may be dissociated from the bulk port-in at any time.

Please visit Guides and Tutorials

", + "description": "

A PUT on a PortinList resource will cause replacement of the list of port-in orders associated with the specified bulk port-in.

This PUT will completely replace the existing list of port-in orders associated with the bulk port-in. If all port-in orders in the list are not valid, the PUT request will fail, due to the potential for losing the port-in to bulk port-in relationships.

Only port-in orders in a draft status may be associated with a bulk port-in order. And port-in orders may only be added to a bulk port-in order while that bulk port-in order is still in a draft state.

Child port-in orders may be dissociated from the bulk port-in at any time.

Please visit Guides and Tutorials

", "operationId": "UpdateBulkChildList", "summary": "Update list of bulk port-in child orders", "parameters": [ @@ -2269,7 +2269,7 @@ "/accounts", "Porting" ], - "description": "Retrieve all notes associated with the order. Please visit Guides and Tutorials", + "description": "Retrieve all notes associated with the order. Please visit Guides and Tutorials", "operationId": "ListBulkNotes", "summary": "List bulk port-in order notes", "parameters": [ @@ -2320,7 +2320,7 @@ "/accounts", "Porting" ], - "description": "Updates the Notes resource by adding a note. Adding a note to a port-in order causes a notification to be sent to Bandwidth Operations, so that they may assist as necessary. A note may be up to 500 characters in length. Please visit Guides and Tutorials", + "description": "Updates the Notes resource by adding a note. Adding a note to a port-in order causes a notification to be sent to Bandwidth Operations, so that they may assist as necessary. A note may be up to 500 characters in length. Please visit Guides and Tutorials", "operationId": "CreateBulkNote", "summary": "Create bulk port-in order note", "parameters": [ @@ -2388,7 +2388,7 @@ "/accounts", "Porting" ], - "description": "Update a specified note. Notes may only be updated, not deleted. Please visit Guides and Tutorials", + "description": "Update a specified note. Notes may only be updated, not deleted. Please visit Guides and Tutorials", "operationId": "UpdateBulkNote", "summary": "Update bulk port-in order note", "parameters": [ @@ -2466,7 +2466,7 @@ "/accounts", "Porting" ], - "description": "

The information returned in the GET /tnList response payload depends on the ProcessingStatus of the bulk port-in order. See the Responses tab for examples of each response payload.

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

\n ProcessingStatus\n

\n 		\n

\n Information Returned\n

\n
\n

\n DRAFT\n

\n 		\n

\n In this state, no tnList has been provided, so the response\n includes empty portable and non-portable telephone number lists.\n

\n
\n

\n VALIDATE_DRAFT_TNS\n

\n 		\n

\n In this state, validation of the tnList is still in progress,\n so the response includes all of the tnList telephone numbers\n in a 'not validated' list. This is a temporary state until\n the validation completes. Validation takes longer when toll\n free numbers are included in the tnList.\n

\n
\n

\n VALID_DRAFT_TNS\n

\n 		\n

\n In this state, all of the telephone numbers in the tnList have\n been determined to be portable. The response payload includes\n a list of the child port-in orders and shows which telephone\n numbers are assigned to each child port-in order.\n

\n
\n

\n INVALID_DRAFT_TNS\n

\n 		\n

\n In this state, at least one of the telephone numbers in the tnList\n has been determined to be non-portable. The response payload includes\n a list of portable numbers (if any) and a list of errors showing which\n telephone numbers are non-portable as well as the reasons why they\n cannot be ported. Or, if communication errors prevented us from\n determining telephone number portability, those errors will be included.\n

\n
\n

Please visit Guides and Tutorials

", + "description": "

The information returned in the GET /tnList response payload depends on the ProcessingStatus of the bulk port-in order. See the Responses tab for examples of each response payload.

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
\n

\n ProcessingStatus\n

\n 		\n

\n Information Returned\n

\n
\n

\n DRAFT\n

\n 		\n

\n In this state, no tnList has been provided, so the response\n includes empty portable and non-portable telephone number lists.\n

\n
\n

\n VALIDATE_DRAFT_TNS\n

\n 		\n

\n In this state, validation of the tnList is still in progress,\n so the response includes all of the tnList telephone numbers\n in a 'not validated' list. This is a temporary state until\n the validation completes. Validation takes longer when toll\n free numbers are included in the tnList.\n

\n
\n

\n VALID_DRAFT_TNS\n

\n 		\n

\n In this state, all of the telephone numbers in the tnList have\n been determined to be portable. The response payload includes\n a list of the child port-in orders and shows which telephone\n numbers are assigned to each child port-in order.\n

\n
\n

\n INVALID_DRAFT_TNS\n

\n 		\n

\n In this state, at least one of the telephone numbers in the tnList\n has been determined to be non-portable. The response payload includes\n a list of portable numbers (if any) and a list of errors showing which\n telephone numbers are non-portable as well as the reasons why they\n cannot be ported. Or, if communication errors prevented us from\n determining telephone number portability, those errors will be included.\n

\n
\n

Please visit Guides and Tutorials

", "operationId": "ListBulkTns", "summary": "List bulk port-in order tns", "parameters": [ @@ -2514,7 +2514,7 @@ "/accounts", "Porting" ], - "description": "

This operation is used to add telephone numbers to a draft bulk port-in order.\n The telephone numbers may be a mix of toll free and non-toll free. Once the\n telephone numbers are added, they will be checked for portability, and if\n portable, decomposed into individual child port-in orders. Both the bulk\n port-in order and the child port-in orders remain in draft status until you\n explicitly submit them.

\n\n

After submitting a tnList with the PUT operation, you will need to poll for\n completion of the validation and decomposition using the GET /tnList operation\n or the GET /bulkPortins/orderId operation (both include the order ProcessingStatus).\n The basic ProcessingStatus flow is as follows:

\n\n
  • On submission of the tnList, the bulk port-in order transitions from DRAFT\n status to VALIDATE_DRAFT_TNS. The order will remain in this state until validation\n is complete. For a tnList that does not contain any toll free telephone numbers, the\n validation step is very fast. When the tnList does contain toll free telephone\n numbers, the time it takes to validate the toll free numbers is roughly proportional\n to the number of toll free telephone numbers. If you PUT a new tnList while validation\n is in progress for a previous tnList, the validation of the previous tnList will be\n abandoned and replaced by validation of the new tnList.
    • \n
  • If all of the telephone numbers in the tnList are portable, the bulk port-in\n transitions to the VALID_DRAFT_TNS state. At this point, child port-in orders have\n been created in DRAFT status to meet requirements about which telephone numbers can\n be ported together in the same port-in order. The bulk port-in will remain in this\n state until you use the PATCH operation on the bulk port-in order to change the\n ProcessingStatus to IN_PROGRESS. If you PUT an updated tnList, all draft child\n port-in orders are removed, and the validation process begins again with the new\n tnList.
    • \n
  • If at least one of the telephone numbers in the tnList is not portable, the bulk\n port-in transitions to the INVALID_DRAFT_TNS state. When this happens, no child\n port-in orders are created. You can use the GET operation on /tnList to see reasons\n why telephone numbers are non-portable. You’ll need to update the tnList to remove\n non-portable telephone numbers and PUT the tnList again to restart the validation\n step. The goal is to get to the VALID_DRAFT_TNS state, from which you can submit\n the bulk port-in order.
\n

Please visit Guides and Tutorials

", + "description": "

This operation is used to add telephone numbers to a draft bulk port-in order.\n The telephone numbers may be a mix of toll free and non-toll free. Once the\n telephone numbers are added, they will be checked for portability, and if\n portable, decomposed into individual child port-in orders. Both the bulk\n port-in order and the child port-in orders remain in draft status until you\n explicitly submit them.

\n\n

After submitting a tnList with the PUT operation, you will need to poll for\n completion of the validation and decomposition using the GET /tnList operation\n or the GET /bulkPortins/orderId operation (both include the order ProcessingStatus).\n The basic ProcessingStatus flow is as follows:

\n\n
  • On submission of the tnList, the bulk port-in order transitions from DRAFT\n status to VALIDATE_DRAFT_TNS. The order will remain in this state until validation\n is complete. For a tnList that does not contain any toll free telephone numbers, the\n validation step is very fast. When the tnList does contain toll free telephone\n numbers, the time it takes to validate the toll free numbers is roughly proportional\n to the number of toll free telephone numbers. If you PUT a new tnList while validation\n is in progress for a previous tnList, the validation of the previous tnList will be\n abandoned and replaced by validation of the new tnList.
    • \n
  • If all of the telephone numbers in the tnList are portable, the bulk port-in\n transitions to the VALID_DRAFT_TNS state. At this point, child port-in orders have\n been created in DRAFT status to meet requirements about which telephone numbers can\n be ported together in the same port-in order. The bulk port-in will remain in this\n state until you use the PATCH operation on the bulk port-in order to change the\n ProcessingStatus to IN_PROGRESS. If you PUT an updated tnList, all draft child\n port-in orders are removed, and the validation process begins again with the new\n tnList.
    • \n
  • If at least one of the telephone numbers in the tnList is not portable, the bulk\n port-in transitions to the INVALID_DRAFT_TNS state. When this happens, no child\n port-in orders are created. You can use the GET operation on /tnList to see reasons\n why telephone numbers are non-portable. You’ll need to update the tnList to remove\n non-portable telephone numbers and PUT the tnList again to restart the validation\n step. The goal is to get to the VALID_DRAFT_TNS state, from which you can submit\n the bulk port-in order.
\n

Please visit Guides and Tutorials

", "operationId": "UpdateBulkTnList", "summary": "Update bulk port-in order tn list", "parameters": [ @@ -2595,7 +2595,7 @@ "/accounts", "Porting" ], - "description": "Retrieves the history of the specified bulk port-in order. Obtaining history for a draft bulk port-in is not supported.

Please visit Guides and Tutorials

", + "description": "Retrieves the history of the specified bulk port-in order. Obtaining history for a draft bulk port-in is not supported.

Please visit Guides and Tutorials

", "operationId": "GetBulkHistory", "summary": "Retrieve bulk port-in order history", "parameters": [ From 3894421d784def885c13cdf5360da3c73d70b5b8 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Tue, 2 Aug 2022 13:50:17 +0300 Subject: [PATCH 15/20] Porting - address comments --- .../numbers/porting/createBulkPortins.mdx | 2 +- site/docs/numbers/porting/lnpChecker.mdx | 41 ++++++++++--------- site/docs/numbers/porting/loaUpload.mdx | 2 +- site/docs/numbers/porting/portingNumbers.mdx | 4 +- 4 files changed, 25 insertions(+), 24 deletions(-) diff --git a/site/docs/numbers/porting/createBulkPortins.mdx b/site/docs/numbers/porting/createBulkPortins.mdx index 4ad113b77..3ec286788 100644 --- a/site/docs/numbers/porting/createBulkPortins.mdx +++ b/site/docs/numbers/porting/createBulkPortins.mdx @@ -184,7 +184,7 @@ The child port-ins as a bulk port are also created in ```DRAFT``` status, allowi ## Where to next? -Now that you have learnt how to create a Bulk Port-in order, check out some of the available actions in the following guides: +Now that you have learned how to create a Bulk Port-in order, check out some of the other available actions in the following guides: - [How to submit Bulk Port-in →](/docs/numbers/guides/porting/submitBulkPortins) - [How to update Bulk Port-in →](/docs/numbers/guides/porting/updateBulkPortins) \ No newline at end of file diff --git a/site/docs/numbers/porting/lnpChecker.mdx b/site/docs/numbers/porting/lnpChecker.mdx index 5615c6bef..63e4a1737 100644 --- a/site/docs/numbers/porting/lnpChecker.mdx +++ b/site/docs/numbers/porting/lnpChecker.mdx @@ -2,7 +2,7 @@ id: lnpChecker title: Check number(s) portability slug: /numbers/guides/porting/lnpChecker -description: How to check number(s) portability +description: How to check if a number is portable keywords: - bandwidth - numbers @@ -35,31 +35,20 @@ export const Highlight = ({children, color}) => ( ); -A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network. +For a smoother porting experience, you can check to see if your numbers are portable to the Bandwidth Network, before submitting a port order. :::info -As an alternative to individual porting the `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/createBulkPortins). +The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/createBulkPortins). ::: -TNs can be ported in a single `/portins` request if all the following are true: +For all TNs in a `/portins` request, all of the following must be true: 1. They all have the same Port Type (see the `Port Types` section below) -2. Telephone numbers all have the same losing carrier (toll free telephone numbers all have the same losing RespOrg) +2. They all have the same losing carrier (toll free telephone numbers all have the same losing RespOrg) 3. They are all associated with the same billing TN and Service Address -:::caution -There are also a number of reasons why a TN may not be able to be ported in: - -* The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. -* The TN is an off-net TN, and the account is configured to support tier zero (on-net) only. -* The TN belongs to a losing carrier that Bandwidth does not have a Trading Partner Agreement with. -* The TN is already being processed in another active port-in order. -* The Bandwidth account has not been enabled for porting. -Otherwise, the user must separate the TNs into individual `/portins` requests. -::: - ### Port Types -Port Type - is a categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. +Port Type is a categorization of how the TNs submitted to the /lnpchecker API will be handled by Bandwidth. | Port Type | Description | | |:----------------------------------|:-------------------------------------------------------| @@ -78,7 +67,7 @@ A number or set of numbers can be checked to see if they can be ported into the POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker +:::caution +There are some cases that you won't be able to port in a TN: + +* The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. +* The TN is an off-net TN, and the account is configured to support tier zero (on-net) only. +* The TN belongs to a losing carrier with whom Bandwidth does not have a Trading Partner Agreement. +* The TN is already being processed in another active port-in order. +* The Bandwidth account has not been enabled for porting. +Otherwise, the user must separate the TNs into individual `/portins` requests. +::: + ## Where to next? -Now that you have learnt how to check numbers portability, check out some of the available actions in the following guides: -- [How to create Port in request →](/docs/numbers/guides/porting/portingNumbers) +Now that you have learned how to check the portability of a number, check out some of the other available actions in the following guides: +- [How to create a Port-In Request →](/docs/numbers/guides/porting/portingNumbers) + diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx index 7375b6779..bbf24c290 100644 --- a/site/docs/numbers/porting/loaUpload.mdx +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -162,5 +162,5 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} ## Where to next? -Now that you have learnt how to create a Port in order, check out some of the available actions in the following guides: +Now that you have learned how to upload a LOA file, check out some of the other available actions in the following guides: - [How to manage Port in →](/docs/numbers/guides/porting/updatePortin) diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 1b4f1dc2c..2e0cac132 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -37,7 +37,7 @@ The Bandwidth Phone Number `/portins` API is used to submit Port-In requests. Th In order to successfully port telephone numbers they need to correspond to a set of criteria. To check them follow the [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) guide. :::info -As an alternative to individual porting the `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/createBulkPortins). +The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/createBulkPortins). ::: ## Create a Port-in Order @@ -219,7 +219,7 @@ If your port-on order stuck in a ```PENDING_DOCUMENTS``` status and does not tra ## Where to next? -Now that you have learnt how to create a Port in order, check out some of the available actions in the following guides: +Now that you have learned how to create a Port in order, check out some of the other available actions in the following guides: - [How to check numbers portability ←](/docs/numbers/guides/porting/lnpChecker) - [How to upload LOA (Letter of authorization) →](/docs/numbers/guides/porting/loaUpload) From 23a0d95abee4fcdddce4f1fa7facd23dd21a133a Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Wed, 10 Aug 2022 16:09:46 +0300 Subject: [PATCH 16/20] Address review comments --- site/docs/numbers/orderWebhook.md | 2 +- .../numbers/porting/createBulkPortins.mdx | 95 +++++++++++++++++-- site/docs/numbers/porting/lnpChecker.mdx | 2 +- site/docs/numbers/porting/loaUpload.mdx | 2 +- site/docs/numbers/porting/portingNumbers.mdx | 2 +- .../docs/numbers/porting/submitBulkportin.mdx | 10 +- .../numbers/porting/updateBulkPortins.mdx | 16 ++-- site/docs/numbers/porting/updatePortin.mdx | 4 +- 8 files changed, 105 insertions(+), 28 deletions(-) diff --git a/site/docs/numbers/orderWebhook.md b/site/docs/numbers/orderWebhook.md index 5aaeccfff..de8a8da88 100644 --- a/site/docs/numbers/orderWebhook.md +++ b/site/docs/numbers/orderWebhook.md @@ -12,7 +12,7 @@ image: ../../static/img/bandwidth-logo.png The notification webhook API is used to notify customers of events and changes that occur with various feature and service orders that are being processed by the Bandwidth Numbers API on their behalf. In general this notification webhook will be called whenever an order that is in-scope changes state or has a note added to it. Alternatively, notification webhook will be called whenever a subscribed event occurs -When an order changes OR when numbers in customer account are impacted due to orders placed outside of their account the Bandwidth Dashboard API will POST a pre-defined payload to our customer at the URL that they have defined by use of the `/accounts/{{accountId}}/subscriptions` API call. Please see the subscription documentation to understand how to register the notification webhook API with the Bandwidth Numbers API. +When an order changes OR when numbers in customer account are impacted due to orders placed outside of their account the Bandwidth Dashboard API will POST a pre-defined payload to our customer at the URL that they have defined by use of the [`/accounts/{accountId}/subscriptions`](/apis/numbers/#operation/CreateSubscriptions) API call. Please see the subscription documentation to understand how to register the notification webhook API with the Bandwidth Numbers API. ### Order Types diff --git a/site/docs/numbers/porting/createBulkPortins.mdx b/site/docs/numbers/porting/createBulkPortins.mdx index 3ec286788..86becdef7 100644 --- a/site/docs/numbers/porting/createBulkPortins.mdx +++ b/site/docs/numbers/porting/createBulkPortins.mdx @@ -67,7 +67,7 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins > Response -``` +```xml @@ -89,7 +89,7 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins -```cURL +```xml Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/bulkPortins' \ @@ -104,15 +104,36 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/bulkPortins' ' ``` +> Response + +```xml + + + + Order Id for all child orders + 2021-06-30T00:00:00.000Z + 14020 + 521434 + DRAFT + 9900572 + jgilmore + jgilmore + 2021-06-21T19:42:34.760Z + 2021-06-21T19:42:34.760Z + ac2c8ab2-7a63-44da-a307-edcabe0b6c81 + + +``` + -When bulk port-in is created, it has ```DRAFT``` status, which means it has not been processed yet. -If you want to update your bulk port-in (either in ```DRAFT``` or other further state) follow the [How to update Bulk Port-in](/docs/numbers/guides/porting/updateBulkPortins) guide. +When a Bulk Port-in is created, it has ```DRAFT``` status, which means it has not been processed yet. +If you want to update your Bulk Port-in (either in ```DRAFT``` or other further state) follow the [How to update Bulk Port-in](/docs/numbers/guides/porting/updateBulkPortins) guide. ## Provide telephone number(s) to port -After Bulk Port-in is created the next step is to add telephone numbers to the order. To do it you must send a PUT request to our [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/UpdateBulkTnList) endpoint. This can be done through tools like Postman, or in command line. +After the Bulk Port-in is created, add telephone numbers to the order by sending a PUT request to our [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/UpdateBulkTnList) endpoint. This can be done through tools like Postman, or in command line. PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList Response -``` +```xml ac2c8ab2-7a63-44da-a307-edcabe0b6c81 @@ -154,7 +175,7 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/t -```cURL +```xml Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList' \ @@ -170,10 +191,68 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orde ' ``` +> Response + +```xml + + + ac2c8ab2-7a63-44da-a307-edcabe0b6c81 + VALIDATE_DRAFT_TNS + +``` + -After submitting a tnList with the ```PUT``` operation, you will need to poll for completion of the validation and decomposition using the GET [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/ListBulkTns). Check the ```ProcessingStatus``` field. If all the telephone numbers in the tnList are portable, the bulk port-in transitions to the ```VALID_DRAFT_TNS``` state. +### Polling vs. Webhooks + +After submitting a tnList with the ```PUT``` operation, you will need to check the validation and decomposition completion. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription. Follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) to learn more. + +> Example + +```xml +Note: Remember to add authentication for your application if needed! + +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions + + + + bulkPortins + + "http://yourhost:8080/path/to/resource" + 12000 + + + superuser + s3cure + + LS0tLS1CRUdJTiBDRVJUSU [...] kQgQ0VSVElGSUNBVEUtLS0tLQ0K + + + +``` + +When notification is sent, you need to check `Status` field + +> Notification example + +```xml +POST your_url.com/webhookService HTTP/1.1 +Content-Type: application/xml; charset=utf-8 + + + + ... + bulkPortins + ... + VALID_DRAFT_TNS + +``` + + +If you want to use polling you can make a [GET /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/ListBulkTns) request and check the ```ProcessingStatus``` field. + +If all the telephone numbers in the tnList are portable, the bulk port-in transitions to the ```VALID_DRAFT_TNS``` state. :::caution If at least one of the telephone numbers in the tnList is not portable, the bulk port-in transitions to the ```INVALID_DRAFT_TNS``` state. You will see reasons why telephone numbers are non-portable in response body. To fix it you’ll need to update the tnList to remove non-portable telephone numbers. diff --git a/site/docs/numbers/porting/lnpChecker.mdx b/site/docs/numbers/porting/lnpChecker.mdx index 63e4a1737..39f532a50 100644 --- a/site/docs/numbers/porting/lnpChecker.mdx +++ b/site/docs/numbers/porting/lnpChecker.mdx @@ -156,7 +156,7 @@ Content-Type: application/xml; charset=utf-8 -```cURL +```xml Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker?fullcheck=true' \ diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx index bbf24c290..2b52d9ec2 100644 --- a/site/docs/numbers/porting/loaUpload.mdx +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -146,7 +146,7 @@ To manage your LOA files use our APIs like [/portins/{orderid}/loas/{fileId}](/a > Request -```cURL +```xml curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata' \ -X PUT \ -U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 2e0cac132..f2b497565 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -143,7 +143,7 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/portins -```cURL +```xml Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ diff --git a/site/docs/numbers/porting/submitBulkportin.mdx b/site/docs/numbers/porting/submitBulkportin.mdx index caabdd9a5..d2ed08381 100644 --- a/site/docs/numbers/porting/submitBulkportin.mdx +++ b/site/docs/numbers/porting/submitBulkportin.mdx @@ -29,12 +29,10 @@ export const Highlight = ({children, color}) => ( ); -[The bulkPortins endpoint](/apis/numbers#operation/CreateBulkPortin) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. - -## Submit Bulk Port-in - On this step we assume that you have created your bulk port-in and added telephone numbers which you wanted to port into the Bandwidth Dashboard. If not, follow the [How to create Bulk Port in](/docs/numbers/guides/porting/createBulkPortins) guide. +These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. + The bulk port-in and child port-in orders will remain in draft states until you submit them. You can submit all the port-ins together under the umbrella of the bulk port-in by changing bulk port-in status to ```IN_PROGRESS```. :::info @@ -72,7 +70,7 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} > Response -``` +```xml @@ -94,7 +92,7 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} -```cURL +```xml Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ diff --git a/site/docs/numbers/porting/updateBulkPortins.mdx b/site/docs/numbers/porting/updateBulkPortins.mdx index cc85b219a..bd0a1da13 100644 --- a/site/docs/numbers/porting/updateBulkPortins.mdx +++ b/site/docs/numbers/porting/updateBulkPortins.mdx @@ -1,6 +1,6 @@ --- id: updateBulkPortins -title: Update Bulk Port-in +title: Update or Delete Bulk Port-in slug: /numbers/guides/porting/updateBulkPortins description: How to update bulk port-in order using the Bandwidth API keywords: @@ -28,7 +28,7 @@ export const Highlight = ({children, color}) => ( ); -[The bulkPortins endpoint](/apis/numbers#operation/CreateBulkPortin) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. +Follow this guide if you'd like to update or delete a Bulk Port-in order. ## Update Bulk Port-in @@ -47,7 +47,7 @@ Subtending orders are created after tns are added to the bulk port-in using the ### Example -In the following example we are adding ```LoaAuthorizingPerson``` field to the bulk porting (to apply it to all future subtending port-in orders): +In the following example we are adding ```LoaAuthorizingPerson``` field to the bulk port-in (to apply it to all future subtending port-in orders): PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} Response -``` +```xml @@ -99,7 +99,7 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} -```cURL +```xml Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ @@ -145,7 +145,7 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} > Response -``` +```xml @@ -168,7 +168,7 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} -```cURL +```xml Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ @@ -185,7 +185,7 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orde ## Delete Bulk Port-in -You can delete a bulk port-in order with child port-ins. Deleting a bulk port-in is allowed for ```DRAFT``` state only. Deleting a bulk port-in will delete all ```DRAFT``` child port-ins associated with the bulk port-in. When the bulk port-in is deleted, any child port-in orders that are not in a ```DRAFT``` status are dissociated from the bulk port-in, but not deleted. +You can delete a Bulk Port-in order with child port-ins. Deleting a bulk port-in is allowed for ```DRAFT``` state only. Deleting a bulk port-in will delete all ```DRAFT``` child port-ins associated with the bulk port-in. When the bulk port-in is deleted, any child port-in orders that are not in a ```DRAFT``` status are dissociated from the bulk port-in, but not deleted. ### Examples DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx index 5337c28aa..8c2988e34 100644 --- a/site/docs/numbers/porting/updatePortin.mdx +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -124,7 +124,7 @@ Content-Type: application/xml; charset=utf-8 -```cURL +```xml Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins/d28b36f7-fa96-49eb-9556-a40fca49f7c6' \ @@ -206,7 +206,7 @@ The API allows a user to cancel an existing LNP order. The order number that was }> -```http +```xml curl -X DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/d28b36f7-fa96-49eb-9556-a40fca49f7c6 \ -U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ -H 'Content-Type: application/xml' From e34e0036558f7f7b6fd18217c07a1ae9b4acdb63 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Tue, 30 Aug 2022 13:36:33 +0300 Subject: [PATCH 17/20] Address comments --- site/docs/numbers/lsrOrders.mdx | 2 +- site/docs/numbers/orderWebhook.md | 2 +- .../numbers/porting/createBulkPortins.mdx | 107 +++++++++++++----- site/docs/numbers/porting/lnpChecker.mdx | 6 +- site/docs/numbers/porting/loaUpload.mdx | 4 +- site/docs/numbers/porting/portingNumbers.mdx | 10 +- .../docs/numbers/porting/submitBulkportin.mdx | 10 +- .../numbers/porting/updateBulkPortins.mdx | 10 +- site/docs/numbers/porting/updatePortin.mdx | 18 +-- site/specs-temp/numbers.json | 86 +++++++------- 10 files changed, 151 insertions(+), 104 deletions(-) diff --git a/site/docs/numbers/lsrOrders.mdx b/site/docs/numbers/lsrOrders.mdx index b6171d42c..89cc75240 100644 --- a/site/docs/numbers/lsrOrders.mdx +++ b/site/docs/numbers/lsrOrders.mdx @@ -72,7 +72,7 @@ The payload fields are described below: |:--------------------------|:-------------------------------------| | `Pon` | The Pon is customer specified order identifier field. Allowed alphanumeric and "#","-","_". Up to 25 characters long. (required) | | `CustomerOrderId` | The CustomerOrderId is customer specified order identifier field. Allowed alphanumeric, spaces and dashes. Up to 40 characters long. (optional) | -| `SPID` | Identifier used in porting process. If account is no multi-SPID option - default with account value, otherwise value is required. Up to 4 characters long. (required | +| `SPID` | Identifier used in porting process. If account is no multi-SPID option - default with account value, otherwise value is required. Up to 4 characters long. (required) | | `BillingTelephoneNumber` | Non-tollfree 10 digit phone number (optional) | | `RequestedFocDate` | optional (next day if not specified) | | `SubscriberType` | Subscriber type. BUSINESS | RESEDENTIAL (optional) (RESEDENTIAL if not specified) | diff --git a/site/docs/numbers/orderWebhook.md b/site/docs/numbers/orderWebhook.md index e69197127..aef13382f 100644 --- a/site/docs/numbers/orderWebhook.md +++ b/site/docs/numbers/orderWebhook.md @@ -12,7 +12,7 @@ image: '@site/static/img/bw-icon.svg' The notification webhook API is used to notify customers of events and changes that occur with various feature and service orders that are being processed by the Bandwidth Numbers API on their behalf. In general this notification webhook will be called whenever an order that is in-scope changes state or has a note added to it. Alternatively, notification webhook will be called whenever a subscribed event occurs -When an order changes OR when numbers in customer account are impacted due to orders placed outside of their account the Bandwidth Dashboard API will POST a pre-defined payload to our customer at the URL that they have defined by use of the [`/accounts/{accountId}/subscriptions`](/apis/numbers/#operation/CreateSubscriptions) API call. Please see the subscription documentation to understand how to register the notification webhook API with the Bandwidth Numbers API. +When an order changes OR when numbers in customer account are impacted due to orders placed outside of their account, the Bandwidth Dashboard API will POST a pre-defined payload to our customer at the URL that they have defined by use of the [`/accounts/{accountId}/subscriptions`](/apis/numbers/#operation/CreateSubscriptions) API call. Please see the subscription documentation to understand how to register the notification webhook API with the Bandwidth Numbers API. ### Order Types diff --git a/site/docs/numbers/porting/createBulkPortins.mdx b/site/docs/numbers/porting/createBulkPortins.mdx index 773aa8c08..eb449684f 100644 --- a/site/docs/numbers/porting/createBulkPortins.mdx +++ b/site/docs/numbers/porting/createBulkPortins.mdx @@ -29,11 +29,11 @@ export const Highlight = ({children, color}) => ( ); -[The bulkPortins endpoint](/apis/numbers#operation/CreateBulkPortin) is used to manage requests to port a diverse collection of Telephone Numbers into the Bandwidth Dashboard. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. +[The bulkPortins endpoint](/apis/numbers#operation/CreateBulkPortin) is used to manage requests to port a diverse collection of telephone numbers into the Bandwidth network. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId or RequestedFocDate. ## Create Bulk Port-in Draft -To create Bulk Port-in request order, you must make a POST request to our [API /bulkPortins](/apis/numbers/#operation/CreateBulkPortin) endpoint. This order is used to manage the porting event throughout the lifecycle of the request. This can be done through tools like Postman, or in command line. Note the ```OrderId``` field in response. It will be used for the next steps. +To create Bulk Port-in request order, you must make a POST request to our [API /bulkPortins](/apis/numbers/#operation/CreateBulkPortin) endpoint. This order is used to manage the porting event throughout the lifecycle of the request. This can be done through tools like Postman or cURL. Note the ```OrderId``` field in response. It will be used for the next steps. :::info Only fields that you wish to use as defaults for all of the child port-in orders should be included in the bulk port-in order. @@ -53,7 +53,7 @@ Only fields that you wish to use as defaults for all of the child port-in orders > Request ```xml -Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH_PASSWORD https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins \n @@ -77,8 +77,8 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins 521434 DRAFT 9900572 - jgilmore - jgilmore + testuser + testuser 2021-06-21T19:42:34.760Z 2021-06-21T19:42:34.760Z ac2c8ab2-7a63-44da-a307-edcabe0b6c81 @@ -94,7 +94,7 @@ Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/bulkPortins' \ -X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH_PASSWORD}' \ -H 'Content-Type: application/xml' \ -d ' Order Id for all child orders @@ -116,8 +116,8 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/bulkPortins' 521434 DRAFT 9900572 - jgilmore - jgilmore + testuser + testuser 2021-06-21T19:42:34.760Z 2021-06-21T19:42:34.760Z ac2c8ab2-7a63-44da-a307-edcabe0b6c81 @@ -133,7 +133,7 @@ If you want to update your Bulk Port-in (either in ```DRAFT``` or other further ## Provide telephone number(s) to port -After the Bulk Port-in is created, add telephone numbers to the order by sending a PUT request to our [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/UpdateBulkTnList) endpoint. This can be done through tools like Postman, or in command line. +After the Bulk Port-in is created, add telephone numbers to the order by sending a PUT request to our [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/UpdateBulkTnList) endpoint. This can be done through tools like Postman or cURL. PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList Request ```xml -Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH_PASSWORD https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList \n @@ -180,7 +180,7 @@ Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList' \ -X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH_PASSWORD}' \ -H 'Content-Type: application/xml' \ -d ' [telephone number] @@ -204,36 +204,44 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orde -### Polling vs. Webhooks +### Checking the Decomposition Status of a Bulk Port-in -After submitting a tnList with the ```PUT``` operation, you will need to check the validation and decomposition completion. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription. Follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) to learn more. +After submitting a tnList with the ```PUT``` operation it takes some time for the phone numbers to be validated and child port-ins to be created. This is done asynchronously which means you will need to check the validation and decomposition completion later. There are two ways to do that - using subscription or polling. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription. -> Example + + + +Below is a basic example of configuring the subscription. Follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) to learn more. + +PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions ```xml Note: Remember to add authentication for your application if needed! -PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/subscriptions - - bulkPortins - - "http://yourhost:8080/path/to/resource" - 12000 - - - superuser - s3cure - - LS0tLS1CRUdJTiBDRVJUSU [...] kQgQ0VSVElGSUNBVEUtLS0tLQ0K - - + bulkPortins + + "http://yourhost:8080/path/to/resource" + 12000 + + + superuser + s3cure + + LS0tLS1CRUdJTiBDRVJUSU [...] kQgQ0VSVElGSUNBVEUtLS0tLQ0K + + ``` -When notification is sent, you need to check `Status` field - > Notification example ```xml @@ -249,11 +257,50 @@ Content-Type: application/xml; charset=utf-8 ``` +When notification is sent, you need to check `Status` field. If all the telephone numbers in the tnList are portable, the bulk port-in transitions to the ```VALID_DRAFT_TNS``` state. + + + If you want to use polling you can make a [GET /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/ListBulkTns) request and check the ```ProcessingStatus``` field. +GET https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList + +> Response example + +```xml + + + VALID_DRAFT_TNS + ac2c8ab2-7a63-44da-a307-edcabe0b6c81 + + + xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1 + + [telephone number] + + + + xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2 + + [telephone number] + + + + xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx3 + + [telephone number] + [telephone number] + + + + +``` If all the telephone numbers in the tnList are portable, the bulk port-in transitions to the ```VALID_DRAFT_TNS``` state. + + + :::caution If at least one of the telephone numbers in the tnList is not portable, the bulk port-in transitions to the ```INVALID_DRAFT_TNS``` state. You will see reasons why telephone numbers are non-portable in response body. To fix it you’ll need to update the tnList to remove non-portable telephone numbers. ::: diff --git a/site/docs/numbers/porting/lnpChecker.mdx b/site/docs/numbers/porting/lnpChecker.mdx index 2615dd3d0..433410f3e 100644 --- a/site/docs/numbers/porting/lnpChecker.mdx +++ b/site/docs/numbers/porting/lnpChecker.mdx @@ -52,7 +52,7 @@ Port Type is a categorization of how the TNs submitted to the /lnpchecker API wi | Port Type | Description | | |:----------------------------------|:-------------------------------------------------------| -| MANUAL | `MANUAL` (for all port types starting with `MANUAL`) indicates that if the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a Zendesk ticket will be automatically created to notify the Bandwidth LNP team. | +| MANUAL | `MANUAL` (for all port types starting with `MANUAL`) indicates that if the TNs cannot be ported automatically, the Bandwidth LNP team will work with the appropriate porting vendor or losing carrier to ensure completion of the port-in. The /portins API can be used to submit manual port-ins, which will be identified as such, and a support ticket will be automatically created to notify the Bandwidth LNP team. | | MANUALOFFNET | `Off-net` means that the telephone numbers in the port-in exist in a rate center supported by one of Bandwidth’s partners. Off-net port-ins are processed manually when the Bandwidth partner does not have APIs by which the port-in can be automated, or Bandwidth has not implemented those APIs. Orders may also be processed manually if there are more numbers in the port-in than the partner’s interface supports, e.g. off-net ports with vendor Level 3 and with more than 49 TNs are automatically submitted as manual ports.| | MANUALONNET | `On-net` means that the telephone numbers in the port-in exist in a rate center supported by Bandwidth. On-net port-ins are processed manually only when there are more numbers in the port-in than the porting vendor’s interface supports (e.g more than 999 TNs). | | MANUALTOLLFREE | Currently all toll free port-ins are handled manually by Bandwidth’s LNP team. But Bandwidth is in the process of automating portions of toll free porting, with a goal of eventually automating the entire process. | @@ -61,7 +61,7 @@ Port Type is a categorization of how the TNs submitted to the /lnpchecker API wi ### Check number(s) portability -A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the POST request to [`/accounts/{accountId}/lnpChecker`](/apis/numbers#operation/RequestPortabilityInfo) API endpoint. This can be done using tools like Postman, or in command line. +A number or set of numbers can be checked to see if they can be ported into the Bandwidth Network using the POST request to [`/accounts/{accountId}/lnpChecker`](/apis/numbers#operation/RequestPortabilityInfo) API endpoint. This can be done using tools like Postman or cURL. ### Examples POST https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker @@ -161,7 +161,7 @@ Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/lnpChecker?fullcheck=true' \ -X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH_PASSWORD}' \ -H 'Content-Type: application/xml' \ -d ' diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx index 07346ba82..8163c76f8 100644 --- a/site/docs/numbers/porting/loaUpload.mdx +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -57,7 +57,7 @@ The following MIME types are supported for the LOA upload file: * ZIP (“application/zip”) -To upload and manage the LOA you can use different requests to [/portins/{orderId}/loas API](/apis/numbers/#operation/UploadPortinLoaFile). This can be done using tools like Postman, or in command line. +To upload and manage the LOA you can use different requests to [/portins/{orderId}/loas API](/apis/numbers/#operation/UploadPortinLoaFile). This can be done using tools like Postman or cURL. ### Examples POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas @@ -149,7 +149,7 @@ To manage your LOA files use our APIs like [/portins/{orderid}/loas/{fileId}](/a ```xml curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId}/loas/{fileId}/metadata' \ -X PUT \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH_PASSWORD}' \ -H 'Content-Type: application/xml' \ -d ' [string] diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 0388e00a8..be590cdb6 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -44,7 +44,7 @@ The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting The API allows a user to create a new LNP order. An order id will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. -To create Port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done using tools like Postman, or in command line. +To create Port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done using tools like Postman or cURL. ### Examples POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins @@ -64,7 +64,7 @@ To create Port-in request, you must make a POST 2016-03-25T21:15:00.000Z X455 @@ -148,7 +148,7 @@ Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ -X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH_PASSWORD}' \ -H 'Content-Type: application/xml' \ -d ' 2016-03-25T21:15:00.000Z @@ -190,7 +190,7 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ Porting numbers in the Bandwidth Dashboard is asynchronous which means the orders are processed and the order status is updated asynchronously. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. Please follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) guide. -To poll an information about your Port in you can still use a GET request to [accounts/{accountId}/portins API](/apis/numbers/#operation/GetPortin). This can be done using tools like Postman, or in command line. +To poll an information about your Port in you can still use a GET request to [accounts/{accountId}/portins API](/apis/numbers/#operation/GetPortin). This can be done using tools like Postman or cURL. GET https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} PATCH request to our [API /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkPortin) endpoint. This can be done through tools like Postman, or in command line. +To trigger Bulk Port-in processing use the ```PATCH``` operation on the bulk port-in order to change the ```ProcessingStatus``` to ```IN_PROGRESS```. To do it you must send a PATCH request to our [API /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkPortin) endpoint. This can be done through tools like Postman or cURL. :::caution Changing the ProcessingStatus to 'IN_PROGRESS' is only valid if child port-ins exist for the bulk port-in. Check [How to Provide telephone number(s) to port](/docs/numbers/guides/porting/createBulkPortins/#provide-telephone-numbers-to-port) guide. @@ -59,7 +59,7 @@ Changing the ProcessingStatus to 'IN_PROGRESS' is only valid if child port-ins e > Request ```xml -Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH_PASSWORD https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} \n @@ -80,8 +80,8 @@ https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} 521434 IN_PROGRESS 9900572 - jgilmore - jgilmore + testuser + testuser 2021-06-21T19:42:34.760Z 2021-06-21T19:42:34.760Z ac2c8ab2-7a63-44da-a307-edcabe0b6c81 @@ -97,7 +97,7 @@ Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ -X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH_PASSWORD}' \ -H 'Content-Type: application/xml' \ -d ' IN_PROGRESS diff --git a/site/docs/numbers/porting/updateBulkPortins.mdx b/site/docs/numbers/porting/updateBulkPortins.mdx index d92582ca0..adb5e4966 100644 --- a/site/docs/numbers/porting/updateBulkPortins.mdx +++ b/site/docs/numbers/porting/updateBulkPortins.mdx @@ -62,7 +62,7 @@ In the following example we are adding ```LoaAuthorizingPerson``` field to the b > Request ```xml -Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH_PASSWORD https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} @@ -104,7 +104,7 @@ Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ -X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH_PASSWORD}' \ -H 'Content-Type: application/xml' \ -d ' Order Id for all child orders @@ -135,7 +135,7 @@ Note that ```PUT``` completely replaces the existing Bulk Port-in order with the > Request ```xml -Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH:PASSWORD +Note: Make sure an authentication header is added with your BANDWIDTH_USERNAME and BANDWIDTH_PASSWORD https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} @@ -173,7 +173,7 @@ Note: Remember to add authentication for your application if needed! curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}' \ -X POST \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH_PASSWORD}' \ -H 'Content-Type: application/xml' \ -d ' The Guy @@ -201,7 +201,7 @@ You can delete a Bulk Port-in order with child port-ins. Deleting a bulk port-in ```http curl -X DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}} \ --U '{BANDWIDTH_USERNAME}:{BANDWIDTH:PASSWORD}' \ +-U '{BANDWIDTH_USERNAME}:{BANDWIDTH_PASSWORD}' \ -H 'Content-Type: application/xml' ``` diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx index a01c162f3..1fc1d2ca8 100644 --- a/site/docs/numbers/porting/updatePortin.mdx +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -46,7 +46,7 @@ Regarding the fields which can be updated for different port types check the req The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. ### Examples -To update Port-in request, you must make a PUT request to our [API /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) endpoint. This can be done using tools like Postman, or in command line. +To update Port-in request, you must make a PUT request to our [API /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) endpoint. This can be done using tools like Postman or cURL. PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} RESIDENTIAL - Steve - McKinnon + TestName + TestLastName \n\t\t -- link to first page of results -- \n\t\t\n\t\t\n\t\t -- link to next page of results -- \n\t\n\t\n\t\t\n\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t2020-03-18T21:26:47.403Z\n\t\t\t2020-03-18T21:26:47.403Z\n\t\t\tjgilmore\n\t\t\tThis is a description of the emergency notification recipient.\n\t\t\tCALLBACK\n\t\t\t\n\t\t\t\thttps://foo.bar/baz\n\t\t\t\t\n\t\t\t\t\tjgilmore\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\n\t\t\n\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t2020-03-22T12:13:25.782Z\n\t\t\t2020-03-22T12:13:25.782Z\n\t\t\tgfranklin\n\t\t\tThis is a description of the emergency notification recipient.\n\t\t\tEMAIL\n\t\t\tfred@gmail.com\n\t\t\n\t\t\n\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t2020-03-25T17:04:53.042Z\n\t\t\t2020-03-25T17:04:53.042Z\n\t\t\tmsimpson\n\t\t\tThis is a description of the emergency notification recipient.\n\t\t\tSMS\n\t\t\t\n\t\t\t\t12015551212\n\t\t\t\n\t\t\n\t\t\n\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t2020-03-29T20:14:01.736Z\n\t\t\t2020-03-29T20:17:53.294Z\n\t\t\tlsimpson\n\t\t\tThis is a description of the emergency notification recipient.\n\t\t\tTTS\n\t\t\t\n\t\t\t\t12015551212\n\t\t\t\n\t\t\n\t\n" + "value": "\n\n\t\n\t\t\n\t\t -- link to first page of results -- \n\t\t\n\t\t\n\t\t -- link to next page of results -- \n\t\n\t\n\t\t\n\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t2020-03-18T21:26:47.403Z\n\t\t\t2020-03-18T21:26:47.403Z\n\t\t\ttestuser\n\t\t\tThis is a description of the emergency notification recipient.\n\t\t\tCALLBACK\n\t\t\t\n\t\t\t\thttps://foo.bar/baz\n\t\t\t\t\n\t\t\t\t\ttestuser\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\n\t\t\n\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t2020-03-22T12:13:25.782Z\n\t\t\t2020-03-22T12:13:25.782Z\n\t\t\tgfranklin\n\t\t\tThis is a description of the emergency notification recipient.\n\t\t\tEMAIL\n\t\t\tfred@gmail.com\n\t\t\n\t\t\n\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t2020-03-25T17:04:53.042Z\n\t\t\t2020-03-25T17:04:53.042Z\n\t\t\tmsimpson\n\t\t\tThis is a description of the emergency notification recipient.\n\t\t\tSMS\n\t\t\t\n\t\t\t\t12015551212\n\t\t\t\n\t\t\n\t\t\n\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t2020-03-29T20:14:01.736Z\n\t\t\t2020-03-29T20:17:53.294Z\n\t\t\tlsimpson\n\t\t\tThis is a description of the emergency notification recipient.\n\t\t\tTTS\n\t\t\t\n\t\t\t\t12015551212\n\t\t\t\n\t\t\n\t\n" } } } @@ -4574,7 +4574,7 @@ }, "callback": { "description": "Sample request payload for an CALLBACK recipient", - "value": "\nCallback to property management system\n\tCALLBACK\n\t\n\t\thttps://foo.bar/baz\n\t\t\n\t\t\tjgilmore\n\t\t\tx23388%SLHss\n\t\t\n\t\n" + "value": "\nCallback to property management system\n\tCALLBACK\n\t\n\t\thttps://foo.bar/baz\n\t\t\n\t\t\ttestuser\n\t\t\tx23388%SLHss\n\t\t\n\t\n" } } } @@ -4604,7 +4604,7 @@ "examples": { "example": { "description": "example", - "value": "\n\n\t\n\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t2020-03-18T21:26:47.403Z\n\t\t2020-03-18T21:26:47.403Z\n\t\tjgilmore\n\t\tThis is a description of the emergency notification recipient.\n\t\tCALLBACK\n\t\t\n\t\t\thttps://foo.bar/baz\n\t\t\t\n\t\t\t\tjgilmore\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" + "value": "\n\n\t\n\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t2020-03-18T21:26:47.403Z\n\t\t2020-03-18T21:26:47.403Z\n\t\ttestuser\n\t\tThis is a description of the emergency notification recipient.\n\t\tCALLBACK\n\t\t\n\t\t\thttps://foo.bar/baz\n\t\t\t\n\t\t\t\ttestuser\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" } } } @@ -4711,7 +4711,7 @@ }, "callback": { "description": "For an CALLBACK type emergency notification recipient", - "value": "\n\t\n\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t2020-03-18T21:26:47.403Z\n\t\t2020-04-01T18:32:22.316Z\n\t\tjgilmore\n\t\tThis is a description of the emergency notification recipient.\n\t\tCALLBACK\n\t\t\n\t\t\thttps://foo.bar/baz\n\t\t\t\n\t\t\t\tjgilmore\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" + "value": "\n\t\n\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t2020-03-18T21:26:47.403Z\n\t\t2020-04-01T18:32:22.316Z\n\t\ttestuser\n\t\tThis is a description of the emergency notification recipient.\n\t\tCALLBACK\n\t\t\n\t\t\thttps://foo.bar/baz\n\t\t\t\n\t\t\t\ttestuser\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" } } } @@ -4801,7 +4801,7 @@ }, "callback": { "description": "Sample request payload for an CALLBACK recipient:", - "value": "\n\tCallback to property management system\n\tCALLBACK\n\t\n\t\thttps://foo.bar/baz\n\t\t\n\t\t\tjgilmore\n\t\t\tx23388%SLHss\n\t\t\n\t\n" + "value": "\n\tCallback to property management system\n\tCALLBACK\n\t\n\t\thttps://foo.bar/baz\n\t\t\n\t\t\ttestuser\n\t\t\tx23388%SLHss\n\t\t\n\t\n" } } } @@ -4831,7 +4831,7 @@ "examples": { "example": { "description": "example", - "value": "\n\n\t\n\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t2020-03-18T21:26:47.403Z\n\t\t2020-04-01T18:32:22.316Z\n\t\tjgilmore\n\t\tThis is a description of the emergency notification recipient.\n\t\tCALLBACK\n\t\t\n\t\t\thttps://foo.bar/baz\n\t\t\t\n\t\t\t\tjgilmore\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" + "value": "\n\n\t\n\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t2020-03-18T21:26:47.403Z\n\t\t2020-04-01T18:32:22.316Z\n\t\ttestuser\n\t\tThis is a description of the emergency notification recipient.\n\t\tCALLBACK\n\t\t\n\t\t\thttps://foo.bar/baz\n\t\t\t\n\t\t\t\ttestuser\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" } } } @@ -4980,7 +4980,7 @@ "schema": { "type": "string" }, - "example": "jgilmore" + "example": "testuser" }, { "name": "processingStatus", @@ -5197,7 +5197,7 @@ }, "201 for updated description": { "description": "A sample 201 response to an order payload for updating an emergency notification group description looks like the following", - "value": "\n\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t2020-01-23T18:34:17.284Z\n\tjgilmore\n\tPROCESSING \n\tALG-31233884\n\t\n\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t This is an updated description of the emergency notification Group. \n\t\n" + "value": "\n\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t2020-01-23T18:34:17.284Z\n\ttestuser\n\tPROCESSING \n\tALG-31233884\n\t\n\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t This is an updated description of the emergency notification Group. \n\t\n" }, "201 for adding recipients": { "description": "A sample 201 response to an order payload for updating an emergency notification group by adding emergency notification recipients looks like the following", @@ -5287,7 +5287,7 @@ "examples": { "example": { "description": "example", - "value": "\n\n\t\n\t\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t\t2020-01-23T18:34:17.284Z\n\t\tjgilmore\n\t\tCOMPLETED\n\t\tALG-31233884\n\t\t\n\t\t\t\n\t\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t\tBuilding 5, 5th Floor.\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t\t\t\t\tBuilding 5 front desk email\n\t\t\t\t\t\t\tEMAIL\n\t\t\t\t\t\t\tBldg5Reception@company.com\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\tef47eb61-e3b1-449d-834b-0fbc5a11da30\n\t\t\t\t\t\t\tBuilding 5 5th floor responder text\n\t\t\t\t\t\t\tSMS\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\t12124487782\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\tc9a2f068-e1b0-4454-9c0b-74c4113f6141\n\t\t\t\t\t\t\tCallback for MyCompany\n\t\t\t\t\t\t\tCALLBACK\n\t\t\t\t\t\t\thttps://foo.bar/baz\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\tjgilmore\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" + "value": "\n\n\t\n\t\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t\t2020-01-23T18:34:17.284Z\n\t\ttestuser\n\t\tCOMPLETED\n\t\tALG-31233884\n\t\t\n\t\t\t\n\t\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t\tBuilding 5, 5th Floor.\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t\t\t\t\tBuilding 5 front desk email\n\t\t\t\t\t\t\tEMAIL\n\t\t\t\t\t\t\tBldg5Reception@company.com\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\tef47eb61-e3b1-449d-834b-0fbc5a11da30\n\t\t\t\t\t\t\tBuilding 5 5th floor responder text\n\t\t\t\t\t\t\tSMS\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\t12124487782\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\tc9a2f068-e1b0-4454-9c0b-74c4113f6141\n\t\t\t\t\t\t\tCallback for MyCompany\n\t\t\t\t\t\t\tCALLBACK\n\t\t\t\t\t\t\thttps://foo.bar/baz\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t\ttestuser\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" } } } @@ -5423,7 +5423,7 @@ "examples": { "example": { "description": "example", - "value": "\n\n\t\n\t\t\n\t\t -- link to first page of results -- \n\t\t\n\t\t\n\t\t -- link to next page of results -- \n\t\n\t\n\t\t\n\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t2020-01-23T18:34:17.284Z\n\t\t\tjgilmore\n\t\t\t2020-01-23T18:34:17.284Z\n\t\t\tThis is a description of the emergency notification group.\n\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\tef47eb61-e3b1-449d-834b-0fbc5a11da30\n\t\t\t\t\n\t\t\t\n\t\t\n\t\t\n\t\t\t29477382-23947-23c-2349-aa8238b22743\n\t\t\t2020-01-23T18:36:51.987Z\n\t\t\tjgilmore\n\t\t\t2020-01-23T18:36:51.987Z\n\t\t\tThis is a description of the emergency notification group.\n\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\t37742335-8722-3abc-8722-e2434f123a4d\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" + "value": "\n\n\t\n\t\t\n\t\t -- link to first page of results -- \n\t\t\n\t\t\n\t\t -- link to next page of results -- \n\t\n\t\n\t\t\n\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t2020-01-23T18:34:17.284Z\n\t\t\ttestuser\n\t\t\t2020-01-23T18:34:17.284Z\n\t\t\tThis is a description of the emergency notification group.\n\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\tef47eb61-e3b1-449d-834b-0fbc5a11da30\n\t\t\t\t\n\t\t\t\n\t\t\n\t\t\n\t\t\t29477382-23947-23c-2349-aa8238b22743\n\t\t\t2020-01-23T18:36:51.987Z\n\t\t\ttestuser\n\t\t\t2020-01-23T18:36:51.987Z\n\t\t\tThis is a description of the emergency notification group.\n\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\t37742335-8722-3abc-8722-e2434f123a4d\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" } } } @@ -5526,7 +5526,7 @@ "examples": { "example": { "description": "example", - "value": "\n\n\t\n\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t2020-01-23T18:34:17.284Z\n\t\tjgilmore\n\t\t2020-01-23T18:34:17.284Z\n\t\tThis is a description of the emergency notification group.\n\t\t\n\t\t\t\n\t\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t\n\t\t\t\n\t\t\t\tef47eb61-e3b1-449d-834b-0fbc5a11da30\n\t\t\t\n\t\t\n\t\t\n\t\t\t\n\t\t\t\t19152431000\n\t\t\t\tACIDIdentifier12345\n\t\t\t\n\t\t\n\t\n" + "value": "\n\n\t\n\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t2020-01-23T18:34:17.284Z\n\t\ttestuser\n\t\t2020-01-23T18:34:17.284Z\n\t\tThis is a description of the emergency notification group.\n\t\t\n\t\t\t\n\t\t\t\t63865500-0904-46b1-9b4f-7bd237a26363\n\t\t\t\n\t\t\t\n\t\t\t\tef47eb61-e3b1-449d-834b-0fbc5a11da30\n\t\t\t\n\t\t\n\t\t\n\t\t\t\n\t\t\t\t19152431000\n\t\t\t\tACIDIdentifier12345\n\t\t\t\n\t\t\n\t\n" } } } @@ -5592,7 +5592,7 @@ "schema": { "type": "string" }, - "example": "jgilmore" + "example": "testuser" }, { "name": "processingStatus", @@ -5699,7 +5699,7 @@ "examples": { "example": { "description": "example", - "value": "\n\n\t\n\t\t\n\t\t -- link to first page of results -- \n\t\t\n\t\t\n\t\t -- link to next page of results -- \n\t\n\t\n\t\t\n\t\t\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t\t\t2020-01-23T18:34:17.284Z\n\t\t\tjgilmore\n\t\t\tCOMPLETED\n\t\t\tALG-31233884\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t3e9a852e-2d1d-4e2d-84c3-04595ba2eb93\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t2248838829\n\t\t\t\t\t\t\t4052397735\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\tFred992834\n\t\t\t\t\t\t\tBob00359\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\n\t\t\n\t\t\t\n\t\t\n\t\t\n\t\t\t\n\t\t\n\t\n" + "value": "\n\n\t\n\t\t\n\t\t -- link to first page of results -- \n\t\t\n\t\t\n\t\t -- link to next page of results -- \n\t\n\t\n\t\t\n\t\t\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t\t\t2020-01-23T18:34:17.284Z\n\t\t\ttestuser\n\t\t\tCOMPLETED\n\t\t\tALG-31233884\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t3e9a852e-2d1d-4e2d-84c3-04595ba2eb93\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t2248838829\n\t\t\t\t\t\t\t4052397735\n\t\t\t\t\t\t\n\t\t\t\t\t\t\n\t\t\t\t\t\t\tFred992834\n\t\t\t\t\t\t\tBob00359\n\t\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\n\t\t\n\t\t\t\n\t\t\n\t\t\n\t\t\t\n\t\t\n\t\n" } } } @@ -5781,11 +5781,11 @@ "examples": { "add endpoint": { "description": "The 201 response payload for creating an order to add emergency endpoint associations to an emergency notification group", - "value": "\n\t \n\t\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t\t2020-01-23T18:34:17.284Z\n\t\tjgilmore \n\t\tCOMPLETED \n\t\tALG-31233884 \n\t\t \n\t\t\t \n\t\t\t\t3e9a852e-2d1d-4e2d-84c3-04595ba2eb93\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t2248838829\n\t\t\t\t\t\t4052397735 \n\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\tFred992834\n\t\t\t\t\t\tBob00359\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t \n\t\t\n\t\n" + "value": "\n\t \n\t\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t\t2020-01-23T18:34:17.284Z\n\t\ttestuser \n\t\tCOMPLETED \n\t\tALG-31233884 \n\t\t \n\t\t\t \n\t\t\t\t3e9a852e-2d1d-4e2d-84c3-04595ba2eb93\n\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t2248838829\n\t\t\t\t\t\t4052397735 \n\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\tFred992834\n\t\t\t\t\t\tBob00359\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t \n\t\t\n\t\n" }, "remove endpoint": { "description": "The 201 response payload for creating an order to remove emergency endpoint associations from an emergency notification group", - "value": "\n\t\n\t\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t\t2020-01-23T18:34:17.284Z\n\t\tjgilmore\n\t\tPROCESSING\n\t\tALG-31233884\n\t\t\n\t\t\t3e9a852e-2d1d-4e2d-84c3-04595ba2eb93\n\t\t\n\t\t\n\t\t\n\t\t\t\n\t\t\t\n\t\t\t\t9152877649\n\t\t\t\n\t\t\t\n\t\t\t\tSally88744\n\t\t\t\n\t\t\t\n\t\t\n\t\t\n\t\n" + "value": "\n\t\n\t\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t\t2020-01-23T18:34:17.284Z\n\t\ttestuser\n\t\tPROCESSING\n\t\tALG-31233884\n\t\t\n\t\t\t3e9a852e-2d1d-4e2d-84c3-04595ba2eb93\n\t\t\n\t\t\n\t\t\n\t\t\t\n\t\t\t\n\t\t\t\t9152877649\n\t\t\t\n\t\t\t\n\t\t\t\tSally88744\n\t\t\t\n\t\t\t\n\t\t\n\t\t\n\t\n" } } } @@ -5867,7 +5867,7 @@ "examples": { "example": { "description": "example", - "value": "\n\n\t\n\t\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t\t2020-01-23T18:34:17.284Z\n\t\tjgilmore\n\t\tCOMPLETED\n\t\tALG-31233884\n\t\t\n\t\t\t\n\t\t\t\t3e9a852e-2d1d-4e2d-84c3-04595ba2eb93\n\t\t\t\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t2248838829\n\t\t\t\t\t\t4052397735\n\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\tFred992834\n\t\t\t\t\t\tBob00359\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" + "value": "\n\n\t\n\t\t3e9a852e-2d1d-4e2d-84c3-87223a78cb70\n\t\t2020-01-23T18:34:17.284Z\n\t\ttestuser\n\t\tCOMPLETED\n\t\tALG-31233884\n\t\t\n\t\t\t\n\t\t\t\t3e9a852e-2d1d-4e2d-84c3-04595ba2eb93\n\t\t\t\n\t\t\t\n\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\t2248838829\n\t\t\t\t\t\t4052397735\n\t\t\t\t\t\n\t\t\t\t\t\n\t\t\t\t\t\tFred992834\n\t\t\t\t\t\tBob00359\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n" } } } @@ -10084,13 +10084,13 @@ "value": "\n\t\n\t\t7205\n\t\tTelephone number is already being processed on another order\n\t\n\tCANCELLED\n\tb4e227b3-2caf-4546-9af7-849c60dce942\n\t2016-03-25T21:15:00.000Z\n\t\n\t2016-03-25T21:15:00.000Z\n\tSJM00002\n\tThe Authguy\n\t\n\t\tBUSINESS\n\t\tFirst\n\t\tLast\n\t\t\n\t\t\t11235\n\t\t\tBack\n\t\t\tDenver\n\t\t\tCO\n\t\t\t27541\n\t\t\tCanyon\n\t\t\tUnited States\n\t\t\tService\n\t\t\n\t\n\t\n\t\t771297665AABC\n\t\t1234\n\t\n\t\n\t\tProtected\n\t\tExternal\n\t\tImported\n\t\n\t9195551234\n\t9175131245\n\t\n\t\t9194809871\n\t\n\tFoo\n\t20\n\t2857\n\t317771\n\t9998\n\tMock Carrier\n\ttrue\n\tBandwidth CLEC\n\t2014-08-04T13:37:06.323Z\n\t2014-08-04T13:37:08.676Z\n\tjbm\n\tjbm\n\tfalse\n\tfalse\n\tfalse\n\tAUTOMATED\n" }, "Toll Free VALID_DRAFT_TFNS state": { - "value": "\n\tVALID_DRAFT_TFNS\n\t2021-06-23T15:30:00Z\n\t2021-06-23T15:30:00Z\n\tJane Doe\n\t\n\t\t8336532112\n\t\t8336532113\n\t\t8336532114\n\t\n\t9900572\n\t14020\n\t521434\n\t2021-06-16T18:51:42.161Z\n\t2021-06-16T19:51:06.244Z\n\tjgilmore\n\tjgilmore\n\tMyTestOrder\n\tfalse\n\tMANUAL_TOLLFREE\n\tCOMPLETE\n\tPHASE_1_TOLLFREE\n !scope internal\n \n\tTST52\n !scope internal\n \n\tJYT01\n\ttrue\n\tfalse\n" + "value": "\n\tVALID_DRAFT_TFNS\n\t2021-06-23T15:30:00Z\n\t2021-06-23T15:30:00Z\n\tJane Doe\n\t\n\t\t8336532112\n\t\t8336532113\n\t\t8336532114\n\t\n\t9900572\n\t14020\n\t521434\n\t2021-06-16T18:51:42.161Z\n\t2021-06-16T19:51:06.244Z\n\ttestuser\n\ttestuser\n\tMyTestOrder\n\tfalse\n\tMANUAL_TOLLFREE\n\tCOMPLETE\n\tPHASE_1_TOLLFREE\n !scope internal\n \n\tTST52\n !scope internal\n \n\tJYT01\n\ttrue\n\tfalse\n" }, "Toll Free INVALID_DRAFT_TFNS state, non-portable TNs": { - "value": "\n\tINVALID_DRAFT_TFNS\n\t2021-06-23T15:30:00Z\n\t2021-06-23T15:30:00Z\n\tJane Doe\n\t\n\t\t8336521001\n\t\t8336522001\n\t\n\t9900572\n\t14020\n\t521434\n\t2021-06-16T21:00:43.694Z\n\t2021-06-16T21:03:42.085Z\n\tjgilmore\n\tjgilmore\n\tMyTestOrder\n\tfalse\n\tMANUAL_TOLLFREE\n\tFAILED\n\t\n\t\t\n\t\t\t\n\t\t\t\t7642\n\t\t\t\tTN list contains at least one toll free number that cannot be ported due to spare status.\n\t\t\t\t\n\t\t\t\t\t8336521001\n\t\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\t7643\n\t\t\t\tTN list contains at least one toll free number that cannot be ported due to unavailable status.\n\t\t\t\t\n\t\t\t\t\t8336522001\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n\tPHASE_1_TOLLFREE\n" + "value": "\n\tINVALID_DRAFT_TFNS\n\t2021-06-23T15:30:00Z\n\t2021-06-23T15:30:00Z\n\tJane Doe\n\t\n\t\t8336521001\n\t\t8336522001\n\t\n\t9900572\n\t14020\n\t521434\n\t2021-06-16T21:00:43.694Z\n\t2021-06-16T21:03:42.085Z\n\ttestuser\n\ttestuser\n\tMyTestOrder\n\tfalse\n\tMANUAL_TOLLFREE\n\tFAILED\n\t\n\t\t\n\t\t\t\n\t\t\t\t7642\n\t\t\t\tTN list contains at least one toll free number that cannot be ported due to spare status.\n\t\t\t\t\n\t\t\t\t\t8336521001\n\t\t\t\t\n\t\t\t\n\t\t\t\n\t\t\t\t7643\n\t\t\t\tTN list contains at least one toll free number that cannot be ported due to unavailable status.\n\t\t\t\t\n\t\t\t\t\t8336522001\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n\tPHASE_1_TOLLFREE\n" }, "Toll Free INVALID_DRAFT_TFNS state, vendor error": { - "value": "\n\tINVALID_DRAFT_TFNS\n\t2021-06-23T15:30:00Z\n\t2021-06-23T15:30:00Z\n\tJane Doe\n\t\n\t\t8336000001\n\t\n\t9900572\n\t14020\n\t521434\n\t2021-06-16T21:00:43.694Z\n\t2021-06-16T21:03:42.085Z\n\tjgilmore\n\tjgilmore\n\tMyTestOrder\n\tfalse\n\tMANUAL_TOLLFREE\n\tFAILED\n\t\n\t\t\n\t\t\t\n\t\t\t\t7617\n\t\t\t\tBatch Number Query received vendor error: Service unavailable. If this condition persists, please contact Bandwidth for support.\n\t\t\t\t\n\t\t\t\t\t8336000001\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n\tPHASE_1_TOLLFREE\n" + "value": "\n\tINVALID_DRAFT_TFNS\n\t2021-06-23T15:30:00Z\n\t2021-06-23T15:30:00Z\n\tJane Doe\n\t\n\t\t8336000001\n\t\n\t9900572\n\t14020\n\t521434\n\t2021-06-16T21:00:43.694Z\n\t2021-06-16T21:03:42.085Z\n\ttestuser\n\ttestuser\n\tMyTestOrder\n\tfalse\n\tMANUAL_TOLLFREE\n\tFAILED\n\t\n\t\t\n\t\t\t\n\t\t\t\t7617\n\t\t\t\tBatch Number Query received vendor error: Service unavailable. If this condition persists, please contact Bandwidth for support.\n\t\t\t\t\n\t\t\t\t\t8336000001\n\t\t\t\t\n\t\t\t\n\t\t\n\t\n\tPHASE_1_TOLLFREE\n" } }, "schema": { @@ -10128,7 +10128,7 @@ "examples": { "example": { "description": "example", - "value": "\n\n SJM00002\n 2014-12-04T13:00:00.000Z\n 8045030092\n 9175131245\n \n 23453245\n 1111\n \n \n Protected\n External\n Imported\n \n \n RESIDENTIAL\n Steve\n McKinnon\n \n \n true \n 115\n Monarch Way\n Cary\n NC\n 27518\n \n \n 743\n true\n \n 2019721004\n 2019721005\n \n Steve McKinnon\n Foo\n\n" + "value": "\n\n SJM00002\n 2014-12-04T13:00:00.000Z\n 8045030092\n 9175131245\n \n 23453245\n 1111\n \n \n Protected\n External\n Imported\n \n \n RESIDENTIAL\n TestName\n TestLastName\n \n \n true \n 115\n Monarch Way\n Cary\n NC\n 27518\n \n \n 743\n true\n \n 2019721004\n 2019721005\n \n TestName TestLastName\n Foo\n\n" } }, "schema": { @@ -17626,19 +17626,19 @@ "examples": { "orderIsStillProcessing": { "summary": "Order is still processing", - "value": "\n\n \n \n MyOptionalOrderId\n PROCESSING\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n \n" + "value": "\n\n \n \n MyOptionalOrderId\n PROCESSING\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n \n" }, "orderIsCompleted": { "summary": "Order is completed", - "value": "\n\n \n \n MyOptionalOrderId\n COMPLETE\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n \n \n \n RespOrg1\n true\n \n 8442948899\n 8774024485\n \n \n \n \n \n \n \n" + "value": "\n\n \n \n MyOptionalOrderId\n COMPLETE\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n \n \n \n RespOrg1\n true\n \n 8442948899\n 8774024485\n \n \n \n \n \n \n \n" }, "orderIsFailed": { "summary": "Order is failed", - "value": "\n\n \n \n MyOptionalOrderId\n FAILED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n 8662894621\n 8773732047\n 8449978331\n 8003985992\n \n \n \n 7859\n Description for error 7859\n \n \n 9877\n Description for error 9877\n \n \n \n \n \n \n RespOrg1\n false\n \n 8662894621\n \n \n \n \n \n \n 8449978331\n \n \n 8003985992\n \n \n \n \n 8442948899\n \n \n 8774024485\n \n \n \n 8773732047\n 07\n NXX CLOSED\n \n \n \n \n \n \n" + "value": "\n\n \n \n MyOptionalOrderId\n FAILED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n 8662894621\n 8773732047\n 8449978331\n 8003985992\n \n \n \n 7859\n Description for error 7859\n \n \n 9877\n Description for error 9877\n \n \n \n \n \n \n RespOrg1\n false\n \n 8662894621\n \n \n \n \n \n \n 8449978331\n \n \n 8003985992\n \n \n \n \n 8442948899\n \n \n 8774024485\n \n \n \n 8773732047\n 07\n NXX CLOSED\n \n \n \n \n \n \n" }, "orderIsCanceled": { "summary": "Order is canceled", - "value": "\n\n \n \n MyOptionalOrderId\n CANCELLED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n \n" + "value": "\n\n \n \n MyOptionalOrderId\n CANCELLED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n \n" } }, "schema": { @@ -17701,19 +17701,19 @@ "examples": { "orderIsStillProcessing": { "summary": "Order is still processing", - "value": "\n\n \n MyOptionalOrderId\n PROCESSING\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" + "value": "\n\n \n MyOptionalOrderId\n PROCESSING\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" }, "orderIsCompleted": { "summary": "Order is completed", - "value": "\n\n \n MyOptionalOrderId\n COMPLETE\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n \n \n \n RespOrg1\n true\n \n 8442948899\n 8774024485\n \n \n \n \n \n \n" + "value": "\n\n \n MyOptionalOrderId\n COMPLETE\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n \n \n \n RespOrg1\n true\n \n 8442948899\n 8774024485\n \n \n \n \n \n \n" }, "orderIsFailed": { "summary": "Order is failed", - "value": "\n\n \n MyOptionalOrderId\n FAILED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n 8662894621\n 8773732047\n 8449978331\n 8003985992\n \n \n \n 7859\n Description for error 7859\n \n \n 9877\n Description for error 9877\n \n \n \n \n \n \n RespOrg1\n false\n \n 8662894621\n \n \n \n \n \n \n 8449978331\n \n \n 8003985992\n \n \n \n \n 8442948899\n \n \n 8774024485\n \n \n \n 8773732047\n 07\n NXX CLOSED\n \n \n \n \n \n" + "value": "\n\n \n MyOptionalOrderId\n FAILED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n 8662894621\n 8773732047\n 8449978331\n 8003985992\n \n \n \n 7859\n Description for error 7859\n \n \n 9877\n Description for error 9877\n \n \n \n \n \n \n RespOrg1\n false\n \n 8662894621\n \n \n \n \n \n \n 8449978331\n \n \n 8003985992\n \n \n \n \n 8442948899\n \n \n 8774024485\n \n \n \n 8773732047\n 07\n NXX CLOSED\n \n \n \n \n \n" }, "orderIsCanceled": { "summary": "Order is canceled", - "value": "\n\n \n MyOptionalOrderId\n CANCELLED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" + "value": "\n\n \n MyOptionalOrderId\n CANCELLED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" } }, "schema": { @@ -17729,7 +17729,7 @@ "examples": { "example": { "description": "example", - "value": "\n \n \n nnnn\n Description of condition nnnn\n \n \n nnnn\n Description of condition nnnn\n \n \n \n MyOptionalOrderId\n FAILED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" + "value": "\n \n \n nnnn\n Description of condition nnnn\n \n \n nnnn\n Description of condition nnnn\n \n \n \n MyOptionalOrderId\n FAILED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" } } } @@ -17766,7 +17766,7 @@ "examples": { "example": { "description": "example", - "value": "\n \n \n nnnn\n Description of condition nnnn\n \n \n nnnn\n Description of condition nnnn\n \n \n \n MyOptionalOrderId\n FAILED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" + "value": "\n \n \n nnnn\n Description of condition nnnn\n \n \n nnnn\n Description of condition nnnn\n \n \n \n MyOptionalOrderId\n FAILED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" } } } @@ -17779,7 +17779,7 @@ "examples": { "example": { "description": "example", - "value": "\n \n \n nnnn\n Description of condition nnnn\n \n \n nnnn\n Description of condition nnnn\n \n \n \n MyOptionalOrderId\n FAILED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" + "value": "\n \n \n nnnn\n Description of condition nnnn\n \n \n nnnn\n Description of condition nnnn\n \n \n \n MyOptionalOrderId\n FAILED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" } } } @@ -17818,19 +17818,19 @@ "examples": { "orderIsStillProcessing": { "summary": "Order is still processing", - "value": "\n\n \n MyOptionalOrderId\n PROCESSING\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" + "value": "\n\n \n MyOptionalOrderId\n PROCESSING\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" }, "orderIsCompleted": { "summary": "Order is completed", - "value": "\n\n \n MyOptionalOrderId\n COMPLETE\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n \n \n \n RespOrg1\n true\n \n 8442948899\n 8774024485\n \n \n \n \n \n \n" + "value": "\n\n \n MyOptionalOrderId\n COMPLETE\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n \n \n \n RespOrg1\n true\n \n 8442948899\n 8774024485\n \n \n \n \n \n \n" }, "orderIsFailed": { "summary": "Order is failed", - "value": "\n\n \n MyOptionalOrderId\n FAILED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n 8662894621\n 8773732047\n 8449978331\n 8003985992\n \n \n \n 7859\n Description for error 7859\n \n \n 9877\n Description for error 9877\n \n \n \n \n \n \n RespOrg1\n false\n \n 8662894621\n \n \n \n \n \n \n 8449978331\n \n \n 8003985992\n \n \n \n \n 8442948899\n \n \n 8774024485\n \n \n \n 8773732047\n 07\n NXX CLOSED\n \n \n \n \n \n" + "value": "\n\n \n MyOptionalOrderId\n FAILED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n 8662894621\n 8773732047\n 8449978331\n 8003985992\n \n \n \n 7859\n Description for error 7859\n \n \n 9877\n Description for error 9877\n \n \n \n \n \n \n RespOrg1\n false\n \n 8662894621\n \n \n \n \n \n \n 8449978331\n \n \n 8003985992\n \n \n \n \n 8442948899\n \n \n 8774024485\n \n \n \n 8773732047\n 07\n NXX CLOSED\n \n \n \n \n \n" }, "orderIsCanceled": { "summary": "Order is canceled", - "value": "\n\n \n MyOptionalOrderId\n CANCELLED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" + "value": "\n\n \n MyOptionalOrderId\n CANCELLED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" } }, "schema": { @@ -17893,7 +17893,7 @@ "examples": { "successPatchResponse": { "summary": "Success patch response", - "value": "\n\n \n MyOptionalOrderId\n CANCELLED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" + "value": "\n\n \n MyOptionalOrderId\n CANCELLED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" }, "failedPatchResponse": { "summary": "Failed patch response", @@ -17947,7 +17947,7 @@ "examples": { "example": { "description": "example", - "value": "\n \n \n nnnn\n Description of condition nnnn\n \n \n nnnn\n Description of condition nnnn\n \n \n \n MyOptionalOrderId\n FAILED\n 9900572\n jgilmore\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" + "value": "\n \n \n nnnn\n Description of condition nnnn\n \n \n nnnn\n Description of condition nnnn\n \n \n \n MyOptionalOrderId\n FAILED\n 9900572\n testuser\n 2020-08-20T14:51:58.695Z\n e2b029cf-1cfa-4285-a875-80e8fd951208\n \n 8442948899\n 8774024485\n \n \n" } } } From 525dab40032a8c7cd8a246928d5e88285cb13871 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Thu, 1 Sep 2022 14:22:21 +0300 Subject: [PATCH 18/20] Address PR comments --- site/docs/numbers/porting/portingNumbers.mdx | 6 +----- site/docs/numbers/porting/submitBulkportin.mdx | 5 ++--- site/docs/numbers/porting/updateBulkPortins.mdx | 6 +++--- site/docs/numbers/porting/updatePortin.mdx | 14 +++++++------- 4 files changed, 13 insertions(+), 18 deletions(-) diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index be590cdb6..29821246d 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -32,14 +32,10 @@ export const Highlight = ({children, color}) => ( ); -The Bandwidth Phone Number `/portins` API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. +The `/portins` API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. In order to successfully port telephone numbers they need to correspond to a set of criteria. To check them follow the [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) guide. -:::info -The `/bulkPortins` API eliminates the need for the `/lnpchecker` API by sorting the list of TNs automatically into a set of port-in requests by Port Type. For more details follow the [How to Bulk Port](/docs/numbers/guides/porting/createBulkPortins). -::: - ## Create a Port-in Order The API allows a user to create a new LNP order. An order id will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. diff --git a/site/docs/numbers/porting/submitBulkportin.mdx b/site/docs/numbers/porting/submitBulkportin.mdx index 96fa9d168..4384fc866 100644 --- a/site/docs/numbers/porting/submitBulkportin.mdx +++ b/site/docs/numbers/porting/submitBulkportin.mdx @@ -31,8 +31,7 @@ export const Highlight = ({children, color}) => ( On this step we assume that you have created your bulk port-in and added telephone numbers which you wanted to port into the Bandwidth Dashboard. If not, follow the [How to create Bulk Port in](/docs/numbers/guides/porting/createBulkPortins) guide. -These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc., making all reasonable attempts to treat the individual port-in requests in a uniform manner. The elements supplied in the bulk port-in payload are cascaded to the child port-in orders when possible. This is useful, for example, if you want all of the child orders to have the same CustomerOrderId, or RequestedFocDate. - +These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc. The bulk port-in and child port-in orders will remain in draft states until you submit them. You can submit all the port-ins together under the umbrella of the bulk port-in by changing bulk port-in status to ```IN_PROGRESS```. :::info @@ -42,7 +41,7 @@ If for any reason you want to work with individual port-ins you still can submit To trigger Bulk Port-in processing use the ```PATCH``` operation on the bulk port-in order to change the ```ProcessingStatus``` to ```IN_PROGRESS```. To do it you must send a PATCH request to our [API /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkPortin) endpoint. This can be done through tools like Postman or cURL. :::caution -Changing the ProcessingStatus to 'IN_PROGRESS' is only valid if child port-ins exist for the bulk port-in. Check [How to Provide telephone number(s) to port](/docs/numbers/guides/porting/createBulkPortins/#provide-telephone-numbers-to-port) guide. +Changing the ProcessingStatus to 'IN_PROGRESS' is only valid if child port-ins exist for the bulk port-in. Check [How to Provide Telephone Number(s) to Port](/docs/numbers/guides/porting/createBulkPortins/#provide-telephone-numbers-to-port) guide. ::: PATCH https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} diff --git a/site/docs/numbers/porting/updateBulkPortins.mdx b/site/docs/numbers/porting/updateBulkPortins.mdx index adb5e4966..4f2ee46ce 100644 --- a/site/docs/numbers/porting/updateBulkPortins.mdx +++ b/site/docs/numbers/porting/updateBulkPortins.mdx @@ -28,18 +28,18 @@ export const Highlight = ({children, color}) => ( ); -Follow this guide if you'd like to update or delete a Bulk Port-in order. +In this guide, you will learn how to update or delete a bulk port-in order. ## Update Bulk Port-in -It is possible to update Bulk Port-in order using ```PUT``` or ```PATCH``` request to ```/bulkPortins/{orderId} API``` on the existing order-id: +To update a bulk port-in order use ```PUT``` or ```PATCH``` request to ```/bulkPortins/{orderId} API``` on the existing order-id: * If Bulk Port-in is not in terminal (```COMPLETED```, ```CANCELLED```, or ```PARTIAL```) status * As with the ```POST```, any data associated with the bulk port-in will cascade to subtending orders when they are created * If the port-in orders contained within the Bulk Port are in ```DRAFT``` state, any field can be modified * If any child port-in order in the Bulk Port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller :::info -Subtending orders are created after tns are added to the bulk port-in using the /tnList endpoint, see the next section of this tutorial. +Subtending orders are created after telephone numbers are added to the bulk port-in using the /tnList endpoint, see the next section of this tutorial. ::: * The [```PUT``` /bulkPortins/{orderId}](/apis/numbers/#operation/PutBulkOrder) operation is available only for bulk port-in orders that are not yet associated with subtending orders diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx index 1fc1d2ca8..a913831b4 100644 --- a/site/docs/numbers/porting/updatePortin.mdx +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -34,7 +34,7 @@ export const Highlight = ({children, color}) => ( ); -In this guide we will show you how to manage your Port in order. We assume that you have [created Port in order](/docs/numbers/guides/porting/updatePortin). +In this guide we will show you how to update your port-in order. We assume that you have [created Port in order](/docs/numbers/guides/porting/updatePortin). ## Update Port-in Order @@ -83,11 +83,11 @@ Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= those which should be required remain required. Affect only supp. Default false. --> true - 115 - Monarch Way + 123 + Main Street Cary NC - 27518 + 54321 743 @@ -149,11 +149,11 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins/d28b3 those which should be required remain required. Affect only supp. Default false. --> true - 115 - Monarch Way + 123 + Main Street Cary NC - 27518 + 54321 743 From e7a42e301f707d843e8144fd7dd469dcd908a703 Mon Sep 17 00:00:00 2001 From: Paul Isaichuk Date: Fri, 2 Sep 2022 12:19:55 +0300 Subject: [PATCH 19/20] Address review comments --- site/docs/numbers/eventWebhook.md | 2 +- .../docs/numbers/porting/createBulkPortins.mdx | 14 +++++++------- site/docs/numbers/porting/lnpChecker.mdx | 4 ++-- site/docs/numbers/porting/loaUpload.mdx | 2 +- site/docs/numbers/porting/portingNumbers.mdx | 18 +++++++++--------- site/docs/numbers/porting/submitBulkportin.mdx | 10 +++++----- .../docs/numbers/porting/updateBulkPortins.mdx | 12 ++++++------ site/docs/numbers/porting/updatePortin.mdx | 12 ++++++------ 8 files changed, 37 insertions(+), 37 deletions(-) diff --git a/site/docs/numbers/eventWebhook.md b/site/docs/numbers/eventWebhook.md index 609d799db..69d479203 100644 --- a/site/docs/numbers/eventWebhook.md +++ b/site/docs/numbers/eventWebhook.md @@ -12,7 +12,7 @@ image: '@site/static/img/bw-icon.svg' The notification webhook API is used to notify customers of events and changes that occur with various feature and service orders that are being processed by the Bandwidth Numbers API on their behalf. In general this notification webhook will be called whenever an **event** occurs. -The event notifications occur when TNs in your account are impacted due to orders outside of your account. For example, a `MESSAGING_LOST` event is reported on a TN with hosted messaging service in your account when a port in order placed by another account on the same TN is executed. +The event notifications occur when TNs in your account are impacted due to orders outside of your account. For example, a `MESSAGING_LOST` event is reported on a TN with hosted messaging service in your account when a port-in order placed by another account on the same TN is executed. An order placed in your account to remove the TN will NOT report a `MESSAGING_LOST` event. Please see the subscription documentation to understand how to register the notification webhook API with the Bandwidth Numbers API. diff --git a/site/docs/numbers/porting/createBulkPortins.mdx b/site/docs/numbers/porting/createBulkPortins.mdx index eb449684f..522b9860a 100644 --- a/site/docs/numbers/porting/createBulkPortins.mdx +++ b/site/docs/numbers/porting/createBulkPortins.mdx @@ -33,7 +33,7 @@ export const Highlight = ({children, color}) => ( ## Create Bulk Port-in Draft -To create Bulk Port-in request order, you must make a POST request to our [API /bulkPortins](/apis/numbers/#operation/CreateBulkPortin) endpoint. This order is used to manage the porting event throughout the lifecycle of the request. This can be done through tools like Postman or cURL. Note the ```OrderId``` field in response. It will be used for the next steps. +To create bulk port-in request order, you must make a POST request to our [API /bulkPortins](/apis/numbers/#operation/CreateBulkPortin) endpoint. This order is used to manage the porting event throughout the lifecycle of the request. This can be done through tools like Postman or cURL. Note the ```OrderId``` field in response. It will be used for the next steps. :::info Only fields that you wish to use as defaults for all of the child port-in orders should be included in the bulk port-in order. @@ -128,12 +128,12 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/bulkPortins' -When a Bulk Port-in is created, it has ```DRAFT``` status, which means it has not been processed yet. -If you want to update your Bulk Port-in (either in ```DRAFT``` or other further state) follow the [How to update Bulk Port-in](/docs/numbers/guides/porting/updateBulkPortins) guide. +When a bulk port-in is created, it has ```DRAFT``` status, which means it has not been processed yet. +If you want to update your bulk port-in (either in ```DRAFT``` or other further state) follow the [How to Update Bulk Port-in](/docs/numbers/guides/porting/updateBulkPortins) guide. ## Provide telephone number(s) to port -After the Bulk Port-in is created, add telephone numbers to the order by sending a PUT request to our [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/UpdateBulkTnList) endpoint. This can be done through tools like Postman or cURL. +After the bulk port-in is created, add telephone numbers to the order by sending a PUT request to our [API /bulkPortins/{orderId}/tnList](/apis/numbers/#operation/UpdateBulkTnList) endpoint. This can be done through tools like Postman or cURL. PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId}/tnList :::caution -There are some cases that you won't be able to port in a TN: +There are some cases that you won't be able to port-in a TN: * The TN is in a rate center that is not supported by Bandwidth or any of Bandwidth's partners. * The TN is an off-net TN, and the account is configured to support tier zero (on-net) only. @@ -188,5 +188,5 @@ Otherwise, the user must separate the TNs into individual `/portins` requests. ## Where to next? Now that you have learned how to check the portability of a number, check out some of the other available actions in the following guides: -- [How to create a Port-In Request →](/docs/numbers/guides/porting/portingNumbers) +- [How to Create a Port-In Request →](/docs/numbers/guides/porting/portingNumbers) diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx index 8163c76f8..870152b19 100644 --- a/site/docs/numbers/porting/loaUpload.mdx +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -163,4 +163,4 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} ## Where to next? Now that you have learned how to upload a LOA file, check out some of the other available actions in the following guides: -- [How to manage Port in →](/docs/numbers/guides/porting/updatePortin) +- [How to Manage Port-in →](/docs/numbers/guides/porting/updatePortin) diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index 29821246d..b96419633 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -32,15 +32,15 @@ export const Highlight = ({children, color}) => ( ); -The `/portins` API is used to submit Port-In requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. +The `/portins` API is used to submit port-in requests. These requests to move phone numbers from a “losing carrier” to Bandwidth are part of the Local Number Portability (LNP) process. These LNP requests are automatically validated and processed. -In order to successfully port telephone numbers they need to correspond to a set of criteria. To check them follow the [How to check numbers portability](/docs/numbers/guides/porting/lnpChecker) guide. +In order to successfully port telephone numbers they need to correspond to a set of criteria. To check them follow the [How to Check Numbers Portability](/docs/numbers/guides/porting/lnpChecker) guide. ## Create a Port-in Order The API allows a user to create a new LNP order. An order id will be auto-generated and provided to the customer. The order must pass synchronous and asynchronous validation. Synchronous validation will return validation failures immediately in the response. If synchronous validation passes, but asynchronous validation fails, the customer will not receive the error response until they check the order status. -To create Port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done using tools like Postman or cURL. +To create port-in request, you must make a POST request to our [API /portins](/apis/numbers/#operation/CreatePortin) endpoint. This can be done using tools like Postman or cURL. ### Examples POST https://dashboard.bandwidth.com/api/accounts/{accountId}/portins @@ -186,7 +186,7 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ Porting numbers in the Bandwidth Dashboard is asynchronous which means the orders are processed and the order status is updated asynchronously. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. Please follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) guide. -To poll an information about your Port in you can still use a GET request to [accounts/{accountId}/portins API](/apis/numbers/#operation/GetPortin). This can be done using tools like Postman or cURL. +To poll an information about your port-in you can still use a GET request to [accounts/{accountId}/portins API](/apis/numbers/#operation/GetPortin). This can be done using tools like Postman or cURL. GET https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} ( ); -On this step we assume that you have created your bulk port-in and added telephone numbers which you wanted to port into the Bandwidth Dashboard. If not, follow the [How to create Bulk Port in](/docs/numbers/guides/porting/createBulkPortins) guide. +On this step we assume that you have created your bulk port-in and added telephone numbers which you wanted to port into the Bandwidth Dashboard. If not, follow the [How to create Bulk Port-in](/docs/numbers/guides/porting/createBulkPortins) guide. These telephone numbers will be decomposed into a set of individual port-in orders based on port-type, losing carrier, losing RespOrg, etc. The bulk port-in and child port-in orders will remain in draft states until you submit them. You can submit all the port-ins together under the umbrella of the bulk port-in by changing bulk port-in status to ```IN_PROGRESS```. @@ -38,7 +38,7 @@ The bulk port-in and child port-in orders will remain in draft states until you If for any reason you want to work with individual port-ins you still can submit them separately through ```PUT``` request to [/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin). Check [Update Port-in](/docs/numbers/guides/porting/updatePortin) guide to learn more. ::: -To trigger Bulk Port-in processing use the ```PATCH``` operation on the bulk port-in order to change the ```ProcessingStatus``` to ```IN_PROGRESS```. To do it you must send a PATCH request to our [API /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkPortin) endpoint. This can be done through tools like Postman or cURL. +To trigger bulk port-in processing use the ```PATCH``` operation on the bulk port-in order to change the ```ProcessingStatus``` to ```IN_PROGRESS```. To do it you must send a PATCH request to our [API /bulkPortins/{orderId}](/apis/numbers/#operation/PatchBulkPortin) endpoint. This can be done through tools like Postman or cURL. :::caution Changing the ProcessingStatus to 'IN_PROGRESS' is only valid if child port-ins exist for the bulk port-in. Check [How to Provide Telephone Number(s) to Port](/docs/numbers/guides/porting/createBulkPortins/#provide-telephone-numbers-to-port) guide. @@ -115,6 +115,6 @@ A bulk port-in order may have one of 3 terminal processing statuses: ```COMPLETE ## Where to next? -- [How to create Bulk Port-in ←](/docs/numbers/guides/porting/updateBulkPortins) -- [How to update Bulk Port-in →](/docs/numbers/guides/porting/updateBulkPortins) -- [How to manage Port in →](/docs/numbers/guides/porting/updatePortin) \ No newline at end of file +- [How to Create Bulk Port-in ←](/docs/numbers/guides/porting/updateBulkPortins) +- [How to Update Bulk Port-in →](/docs/numbers/guides/porting/updateBulkPortins) +- [How to Manage Port-in →](/docs/numbers/guides/porting/updatePortin) \ No newline at end of file diff --git a/site/docs/numbers/porting/updateBulkPortins.mdx b/site/docs/numbers/porting/updateBulkPortins.mdx index 4f2ee46ce..8b2a830f4 100644 --- a/site/docs/numbers/porting/updateBulkPortins.mdx +++ b/site/docs/numbers/porting/updateBulkPortins.mdx @@ -33,10 +33,10 @@ In this guide, you will learn how to update or delete a bulk port-in order. ## Update Bulk Port-in To update a bulk port-in order use ```PUT``` or ```PATCH``` request to ```/bulkPortins/{orderId} API``` on the existing order-id: -* If Bulk Port-in is not in terminal (```COMPLETED```, ```CANCELLED```, or ```PARTIAL```) status +* If bulk port-in is not in terminal (```COMPLETED```, ```CANCELLED```, or ```PARTIAL```) status * As with the ```POST```, any data associated with the bulk port-in will cascade to subtending orders when they are created * If the port-in orders contained within the Bulk Port are in ```DRAFT``` state, any field can be modified -* If any child port-in order in the Bulk Port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller +* If any child port-in order in the bulk port-in is in any other state, normal SUPP rules apply, and the list of appropriate fields is smaller :::info Subtending orders are created after telephone numbers are added to the bulk port-in using the /tnList endpoint, see the next section of this tutorial. @@ -118,7 +118,7 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orde -Note that ```PUT``` completely replaces the existing Bulk Port-in order with the given payload while ```PATCH``` replaces only the elements included in the request payload. +Note that ```PUT``` completely replaces the existing bulk port-in order with the given payload while ```PATCH``` replaces only the elements included in the request payload. PATCH https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} @@ -185,7 +185,7 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orde ## Delete Bulk Port-in -You can delete a Bulk Port-in order with child port-ins. Deleting a bulk port-in is allowed for ```DRAFT``` state only. Deleting a bulk port-in will delete all ```DRAFT``` child port-ins associated with the bulk port-in. When the bulk port-in is deleted, any child port-in orders that are not in a ```DRAFT``` status are dissociated from the bulk port-in, but not deleted. +You can delete a bulk port-in order with child port-ins. Deleting a bulk port-in is allowed for ```DRAFT``` state only. Deleting a bulk port-in will delete all ```DRAFT``` child port-ins associated with the bulk port-in. When the bulk port-in is deleted, any child port-in orders that are not in a ```DRAFT``` status are dissociated from the bulk port-in, but not deleted. ### Examples DELETE https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} @@ -216,5 +216,5 @@ HTTP 200 OK ## Where to next? -- [How to create Bulk Port-in ←](/docs/numbers/guides/porting/createBulkPortins) -- [How to submit Bulk Port-in →](/docs/numbers/guides/porting/submitBulkPortins) \ No newline at end of file +- [How to Create Bulk Port-in ←](/docs/numbers/guides/porting/createBulkPortins) +- [How to Submit Bulk Port-in →](/docs/numbers/guides/porting/submitBulkPortins) \ No newline at end of file diff --git a/site/docs/numbers/porting/updatePortin.mdx b/site/docs/numbers/porting/updatePortin.mdx index a913831b4..e9c3fbfb6 100644 --- a/site/docs/numbers/porting/updatePortin.mdx +++ b/site/docs/numbers/porting/updatePortin.mdx @@ -34,7 +34,7 @@ export const Highlight = ({children, color}) => ( ); -In this guide we will show you how to update your port-in order. We assume that you have [created Port in order](/docs/numbers/guides/porting/updatePortin). +In this guide we will show you how to update your port-in order. We assume that you have [created port-in order](/docs/numbers/guides/porting/updatePortin). ## Update Port-in Order @@ -43,10 +43,10 @@ The PUT to [/portins/{orderId} API](/apis/numbers/#oper If the order ProcessingStatus is `DRAFT`, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from `DRAFT` to `SUBMITTED`. The AltSpid element can be modified if it is not configured at the system level. Regarding the fields which can be updated for different port types check the request schema section of [PUT /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) specification. -The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by Port-In Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. +The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by port-in Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint. ### Examples -To update Port-in request, you must make a PUT request to our [API /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) endpoint. This can be done using tools like Postman or cURL. +To update port-in request, you must make a PUT request to our [API /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) endpoint. This can be done using tools like Postman or cURL. PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} Date: Mon, 5 Sep 2022 12:43:35 +0300 Subject: [PATCH 20/20] Address review comments --- site/docs/numbers/porting/loaUpload.mdx | 2 +- site/docs/numbers/porting/portingNumbers.mdx | 2 +- site/docs/numbers/porting/updateBulkPortins.mdx | 2 +- site/docs/numbers/porting/updatePortin.mdx | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/site/docs/numbers/porting/loaUpload.mdx b/site/docs/numbers/porting/loaUpload.mdx index 870152b19..4cc076d4b 100644 --- a/site/docs/numbers/porting/loaUpload.mdx +++ b/site/docs/numbers/porting/loaUpload.mdx @@ -39,7 +39,7 @@ export const Highlight = ({children, color}) => ( ); -After successfully submitting the [Create LNP Order request](/docs/numbers/guides/porting/portingNumbers), an Letter of Authorization (LOA) may be uploaded using our LOA API. +After successfully submitting the [Create LNP Order request](/docs/numbers/guides/porting/portingNumbers), a Letter of Authorization (LOA) may be uploaded using our LOA API. :::caution If your port-on order has a ```PENDING_DOCUMENTS``` status then LOA upload is a required action. diff --git a/site/docs/numbers/porting/portingNumbers.mdx b/site/docs/numbers/porting/portingNumbers.mdx index b96419633..3297a1711 100644 --- a/site/docs/numbers/porting/portingNumbers.mdx +++ b/site/docs/numbers/porting/portingNumbers.mdx @@ -186,7 +186,7 @@ curl 'https://dashboard.bandwidth.com/api/accounts/{BW_ACCOUNT_ID}/portins' \ Porting numbers in the Bandwidth Dashboard is asynchronous which means the orders are processed and the order status is updated asynchronously. As times can vary and are not guaranteed Bandwidth recommends configuring your account with a subscription instead of polling the order resource for ``. Please follow the [How to setup Notification Webhook](/docs/numbers/webhooks/orderWebhook) guide. -To poll an information about your port-in you can still use a GET request to [accounts/{accountId}/portins API](/apis/numbers/#operation/GetPortin). This can be done using tools like Postman or cURL. +To poll for information about your port-in you can still use a GET request to [accounts/{accountId}/portins API](/apis/numbers/#operation/GetPortin). This can be done using tools like Postman or cURL. GET https://dashboard.bandwidth.com/api/accounts/{accountId}/portins/{orderId} PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/bulkPortins/{orderId} PUT to [/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin) API allows a user to modify an existing LNP order, by sending a so-called SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the ```PUT``` on a porting order-id does not require that the full order payload is included. +The PUT to [/portins/{orderId} API](/apis/numbers/#operation/UpdatePortin) API allows a user to modify an existing LNP order, by sending a SUPP request. Modifications are only allowed for orders that are not yet `complete` or `cancelled`. Since many of the entries in an LNP Order cannot be changed after the initial order is placed, the ```PUT``` on a porting order-id does not require that the full order payload is included. -If the order ProcessingStatus is `DRAFT`, the rules about what can be changed are much more relaxed. Validation is performed when the ProcessingStatus is changed from `DRAFT` to `SUBMITTED`. The AltSpid element can be modified if it is not configured at the system level. +If the order ProcessingStatus is `DRAFT`, the rules about what can be changed are much more lenient. Validation is performed when the ProcessingStatus is changed from `DRAFT` to `SUBMITTED`. The AltSpid element can be modified if it is not configured at the system level. Regarding the fields which can be updated for different port types check the request schema section of [PUT /portins/{orderId}](/apis/numbers/#operation/UpdatePortin) specification. The general approach to handling this API call is to replace the elements included in the request body, and leave other preexisting elements in an unmodified condition. This is typical of a PATCH method, but because of our commitment to backwards compatibility we have elected not to "Fix" this behavior. As a result, there are some elements that cannot be modified using the PUT method. The elements affected vary by port-in Order type, which can be determined using a GET request to the `/portins/{orderId}` endpoint.