Getting Started
This is a brief overview to help you get started on Bandwidth's new Universal Platform (UP). This guide will walk you through how to purchase, configure, and provision service on a global phone number.
First, some assumptions that we are making for users of this page:
- You are contracted for a UP account
- Services enabled on account
- You have set up your UP account
For this quick-start guide, we will walk you through an example of purchasing and provisioning an Italian, geographic phone number for a Business end-user. Please note that this guide is only intended to help guide you through a potential workflow and that the response content does not necessarily reflect the restrictions or requirements for your account.
Overview
- Review Restrictions and Activation Requirements
- Purchase a Phone Number
- Check Service Activation Requirements
- Activate Services
- Manage Phone Numbers
Review Restrictions and Activation Requirements
Many countries have service restrictions and activation requirements that must be met before any services can be activated on a number. In some cases, you may be required to complete steps external to Bandwidth before your account will be enabled to purchase, port, or host phone numbers for a given country and number type. Before obtaining phone numbers in a new country, we recommend reviewing your account Restrictions and Activation Requirements.
This information will be updated periodically as regulations and/or supported services change, and can be accessed directly by hitting /restrictions and /requirements. Keep in mind that this list of restrictions is intended to help improve your experience, but it may not be exhaustive of all restrictions on your account.
Retrieve Restrictions
Request
GET https://api.bandwidth.com/api/v2/restrictions?countryCodeA3=ITA HTTP/1.1
Authorization: Bearer mySecretToken
Response
<RestrictionResponse>
<Restrictions>
<Restriction>
<CountryCodeA3>ITA</CountryCodeA3>
<RestrictionCategory>Sub allocation</RestrictionCategory>
<RestrictionDescription>Customers providing Electronic Communication Services must be registered operators with the local regulator and must provide these services to end users.</RestrictionDescription>
<RestrictionType>LEGAL</RestrictionType>
</Restriction>
<Restriction>
<CountryCodeA3>ITA</CountryCodeA3>
<RestrictionCategory>Others</RestrictionCategory>
<RestrictionDescription>Customers or end users conducting call center activities must be notified/registered operators with the local regulator.</RestrictionDescription>
<RestrictionType>LEGAL</RestrictionType>
</Restriction>
<Restriction>
<CountryCodeA3>ITA</CountryCodeA3>
<RestrictionCategory>Reachability</RestrictionCategory>
<RestrictionDescription>199 numbers are reachable from Italy only.</RestrictionDescription>
<RestrictionType>SERVICE</RestrictionType>
</Restriction>
<Restriction>
<CountryCodeA3>ITA</CountryCodeA3>
<RestrictionCategory>Mobile numbers</RestrictionCategory>
<RestrictionDescription>Outbound SMS are limited to 2000 messages per day per DID number.</RestrictionDescription>
<RestrictionType>SERVICE</RestrictionType>
</Restriction>
</Restrictions>
</RestrictionResponse>
Retrieve Requirements
Request
GET https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirements?countryCodeA3[eq]=ITA&phoneNumberType[eq]=GEOGRAPHIC&endUserType[eq]=BUSINESS HTTP/1.1
Authorization: Bearer mySecretToken
This API uses deepObject query parameters. Brackets ([]) are unsafe URL characters and should be encoded in requests. Some clients may automatically encode these characters for you.
For example, the query parameter countryCodeA3[eq]=ITA should be encoded as countryCodeA3%5Beq%5D=ITA.
Response
{
"data": [
{
"countryCodeA3": "ITA",
"endUserType": "BUSINESS",
"phoneNumberType": "GEOGRAPHIC",
"requirement": {
"address": {
"location": "NATIONAL"
},
"endUser": {
"fields": [
{
"fieldName": "salutation",
"friendlyName": "Salutation",
"maxLength": 10,
"required": true,
"type": "String",
"values": ["Mr.", "Mrs."]
}
],
"type": "BUSINESS"
},
"supportingDocuments": [
{
"acceptedDocuments": [
{
"fields": [
{
"fieldName": "companyName",
"friendlyName": "Company Name",
"maxLength": 500,
"type": "String"
},
{
"fieldName": "issueDate",
"friendlyName": "Issue Date",
"type": "Date"
}
],
"friendlyName": "Business registration",
"type": "businessRegistration"
}
],
"description": "The business registration document",
"name": "Business registration",
"type": "ADDRESS"
}
]
}
}
],
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirements",
"rel": "self",
"type": "GET"
}
]
}
Purchase a Phone Number
Before you can activate services on a phone number, you must have one on your account.
You have the option to provide all activation requirements in the order to “auto-activate” services. See how to purchase a phone number for more information about new number orders and auto-activating service at order time.
Check Service Activation Requirements
Use the Service activation checker to see the status of each service type. If the “serviceTypes” you wish to activate are in status READY_TO_ACTIVATE you can skip this step.
Check Service Activation Status
Request
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/serviceActivationChecker HTTP/1.1
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"phoneNumbers": [
"+390144230024",
"+390144230034"
]
}
Response
{
"data": {
"phoneNumbers": [
{
"phoneNumber": "+390144230024",
"serviceTypes": {
"emergency": {
"status": "IN_SERVICE"
},
"messaging": {
"status": "READY_TO_ACTIVATE"
},
"voice": {
"status": "IN_SERVICE"
}
}
},
{
"phoneNumber": "+390144230034",
"serviceTypes": {
"emergency": {
"reasons": [
{
"code": "20000",
"description": "A requirements package is required to activate services on these numbers"
}
],
"status": "ACTIVATION_REQUIREMENTS_NOT_MET"
},
"messaging": {
"reasons": [
{
"code": "20000",
"description": "A requirements package is required to activate services on these numbers"
},
{
"code": "20002",
"description": "This telephone number is in a location with Messaging set to disabled for all telephone numbers. If you wish to enable it for this telephone number, you must update the location first."
}
],
"status": "ACTIVATION_REQUIREMENTS_NOT_MET"
},
"voice": {
"reasons": [
{
"code": "20000",
"description": "A requirements package is required to activate services on these numbers"
},
{
"code": "1002",
"description": "Voice config not defined"
}
],
"status": "ACTIVATION_REQUIREMENTS_NOT_MET"
}
}
}
]
},
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/1/serviceActivationChecker",
"method": "POST",
"rel": "self"
}
]
}
Resolve Service Activation Issues
For “serviceTypes” in status "ACTIVATION_REQUIREMENTS_NOT_MET", additional steps must be taken before you can activate that specific service. Once all requirements have been satisfied, the status of the service type will automatically update to “READY_TO_ACTIVATE".
To activate Voice, Messaging, and Emergency services, any or all of the following steps may be required for activation:
Create a Requirements Package and Attach to Phone Number
Provide a Requirements Package to validate the end-user. First, create a requirements package, and then attach it to the phone number.
- Create a requirements package. This requirement will not be fully met until the package has been approved by our Compliance team and is in a “VERIFIED” status.
- Attach the requirements package to the phone number
Visit how to create a requirements package for more details on creating Requirements Packages.
Request
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirementsPackages/55f9f932-6136-48cf-a724-401ec8fe5ff2/phoneNumbers/bulk HTTP/1.1
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"action": "add",
"allDetailsAccurate": true,
"phoneNumbers": [
"+390144230024",
"+390144230034"
]
}
Response
{
"data": {
"description": "The +390144230024, +390144230034 numbers has been successfully added to requirements package:55f9f932-6136-48cf-a724-401ec8fe5ff2. A link to the note is included in the Location header of the response.",
"phoneNumbers": [
{
"phoneNumber": "+390144230024"
},
{
"phoneNumber": "+390144230034"
}
]
},
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/{accountId}/compliance/requirementsPackages/55f9f932-6136-48cf-a724-401ec8fe5ff2/phoneNumbers/bulk",
"method": "POST",
"rel": "self"
}
]
}
Configure a Voice Configuration Package (VCP)
Creating a Voice Configuration Package (VCP) is required to activate Voice services on a phone number. A VCP is a collection of voice features that can be applied to a phone number. Once a VCP is created, it can be attached to a phone number to enable voice services.
For more information on creating a VCP and attaching it to your number(s), check out our guide on how to create a VCP.
Configure Messaging
Configuring Messaging settings on the Universal Platform hasn't changed much! We took the existing Messaging APIs and simply allowed you to pass in your international phone numbers to send from.
For more information on configuring Messaging settings, check out our messaging quick start guide.
Emergency
More information on getting started with Emergency Services on Bandwidth's Unified Platform is coming soon.
In the meantime - feel free to check out our Unified Emergency Services API Reference here.
Activate Services
Now that you have resolved all activation requirements, you can activate services on your phone number.
For voice and messaging - this is as simple as creating a Service Activation Order.
Example
Request
POST https://api.bandwidth.com/api/v2/accounts/{accountId}/serviceActivation HTTP/1.1
Content-Type: application/json
Authorization: Bearer mySecretToken
{
"action": "ACTIVATE",
"customerOrderId": "exampleOrder",
"phoneNumbers": [
"+19195551212",
"+19195551313"
],
"serviceTypes": [
"VOICE",
"MESSAGING"
]
}
Response
{
"data": {
"customerOrderId": "exampleOrder",
"orderId": "39348601-8a95-4096-9704-bf8316f218b9",
"orderRequest": {
"action": "ACTIVATE",
"customerOrderId": "exampleOrder",
"phoneNumbers": ["+19195551212", "+19195551313"],
"serviceTypes": ["VOICE", "MESSAGING"]
},
"orderStatus": "RECEIVED",
"phoneNumbers": [
{
"phoneNumber": "+19195551212",
"serviceTypes": {
"messaging": {
"status": "NOT_IN_SERVICE"
},
"voice": {
"status": "NOT_IN_SERVICE"
}
}
},
{
"phoneNumber": "+19195551313",
"serviceTypes": {
"messaging": {
"status": "NOT_IN_SERVICE"
},
"voice": {
"status": "NOT_IN_SERVICE"
}
}
}
]
},
"errors": [],
"links": [
{
"href": "https://api.bandwidth.com/api/v2/accounts/1234/serviceActivation",
"method": "POST",
"rel": "self"
},
{
"href": "https://api.bandwidth.com/api/v2/accounts/1234/serviceActivation/39348601-8a95-4096-9704-bf8316f218b9",
"method": "GET",
"rel": "serviceActivationOrder"
}
]
}