Bandwidth CSP Campaign API

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

Familiarity with Account API Credentials
Created an API Credential Pair within the UI
Your account has Messaging and Campaign Management products enabled
Your account has 10dlcCampaigns product feature enabled
Your user has been assigned the Campaign Management user role
You have registered a brand

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'.
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

Create campaign

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns

Request Body	Mandatory	Description
`Campaign`	Yes	An object containing brand information

Campaign	Mandatory	Description
`BrandId`	Yes	Alphanumeric identifier of the brand associated with this campaign
`Vertical`	No	Optional business/industry segment of this campaign (any value allowed) as TCR has deprecated this field.
`Usecase`	Yes	Campaign usecase. Must be of defined valid types
`SubUsecases`	No (Required for some usecases)	Campaign sub-usecases. Must be of defined valid types
`ResellerId`	No	Alphanumeric identifier of the reseller that you want to associate with this campaign.
`Description`	Yes	Summary description of this campaign. Min length 40. Max length 4096
`EmbeddedLink`	No	Does message generated by the campaign include URL link in SMS? Default false
`EmbeddedPhone`	No	Does message generated by the campaign include phone number in SMS? Default false
`NumberPool`	No	Does campaign utilize pool of phone numbers? Default false
`AgeGated`	No	Age gated content in campaign? Default false
`DirectLending`	No	Will the campaign include content related to direct lending or other loan arrangements? Default false
`SubscriberOptIn`	No	Does campaign require subscriber to opt-in before SMS is sent to subscriber? Default false
`SubscriberOptOut`	No	Does campaign support subscriber opt-out keyword(s)? Default false
`SubscriberHelp`	No	Have you implemented a response to the HELP keyword informing customers of how they can contact the message sender? Default false
`Sample1`	Yes	Message sample. Some campaign tiers require 1 or more message samples. Min length 20. Max length 1024
`Sample2`	No (Required for some usecases)	Message sample. Some campaign tiers require 2 or more message samples. Min length 20. Max length 1024
`Sample3`	No (Required for some usecases)	Message sample. Some campaign tiers require 3 or more message samples. Min length 20. Max length 1024
`Sample4`	No (Required for some usecases)	Message sample. Some campaign tiers require 4 or more message samples. Min length 20. Max length 1024
`Sample5`	No (Required for some usecases)	Message sample. Some campaign tiers require 5 message samples. Min length 20. Max length 1024
`MessageFlow`	Yes	Message flow description. Min length 40. Max length 2048
`HelpMessage`	Yes	Help message of the campaign. Min length 20. Max length 320
`HelpKeywords`	No	Help keywords of the campaign. Max length 320. TCR will default the value to HELP. Multiple keywords are comma separated without space.
`OptinMessage`	No	Opt-In message of the campaign. Min length 20. Max length 320
`OptinKeywords`	No	Opt-In keywords of the campaign. Max length 320. Multiple keywords are comma separated without space.
`OptoutMessage`	Yes	Opt-Out message of the campaign. Min length 20. Max length 320
`OptoutKeywords`	No	Opt-Out keywords of the campaign. Max length 320. TCR will default the value to STOP. Multiple keywords are comma separated without space.
`AffiliateMarketing`	No	Is affiliate marketing being used (or was used in the creation of the campaign)? Default false
`ReferenceId`	No	Caller 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
`AutoRenewal`	Yes	Campaign subscription auto-renewal status. Default true

Examples

Request

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>
  <MessageFlow>This is a sample Message Flow of my campaign.</MessageFlow>
  <HelpKeywords>HELP</HelpKeywords>
  <HelpMessage>This is a sample Help Message of my campaign.</HelpMessage>
  <OptinKeywords>START,YES</OptinKeywords>
  <OptinMessage>This is a sample Opt-In Message of my campaign.</OptinMessage>
  <OptoutKeywords>STOP,NO</OptoutKeywords>
  <OptoutMessage>This is a sample Opt-Out Message of my campaign.</OptoutMessage>
</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>
		<SecondaryDcaSharingStatus>PENDING</SecondaryDcaSharingStatus>
		<AffiliateMarketing>false</AffiliateMarketing>
        <MessageFlow>This is a sample Message Flow of my campaign.</MessageFlow>
        <HelpKeywords>HELP</HelpKeywords>
        <HelpMessage>This is a sample Help Message of my campaign.</HelpMessage>
        <OptinKeywords>START,YES</OptinKeywords>
        <OptinMessage>This is a sample Opt-In Message of my campaign.</OptinMessage>
        <OptoutKeywords>STOP,NO</OptoutKeywords>
        <OptoutMessage>This is a sample Opt-Out Message of my campaign.</OptoutMessage>
		<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>

Update campaign

Request URL

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

Request Body	Mandatory	Description
`Campaign`	Yes	An object containing brand information

Campaign	Mandatory	Editable	Description
`ResellerId`	No	Yes	Alphanumeric identifier of the reseller that you want to associate with this campaign.
`Sample1`	No	Yes	Message sample. Some campaign tiers require 1 or more message samples. Min length 20. Max length 1024
`Sample2`	No (Required for some usecases)	Yes	Message sample. Some campaign tiers require 2 or more message samples. Min length 20. Max length 1024
`Sample3`	No (Required for some usecases)	Yes	Message sample. Some campaign tiers require 3 or more message samples. Min length 20. Max length 1024
`Sample4`	No (Required for some usecases)	Yes	Message sample. Some campaign tiers require 4 or more message samples. Min length 20. Max length 1024
`Sample5`	No (Required for some usecases)	Yes	Message sample. Some campaign tiers require 5 message samples. Min length 20. Max length 1024
`MessageFlow`	Yes	Yes	Message flow description. Min length 40. Max length 2048
`HelpMessage`	Yes	Yes	Help message of the campaign. Min length 20. Max length 320
`AutoRenewal`	No	Yes	Campaign subscription auto-renewal status. Default true
`BrandId`	Yes	No	Alphanumeric identifier of the brand associated with this campaign
`Vertical`	No	No	Optional business/industry segment of this campaign (any value allowed) as TCR has deprecated this field.
`Usecase`	Yes	No	Campaign usecase. Must be of defined valid types
`SubUsecases`	No (Required for some usecases)	No	Campaign sub-usecases. Must be of defined valid types
`Description`	Yes	No	Summary description of this campaign. Max length 4096
`EmbeddedLink`	No	No	Does message generated by the campaign include URL link in SMS? Default false
`EmbeddedPhone`	No	No	Does message generated by the campaign include phone number in SMS? Default false
`NumberPool`	No	No	Does campaign utilize pool of phone numbers? Default false
`AgeGated`	No	No	Age gated content in campaign? Default false
`DirectLending`	No	No	Will the campaign include content related to direct lending or other loan arrangements? Default false
`SubscriberOptIn`	No	No	Does campaign require subscriber to opt-in before SMS is sent to subscriber? Default false
`SubscriberOptOut`	No	No	Does campaign support subscriber opt-out keyword(s)? Default false
`SubscriberHelp`	No	No	Have you implemented a response to the HELP keyword informing customers of how they can contact the message sender? Default false
`AffiliateMarketing`	No	No	Is affiliate marketing being used (or was used in the creation of the campaign)? Default false
`ReferenceId`	No	No	Caller 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
`HelpKeywords`	No	Yes	Help keywords of the campaign. Max length 320. TCR will default the value to HELP. Multiple keywords are comma separated without space.
`OptinMessage`	No	Yes	Opt-In message of the campaign. Min length 20. Max length 320
`OptinKeywords`	No	Yes	Opt-In keywords of the campaign. Max length 320. Multiple keywords are comma separated without space.
`OptoutMessage`	Yes	Yes	Opt-Out message of the campaign. Min length 20. Max length 320
`OptoutKeywords`	No	Yes	Opt-Out keywords of the campaign. Max length 320. TCR will default the value to STOP. Multiple keywords are comma separated without space.

Examples

Request

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>
        <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>
        <SecondaryDcaSharingStatus>PENDING</SecondaryDcaSharingStatus>
        <AffiliateMarketing>false</AffiliateMarketing>
        <MessageFlow>This is a sample Message Flow of my campaign.</MessageFlow>
        <HelpKeywords>HELP</HelpKeywords>
        <HelpMessage>This is a sample Help Message of my campaign.</HelpMessage>
        <OptinKeywords>START,YES</OptinKeywords>
        <OptinMessage>This is a sample Opt-In Message of my campaign.</OptinMessage>
        <OptoutKeywords>STOP,NO</OptoutKeywords>
        <OptoutMessage>This is a sample Opt-Out Message of my campaign.</OptoutMessage>
    </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>

Fetch campaign

Request URL

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

Examples

Request

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>
		<SecondaryDcaSharingStatus>ACCEPTED</SecondaryDcaSharingStatus>
		<AffiliateMarketing>false</AffiliateMarketing>
		<MessageFlow>This is a sample Message Flow of my campaign.</MessageFlow>
        <HelpKeywords>HELP</HelpKeywords>
        <HelpMessage>This is a sample Help Message of my campaign.</HelpMessage>
        <OptinKeywords>START,YES</OptinKeywords>
        <OptinMessage>This is a sample Opt-In Message of my campaign.</OptinMessage>
        <OptoutKeywords>STOP,NO</OptoutKeywords>
        <OptoutMessage>This is a sample Opt-Out Message of my campaign.</OptoutMessage>
		<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>

Fetch campaign list

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

Request URL

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

Examples

Request

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>
            <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>
            <SecondaryDcaSharingStatus>PENDING</SecondaryDcaSharingStatus>
            <AffiliateMarketing>false</AffiliateMarketing>
            <MessageFlow>This is a sample Message Flow of my campaign.</MessageFlow>
            <HelpKeywords>HELP</HelpKeywords>
            <HelpMessage>This is a sample Help Message of my campaign.</HelpMessage>
            <OptinKeywords>START,YES</OptinKeywords>
            <OptinMessage>This is a sample Opt-In Message of my campaign.</OptinMessage>
            <OptoutKeywords>STOP,NO</OptoutKeywords>
            <OptoutMessage>This is a sample Opt-Out Message of my campaign.</OptoutMessage>
            <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>
            <SecondaryDcaSharingStatus>DECLINED</SecondaryDcaSharingStatus>
            <SecondaryDcaDeclineReason>Campaign was declined.</SecondaryDcaDeclineReason>
            <AffiliateMarketing>false</AffiliateMarketing>
            <MessageFlow>This is a sample Message Flow of my campaign.</MessageFlow>
            <HelpKeywords>HELP</HelpKeywords>
            <HelpMessage>This is a sample Help Message of my campaign.</HelpMessage>
            <OptinKeywords>START, YES</OptinKeywords>
            <OptinMessage>This is a sample Opt-In Message of my campaign.</OptinMessage>
            <OptoutKeywords>STOP, NO</OptoutKeywords>
            <OptoutMessage>This is a sample Opt-Out Message of my campaign.</OptoutMessage>
            <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>

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

Examples

Request

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>
            <SecondaryDcaSharingStatus>ACCEPTED</SecondaryDcaSharingStatus>
            <AffiliateMarketing>false</AffiliateMarketing>
            <MessageFlow>This is a sample Message Flow of my campaign.</MessageFlow>
            <HelpKeywords>HELP</HelpKeywords>
            <HelpMessage>This is a sample Help Message of my campaign.</HelpMessage>
            <OptinKeywords>START,YES</OptinKeywords>
            <OptinMessage>This is a sample Opt-In Message of my campaign.</OptinMessage>
            <OptoutKeywords>STOP,NO</OptoutKeywords>
            <OptoutMessage>This is a sample Opt-Out Message of my campaign.</OptoutMessage>
            <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>
            <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>
            <SecondaryDcaSharingStatus>DECLINED</SecondaryDcaSharingStatus>
            <SecondaryDcaDeclineReason>Campaign was declined.</SecondaryDcaDeclineReason>
            <AffiliateMarketing>false</AffiliateMarketing>
            <MessageFlow>This is a sample Message Flow of my campaign.</MessageFlow>
            <HelpKeywords>HELP</HelpKeywords>
            <HelpMessage>This is a sample Help Message of my campaign.</HelpMessage>
            <OptinKeywords>START,YES</OptinKeywords>
            <OptinMessage>This is a sample Opt-In Message of my campaign.</OptinMessage>
            <OptoutKeywords>STOP,NO</OptoutKeywords>
            <OptoutMessage>This is a sample Opt-Out Message of my campaign.</OptoutMessage>
            <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>

Deactivate campaign

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

Request URL

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

Examples

Request

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>

Re-Vet campaign

This endpoint will send a reverification request to TCR for DCA2 declined campaign.

Request URL

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

Examples

Request

PUT https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/campaigns/{campaignId}/revet 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}/revet

Error Response

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

<?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>

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignResponse>
    <ResponseStatus>
        <ErrorCode>12189</ErrorCode>
        <Description>Campaign with id 'CTW3YRE' not found"</Description>
    </ResponseStatus>
</CampaignResponse>

Update Campaign TN Relationship

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

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

Request Body	Mandatory	Description
`TnOptionGroups`	Yes	A list of TnOptionGroup.
`CustomerOrderId`	No	Optional value for Id set by customer. Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters.

TnOptionGroup	Mandatory	Description
`Sms`	Yes	'on' or 'off'. Sms must be turned 'on' to enable A2pSettings
`A2pSettings`	Yes	An object containing A2pSettings
`TelephoneNumbers`	Yes	A list of Telephone Numbers to assign Campaign Id

A2pSettings	Mandatory	Description
`CampaignId`	No	The Campaign Id provided by The Campaign Registry (TCR). Leave this field out if deleting
`Action`	Yes	Must be set to 'asSpecified' to add campaign or 'delete' to remove

Examples

Request

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>

Fetch Campaign TNs

This endpoint allows you to fetch the telephone numbers that have been registered to a specific campaign.

Request URL

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

Examples

Request

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

Response

HTTP/1.1 200 No Content
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignTnsResponse>
  <TotalCount>1</TotalCount>
  <TelephoneNumbers>
    <TelephoneNumber>8888888888</TelephoneNumber>
  </TelephoneNumbers>
</CampaignTnsResponse>

Error Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CampaignTnsResponse>
  <ResponseStatus>
    <ErrorCode>5081</ErrorCode>
    <Description>Number Format 'wrong' is invalid.</Description>
  </ResponseStatus>
</CampaignTnsResponse>

Bulk Update Campaign TN Relationships

We do not have a publicly exposed REST endpoint for bulk TN updates. Please see how to import a csv in our CSP campaign App 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 -

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

For more info on TNs, please see Number Management.

Assumptions​

Important Notes​

API Authentication​

API Error Codes​

Getting Started​

Create campaign​

Request URL​

Examples​

Update campaign​

Request URL​

Examples​

Fetch campaign​

Request URL​

Examples​

Fetch campaign list​

Request URL​

Examples​

Fetch campaign list by brand​

Request URL​

Examples​

Deactivate campaign​

Request URL​

Examples​

Re-Vet campaign​

Request URL​

Examples​

Update Campaign TN Relationship​

Assumption​

Request URL​

Examples​

Fetch Campaign TNs​

Request URL​

Examples​

Bulk Update Campaign TN Relationships​

Next Steps​

Assumptions

Important Notes

API Authentication

API Error Codes

Getting Started

Create campaign

Request URL

Examples

Update campaign

Request URL

Examples

Fetch campaign

Request URL

Examples

Fetch campaign list

Request URL

Examples

Fetch campaign list by brand

Request URL

Examples

Deactivate campaign

Request URL

Examples

Re-Vet campaign

Request URL

Examples

Update Campaign TN Relationship

Assumption

Request URL

Examples

Fetch Campaign TNs

Request URL

Examples

Bulk Update Campaign TN Relationships

Next Steps