Skip to main content

Upgrading from Legacy Global API

This guide is designed for developers and coding agents who are familiar with the Legacy Global APIs (formerly Voxbone) and need to migrate to Bandwidth's Universal Platform (UP). Here, you'll find a walkthrough of every major change, with side-by-side code comparisons for each API area.

For a quick conceptual overview, see the Universal Platform Getting Started guide.

Important Note

The Universal Platform API cannot be used to manage numbers and service configuration in the Legacy Global platform (formerly Voxbone).

It is intended for managing and configuring numbers purchased or moved to your new Universal Platform account provided during the account onboarding process.

The tools to move Legacy Global Platform numbers to the Universal Platform are available for upgrading customers. Please contact your account representative to start this process.

Before you start​

Before writing any code, you need:

  1. A Universal Platform account: If you don't have one yet, contact your account representative to start the upgrade process.
  2. New API credentials: Your Legacy Global API key will not work on the Universal Platform. Create new credentials under your UP account via the Bandwidth App (Account > API Credentials). You will see references to the Universal Platform supporting both HTTP Basic and OAuth 2.0 Bearer token authentication. It is highly recommended that you start by using OAuth2.0 as Basic Auth is deprecated. See the Credentials documentation.
  3. Understanding of the account hierarchy: The Universal Platform uses a hierarchical account model (Account > Sub-account > Location) rather than the flat model in Legacy Global. See Account Structure.
  4. API changeover plan: For small accounts with relatively few numbers it may make sense to move numbers to your new UP account at the same time as changing over the API that is used. For larger accounts, we recommend implementing UP API integration alongside your existing Legacy Global API setup, to allow for numbers to be moved to the new UP account in smaller batches.

Overview of API changes​

Legacy Global APIUniversal Platform API
Base URLhttps://api.voxbone.com/v1https://api.bandwidth.com/api/v2
AuthenticationAPI key (apikey header)OAuth 2.0 Bearer token
Content typeJSONXML (core number APIs), JSON (newer APIs)
Phone number formatE.164E.164
Account modelFlatAccount > Sub-account (Site) > Location (SipPeer)
Number orderingCart > Add items > CheckoutSearch available number > Order number
ProcessingSynchronousAsynchronous (order tracking with polling or webhooks)
Voice routingVoice URIVoice Configuration Package (VCP)
SMS routingSMS Link / SMS Link GroupApplication + Location config
ComplianceRegulation AddressRequirements Package (Address + End User + Documents)

Authentication​

The Legacy Global API uses an API key passed as a header. The Universal Platform supports HTTP Basic authentication and OAuth 2.0 Bearer tokens. OAuth 2.0 is recommended.

See the Credentials documentation for setup instructions.

Authenticating a request​

Step 1: Get a Bearer token using account credentials (clientId,clientSecret).

POST /api/v1/oauth2/token
Host: api.bandwidth.com
Authorization: Basic base64(clientId:clientSecret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Response:

{
  "access_token": "eyJraWQiOi...",
  "access_token_id": "a5xA3xMKEggGwvpSLtk2lRb",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 2: Use the token in subsequent requests

GET /api/v2/accounts/{accountId}/orders
Host: api.bandwidth.com
Authorization: Bearer eyJraWQiOi...

Account structure​

In the Legacy Global API, your account is a flat structure — numbers, voice URIs, SMS links, and capacity groups all exist at the top level.

The Universal Platform uses a hierarchical model:

  • Account — top level, created by Bandwidth support
  • Sub-account (API name: Site) — an organizational grouping for numbers
  • Location (API name: SipPeer) — the lowest level where numbers are assigned; holds messaging configuration

This hierarchy affects how you organize numbers, assign voice configuration, and configure messaging. See Account Structure.

Number search and inventory​

What changed:

  • Both systems allow number inventory searches based on country, area code, and number type. Results are presented in "didGroups" for the Legacy Global API, and directly as a list of numbers for the Universal Platform.
  • On the Universal Platform there is no didGroupId intermediary — you search and order numbers directly.
  • When using the Universal Platform API more details can be retrieved using the enableTNDetail parameter.
  • Note: For operational reasons, the inventory lists held in each platform are not expected to be the same, so similar searches will not return the same results.

See the Number Ordering guide.

Search available numbers​

GET /api/v2/accounts/{accountId}/availableNumbers?countryCodeA3=USA&phoneNumberType=GEOGRAPHIC&areaCode=212&quantity=2
Host: api.bandwidth.com
Authorization: Bearer {token}
Accept: application/json

Response:

{
  "resultCount": 2,
  "phoneNumbers": [
    "+12125551234",
    "+12125551235"
  ]
}

Number ordering​

What changed:

  • The Legacy Global API uses a cart model: create a cart, add products, then checkout. The Universal Platform submits orders directly — no cart step.
  • Orders on the Universal Platform are asynchronous. You receive an order ID and poll for completion, or subscribe to webhooks for status updates.
  • The Universal Platform does not have a concept of credit packages or account balance APIs.

See the Number Ordering guide.

Submit an order directly:

POST /api/v2/accounts/{accountId}/orders
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "backOrderRequested": false,
  "customerOrderId": "123456789",
  "orderType": {
    "areaCode": "617",
    "city": "RALEIGH",
    "enableLCA": false,
    "lata": "224",
    "quantity": 1,
    "rateCenter": "RALEIGH",
    "state": "NC",
    "type": "combinedSearchAndOrderType",
    "zip": "27606"
  },
  "partialAllowed": false,
  "subAccountId": 743,
  "tags": [
    {
      "tagName": "customerId",
      "tagValue": "11111111-1111-1111-1111-111111111111"
    }
  ],
  "requirementsPackageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "voiceConfigurationPackageId": "d21315af-9b5b-4b45-a6f4-9106cbfe87d1",
  "voiceIntegrationIds": [
    "5fa85f64-5717-4562-b3fc-2c963f66afa6",
    "5fa85f64-5717-4562-b3fc-2c963f66afa7"
  ]
}

Response:

{
  "order": {
    "autoActivate": true,
    "backOrderRequested": false,
    "id": "d79121c4-e4af-4569-ae07-b7f51587c952",
    "orderCreateDate": "2025-05-06T17:58:29.964Z",
    "orderType": {
      "enableLCA": true,
      "quantity": 1,
      "rateCenter": "RALEIGH",
      "state": "NC",
      "type": "combinedSearchAndOrderType"
    },
    "partialAllowed": true,
    "subAccountId": 491,
    "voiceIntegrationIds": [
      "5fa85f64-5717-4562-b3fc-2c963f66afa6",
      "5fa85f64-5717-4562-b3fc-2c963f66afa7"
    ],
    "bulkNumberSyncId": "d21315af-9b5b-4b45-a6f4-9106cbfe87d1",
    "tags": [
      {
        "tagName": "customerId",
        "tagValue": "11111111-1111-1111-1111-111111111111"
      }
    ]
  },
  "orderStatus": "RECEIVED"
}

Check order status​

GET /api/v2/accounts/{accountId}/orders/{orderId}
Host: api.bandwidth.com
Authorization: Bearer {token}
Accept: application/json

Response:

{
  "orderStatus": "COMPLETE",
  "completedQuantity": 2,
  "completedPhoneNumbers": [
    "+12125551234",
    "+12125551235"
  ],
  "failedQuantity": 0,
  "customerOrderId": "order-2024-001",
  "orderCompleteDate": "2024-01-15T10:30:05Z",
  "order": {
    "autoActivate": true,
    "backOrderRequested": false,
    "id": "d79121c4-e4af-4569-ae07-b7f51587c952",
    "orderCreateDate": "2025-05-06T17:58:29.964Z",
    "orderType": {
      "enableLCA": true,
      "quantity": 1,
      "rateCenter": "RALEIGH",
      "state": "NC",
      "type": "combinedSearchAndOrderType"
    },
    "partialAllowed": true,
    "subAccountId": 491,
    "voiceIntegrationIds": [
      "5fa85f64-5717-4562-b3fc-2c963f66afa6",
      "5fa85f64-5717-4562-b3fc-2c963f66afa7"
    ],
    "bulkNumberSyncId": "d21315af-9b5b-4b45-a6f4-9106cbfe87d1",
    "tags": [
      {
        "tagName": "customerId",
        "tagValue": "11111111-1111-1111-1111-111111111111"
      }
    ]
  }
}

List numbers in account​

What changed:

  • The Legacy Global API uses similar endpoint paths to list numbers in your account or find available numbers (/inventory/did and /inventory/didgroup). In the Universal Platform, the endpoints have distinct paths (/tns and /availableNumbers).
  • In the Universal Platform, some extra search query parameters are available for North American Numbering Plan phone numbers that are not available for other countries, including lata and ratecenter.

See the Search your Numbers guide.

GET /api/v2/tns?countryCodeA3=USA&phoneNumberType=GEOGRAPHIC&page=1&size=100
Host: api.bandwidth.com
Authorization: Bearer {token}
Accept: application/json

Response:

{
  "links": {
    "first": "Link=<https://api.bandwidth.com:443/api/v2/tns?page=1&size=2>;rel=\"first\";",
    "next": "Link=<https://api.bandwidth.com:443/api/v2/tns?page=%2B390541605183&size=2>;rel=\"next\";"
  },
  "phoneNumberCount": 2,
  "phoneNumbers": [
    {
      "accountId": 101,
      "city": "JERSEY CITY",
      "countryCodeA3": "USA",
      "isHostedVoice": false,
      "isOnNetVendor": true,
      "lastModified": "2019-01-02T20:00:42.000Z",
      "lata": 224,
      "phoneNumber": "+12015550123",
      "phoneNumberType": "GEOGRAPHIC",
      "rateCenter": "JERSEYCITY",
      "state": "NJ",
      "status": "Inservice",
      "tier": 0,
      "vendorId": 49,
      "vendorName": "Bandwidth CLEC"
    },
    {
      "accountId": 101,
      "city": "JERSEY CITY",
      "countryCodeA3": "USA",
      "isHostedVoice": false,
      "isOnNetVendor": true,
      "lastModified": "2019-01-02T20:00:42.000Z",
      "lata": 224,
      "phoneNumber": "+12015550124",
      "phoneNumberType": "GEOGRAPHIC",
      "rateCenter": "JERSEYCITY",
      "state": "NJ",
      "status": "Inservice",
      "tier": 0,
      "vendorId": 49,
      "vendorName": "Bandwidth CLEC"
    }
  ]
}

Voice configuration​

What changed:

  • The Legacy Global Voice URI is replaced by Voice Configuration Packages (VCPs) on the Universal Platform, which bundle voice routing with additional features like CNAM, STIR/SHAKEN, and HTTP Voice settings.
  • Legacy Global assigns a Voice URI to individual DIDs via didConfiguration. The Universal Platform assigns phone numbers to a VCP in bulk.
  • The Legacy Global concept of trunks is absorbed into VCPs and account-level SIP configuration on the Universal Platform. Assigning numbers to a 'Capacity Group' is not a feature in the Universal Platform.

See the Voice Configuration Package guide.

Get voice configuration details​

Retrieve Voice Configuration Packages:

GET /v2/accounts/{accountId}/voiceConfigurationPackages
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

Response:

{
  "links": [...],
  "data": [
    {
      "voiceConfigurationPackageId": "53638c12-7831-470a-af2f-c755389cf635",
      "accountId": 123456,
      "name": "Voice Configuration Package Name",
      "description": "Voice Configuration Package Description",
      "cnam": {
        "enabled": true
      },
      "pindropIntegration": {
        "enabled": false
      },
      "callVerification": {
        "enabled": false
      },
      "originationRoutePlan": {
        "routes": [
          {
            "priority": 1,
            "name": "Route Name",
            "endpoints": [
              {
                "endpoint": "+12345678910",
                "type": "TN",
                "weight": 20,
                "trunkInfo": {
                  "trunkId": "66059341226405797b14d4c1",
                  "capabilityPipeId": "201954af-e0ef-494b-bf26-541a4e99904a"
                }
              },
              {
                "endpoint": "+12345670000",
                "type": "TN",
                "weight": 20
              }
            ]
          }
        ]
      },
      "stirShakenBehavior": {
        "verstat": "BASIC",
        "identity": true
      },
      "httpVoiceV2ApplicationId": null,
      "analyticEngine": "FIRST_ORION"
    }
  ],
  "errors": [],
  "page": {
    "pageSize": 25,
    "totalElements": 100,
    "totalPages": 4,
    "pageNumber": 0
  }
}

Create voice routing​

Create a Voice Configuration Package:

POST /v2/accounts/{accountId}/voiceConfigurationPackages
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Primary SIP Endpoint",
  "description": "Main voice routing package",
  "originationRoutePlan": {
    "routes": [
      {
        "priority": 1,
        "name": "primary route",
        "endpoints": [
          {
            "endpoint": "+sip:inbound@your-pbx.example.com",
            "type": "SIP",
            "weight": 20
          }
        ]
      }
    ]
  },
}

Response:

{
  "id": "a1b2c3d4-5678-9012-abcd-ef1234567890",
  "name": "Primary SIP Endpoint",
  "description": "Main voice routing package",
  "originationRoutePlan": {
    "routes": [
      {
        "priority": 1,
        "name": "primary route",
        "endpoints": [
          {
            "endpoint": "+sip:inbound@your-pbx.example.com",
            "type": "SIP",
            "weight": 20.
            ...
          }
        ]
      }
    ]
  }
}

Assign voice config to numbers​

Bulk assign numbers to a VCP:

POST /v2/accounts/{accountId}/voiceConfigurationPackages/{vcpId}/phoneNumbers/bulk
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "action": "ADD",
  "phoneNumbers": ["+12125551234", "+12125551235"]
}

Response: 204 No Content (success) or 200 with partial errors.

Emergency Services Endpoint Provisioning​

What changed:

SMS and messaging configuration​

What changed:

  • The Legacy Global platform no longer offers SMS messaging. Previously this used SMS Links (protocol-level connections: SMPP, SIP, REST, SMTP) grouped into SMS Link Groups, then assigned to DIDs.
  • The Universal Platform uses Applications with HTTP webhook callbacks, configured at the Location (SipPeer) level. Numbers inherit messaging config from their Location.
  • Note the use of a different endpoint for sending messages (messaging.bandwidth.com).

See the Messaging documentation and the Applications guide.

Regulatory compliance and service activation​

What changed:

  • The Legacy Global Regulation Address concept is replaced by Requirements Packages on the Universal Platform, which are composable: an Address, End User details, and Documents (if required).
  • The Universal Platform supports country-specific address field discovery via /addresses/fields/{countryCodeA3}, so you can dynamically build address forms.
  • Linking numbers to the Requirements package is a separate step on the Universal Platform to providing the required regulatory data. Once all necessary information is provided phone numbers already on the account will need to have the appropriate service activated.
  • Terminology: Legacy Global "LAR" (Local Address Requirements) becomes "Requirements Package".

See the Requirements Package documentation, Address creation guide, and Service Activation guide.

Retrieve an existing address​

Retrieving a specific address using the associated Id is straightforward.

GET /api/v2/accounts/{accountId}/addresses/{addressId}
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

Response:

{
  "links": [...],
  "data": {
    "address": {
      "customReference": "home_office",
      "countryCodeA3": "USA",
      "addressLine1": "123 Main St",
      "addressLine2": "Suite 200",
      "city": "Seattle",
      "stateAbbreviation": "WA",
      "postalCode": "98104",
      "geoValidationStatus": "GEO_VALID",
      "addressId": "daa9dd0f-de97-4103-8530-b31bf4be8fc0",
      "createdDateTime": "2024-03-11T04:09:25.399Z",
      "updatedDateTime": "2024-03-11T04:09:25.399Z"
    }
  },
  "errors": [
    {
      "id": "optional-error-id",
      "type": "REQUEST_ERROR",
      "description": "There was an issue with a field in your request body",
      "code": 51130,
      "meta": {},
      "source": {
        "parameter": "someParameter",
        "field": "someField",
        "header": "someHeader",
        "reference": "/some/reference"
      }
    }
  ]
}

Create an address​

Step 1 (optional): Discover required address fields for the country

GET /api/v2/addresses/fields/USA
Host: api.bandwidth.com
Authorization: Bearer {token}

Before creating an address you can also pre-validate that the proposed values meet the pre-requisites for the country and feature intended for use.

Step 2: Create the address

POST /api/v2/accounts/{accountId}/addresses
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "countryCodeA3": "USA",
  "city": "New York",
  "postalCode": "10001",
  "stateAbbreviation": "NY",
  "addressLine1": "123 Main Street",
  "addressLine2": "Suite 200",
  "customReference": "office-nyc"
}

Response:

{
  "id": "addr-abc123",
  "countryCodeA3": "USA",
  "city": "New York",
  "postalCode": "10001",
  "stateCode": "NY",
  "houseNumber": "123",
  "streetName": "Main Street"
}

On the Universal Platform, you build a Requirements Package (Address + End User + Documents), then assign numbers to the package.

Step 1: Create a Requirements Package

Combine the address ID, end user details, and any required documents into a requirements package. For full details see this guide.

Step 2: Attach numbers to a Requirements Package

POST /api/v2/accounts/{accountId}/compliance/requirementsPackages/{requirementsPackageId}/bulk
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "phoneNumbers": ["+12125551234"],
  "action": "add",
  "allDetailsAccurate": true
}

See the Create a Requirements Package guide. If necessary service must be activated on the number once the regulatory requirements are met, see the Service Activation guide.

CDRs and call insights​

What changed:

  • The Legacy Global CDR API (/v2/cdr/calls) is replaced by the Insights API on the Universal Platform.
  • Note there is a different base URL than other UP APIs (insight.bandwidth.com/api).
  • The Universal Platform also offers downloadable reports for bulk CDR export.

Query call records​

GET /api/v1/voice/calls?accountId={accountId}&startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z&limit=100
Host: insights.bandwidth.com
Authorization: Bearer {token}

Response:

{
  "calls": [
    {
      "callId": "1234567890abcdef",
      "accountId": "1234567",
      "startTime": "2024-01-15T10:30:00Z",
      "endTime": "2024-01-15T10:32:00Z",
      "duration": 120000,
      "callingNumber": "+18005551234",
      "calledNumber": "+12125551234",
      "callDirection": "INBOUND",
      "callType": "VOICE",
      "cost": 0.005
    }
  ]
}

Key field differences:

Legacy GlobalUniversal Platform
e164callingNumber / calledNumber
eventType (IN_VOICE_END)callDirection (INBOUND)
callType (VOXDID)callType (VOICE)
duration (seconds)duration (milliseconds)

Porting​

What changed:

  • The Legacy Global porting API (/v3/porting/*) is replaced by the Bulk Port-Ins API on the Universal Platform.
  • Legacy Global combines portability check + order creation into a single flow; Universal Platform separates these into discrete steps.
  • The Universal Platform has a richer porting workflow: create draft → add TNs → validate → upload LOA → submit.
  • Universal Platform porting supports both XML and JSON.

See the Porting overview.

Port-in workflow overview​

The Universal Platform bulk port-in follows a multi-step workflow:

  1. Create a bulk port-in order (status: DRAFT)
  2. Add phone numbers to the order (status: VALIDATE_DRAFT_TNS → VALID_DRAFT_TNS)
  3. Upload LOA document
  4. Submit the order via PATCH (status: IN_PROGRESS)

Processing statuses: DRAFT → VALIDATE_DRAFT_TNS → VALID_DRAFT_TNS → IN_PROGRESS → COMPLETED

If validation fails, the status moves to INVALID_DRAFT_TNS and you can retrieve the TN list to see which numbers are non-portable.

Step 1: Create the port-in order​

POST /api/v2/accounts/{accountId}/bulkPortins
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "customerOrderId": "PORT-001",
  "requestedFocDate": "2024-03-10",
  "subscriber": {
    "subscriberType": "BUSINESS",
    "businessName": "Acme Corp",
    "serviceAddress": {
      "streetName": "Rue Vanderkindere",
      "houseNumber": "489",
      "city": "Brussels",
      "country": "BEL",
      "zip": "1050"
    }
  }
}

Response:

{
  "orderId": "a1b2c3d4-5678-9012-abcd-ef1234567890",
  "customerOrderId": "PORT-001",
  "processingStatus": "DRAFT",
  "requestedFocDate": "2024-03-10T00:00:00Z",
  "accountId": "{accountId}"
}

Step 2: Add phone numbers and validate​

On Legacy Global, phone numbers are included in the order creation request. On the Universal Platform, you add them separately and the system validates portability automatically.

Add phone numbers (triggers automatic validation):

PUT /api/v2/accounts/{accountId}/bulkPortins/{orderId}/tnList
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "phoneNumbers": ["+3228090001", "+3228090002"]
}

Poll the order until status reaches VALID_DRAFT_TNS or INVALID_DRAFT_TNS:

GET /api/v2/accounts/{accountId}/bulkPortins/{orderId}
Host: api.bandwidth.com
Authorization: Bearer {token}
Accept: application/json

Response:

{
  "orderId": "a1b2c3d4-5678-9012-abcd-ef1234567890",
  "processingStatus": "VALID_DRAFT_TNS",
  "customerOrderId": "PORT-001"
}

If INVALID_DRAFT_TNS, retrieve the TN list to see which numbers failed:

GET /api/v2/accounts/{accountId}/bulkPortins/{orderId}/tnList
Host: api.bandwidth.com
Authorization: Bearer {token}
Accept: application/json

Step 3: Upload LOA document​

On Legacy Global, LOA documents are managed separately. On the Universal Platform, they are attached directly to the bulk port-in order.

Upload the LOA as a binary file. The request is the same regardless of your XML/JSON preference — document uploads always use the file's native content type.

POST /api/v2/accounts/{accountId}/bulkPortins/{orderId}/loas?documentType=LOA
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/pdf

[PDF binary content]

Supported document types: LOA, INVOICE, CSR, OTHER

List uploaded documents:

GET /api/v2/accounts/{accountId}/bulkPortins/{orderId}/loas
Host: api.bandwidth.com
Authorization: Bearer {token}
Accept: application/json

Step 4: Submit the port-in order​

On Legacy Global, the order is submitted at creation time. On the Universal Platform, you explicitly submit the draft order by PATCHing the processingStatus to IN_PROGRESS.

PATCH /api/v2/accounts/{accountId}/bulkPortins/{orderId}
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "processingStatus": "IN_PROGRESS"
}

Response:

{
  "orderId": "a1b2c3d4-5678-9012-abcd-ef1234567890",
  "processingStatus": "IN_PROGRESS",
  "customerOrderId": "PORT-001",
  "requestedFocDate": "2024-03-10T00:00:00Z"
  ...
}

You can also update other fields in the same PATCH request (e.g., requestedFocDate, customerOrderId). Only fields included in the PATCH payload are modified.

Port-out monitoring​

The Legacy Global API does not expose port-out endpoints — port-outs are handled by the losing carrier. The Universal Platform provides read-only endpoints to monitor port-out requests against your numbers.

List port-out requests:

GET /api/v2/accounts/{accountId}/portouts?status=complete&page=1&size=25
Host: api.bandwidth.com
Authorization: Bearer {token}

Get details for a specific port-out:

GET /api/v2/accounts/{accountId}/portouts/{orderId}
Host: api.bandwidth.com
Authorization: Bearer {token}

Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<LnpOrderResponse>
    <RequestedFocDate>2014-08-02T12:34:37Z</RequestedFocDate>
    <ActualFocDate>2014-08-02T12:34:37Z</ActualFocDate>
    <PON>8a89dea8-a145-4796-8e73-0d859fc74cad</PON>
    <AccountId>20</AccountId>
    <OrderCreateDate>2014-07-31T16:34:37.480Z</OrderCreateDate>
    <LastModifiedDate>2014-07-31T16:34:37.530Z</LastModifiedDate>
    <userId>System</userId>
    <PortOutStatus>NEW</PortOutStatus>
    <SPID>512E</SPID>
</LnpOrderResponse>
tip

Subscribe to port-out notifications using the Subscriptions API to receive real-time webhooks when port-out requests are filed against your numbers, rather than polling the portouts endpoint.

Subscriptions and webhooks​

What changed:

  • Legacy Global subscriptions are scoped by product (GLOBAL) and eventType (ORDER_COMPLETED, etc.).
  • Universal Platform subscriptions are scoped by subscriptionDefinitionName (e.g., Package_Update) and support filters.
  • The Universal Platform also supports email delivery in addition to webhooks.

See the Subscriptions documentation and the Webhooks guide.

Create a webhook subscription​

POST /v2/subscriptions
Host: api.bandwidth.com
Authorization: Bearer {token}
Content-Type: application/json

{
  "accountId": "{accountId}",
  "customName": "Order Status Webhook",
  "subscriptionDefinitionName": "Package_Update",
  "deliveryType": "WEBHOOK",
  "webhookUrl": "https://your-server.com/webhooks/orders",
  "filters": [
    {
      "field": "status",
      "operator": "IN",
      "value": ["COMPLETE", "FAILED"]
    }
  ]
}

Moving numbers from Legacy Global to Universal Platform​

The Legacy Global API provides an endpoint to migrate numbers to the Universal Platform. This is a BWI-side operation that requires credentials for both platforms. See the BWI API documentation and Move tool support article for more details.

Migration workflow​

  1. Initiate move: POST /v1/upgrade/movePhoneNumbers
  2. Check status: GET /v1/upgrade/movePhoneNumbers/status/{orderId}
  3. Complete move: POST /v1/upgrade/movePhoneNumbers/complete
  4. Check completion: GET /v1/upgrade/movePhoneNumbers/complete/status/{orderId}

Initiate a number move​

POST /v1/upgrade/movePhoneNumbers
Host: api.voxbone.com
apikey: YOUR_API_KEY
X-Bandwidth-Authorization: Bearer {token}
Content-Type: application/json

{
  "phoneNumbers": ["+12125551234", "+12125551235"],
  "accountId": "UP_ACCOUNT_ID",
  "subAccountId": "UP_SUB_ACCOUNT_ID",
  "locationId": "UP_LOCATION_ID",
  "voiceConfigurationPackageId": "VCP_ID"
}
note
  • Maximum 1000 numbers per request
  • Requires both Legacy Global apikey and Universal Platform credentials via X-Bandwidth-Authorization
  • The move is asynchronous — poll the status endpoint until complete
  • This feature is available to customers upgrading to a UP account. Contact your account representative if you want to begin this process.

Deprecated features with no direct equivalent​

The following Legacy Global features do not have a direct equivalent on the Universal Platform:

Legacy Global FeatureStatus on Universal Platform
Fax URI (/configuration/faxuri)Fax service is available on the Universal Platform, but the VoxFax Fax-to-PDF/email functionality which uses Fax URI is not supported.
Capacity Groups (/configuration/capacitygroup)No Universal Platform equivalent. Organising groups of numbers can be achieved with Sub-accounts and Locations.
POPs (/configuration/pop)Routing is managed via VCP route plans. No direct API equivalent.
Trunks (/inventory/trunk)No direct API equivalent. Replaced with SBC configuration.
Credit Packages (/inventory/creditpackage)Legacy Global platform only — no Universal Platform equivalent.
Account Balance (/ordering/accountbalance)Legacy Global platform only — no Universal Platform equivalent.
Number 'Whitelisting' (beta: /whitelist)On the UP you do not need to register/whitelist numbers outside of Bandwidth to make outbound calls using our network.
Inventory Zones (/inventory/zone)No equivalent — search by countryCodeA3 and phoneNumberType instead.
Inventory Features (/inventory/feature)Feature availability is handled differently on the Universal Platform.

Glossary​

Legacy GlobalUniversal Platform
InboundOrigination
OutboundTermination
Voice URIVoice Configuration Package (VCP)
DIDPhone Number / TN
DID Group(search directly by criteria)
Regulation AddressRequirements Package (Address + End User + Documents)
SMS Link / SMS Link GroupApplication + Location config
Cart + CheckoutOrder (direct)
CNAM DID configurationLIDB Update
apikey headerOAuth2.0 Bearer token
api.voxbone.comapi.bandwidth.com (in most cases)

Programmable Voice (new capability)​

The Universal Platform introduces Programmable Voice (also known as HTTP Voice or the Voice API), a new capability that allows you to initiate, manage, and control voice calls from an HTTP-based interface. This has no equivalent in the Legacy Global API and enables building voice-enabled applications by sending and receiving HTTPS requests.

See Programmable Voice documentation.

CNAM / LIDB​

The Universal Platform introduces two CNAM-related capabilities:

  • CNAM per Dip: Retrieve the CNAM associated with a phone number from the industry database. This is not available on Legacy Global. See the CNAM per Dip documentation.
  • LIDB Update: Update the CNAM name of a number in the industry LIDB database. On Legacy Global, this was part of the CNAM DID configuration. See the LIDB Update documentation.

We hope this guide helps you transition smoothly to the Universal Platform APIs. For further details, please refer to the resources below.

Additional resources​

Need help? Reach out to our team for dev tips
Contact Us
Our Company
About UsBlogContactNewsroomCareersInvestor RelationsLeadership
Quicklinks
SupportService StatusDevelopersResourcesSecurityPartner ProgramCustomersRelease NotesGlossaryTwilio AlternativeRegulations
Legal
GeneralAccessibilityLaw Enforcement GuideBandwidth Privacy NoticeReport a Phone NumberCookie NoticeTerms of Use
Request trialTalk to an expert
Call Us
+1 800 808 5150
The Bandwidth logo is a registered trademark of Bandwidth Inc. in the United States and/or other countries. All other marks are the property of their respective owners. Bandwidth.com CLEC, LLC is a wholly owned subsidiary of Bandwidth Inc. ©2026