Skip to main content

Programmatic API Setup

This walks through how to setup and configure your Bandwidth account via Bandwidth's Number Management API for use with our HTTP Voice, and HTTP Messaging APIs. Unless you are already comfortable with our Number Management API and Bandwidth account structures, it is recommended that you follow our App Setup Guide for the Bandwidth App instead of using this programmatic guide.

Assumptions​

  • You have been contracted and given access to your Bandwidth Account
  • Your account is enabled for HTTP Voice and/or Messaging
  • You have administrator access on the account to create users and change roles

Steps​

  1. Create Sub-Account
  2. Create a Location
  3. Enable Services for Location
  4. Order a Phone Number
  5. Create an Application

Create a Sub-Account (Site)​

To create a Sub-Account, also referred to as a site, follow the instructions below.

Request URL​

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/sites

Request Body Fields​

The fields below should be formatted as XML elements and put in the request body as shown in the example below.

FieldRequiredDescription
NameYesThe name of the site. Max length of 10 characters
DescriptionNoThe description of the site
CustomerProvidedIDNoOptional custom ID to assign to your application. Max length of 10 characters
CustomerNameNoOptional custom name to assign to your application. Max length of 50 characters
AddressYesThe address of the site
Address.HouseNumberYesThe number of the house
Address.HousePrefixNoThe prefix of the house
Address.HouseSuffixNoThe suffix of the house
Address.StreetNameYesThe name of the street
Address.StreetSuffixNoThe suffix of the street
Address.AddressLine2NoThe optional second line of the address (apartment, extension, etc)
Address.CityYesThe city of the address
Address.StateCodeYesThe 2 character state code
Address.ZipYesThe 6 digit zip code
Address.PlusFourNoThe 4 digit zip code extension
Address.CountyNoThe county of the address
Address.CountryNoThe country of the address
Address.AddressTypeYesThe type of the address. Must be Billing or Service

Example​

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/sites HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<Site>
  <Name>SetupTest</Name>
  <Description>Programmatic Setup Test</Description>
  <CustomerName>BW</CustomerName>
  <Address>
    <HouseNumber>900</HouseNumber>
    <StreetName>Main Campus Dr</StreetName>
    <City>RALEIGH</City>
    <StateCode>NC</StateCode>
    <Zip>27606</Zip>
    <AddressType>Billing</AddressType>
  </Address>
</Site>

Create a Location (SIP Peer)​

To create a Location, also referred to as a SIP Peer, follow the instructions below.

Request URL​

The siteId in this URL refers to the site you would like to become the parent sub account of the new location. It can be retrieved from the response of the site's creation request, via the App, or by performing a GET request on the /sites endpoint and looking at the <Id> tag for your site.

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers

Request Body Fields​

The fields below should be formatted as XML elements and put in the request body as shown in the example below.

FieldRequiredDescription
PeerNameYesPlain text name of the Location (sippeer)
IsDefaultPeerNoBoolean: true or false. The Default SIP Peer is the default "destination" for any Telephone Numbers that are ordered for the Site in which the SIP Peer resides. Each sub-account (site) can have only 1 default SIP Peer. You can configure multiple SIP Peers on a Site

Example​

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<SipPeer>
  <PeerName>Setup Test SIP Peer</PeerName>
  <IsDefaultPeer>true</IsDefaultPeer>
</SipPeer>

Enable SMS for Location​

In order to use HTTP messaging on your account, you need to enable SMS and MMS for each location.

Request URL​

The sippeerId in this URL refers to the location you would like to enable SMS on. It can be retrieved from the Location header of the location creation response, via the Dashbaord UI, or by performing a GET request on the /sites/{siteId}/sippeers endpoint and looking at the <PeerId> tag for your Location.

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/products/messaging/features/sms

Request Body Fields​

The fields below should be formatted as XML elements and put in the request body as shown in the example below.

FieldRequiredDescription
TollFreeYesBoolean: true or false. Will enable texting to and from toll-free phone numbers
ShortCodeYesBoolean: true or false. Will enable texting to and from short codes
ProtocolYesMUST BE SET TO HTTP
Zone1YesMUST BE SET TO: true
Zone2YesBoolean: true or false.
Zone3YesBoolean: true or false.
Zone4YesBoolean: true or false.
Zone5YesBoolean: true or false.

Example​

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/products/messaging/features/sms HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<SipPeerSmsFeature>
  <SipPeerSmsFeatureSettings>
    <TollFree>true</TollFree>
    <ShortCode>true</ShortCode>
    <Protocol>HTTP</Protocol>
    <Zone1>true</Zone1>
    <Zone2>true</Zone2>
    <Zone3>true</Zone3>
    <Zone4>true</Zone4>
    <Zone5>true</Zone5>
  </SipPeerSmsFeatureSettings>
  <HttpSettings />
</SipPeerSmsFeature>

Enable MMS for Location​

In order to use HTTP messaging on your account, you need to enable SMS and MMS for each location.

Warning

MMS can only be enabled once SMS has been enabled. Attempting to enable MMS before SMS will result in a 400 Bad Request.

Request URL​

The sippeerId in this URL refers to the location you would like to enable MMS on. It can be retrieved from the Location header of the location creation response, via the Dashbaord UI, or by performing a GET request on the /sites/{siteId}/sippeers endpoint and looking at the <PeerId> tag for your Location.

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/products/messaging/features/mms

Request Body Fields​

The fields below should be formatted as XML elements and put in the request body as shown in the example below.

FieldRequiredDescription
ProtocolYesMUST BE SET TO HTTP

Example​

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/products/messaging/features/mms HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<MmsFeature>
  <MmsSettings>
    <Protocol>HTTP</Protocol>
  </MmsSettings>
  <Protocols>
    <HTTP>
      <HttpSettings />
    </HTTP>
  </Protocols>
</MmsFeature>

Order a Phone Number​

Ordering a phone number and assigning it to a location is necessary to get an application up and running.

For a guide on ordering phone numbers in the Bandwidth App, click here!

For a guide on ordering phone numbers via the Bandwidth API, click here!

Create an Application​

After assigning the phone number you've ordered to a location, you must create a messaging or voice application and assign it to the location that has the phone number you would like to use.

info

For more information about our applications API, check out our Applications Guide.

Create a Messaging Application​

This section walks though creating a messaging application.

Request URL​

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/applications

Request Body Fields​

The fields below should be formatted as XML elements and put in the request body as shown in the example below.

FieldRequiredDescription
ServiceTypeYesSet to Messaging-V2
AppNameYesPlain text name of the application
MsgCallbackUrlYesUrl to receive all message events
CallbackCredsNoBasic auth credentials to apply to your message events
CallbackCreds.UserIdNoBasic auth UserId
CallbackCreds.PasswordNoBasic auth Password

Example​

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/applications HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<Application>
    <ServiceType>Messaging-V2</ServiceType>
    <AppName>Production Server</AppName>
    <MsgCallbackUrl>https://yourSecureSite.com/callbacks</MsgCallbackUrl>
    <CallbackCreds>
      <UserId>Your-User-id</UserId>
      <Password>Your-Password</Password>
  </CallbackCreds>
</Application>

Assign a Messaging Application to Location​

This walks through assigning a messaging application to a location and enabling V2 messaging on that location. An application must be assigned to a location, the application assigned to the location will run on voice and messaging events for the numbers on the location.

Request URL​

PUThttps://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/products/messaging/applicationSettings

Request Body Fields​

The fields below should be formatted as XML elements and put in the request body as shown in the example below.

FieldRequiredDescription
HttpMessagingV2AppIdYesThe application ID from the application created above

Example​

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/applications HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<ApplicationsSettings>
  <HttpMessagingV2AppId>590cde45-c05d-44e3-a77a-59fd10f17c26</HttpMessagingV2AppId>
</ApplicationsSettings>

Create a Voice Application​

This section walks though creating a voice application.

Request URL​

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/applications

Request Body Fields​

The fields below should be formatted as XML elements and put in the request body as shown in the example below.

FieldRequiredDescription
ServiceTypeYesSet to Voice-V2
AppNameYesPlain text name of the application
CallInitiatedCallbackUrlYesUrl to receive actionable voice events
CallStatusCallbackUrlNoUrl to receive voice events NOT related to Initiated. Such as: rejected or hung up
CallbackCredsNoBasic auth credentials to apply to your voice events
CallbackCreds.UserIdNoBasic auth UserId
CallbackCreds.PasswordNoBasic auth Password

Example​

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/applications HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<Application>
    <ServiceType>Voice-V2</ServiceType>
    <AppName>Setup Test Voice</AppName>
    <CallInitiatedCallbackUrl>https://yourSecureSite.com/callbacks/init</CallInitiatedCallbackUrl>
    <CallStatusCallbackUrl>https://yourSecureSite.com/callbacks/status</CallStatusCallbackUrl>
    <CallbackCreds>
      <UserId>Your-User-id</UserId>
      <Password>Your-Password</Password>
  </CallbackCreds>
</Application>

Assign a Voice Application to Location​

This walks through assigning a voice application to a location and enabling HTTP Voice on that location. An application must be assigned to a location, the application assigned to the location will run on voice and messaging events for the numbers on the location.

Request URL​

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/products/origination/settings

Request Body Fields​

The fields below should be formatted as XML elements and put in the request body as shown in the example below.

FieldRequiredDescription
VoiceProtocolYesMUST BE SET TO HTTP
HttpSettingsYesParent element for HTTP settings
HttpVoiceV2AppIdYesThe applicationId of the Voice application created above

Example​

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/sites/{siteId}/sippeers/{sippeerId}/products/origination/settings HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

<SipPeerOriginationSettings>
  <VoiceProtocol>HTTP</VoiceProtocol>
  <HttpSettings>
    <HttpVoiceV2AppId>{voice-applicationId}</HttpVoiceV2AppId>
  </HttpSettings>
</SipPeerOriginationSettings>
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
Bandwidth.com CLEC, LLC is a wholly owned subsidiary of Bandwidth Inc. ©2024