Brand Vetting API

This walks through how to programmatically use external vetting providers and re-vet your brands via APIs for use with our Campaign, 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 created an existing Brand
If re-vetting, existing brand must be Unverified

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'.
There are fees associated with both external vetting and re-vetting of brands.
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

Request Brand Re-vet

Request URL

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

Request Body	Mandatory	Description
NONE	N/A	This request takes no request body

Examples

Request

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BrandRevetResponse>
    <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>
</BrandRevetResponse>

Error Response

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

<?xml version="1.0" encoding="UTF-8"?>
<BrandRevetResponse>
   <ResponseStatus>
      <ErrorCode>12210</ErrorCode>
      <Description>The Brand 'BEAQBHG'  with identity status 'VETTED_VERIFIED' not allowed to revet</Description>
   </ResponseStatus>
</BrandRevetResponse>

Request External Vetting

Request URL

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

Request Body	Mandatory	Description
`EvpId`	Yes	The External Vetting Provider ID, 'AEGIS' or 'WMC' ('CV' is not currently supported by vetting requests)
`VettingClass`	Yes	Vetting Class, 'STANDARD' or 'POLITICAL'

Examples

Request

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

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<BrandVetting>
  <EvpId>WMC</EvpId>
  <VettingId>STANDARD</VettingId>
</BrandVetting>

Response

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

<?xml version="1.0" encoding="UTF-8"?>
<BrandVettingResponse>
   <BrandVetting>
      <EvpId>WMC</EvpId>
      <VettingId>0FBBD8A674134C20A7D2193CE525FDF5</VettingId>
      <VettingClass>STANDARD</VettingClass>
      <VettingStatus>PENDING</VettingStatus>
      <CreateDate>2022-01-25T20:25:34.777</CreateDate>
   </BrandVetting>
</BrandVettingResponse>

Error Response

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

<?xml version="1.0" encoding="UTF-8"?>
<BrandVettingResponse>
   <ResponseStatus>
      <ErrorCode>12185</ErrorCode>
      <Description>A call to the campaign registry service has failed validation.</Description>
   </ResponseStatus>
   <Errors>
      <Error>
         <Code>525</Code>
         <Description>Vetting re-submission not allowed with same brand information.</Description>
      </Error>
   </Errors>
</BrandVettingResponse>

Import External Vetting Records

Request URL

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

Request Body	Mandatory	Description
`EvpId`	Yes	The External Vetting Provider ID, 'AEGIS', 'WMC', or 'CV'
`VettingId`	Yes	The ID of the vetting record you wish to import
`VettingToken`	Yes	(Only required by AEGIS) Token supplied by AEGIS required to import

Examples

Request

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

<?xml version="1.0" encoding="UTF-8"?>
<BrandVetting>
  <EvpId>AEGIS</EvpId>
  <VettingId>531D1FD09D68401EA0E4624B8B7D4A14</VettingId>
</BrandVetting>

Response

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

<?xml version="1.0" encoding="UTF-8"?>
<BrandVettingResponse>
   <BrandVetting>
      <EvpId>AEGIS</EvpId>
      <VettingId>531D1FD09D68401EA0E4624B8B7D4A14</VettingId>
      <VettingScore>88</VettingScore>
      <VettingClass>STANDARD</VettingClass>
      <VettingStatus>ACTIVE</VettingStatus>
      <CreateDate>2021-11-22T19:58:08</CreateDate>
      <VettedDate>2021-11-22T19:58:38</VettedDate>
   </BrandVetting>
</BrandVettingResponse>Z

Error Response

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

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

Fetch External Vetting Records

Request URL

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

Examples

Request

GET https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}/vetting 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}/vetting

<?xml version="1.0" encoding="UTF-8"?>
<BrandVettingsResponse>
   <BrandVettings>
      <BrandVetting>
         <EvpId>WMC</EvpId>
         <VettingId>531D1FD09D68401EA0E4624B8B7D4A14</VettingId>
         <VettingScore>88</VettingScore>
         <VettingClass>STANDARD</VettingClass>
         <VettingStatus>ACTIVE</VettingStatus>
         <CreateDate>2021-11-22T19:58:08</CreateDate>
         <VettedDate>2021-11-22T19:58:38</VettedDate>
      </BrandVetting>
      <BrandVetting>
         <EvpId>AEGIS</EvpId>
         <VettingId>2ee15ee2-8e77-4c5c-ed14-08d99db075c6</VettingId>
         <VettingScore>80</VettingScore>
         <VettingClass>STANDARD</VettingClass>
         <VettingStatus>ACTIVE</VettingStatus>
         <CreateDate>2021-11-22T18:13:37</CreateDate>
         <VettedDate>2021-11-22T18:13:37</VettedDate>
      </BrandVetting>
   </BrandVettings>
</BrandVettingsResponse>

Error Response

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

<?xml version="1.0" encoding="UTF-8"?>
<BrandVettingResponse>
   <ResponseStatus>
      <ErrorCode>12185</ErrorCode>
      <Description>A call to the campaign registry service has failed validation.</Description>
   </ResponseStatus>
   <Errors>
      <Error>
         <Code>525</Code>
         <Description>Vetting re-submission not allowed with same brand information.</Description>
      </Error>
   </Errors>
</BrandVettingResponse>

Resend 2FA Email Verification

Request URL

POSThttps://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}/2faEmail

Request

POST https://dashboard.bandwidth.com/api/accounts/{accountId}/campaignManagement/10dlc/brands/{brandId}/2faEmail 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/brands/{brandId}/2faEmail

Next Steps

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

Assumptions​

Important Notes​

API Authentication​

API Error Codes​

Getting Started​

Request Brand Re-vet​

Request URL​

Examples​

Request External Vetting​

Request URL​

Examples​

Import External Vetting Records​

Request URL​

Examples​

Fetch External Vetting Records​

Request URL​

Examples​

Resend 2FA Email Verification​

Request URL​

Next Steps​

Assumptions

Important Notes

API Authentication

API Error Codes

Getting Started

Request Brand Re-vet

Request URL

Examples

Request External Vetting

Request URL

Examples

Import External Vetting Records

Request URL

Examples

Fetch External Vetting Records

Request URL

Examples

Resend 2FA Email Verification

Request URL

Next Steps