Introduction to the Universal Platform APIs for Legacy Global API users
This guide is designed for developers who are familiar with the Legacy Global APIs and have been onboarded onto their new Universal Platform account. Here, you'll find valuable information on how to leverage the new Universal Platform API to automate your business processes.
If you're unsure if now is the right time to upgrade to Bandwidth's Universal Platform, please contact your account rep.
The Universal Platform API cannot be used to manage Legacy Global Portal Numbers and configurations.
It is intended for managing and configuring Numbers purchased and associated with your new Universal Platform account provided during the onboarding process.
The tools to move Global Platform Numbers to the Universal Platform is currently available on an early access basis for select customers and with limitations. Lifting these limitations and broader availability is expected over time.
Please contact your account representative if you would like to learn more about getting access to the Universal Platform.
Overview of Changes
The Bandwidth Universal Platform API introduces several significant changes compared to the Legacy Global API. We've highlighted below some key differences:
Account structure
In the Unversal Platform, your account offers a structured way to manage your Numbers and other Services.
Accounts is the top level. As a user, you might have access to multiple accounts. Accounts are created by our support team to support different use cases and products.
Sub-accounts (also known as "Sites" in the API) is the middle level of hierarchy that allows you to arbitrarily allocate Numbers in different separated contexts.
Locations (also known as "Sip Peers" in the API) is the lowest level of hierarchy to which the Numbers are actually assigned. It holds some Messaging configuration, if your account is enabled for Messaging.
See documentation on Account Structure
Orders
In the Universal Platform API and App, an Order represents a request to perform various operations (e.g., Purchase, Port In, Disconnect, Move, etc.), expanding beyond the purchase process as it was in the Legacy Global APIs.
- Orders in the Universal Platform are generally asynchronous, allowing you to monitor their progress using a status endpoint.
- You can also subscribe to orders to receive updates about status changes via a webhook.
Cart (Legacy) & Number Orders (Universal)
In the Universal Platform API, the process for purchasing Numbers resembles a simpler streamlined flow moving away from the traditional cart model where the user:
- Searches for Numbers matching specific criterias
- Orders the list of desired Numbers
See the Number Ordering guide.
Voice URI (Legacy) & Voice Configuration Packages (Universal)
The Universal Platform introduces Voice Configuration Packages, which enhance the Legacy Voice URI concept by including additional settings such as:
- CNAM
- STIR/SHAKEN configuration
- HTTP Voice settings
See the Voice Configuration Package guide.
Addresses (Legacy) & Requirement Packages (Universal)
In the Universal Platform APIs and App, the Address used for Service Activation has been refined into multiple components for improved reusability.
The Requirement Package now consists of:
- an Address
- an End User Details
- some Documents (if required)
See the Requirement Package documentation
HTTP Voice / Voice API / Programmable Voice
Programmable Voice (also known as HTTP Voice or the Voice API) is a new API that allows to initiate, manage and complete Voice calls from an HTTP-based interface. It allows you to build Voice enabled applications by simply sending and receiving HTTPS requests.
See Programmable Voice documentation
Webhooks / Subscriptions
Subscriptions is a new API that allows you to subscribe webhooks to different Orders status changes.
See the Webhooks documentation
Auth & and API credentials
The Universal Platform supports both Basic Auth and OAuth 2.0 Bearer auth schemes.
See the Credentials documentation
Content Type
The Universal Platform supports XML only at the moment with JSON on the roadmap.
CNAM / LIDB
In the Universal Platform, CNAM or CNAM per Dip usually refers to the action of retrieving the CNAM associated to a telephone number from the industry database. The Universal Platform offers an API that you can use to retrieve the associated CNAM to a phone number. This capability is not available in the Legacy Global platform. See the CNAM per Dip API documentation
In the Universal Platform, the action to update the CNAM name of a Number in the industry LIDB database is refered to as "LIDB update". An API is available for this action. See LIDB Update documentation
Glossary
| Legacy Global | Universal Platform |
|---|---|
| Inbound | Origination |
| Outbound | Termination |
| CNAM Did configuration | LIDB Update |
We hope this guide helps you transition smoothly to the Universal Platform APIs. For further details, please refer to the complete Universal Platform API documentation.
Additional Resources
- Documentation: For a complete overview of changes and improvements, refer to the Universal Platform guides and reference documentation.
- Support: If you have questions or require assistance during your upgrade, please contact Bandwidth support for help.