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

Getting Started

1. Request Brand Re-vet
2. Request External Vetting
3. Import External Vetting Records
4. Fetch External Vetting Records

Request Brand Re-vet

Request URL

PUT https://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

POST https://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

PUT https://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

GET https://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>

Next Steps

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

---