Skip to main content

Bandwidth 10DLC Campaign CSP API Guide

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

Assumptions#

Important Notes#

  • We only support campaigns that have been approved by all carriers participating through TCR. While provisioning your campaigns through Bandwidth /campaigns API, they will automatically provision to all participating carriers.
  • 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'.

API Authentication#

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

Getting Started#

  1. Create Campaign
  2. Update Campaign
  3. Fetch Campaign
  4. Fetch Campaign List
  5. Fetch Campaign List By BrandId
  6. Deactivate Campaign
  7. Assign a campaign to a TN
  8. Bulk Assign a campaign to multiple TNs

Create campaign#

Request URL#

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns
Request BodyMandatoryDescription
CampaignYesAn object containing brand information
CampaignMandatoryDescription
BrandIdYesAlphanumeric identifier of the brand associated with this campaign
VerticalYesBusiness/industry segment of this campaign. Must be of defined valid types
UsecaseYesCampaign usecase. Must be of defined valid types
SubUsecasesNo (Required for some usecases)Campaign sub-usecases. Must be of defined valid types
ResellerIdNoAlphanumeric identifier of the reseller that you want to associate with this campaign.
DescriptionYesSummary description of this campaign. Max length 4096
EmbeddedLinkNoDoes message generated by the campaign include URL link in SMS? Default false
EmbeddedPhoneNoDoes message generated by the campaign include phone number in SMS? Default false
NumberPoolNoDoes campaign utilize pool of phone numbers? Default false
AgeGatedNoAge gated content in campaign? Default false
DirectLendingNoWill the campaign include content related to direct lending or other loan arrangements? Default false
SubscriberOptInNoDoes campaign require subscriber to opt-in before SMS is sent to subscriber? Default false
SubscriberOptOutNoDoes campaign support subscriber opt-out keyword(s)? Default false
SubscriberHelpNoHave you implemented a response to the HELP keyword informing customers of how they can contact the message sender? Default false
Sample1YesMessage sample. Some campaign tiers require 1 or more message samples. Max length 1024
Sample2No (Required for some usecases)Message sample. Some campaign tiers require 2 or more message samples. Max length 1024
Sample3No (Required for some usecases)Message sample. Some campaign tiers require 3 or more message samples. Max length 1024
Sample4No (Required for some usecases)Message sample. Some campaign tiers require 4 or more message samples. Max length 1024
Sample5No (Required for some usecases)Message sample. Some campaign tiers require 5 message samples. Max length 1024
MessageFlowNoMessage flow description. Max length 2048
HelpMessageYesHelp message of the campaign. Max length 255
AffiliateMarketingNoIs affiliate marketing being used (or was used in the creation of the campaign)? Default false
ReferenceIdNoCaller supplied campaign reference ID. If supplied, the value must be unique across all submitted campaigns. Can be used to prevent duplicate campaign registrations. Max length 50
AutoRenewalYesCampaign subscription auto-renewal status. Default true

Request Authentication#

The campaigns resource is authenticated with your API Credentials for "Number & Account Management"

POST campaign#

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<Campaign>
<MinMsgSamples>1</MinMsgSamples>
<BrandId>B9AVERT</BrandId>
<Usecase>2FA</Usecase>
<SubUsecases>
</SubUsecases>
<Vertical>COMMUNICATION</Vertical>
<Description>Test Campaign</Description>
<Sample1>Test Sample</Sample1>
<SubscriberOptIn>true</SubscriberOptIn>
<SubscriberOptOut>false</SubscriberOptOut>
<SubscriberHelp>true</SubscriberHelp>
<NumberPool>false</NumberPool>
<DirectLending>false</DirectLending>
<EmbeddedLink>false</EmbeddedLink>
<EmbeddedPhone>false</EmbeddedPhone>
<AffiliateMarketing>false</AffiliateMarketing>
<AgeGated>false</AgeGated>
<AutoRenewal>true</AutoRenewal>
</Campaign>

Response#

HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignResponse>
<Campaign>
<CampaignId>CTW3YRE</CampaignId>
<AutoRenewal>true</AutoRenewal>
<BrandId>B9AVERT</BrandId>
<Vertical>COMMUNICATION</Vertical>
<Usecase>2FA</Usecase>
<SubUsecases/>
<Description>Test Campaign</Description>
<ResellerId>RPTUDEV</ResellerId>
<EmbeddedLink>false</EmbeddedLink>
<EmbeddedPhone>false</EmbeddedPhone>
<NumberPool>false</NumberPool>
<AgeGated>false</AgeGated>
<DirectLending>false</DirectLending>
<SubscriberOptIn>true</SubscriberOptIn>
<SubscriberOptOut>false</SubscriberOptOut>
<SubscriberHelp>true</SubscriberHelp>
<Sample1>Test Sample</Sample1>
<AffiliateMarketing>false</AffiliateMarketing>
<MnoMetadataList>
<MnoMetadata>
<MnoId>10017</MnoId>
<MNO>ATT</MNO>
<MnoSupport>true</MnoSupport>
<MnoReview>false</MnoReview>
<Qualify>true</Qualify>
<MinMessageSamples>1</MinMessageSamples>
<RequireSubscriberOptIn>true</RequireSubscriberOptIn>
<RequireSubscriberOptOut>false</RequireSubscriberOptOut>
<RequireSubscriberHelp>true</RequireSubscriberHelp>
<NoEmbeddedLink>false</NoEmbeddedLink>
<NoEmbeddedPhone>false</NoEmbeddedPhone>
<Surcharge>0.002</Surcharge>
<MessageClass>C</MessageClass>
<TPM>600</TPM>
</MnoMetadata>
<MnoMetadata>
<MnoId>10035</MnoId>
<MNO>T-Mobile</MNO>
<MnoSupport>true</MnoSupport>
<MnoReview>false</MnoReview>
<Qualify>true</Qualify>
<MinMessageSamples>1</MinMessageSamples>
<RequireSubscriberOptIn>true</RequireSubscriberOptIn>
<RequireSubscriberOptOut>false</RequireSubscriberOptOut>
<RequireSubscriberHelp>true</RequireSubscriberHelp>
<NoEmbeddedLink>false</NoEmbeddedLink>
<NoEmbeddedPhone>false</NoEmbeddedPhone>
<Surcharge>0.003</Surcharge>
<BrandTier>LOW</BrandTier>
</MnoMetadata>
</MnoMetadataList>
</Campaign>
</CampaignResponse>

Error Response#

HTTP/1.1 400 Bad Request
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignResponse>
<ResponseStatus>
<ErrorCode>1003</ErrorCode>
<Description>Description is required</Description>
</ResponseStatus>
</CampaignResponse>

Error Codes#

HTTP/1.1 400 Bad Request
HTTP/1.1 403 Unauthorized
HTTP/1.1 429 Too Many Requests

Update campaign#

Request URL#

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId}
Request BodyMandatoryDescription
CampaignYesAn object containing brand information
CampaignMandatoryEditableDescription
ResellerIdNoYesAlphanumeric identifier of the reseller that you want to associate with this campaign.
Sample1NoYesMessage sample. Some campaign tiers require 1 or more message samples. Max length 1024
Sample2No (Required for some usecases)YesMessage sample. Some campaign tiers require 2 or more message samples. Max length 1024
Sample3No (Required for some usecases)YesMessage sample. Some campaign tiers require 3 or more message samples. Max length 1024
Sample4No (Required for some usecases)YesMessage sample. Some campaign tiers require 4 or more message samples. Max length 1024
Sample5No (Required for some usecases)YesMessage sample. Some campaign tiers require 5 message samples. Max length 1024
MessageFlowNoYesMessage flow description. Max length 2048
HelpMessageNoYesHelp message of the campaign. Max length 255
AutoRenewalNoYesCampaign subscription auto-renewal status. Default true
BrandIdYesNoAlphanumeric identifier of the brand associated with this campaign
VerticalYesNoBusiness/industry segment of this campaign. Must be of defined valid types
UsecaseYesNoCampaign usecase. Must be of defined valid types
SubUsecasesNo (Required for some usecases)NoCampaign sub-usecases. Must be of defined valid types
DescriptionYesNoSummary description of this campaign. Max length 4096
EmbeddedLinkNoNoDoes message generated by the campaign include URL link in SMS? Default false
EmbeddedPhoneNoNoDoes message generated by the campaign include phone number in SMS? Default false
NumberPoolNoNoDoes campaign utilize pool of phone numbers? Default false
AgeGatedNoNoAge gated content in campaign? Default false
DirectLendingNoNoWill the campaign include content related to direct lending or other loan arrangements? Default false
SubscriberOptInNoNoDoes campaign require subscriber to opt-in before SMS is sent to subscriber? Default false
SubscriberOptOutNoNoDoes campaign support subscriber opt-out keyword(s)? Default false
SubscriberHelpNoNoHave you implemented a response to the HELP keyword informing customers of how they can contact the message sender? Default false
AffiliateMarketingNoNoIs affiliate marketing being used (or was used in the creation of the campaign)? Default false
ReferenceIdNoNoCaller supplied campaign reference ID. If supplied, the value must be unique across all submitted campaigns. Can be used to prevent duplicate campaign registrations. Max length 50

Request Authentication#

PUT Campaign#

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId} HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<Campaign>
<Sample1>test update sample</Sample1>
</Campaign>

Response#

HTTP/1.1 200 OK
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignResponse>
<Campaign>
<CampaignId>CTW3YRE</CampaignId>
<Status>ACTIVE</Status>
<CreateDate>2021-06-23T12:35:48</CreateDate>
<AutoRenewal>true</AutoRenewal>
<BilledDate>2021-06-23T00:00</BilledDate>
<BrandId>B9AVERT</BrandId>
<Vertical>COMMUNICATION</Vertical>
<Usecase>2FA</Usecase>
<SubUsecases/>
<Description>Test Campaign</Description>
<ResellerId>RPTAYWZ</ResellerId>
<EmbeddedLink>false</EmbeddedLink>
<EmbeddedPhone>false</EmbeddedPhone>
<NumberPool>false</NumberPool>
<AgeGated>false</AgeGated>
<DirectLending>false</DirectLending>
<SubscriberOptIn>true</SubscriberOptIn>
<SubscriberOptOut>false</SubscriberOptOut>
<SubscriberHelp>true</SubscriberHelp>
<Sample1>test update sample</Sample1>
<AffiliateMarketing>false</AffiliateMarketing>
</Campaign>
</CampaignResponse>

Error Response#

HTTP/1.1 400 Bad Request
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignResponse>
<ResponseStatus>
<ErrorCode>12185</ErrorCode>
<Description>A call to the campaign registry service has failed validation.</Description>
</ResponseStatus>
<Errors>
<Error>
<Code>501</Code>
<Field>resellerId</Field>
<Description>Reseller cannot be changed</Description>
</Error>
</Errors>
</CampaignResponse>

Error Codes#

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

Fetch campaign#

Request URL#

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

GET campaign#

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId} 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/campaigns/{campaignId}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignResponse>
<Campaign>
<CampaignId>CTW3YRE</CampaignId>
<Status>ACTIVE</Status>
<CreateDate>2021-06-23T12:35:48</CreateDate>
<AutoRenewal>true</AutoRenewal>
<BilledDate>2021-06-23T00:00</BilledDate>
<BrandId>B9AVERT</BrandId>
<Vertical>COMMUNICATION</Vertical>
<Usecase>2FA</Usecase>
<SubUsecases/>
<Description>Test Campaign</Description>
<ResellerId>RPTAYWZ</ResellerId>
<EmbeddedLink>false</EmbeddedLink>
<EmbeddedPhone>false</EmbeddedPhone>
<NumberPool>false</NumberPool>
<AgeGated>false</AgeGated>
<DirectLending>false</DirectLending>
<SubscriberOptIn>true</SubscriberOptIn>
<SubscriberOptOut>false</SubscriberOptOut>
<SubscriberHelp>true</SubscriberHelp>
<Sample1>test update sample</Sample1>
<AffiliateMarketing>false</AffiliateMarketing>
<MnoMetadataList>
<MnoMetadata>
<MnoId>10035</MnoId>
<MNO>T-Mobile</MNO>
<MnoSupport>true</MnoSupport>
<MnoReview>false</MnoReview>
<Qualify>true</Qualify>
<MinMessageSamples>1</MinMessageSamples>
<RequireSubscriberOptIn>true</RequireSubscriberOptIn>
<RequireSubscriberOptOut>false</RequireSubscriberOptOut>
<RequireSubscriberHelp>true</RequireSubscriberHelp>
<NoEmbeddedLink>false</NoEmbeddedLink>
<NoEmbeddedPhone>false</NoEmbeddedPhone>
<Surcharge>0.003</Surcharge>
<BrandTier>LOW</BrandTier>
</MnoMetadata>
<MnoMetadata>
<MnoId>10017</MnoId>
<MNO>ATT</MNO>
<MnoSupport>true</MnoSupport>
<MnoReview>false</MnoReview>
<Qualify>true</Qualify>
<MinMessageSamples>1</MinMessageSamples>
<RequireSubscriberOptIn>true</RequireSubscriberOptIn>
<RequireSubscriberOptOut>false</RequireSubscriberOptOut>
<RequireSubscriberHelp>true</RequireSubscriberHelp>
<NoEmbeddedLink>false</NoEmbeddedLink>
<NoEmbeddedPhone>false</NoEmbeddedPhone>
<Surcharge>0.002</Surcharge>
<MessageClass>C</MessageClass>
<TPM>600</TPM>
</MnoMetadata>
</MnoMetadataList>
<MnoStatusList>
<MnoStatus>
<MnoName>ATT</MnoName>
<MnoId>10017</MnoId>
<Status>APPROVED</Status>
</MnoStatus>
<MnoStatus>
<MnoName>TMO</MnoName>
<MnoId>10035</MnoId>
<Status>APPROVED</Status>
</MnoStatus>
</MnoStatusList>
<SharingStatus>false</SharingStatus>
</Campaign>
</CampaignResponse>

Error Response#

HTTP/1.1 404 Not Found
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignResponse>
<ResponseStatus>
<ErrorCode>12189</ErrorCode>
<Description>Campaign with id 'CTW3YRE' not found"</Description>
</ResponseStatus>
</CampaignResponse>

Error Codes#

HTTP/1.1 403 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests

Fetch campaign list#

Request URL#

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

GET campaign list#

This endpoint fetches a paginated list of all campaigns for your account.

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns?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/campaigns?page=0&size=2
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignsResponse>
<Campaigns>
<Campaign>
<CampaignId>CH1GMWI</CampaignId>
<Status>ACTIVE</Status>
<CreateDate>2021-05-25T19:06:23</CreateDate>
<AutoRenewal>true</AutoRenewal>
<BilledDate>2021-05-25T00:00</BilledDate>
<BrandId>B9AVERT</BrandId>
<Vertical>HEALTHCARE</Vertical>
<Usecase>2FA</Usecase>
<SubUsecases/>
<Description>test</Description>
<ResellerId>RPTAYWZ</ResellerId>
<EmbeddedLink>false</EmbeddedLink>
<EmbeddedPhone>false</EmbeddedPhone>
<NumberPool>false</NumberPool>
<AgeGated>false</AgeGated>
<DirectLending>false</DirectLending>
<SubscriberOptIn>true</SubscriberOptIn>
<SubscriberOptOut>false</SubscriberOptOut>
<SubscriberHelp>true</SubscriberHelp>
<Sample1>test</Sample1>
<AffiliateMarketing>false</AffiliateMarketing>
<MnoStatusList>
<MnoStatus>
<MnoName>ATT</MnoName>
<MnoId>10017</MnoId>
<Status>APPROVED</Status>
</MnoStatus>
<MnoStatus>
<MnoName>TMO</MnoName>
<MnoId>10035</MnoId>
<Status>APPROVED</Status>
</MnoStatus>
</MnoStatusList>
<SharingStatus>true</SharingStatus>
</Campaign>
<Campaign>
<CampaignId>CU3UTYW</CampaignId>
<Status>EXPIRED</Status>
<CreateDate>2021-06-03T11:50:16</CreateDate>
<AutoRenewal>false</AutoRenewal>
<BilledDate>2021-06-03T00:00</BilledDate>
<BrandId>B9AVERT</BrandId>
<Vertical>ENERGY</Vertical>
<Usecase>2FA</Usecase>
<SubUsecases/>
<Description>test</Description>
<ResellerId>RPTAYWZ</ResellerId>
<EmbeddedLink>false</EmbeddedLink>
<EmbeddedPhone>false</EmbeddedPhone>
<NumberPool>false</NumberPool>
<AgeGated>false</AgeGated>
<DirectLending>false</DirectLending>
<SubscriberOptIn>true</SubscriberOptIn>
<SubscriberOptOut>false</SubscriberOptOut>
<SubscriberHelp>true</SubscriberHelp>
<Sample1>test</Sample1>
<Sample2>test 15</Sample2>
<AffiliateMarketing>false</AffiliateMarketing>
<MnoStatusList>
<MnoStatus>
<MnoName>ATT</MnoName>
<MnoId>10017</MnoId>
<Status>APPROVED</Status>
</MnoStatus>
<MnoStatus>
<MnoName>TMO</MnoName>
<MnoId>10035</MnoId>
<Status>APPROVED</Status>
</MnoStatus>
</MnoStatusList>
<SharingStatus>true</SharingStatus>
</Campaign>
</Campaigns>
<TotalCount>17</TotalCount>
</CampaignsResponse>

Error Response#

HTTP/1.1 403 Unauthorized
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/campaigns?page=0&size=2
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignsResponse>
<ResponseStatus>
<ErrorCode>12055</ErrorCode>
<Description>CampaignManagement feature is not enabled on account 9999999</Description>
</ResponseStatus>
</CampaignsResponse>

Error Codes#

HTTP/1.1 403 Unauthorized
HTTP/1.1 429 Too Many Requests

Fetch campaign list by brand#

This endpoint fetches a paginated list of all campaigns for a given brandId.

Request URL#

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}/campaigns?page=0&size=2

GET campaign list by brand#

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}/campaigns?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/{brandId}/campaigns?page=0&size=2
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignsResponse>
<Campaigns>
<Campaign>
<CampaignId>CRVMWN6</CampaignId>
<Status>ACTIVE</Status>
<CreateDate>2021-05-21T14:17:47</CreateDate>
<AutoRenewal>true</AutoRenewal>
<BilledDate>2021-05-21T00:00</BilledDate>
<BrandId>B9AVERT</BrandId>
<Vertical>ENERGY</Vertical>
<Usecase>2FA</Usecase>
<SubUsecases/>
<Description>test</Description>
<ResellerId>RPTAYWZ</ResellerId>
<EmbeddedLink>false</EmbeddedLink>
<EmbeddedPhone>false</EmbeddedPhone>
<NumberPool>false</NumberPool>
<AgeGated>false</AgeGated>
<DirectLending>false</DirectLending>
<SubscriberOptIn>true</SubscriberOptIn>
<SubscriberOptOut>false</SubscriberOptOut>
<SubscriberHelp>true</SubscriberHelp>
<Sample1>test</Sample1>
<AffiliateMarketing>false</AffiliateMarketing>
<MnoStatusList>
<MnoStatus>
<MnoName>ATT</MnoName>
<MnoId>10017</MnoId>
<Status>APPROVED</Status>
</MnoStatus>
<MnoStatus>
<MnoName>TMO</MnoName>
<MnoId>10035</MnoId>
<Status>APPROVED</Status>
</MnoStatus>
</MnoStatusList>
<SharingStatus>true</SharingStatus>
</Campaign>
<Campaign>
<CampaignId>CX1YQLG</CampaignId>
<Status>ACTIVE</Status>
<CreateDate>2021-05-25T19:06:23</CreateDate>
<AutoRenewal>true</AutoRenewal>
<BilledDate>2021-05-25T00:00</BilledDate>
<BrandId>B9AVERT</BrandId>
<Vertical>HEALTHCARE</Vertical>
<Usecase>2FA</Usecase>
<SubUsecases/>
<Description>test</Description>
<ResellerId>RPTAYWZ</ResellerId>
<EmbeddedLink>false</EmbeddedLink>
<EmbeddedPhone>false</EmbeddedPhone>
<NumberPool>false</NumberPool>
<AgeGated>false</AgeGated>
<DirectLending>false</DirectLending>
<SubscriberOptIn>true</SubscriberOptIn>
<SubscriberOptOut>false</SubscriberOptOut>
<SubscriberHelp>true</SubscriberHelp>
<Sample1>test</Sample1>
<AffiliateMarketing>false</AffiliateMarketing>
<MnoStatusList>
<MnoStatus>
<MnoName>ATT</MnoName>
<MnoId>10017</MnoId>
<Status>APPROVED</Status>
</MnoStatus>
<MnoStatus>
<MnoName>TMO</MnoName>
<MnoId>10035</MnoId>
<Status>APPROVED</Status>
</MnoStatus>
</MnoStatusList>
<SharingStatus>true</SharingStatus>
</Campaign>
</Campaigns>
<TotalCount>6</TotalCount>
</CampaignsResponse>

Error Response#

HTTP/1.1 403 Unauthorized
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}/campaigns?page=0&size=2
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignsResponse>
<ResponseStatus>
<ErrorCode>12055</ErrorCode>
<Description>CampaignManagement feature is not enabled on account 9999999</Description>
</ResponseStatus>
</CampaignsResponse>

Error Codes#

HTTP/1.1 403 Unauthorized
HTTP/1.1 429 Too Many Requests

Deactivate campaign#

This endpoint will update the campaign status to 'EXPIRED'.

Request URL#

DELETE`https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId}`

DELETE campaign#

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

Response#

HTTP/1.1 204 No Content
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId}

Error Response#

HTTP/1.1 403 Unauthorized
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}/campaigns?page=0&size=2
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignResponse>
<ResponseStatus>
<ErrorCode>12055</ErrorCode>
<Description>CampaignManagement feature is not enabled on account 9999999</Description>
</ResponseStatus>
</CampaignResponse>

Error Codes#

HTTP/1.1 403 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests

Assign a campaign to a TN#

Assumption#

This endpoint assumes that TN(s) have already been ordered or ported into our system. For more info, please see our number ordering or number porting guides.

Request URL#

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/tnoptions
Request BodyMandatoryDescription
TnOptionGroupsYesA list of TnOptionGroup.
CustomerOrderIdNoOptional value for Id set by customer. Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters.
TnOptionGroupMandatoryDescription
SmsYes'on' or 'off'. Sms must be turned 'on' to enable A2pSettings
A2pSettingsYesAn object containing A2pSettings
TelephoneNumbersYesA list of Telephone Numbers to assign Campaign Id
A2pSettingsMandatoryDescription
CampaignIdYesThe Campaign Id provided by The Campaign Registry (TCR)
ActionYesMust be set to 'asSpecified'

POST Tn Options#

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/tnoptions HTTP/1.1
Content-Type: application/xml; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
<TnOptionOrder>
<TnOptionGroups>
<TnOptionGroup>
<Sms>on</Sms>
<A2pSettings>
<Action>asSpecified</Action>
<CampaignId>CJEUMDK</CampaignId>
</A2pSettings>
<TelephoneNumbers>
<TelephoneNumber>9999999999</TelephoneNumber>
<TelephoneNumber>8888888888</TelephoneNumber>
</TelephoneNumbers>
</TnOptionGroup>
</TnOptionGroups>
</TnOptionOrder>

Response#

HTTP/1.1 201 Created
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/accounts/{accountId}/tnoptions
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TnOptionOrderResponse>
<TnOptionOrder>
<OrderCreateDate>2021-04-14T18:17:17.791Z</OrderCreateDate>
<AccountId>000000000</AccountId>
<CreatedByUser>user</CreatedByUser>
<OrderId>ac48abbe-2311-4888-ca4a-05eaa336119c</OrderId>
<LastModifiedDate>2021-04-14T18:17:17.792Z</LastModifiedDate>
<ProcessingStatus>RECEIVED</ProcessingStatus>
<TnOptionGroups>
<TnOptionGroup>
<Sms>on</Sms>
<A2pSettings>
<CampaignId>CAHVRZA</CampaignId>
<Action>asSpecified</Action>
</A2pSettings>
<TelephoneNumbers>
<TelephoneNumber>9999999999</TelephoneNumber>
<TelephoneNumber>8888888888</TelephoneNumber>
</TelephoneNumbers>
</TnOptionGroup>
</TnOptionGroups>
<ErrorList/>
<Warnings/>
</TnOptionOrder>
</TnOptionOrderResponse>

Error Response#

HTTP/1.1 400 Bad Request
Content-Type: application/xml
Location: https://dashboard.bandwidth.com/api/accounts/accounts/{accountId}/tnoptions
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TnOptionOrderResponse>
<ResponseStatus>
<ErrorCode>5081</ErrorCode>
<Description>Number Format 'wrong' is invalid.</Description>
</ResponseStatus>
</TnOptionOrderResponse>

Error Codes#

HTTP/1.1 400 Bad Request
HTTP/1.1 409 Conflict

Bulk Assign a campaign to multiple TNs#

We do not have a publicly exposed REST endpoint for bulk TN updates. Please see how to import a csv in our CSP campaign Dashboard UI guide.
For more info on TNs, please see Number Management).
For more info on managing TN Line Features, please see our managing line features guide.

Next Steps#

There are many line options you can add to a TN. This section showed just how to turn SMS on and assign an A2P Campaign ID. For more detailed documentation on other types of TN Option Orders, please -

  1. Go to the Dashboard REST API Documentation
  2. Click on the /Accounts section
  3. Scroll until you see /accounts/{accountId}/tnoptions
  4. Click and see the POST endpoint with detailed descriptions

For more info on TNs, please see Number Management.