Skip to main content

Reseller And Brand API

This walks through how to programmatically provision, manage and view your brands via APIs for use with our Campaign, Number Management and Messaging API's.

Assumptions

Important Notes

  • If you get a '403 Unauthorized' error response while making an HTTP Request to any of the Import endpoints, you will need to reach out to the Implementation team to get the Campaign Management role assigned to your API User.
  • TCR currently has rate limits set on their HTTP REST endpoints. During high volume events, it is possible our APIs will be rate limited and respond with '429 Too Many Requests'.
  • Bandwidth rate limits all Campaign Management endpoints at 30 requests a minute with a burst rate of 20 requests for all the GET endpoints and 10 requests for PUT/POST/DELETE

API Authentication

The Account Management API resources are authenticated with your API Credentials for "Number & Account Management".

API Error Codes

HTTP/1.1 400 Bad Request
HTTP/1.1 403 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 409 Conflict
HTTP/1.1 429 Too Many Requests

Getting Started

  1. Create Campaign Settings
  2. Update Campaign Settings
  3. Fetch Campaign Settings
  4. Create Brand
  5. Update Brand
  6. Fetch Brand
  7. Fetch Detailed Brand List
  8. Fetch Abbreviated Brand List

Create campaign settings

Request URL

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc

Request BodyMandatoryDescription
BusinessIdentityYesThe type of customer you are, 'DirectCustomer' or 'Reseller'
ResellerNoValue required for 'Reseller' BusinessIdentity only. An object containing reseller information
ResellerMandatoryDescription
CompanyNameYesDisplay or company name of the reseller. Max 100 characters
PhoneYesValid phone number in e.164 international format '+18009999999'
EmailYesValid email address of reseller contact. Max 100 characters

Examples

Create Direct Customer Campaign Settings

Request

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

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<CampaignSettings>
<BusinessIdentity>DirectCustomer</BusinessIdentity>
</CampaignSettings>

Response

HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignSettingsResponse>
<CampaignSettings>
<BusinessIdentity>DirectCustomer</BusinessIdentity>
</CampaignSettings>
</CampaignSettingsResponse>

Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignSettingsResponse>
<ResponseStatus>
<ErrorCode>1003</ErrorCode>
<Description>Phone is required</Description>
</ResponseStatus>
</CampaignSettingsResponse>

Update campaign settings

Request URL

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc

Request BodyMandatoryDescription
BusinessIdentityYesThe type of customer you are, 'DirectCustomer' or 'Reseller'
ResellerNoValue required for 'Reseller' BusinessIdentity only. An object containing reseller information
ResellerMandatoryDescription
CompanyNameYesDisplay or company name of the reseller. Max 100 characters
PhoneYesValid phone number in e.164 international format '+18009999999'
EmailYesValid email address of reseller contact. Max 100 characters

Examples

Update Direct Customer Campaign Settings

Request

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

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<CampaignSettings>
<BusinessIdentity>DirectCustomer</BusinessIdentity>
</CampaignSettings>

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignSettingsResponse>
<CampaignSettings>
<BusinessIdentity>DirectCustomer</BusinessIdentity>
</CampaignSettings>
</CampaignSettingsResponse>

Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignSettingsResponse>
<ResponseStatus>
<ErrorCode>1003</ErrorCode>
<Description>Phone is required</Description>
</ResponseStatus>
</CampaignSettingsResponse>

Fetch campaign settings

Request URL

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc

Examples

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignSettingsResponse>
<CampaignSettings>
<BusinessIdentity>Reseller</BusinessIdentity>
<Reseller>
<CompanyName>Test Company 1</CompanyName>
<Phone>+18009999999</Phone>
<Email>Test1@bandwidth.com</Email>
</Reseller>
</CampaignSettings>
</CampaignSettingsResponse>

Error Response

HTTP/1.1 404 Not Found
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignSettingsResponse>
<ResponseStatus>
<ErrorCode>4022</ErrorCode>
<Description>Account '1111111' does not exist or is locked</Description>
</ResponseStatus>
</CampaignSettingsResponse>

Create brand

Request URL

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands

Request BodyMandatoryDescription
BrandYesAn object containing brand information

| Brand | Mandatory | Description | | :------------------ | :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | | EntityType | Yes | Entity type behind the brand. THis is the form of business establishment. 'PRIVATE_PROFIT', 'PUBLIC_PROFIT', 'NON_PROFIT', 'GOVERNMENT', 'SOLE_PROPRIETOR' | | AltBusinessId | No | Alternate business identifier such as DUNS, LEI, GIIN | | AltBusinessIdType | No | Enum value describing AltBussinessId. 'NONE', 'DUNS', 'LEI', 'GIIN' | | BrandRelationship | Yes | Enum value describing the relationship with your Account. Supported values: 'BASIC_ACCOUNT', 'SMALL_ACCOUNT', 'MEDIUM_ACCOUNT', 'LARGE_ACCOUNT', 'KEY_ACCOUNT' | | City | Yes | City name. Max Length 100 characters | | CompanyName | Yes (Not required for Sole Proprietor) | Legal Company Name. Max Length 100 characters | | Country | Yes | ISO2 2 characters country code. Example: US - United States | | DisplayName | Yes | Display or marketing name of the brand. Max 100 characters | | Ein | Yes (Not required for Sole_Proprietor) | Government assigned corporate tax ID. EIN is 9-digits in U.S | | Email | Yes | Valid email address of brand support contact. Max 100 characters | F | | Phone | Yes | Valid phone number in e.164 international format '+18009999999' | | PostalCode | Yes | Postal codes. Use 5 digit zipcode for United States | | State | Yes | State name. Must be 2 letters code for United States | | Street | Yes | street name. Max Length 100 characters | | StockExchange | No (Required for public) | Stock exchange. 'NONE', NASDAQ', 'NYSE', etc. | | StockSymbol | No (Required for public) | Stock symbol | | Vertical | Yes (Disabled for Sole_Proprietor) | Enum value describing vertical or industry segment of the brand | | Website | No | Brand website URL. Max Length 100 characters | | IsMain | Yes | true or false. True if creating 'My Brand', false if creating 'Customer Brand' |

Examples

My Brand Note: Regardless of if you are a DirectCustomer or Reseller, you will need to create a 'My Brand'. You can only create one of these. On the Request Body you can indicate a 'My Brand' by setting the IsMain flag to true.

Request

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

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<Brand>
<EntityType>NON_PROFIT</EntityType>
<AltBusinessId>111111111</AltBusinessId>
<AltBusinessIdType>DUNS</AltBusinessIdType>
<BrandRelationship>MEDIUM_ACCOUNT</BrandRelationship>
<City>Raleigh</City>
<CompanyName>Bandwidth</CompanyName>
<Country>US</Country>
<DisplayName>Bandwidth</DisplayName>
<Ein>111111111</Ein>
<Email>Test1@bandwidth.com</Email>
<Phone>+18009999999</Phone>
<PostalCode>27606</PostalCode>
<State>NC</State>
<Street>1200 Test Road</Street>
<StockExchange>NASDAQ</StockExchange>
<StockSymbol>BAND</StockSymbol>
<Vertical>COMMUNICATION</Vertical>
<Website>https://www.bandwidth.com</Website>
<IsMain>true</IsMain>
</Brand>

Response

HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandResponse>
<Brand>
<BrandId>BJDHM3</BrandId>
<CspId>CMHSJ9</CspId>
<EntityType>NON_PROFIT</EntityType>
<AltBusinessId>111111111</AltBusinessId>
<AltBusinessIdType>DUNS</AltBusinessIdType>
<BrandRelationship>MEDIUM_ACCOUNT</BrandRelationship>
<City>Raleigh</City>
<CompanyName>Bandwidth</CompanyName>
<Country>US</Country>
<DisplayName>Bandwidth</DisplayName>
<Ein>111111111</Ein>
<UniversalEin>111111111</UniversalEin>
<Email>Test1@bandwidth.com</Email>
<Phone>+18009999999</Phone>
<PostalCode>27606</PostalCode>
<State>NC</State>
<Street>1200 Test Road</Street>
<StockExchange>NASDAQ</StockExchange>
<StockSymbol>BAND</StockSymbol>
<Vertical>COMMUNICATION</Vertical>
<Website>https://www.bandwidth.com</Website>
<IsMain>true</IsMain>
</Brand>
</BrandResponse>

Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandResponse>
<ResponseStatus>
<ErrorCode>1003</ErrorCode>
<Description>CompanyName is required</Description>
</ResponseStatus>
</BrandResponse>

Update brand

Note: Non-editable fields will be ignored and will not be updated.

Request URL

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/ {brandId}

Request BodyMandatoryDescription
BrandYesAn object containing brand information
BrandMandatoryEditableDescription
DisplayNameYesYesDisplay or marketing name of the brand. Max 100 characters
WebsiteNoYesBrand website URL. Max Length 100 characters
StreetYesYesstreet name. Max Length 100 characters
CityYesYesCity name. Max Length 100 characters
StateYesYesState name. Must be 2 letters code for United States
PostalCodeYesYesPostal codes. Use 5 digit zipcode for United States
CountryYesYesISO2 2 characters country code. Example: US - United States
EmailYesYesValid email address of brand support contact. Max 100 characters
PhoneYesYesValid phone number in e.164 international format '+18009999999'
VerticalYes (Not required for Sole_Proprietor)YesEnum value describing vertical or industry segment of the brand
BrandRelationshipYesYesEnum value describing the relationship with your Account. Supported values: 'BASIC_ACCOUNT', 'SMALL_ACCOUNT', 'MEDIUM_ACCOUNT', 'LARGE_ACCOUNT', 'KEY_ACCOUNT'
EntityTypeYesNoEntity type behind the brand. THis is the form of business establishment. 'PRIVATE_PROFIT', 'PUBLIC_PROFIT', 'NON_PROFIT'
AltBusinessIdNoNoAlternate business identifier such as DUNS, LEI, GIIN
AltBusinessIdTypeNoNoEnum value describing AltBussinessId. 'NONE', 'DUNS', 'LEI', 'GIIN'
EinYes (Not required for Sole_Proprietor)NoGovernment assigned corporate tax ID. EIN is 9-digits in U.S
StockExchangeNo (Required for public)NoStock exchange. 'NONE', NASDAQ', 'NYSE', etc.
StockSymbolNo (Required for public)NoStock symbol
WebsiteNoNoBrand website URL. Max Length 100 characters

Examples

Request

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

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<Brand>
<EntityType>NON_PROFIT</EntityType>
<AltBusinessId>111111110</AltBusinessId>
<AltBusinessIdType>DUNS</AltBusinessIdType>
<BrandRelationship>MEDIUM_ACCOUNT</BrandRelationship>
<City>Raleigh</City>
<CompanyName>Bandwidth Customer</CompanyName>
<Country>US</Country>
<DisplayName>Bandwidth Customer</DisplayName>
<Ein>111111110</Ein>
<Email>Test1@bandwidthcustomer.com</Email>
<Phone>+18009999999</Phone>
<PostalCode>27606</PostalCode>
<State>NC</State>
<Street>1200 Test Road</Street>
<StockExchange>NASDAQ</StockExchange>
<StockSymbol>TEST</StockSymbol>
<Vertical>COMMUNICATION</Vertical>
<Website>https://www.bandwidthcustomer.com</Website>
<IsMain>false</IsMain>
</Brand>

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandResponse>
<Brand>
<BrandId>BJDHM3</BrandId>
<CspId>CMHSJ9</CspId>
<EntityType>NON_PROFIT</EntityType>
<AltBusinessId>111111110</AltBusinessId>
<AltBusinessIdType>DUNS</AltBusinessIdType>
<BrandRelationship>MEDIUM_ACCOUNT</BrandRelationship>
<City>Raleigh</City>
<CompanyName>Bandwidth Customer</CompanyName>
<Country>US</Country>
<DisplayName>Bandwidth Customer</DisplayName>
<Ein>111111110</Ein>
<Email>Test1@bandwidthcustomer.com</Email>
<Phone>+18009999999</Phone>
<PostalCode>27606</PostalCode>
<State>NC</State>
<Street>1200 Test Road</Street>
<StockExchange>NASDAQ</StockExchange>
<StockSymbol>TEST</StockSymbol>
<Vertical>COMMUNICATION</Vertical>
<Website>https://www.bandwidthcustomer.com</Website>
<IsMain>false</IsMain>
</Brand>
</BrandResponse>

Error Response

HTTP/1.1 400 Bad Request
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandResponse>
<ResponseStatus>
<ErrorCode>1003</ErrorCode>
<Description>Phone is required</Description>
</ResponseStatus>
</BrandResponse>

Fetch brand

Request URL

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/ {brandId}

Examples

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId} HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandResponse>
<Brand>
<BrandId>BJDHM3</BrandId>
<CspId>CMHSJ9</CspId>
<EntityType>NON_PROFIT</EntityType>
<AltBusinessId>111111110</AltBusinessId>
<AltBusinessIdType>DUNS</AltBusinessIdType>
<BrandRelationship>MEDIUM_ACCOUNT</BrandRelationship>
<City>Raleigh</City>
<CompanyName>Bandwidth Customer</CompanyName>
<Country>US</Country>
<DisplayName>Bandwidth Customer</DisplayName>
<Ein>111111110</Ein>
<Email>Test1@bandwidthcustomer.com</Email>
<Phone>+18009999999</Phone>
<PostalCode>27606</PostalCode>
<State>NC</State>
<Street>1200 Test Road</Street>
<StockExchange>NASDAQ</StockExchange>
<StockSymbol>TEST</StockSymbol>
<Vertical>COMMUNICATION</Vertical>
<Website>https://www.bandwidthcustomer.com</Website>
<IsMain>false</IsMain>
</Brand>
</BrandResponse>

Error Response

HTTP/1.1 404 Not Found
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandResponse>
<ResponseStatus>
<ErrorCode>12183</ErrorCode>
<Description>Brand with id 'BJDHM3' not found"</Description>
</ResponseStatus>
</BrandResponse>

Fetch detailed brand list

This endpoint returns a paginated brand list with full brand details.

Request URL

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/details?type= {type}&page={page}&size={size}

Note: type parameter values include -

  1. 'none' which returns both 'My Brand' and 'Customer Brands'.
  2. 'main' which returns 'My Brand' only.
  3. 'customer' which return 'Customer Brands' only.

Examples

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/details?type=main&page=0&size=2 HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/details?type=main&page=0&size=2

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandsResponse>
<Brands>
<Brand>
<BrandId>BJDHM3</BrandId>
<CspId>CMHSJ9</CspId>
<EntityType>NON_PROFIT</EntityType>
<AltBusinessId>111111110</AltBusinessId>
<AltBusinessIdType>DUNS</AltBusinessIdType>
<BrandRelationship>MEDIUM_ACCOUNT</BrandRelationship>
<City>Raleigh</City>
<CompanyName>Bandwidth Customer</CompanyName>
<Country>US</Country>
<DisplayName>Bandwidth Customer</DisplayName>
<Ein>111111110</Ein>
<Email>Test1@bandwidthcustomer.com</Email>
<Phone>+18009999999</Phone>
<PostalCode>27606</PostalCode>
<State>NC</State>
<Street>1200 Test Road</Street>
<StockExchange>NASDAQ</StockExchange>
<StockSymbol>TEST</StockSymbol>
<Vertical>COMMUNICATION</Vertical>
<Website>https://www.bandwidthcustomer.com</Website>
<IsMain>true</IsMain>
</Brand>
</Brands>
<TotalCount>1</TotalCount>
</BrandsResponse>

Error Response

HTTP/1.1 403 Unauthorized
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/details?type=main&page=0&size=2

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandsResponse>
<ResponseStatus>
<ErrorCode>12055</ErrorCode>
<Description>CampaignManagement feature is not enabled on account 9999999</Description>
</ResponseStatus>
</BrandsResponse>

Fetch abbreviated brand list

This endpoint returns a complete, un-paginated, brand list with limited detail.

Request URL

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/details?type= {type}

Note: type parameter values include -

  1. 'none' which returns both 'My Brand' and 'Customer Brands'.
  2. 'main' which returns 'My Brand' only.
  3. 'customer' which return 'Customer Brands' only.

Examples

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/?type=main HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands?type=main

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandsResponse>
<Brands>
<Brand>
<BrandId>BJDHM3</BrandId>
<CspId>CMHSJ9</CspId>
<EntityType>NON_PROFIT</EntityType>
<AltBusinessId>111111110</AltBusinessId>
<AltBusinessIdType>DUNS</AltBusinessIdType>
<BrandRelationship>MEDIUM_ACCOUNT</BrandRelationship>
<City>Raleigh</City>
<CompanyName>Bandwidth Customer</CompanyName>
<Country>US</Country>
<DisplayName>Bandwidth Customer</DisplayName>
<Ein>111111110</Ein>
<Email>Test1@bandwidthcustomer.com</Email>
<Phone>+18009999999</Phone>
<PostalCode>27606</PostalCode>
<State>NC</State>
<Street>1200 Test Road</Street>
<StockExchange>NASDAQ</StockExchange>
<StockSymbol>TEST</StockSymbol>
<Vertical>COMMUNICATION</Vertical>
<Website>https://www.bandwidthcustomer.com</Website>
<IsMain>true</IsMain>
</Brand>
</Brands>
<TotalCount>1</TotalCount>
</BrandsResponse>

Error Response

HTTP/1.1 403 Unauthorized
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands?type=main

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandsResponse>
<ResponseStatus>
<ErrorCode>12055</ErrorCode>
<Description>CampaignManagement feature is not enabled on account 9999999</Description>
</ResponseStatus>
</BrandsResponse>

Next Steps

After successful brand registration, you can register campaigns with our campaign REST APIs