Brands Campaigns Numbers Errors
 
 

10DLC Brand and Campaign Provisioning

APIs relating to 10DLC brand and campaign management

Jump to:

Brands »

APIs relating to working with Brands

Campaigns »

APIs relating to working with Campaigns

Numbers »

APIs relating to working with Numbers in Campaigns

Retrieve all of the brands associated with your account.

List brands

GET https://api-eu.vonage.com/v1/10dlc/brands
Host https://api-eu.vonage.com
GET /v1/10dlc/brands

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Query Parameter

page
integer

Page of results to jump to

page_size
integer

Number of results per page

Responses

200 List of brands that are associated with an account
page_size
integer

Items per page

page
integer

Page Offset

total_pages
integer

Number of pages in the entire result set

total_items
integer

Number of items in the entire result set

_embedded
object
brands
array

Example Responses

200 400 401 404 422
{
  "page_size": 10,
  "page": 2,
  "total_pages": 100,
  "total_items": 100,
  "_embedded": {
    "brands": [
      {
        "account_id": "abcd1234",
        "primary_account_id": "abcd1234",
        "entity_type": "PUBLIC_PROFIT",
        "first_name": "John",
        "last_name": "Smith",
        "display_name": "Vonage",
        "company_name": "Vonage",
        "ein": "20-1111111",
        "ein_issuing_country": "US",
        "universal_ein": "20-1111111",
        "alt_business_id_type": "DUNS",
        "alt_business_id": "150483782",
        "phone": "+15556660001",
        "street": "23 Main Street",
        "city": "Holmdel",
        "state": "NJ",
        "postal_code": "07733",
        "country": "US",
        "email": "devrel@vonage.com",
        "stock_symbol": "VG",
        "stock_exchange": "NASDAQ",
        "website": "https://vonage.com",
        "vertical": "TECHNOLOGY",
        "campaign_count": 5,
        "brand_relationship": "BASIC_ACCOUNT",
        "partner": false,
        "shared": false,
        "owner": false,
        "status": "abc123",
        "reference_id": "abc123",
        "brand_id": "BLQKOPK",
        "created_date": "2020-01-02 05:12:14",
        "last_updated": "2020-02-02 14:12:00",
        "_links": {
          "self": {
            "href": "https://api.nexmo.com/10dlc/brands/BLQKOPK"
          },
          "campaigns": {
            "href": "https://api.nexmo.com/10dlc/brands/BLQKOPK/campaigns"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK?page=2"
    },
    "next": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/?page=1"
    },
    "previous": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/?page=1"
    },
    "first": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/?page=1"
    },
    "last": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/?page=10"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-brand-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your brand, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "company_name",
      "description": "Field 'company_name' is not unique"
    }
  ]
}

Create a new brand for your account

Create a new brand for your account. Register the brand under your CSP account. Mandatory fields vary depending on the type of entity being registered, so be sure to select the type that best represents the brand you wish to create at the top of the Request body table below. Most accounts will be created immediately, and you can move on to qualifying a new campaign for the brand. Some brands may require additional vetting. In such cases, please move on to the vetting API endpoints before attempting to create a campaign.

Please note the entity_type field, as that field value will help determine which fields are required.

POST https://api-eu.vonage.com/v1/10dlc/brands
Host https://api-eu.vonage.com
POST /v1/10dlc/brands

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Request body application/json

account_id
string | Required

The Vonage Account ID

entity_type
string | Required

Entity type behind the brand. This is the form of business establishment. Please refer to the /enum endpoint for an update list of valid values.

Must be one of: PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT or SOLE_PROPRIETOR
display_name
string | Required | Max: 255

Display or marketing name of the brand.

company_name
string | Required | Max: 255

Legal company name.

ein
string | Required | Max: 21

(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.

phone
string | Required

Valid phone number in E.164 international format without the + prefix.

street
string | Required | Max: 100

Street number and name.

city
string | Required | Max: 100

City name

state
string | Required | Max: 20

State. Must be 2 letters code for U.S.A.

postal_code
string | Required | Max: 10

Postal codes. Use 5 digit zipcode for United States

country
string | Required

ISO3166-Alpha2 country code.

email
string | Required | Max: 100

Valid email address of brand support contact.

vertical
string | Required

Business/industry segment of this campaign.

Must be one of: UNKNOWN, REAL_ESTATE, HEALTHCARE, ENERGY, ENTERTAINMENT, RETAIL, AGRICULTURE, INSURANCE, EDUCATION, HOSPITALITY, FINANCIAL, GAMBLING, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY or COMMUNICATION
primary_account_id
string

The Vonage Primary Account ID (the parent account of account_id).

first_name
string | Max: 100

First name of business contact.

last_name
string | Max: 100

Last name of business contact.

ein_issuing_country
string

ISO3166-Alpha2 country code.

universal_ein
string | Max: 50

Universal EIN of Brand, Read-Only

alt_business_id_type
string | Max: 50

Required if alt_business_id is provided.

Must be one of: DUNS, GIIN or LEI
alt_business_id
string | Max: 50

Required if alt_business_id_type is provided.

stock_symbol
string | Max: 10

Stock Symbol - Required if entity_type=PUBLIC_PROFIT.

stock_exchange
string | Max: 10

Required if entity_type=PUBLIC_PROFIT.

Must be one of: NONE, AMEX, AMX, ASX, B3, BME, BSE, FRA, ICEX, JSE, KRX, LON, NASDAQ, NSE, NYSE, OMX, SEHK, SSE, STO, SWX, SZSE, TSX, TWSE or VSE
website
string

Brand website URL.

account_id
string | Required

The Vonage Account ID

entity_type
string | Required

Entity type behind the brand. This is the form of business establishment. Please refer to the /enum endpoint for an update list of valid values.

Must be one of: PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT or SOLE_PROPRIETOR
display_name
string | Required | Max: 255

Display or marketing name of the brand.

company_name
string | Required | Max: 255

Legal company name.

ein
string | Required | Max: 21

(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.

phone
string | Required

Valid phone number in E.164 international format without the + prefix.

street
string | Required | Max: 100

Street number and name.

city
string | Required | Max: 100

City name

state
string | Required | Max: 20

State. Must be 2 letters code for U.S.A.

postal_code
string | Required | Max: 10

Postal codes. Use 5 digit zipcode for United States

country
string | Required

ISO3166-Alpha2 country code.

email
string | Required | Max: 100

Valid email address of brand support contact.

vertical
string | Required

Business/industry segment of this campaign.

Must be one of: UNKNOWN, REAL_ESTATE, HEALTHCARE, ENERGY, ENTERTAINMENT, RETAIL, AGRICULTURE, INSURANCE, EDUCATION, HOSPITALITY, FINANCIAL, GAMBLING, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY or COMMUNICATION
primary_account_id
string

The Vonage Primary Account ID (the parent account of account_id).

first_name
string | Max: 100

First name of business contact.

last_name
string | Max: 100

Last name of business contact.

ein_issuing_country
string

ISO3166-Alpha2 country code.

universal_ein
string | Max: 50

Universal EIN of Brand, Read-Only

alt_business_id_type
string | Max: 50

Required if alt_business_id is provided.

Must be one of: DUNS, GIIN or LEI
alt_business_id
string | Max: 50

Required if alt_business_id_type is provided.

stock_symbol
string | Max: 10

Stock Symbol - Required if entity_type=PUBLIC_PROFIT.

stock_exchange
string | Max: 10

Required if entity_type=PUBLIC_PROFIT.

Must be one of: NONE, AMEX, AMX, ASX, B3, BME, BSE, FRA, ICEX, JSE, KRX, LON, NASDAQ, NSE, NYSE, OMX, SEHK, SSE, STO, SWX, SZSE, TSX, TWSE or VSE
website
string

Brand website URL.

account_id
string | Required

The Vonage Account ID

entity_type
string | Required

Entity type behind the brand. This is the form of business establishment. Please refer to the /enum endpoint for an update list of valid values.

Must be one of: PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT or SOLE_PROPRIETOR
display_name
string | Required | Max: 255

Display or marketing name of the brand.

company_name
string | Required | Max: 255

Legal company name.

ein
string | Required | Max: 21

(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.

phone
string | Required

Valid phone number in E.164 international format without the + prefix.

street
string | Required | Max: 100

Street number and name.

city
string | Required | Max: 100

City name

state
string | Required | Max: 20

State. Must be 2 letters code for U.S.A.

postal_code
string | Required | Max: 10

Postal codes. Use 5 digit zipcode for United States

country
string | Required

ISO3166-Alpha2 country code.

email
string | Required | Max: 100

Valid email address of brand support contact.

stock_symbol
string | Required | Max: 10

Stock Symbol - Required if entity_type=PUBLIC_PROFIT.

stock_exchange
string | Required | Max: 10

Required if entity_type=PUBLIC_PROFIT.

Must be one of: NONE, AMEX, AMX, ASX, B3, BME, BSE, FRA, ICEX, JSE, KRX, LON, NASDAQ, NSE, NYSE, OMX, SEHK, SSE, STO, SWX, SZSE, TSX, TWSE or VSE
vertical
string | Required

Business/industry segment of this campaign.

Must be one of: UNKNOWN, REAL_ESTATE, HEALTHCARE, ENERGY, ENTERTAINMENT, RETAIL, AGRICULTURE, INSURANCE, EDUCATION, HOSPITALITY, FINANCIAL, GAMBLING, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY or COMMUNICATION
primary_account_id
string

The Vonage Primary Account ID (the parent account of account_id).

first_name
string | Max: 100

First name of business contact.

last_name
string | Max: 100

Last name of business contact.

ein_issuing_country
string

ISO3166-Alpha2 country code.

universal_ein
string | Max: 50

Universal EIN of Brand, Read-Only

alt_business_id_type
string | Max: 50

Required if alt_business_id is provided.

Must be one of: DUNS, GIIN or LEI
alt_business_id
string | Max: 50

Required if alt_business_id_type is provided.

website
string

Brand website URL.

account_id
string | Required

The Vonage Account ID

entity_type
string | Required

Entity type behind the brand. This is the form of business establishment. Please refer to the /enum endpoint for an update list of valid values.

Must be one of: PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT or SOLE_PROPRIETOR
first_name
string | Required | Max: 100

First name of business contact.

last_name
string | Required | Max: 100

Last name of business contact.

display_name
string | Required | Max: 255

Display or marketing name of the brand.

company_name
string | Required | Max: 255

Legal company name.

ein
string | Required | Max: 21

(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.

phone
string | Required

Valid phone number in E.164 international format without the + prefix.

street
string | Required | Max: 100

Street number and name.

city
string | Required | Max: 100

City name

state
string | Required | Max: 20

State. Must be 2 letters code for U.S.A.

postal_code
string | Required | Max: 10

Postal codes. Use 5 digit zipcode for United States

country
string | Required

ISO3166-Alpha2 country code.

email
string | Required | Max: 100

Valid email address of brand support contact.

primary_account_id
string

The Vonage Primary Account ID (the parent account of account_id).

ein_issuing_country
string

ISO3166-Alpha2 country code.

universal_ein
string | Max: 50

Universal EIN of Brand, Read-Only

alt_business_id_type
string | Max: 50

Required if alt_business_id is provided.

Must be one of: DUNS, GIIN or LEI
alt_business_id
string | Max: 50

Required if alt_business_id_type is provided.

stock_symbol
string | Max: 10

Stock Symbol - Required if entity_type=PUBLIC_PROFIT.

stock_exchange
string | Max: 10

Required if entity_type=PUBLIC_PROFIT.

Must be one of: NONE, AMEX, AMX, ASX, B3, BME, BSE, FRA, ICEX, JSE, KRX, LON, NASDAQ, NSE, NYSE, OMX, SEHK, SSE, STO, SWX, SZSE, TSX, TWSE or VSE
website
string

Brand website URL.

vertical
string

Business/industry segment of this campaign.

Must be one of: UNKNOWN, REAL_ESTATE, HEALTHCARE, ENERGY, ENTERTAINMENT, RETAIL, AGRICULTURE, INSURANCE, EDUCATION, HOSPITALITY, FINANCIAL, GAMBLING, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY or COMMUNICATION

Responses

201 Return a single brand

Example Request » Non-Profit

{
  "account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "vertical": "TECHNOLOGY"
}
{
  "account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "vertical": "TECHNOLOGY",
  "primary_account_id": "abcd1234",
  "first_name": "John",
  "last_name": "Smith",
  "ein_issuing_country": "US",
  "universal_ein": "20-1111111",
  "alt_business_id_type": "DUNS",
  "alt_business_id": "150483782",
  "stock_symbol": "VG",
  "stock_exchange": "NASDAQ",
  "website": "https://vonage.com"
}

Example Request » Private Company

{
  "account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "vertical": "TECHNOLOGY"
}
{
  "account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "vertical": "TECHNOLOGY",
  "primary_account_id": "abcd1234",
  "first_name": "John",
  "last_name": "Smith",
  "ein_issuing_country": "US",
  "universal_ein": "20-1111111",
  "alt_business_id_type": "DUNS",
  "alt_business_id": "150483782",
  "stock_symbol": "VG",
  "stock_exchange": "NASDAQ",
  "website": "https://vonage.com"
}

Example Request » Public Company

{
  "account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "stock_symbol": "VG",
  "stock_exchange": "NASDAQ",
  "vertical": "TECHNOLOGY"
}
{
  "account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "stock_symbol": "VG",
  "stock_exchange": "NASDAQ",
  "vertical": "TECHNOLOGY",
  "primary_account_id": "abcd1234",
  "first_name": "John",
  "last_name": "Smith",
  "ein_issuing_country": "US",
  "universal_ein": "20-1111111",
  "alt_business_id_type": "DUNS",
  "alt_business_id": "150483782",
  "website": "https://vonage.com"
}

Example Request » Sole Proprietor

{
  "account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "first_name": "John",
  "last_name": "Smith",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com"
}
{
  "account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "first_name": "John",
  "last_name": "Smith",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "primary_account_id": "abcd1234",
  "ein_issuing_country": "US",
  "universal_ein": "20-1111111",
  "alt_business_id_type": "DUNS",
  "alt_business_id": "150483782",
  "stock_symbol": "VG",
  "stock_exchange": "NASDAQ",
  "website": "https://vonage.com",
  "vertical": "TECHNOLOGY"
}

Example Responses

201 400 401 404 409 422
{
  "account_id": "abcd1234",
  "primary_account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "first_name": "John",
  "last_name": "Smith",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "ein_issuing_country": "US",
  "universal_ein": "20-1111111",
  "alt_business_id_type": "DUNS",
  "alt_business_id": "150483782",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "stock_symbol": "VG",
  "stock_exchange": "NASDAQ",
  "website": "https://vonage.com",
  "vertical": "TECHNOLOGY",
  "campaign_count": 5,
  "brand_relationship": "BASIC_ACCOUNT",
  "partner": false,
  "shared": false,
  "owner": false,
  "status": "abc123",
  "reference_id": "abc123",
  "brand_id": "BLQKOPK",
  "created_date": "2020-01-02 05:12:14",
  "last_updated": "2020-02-02 14:12:00",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/10dlc/brands/BLQKOPK"
    },
    "campaigns": {
      "href": "https://api.nexmo.com/10dlc/brands/BLQKOPK/campaigns"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#brand-conflict",
  "title": "An error occurred with this brand while communicating with a third party",
  "detail": "An unknown error occurred while processing this brand with the carrier system. Please contact support or try again later.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-brand-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your brand, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "company_name",
      "description": "Field 'company_name' is not unique"
    }
  ]
}

Retrieve a specific brand

Get a brand

GET https://api-eu.vonage.com/v1/10dlc/brands/:brand_id
Host https://api-eu.vonage.com
GET /v1/10dlc/brands/:brand_id

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

Responses

200 Return a single brand

Example Responses

200 400 401 404 422
{
  "account_id": "abcd1234",
  "primary_account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "first_name": "John",
  "last_name": "Smith",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "ein_issuing_country": "US",
  "universal_ein": "20-1111111",
  "alt_business_id_type": "DUNS",
  "alt_business_id": "150483782",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "stock_symbol": "VG",
  "stock_exchange": "NASDAQ",
  "website": "https://vonage.com",
  "vertical": "TECHNOLOGY",
  "campaign_count": 5,
  "brand_relationship": "BASIC_ACCOUNT",
  "partner": false,
  "shared": false,
  "owner": false,
  "status": "abc123",
  "reference_id": "abc123",
  "brand_id": "BLQKOPK",
  "created_date": "2020-01-02 05:12:14",
  "last_updated": "2020-02-02 14:12:00",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/10dlc/brands/BLQKOPK"
    },
    "campaigns": {
      "href": "https://api.nexmo.com/10dlc/brands/BLQKOPK/campaigns"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-brand-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your brand, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "company_name",
      "description": "Field 'company_name' is not unique"
    }
  ]
}

Partially update a specific brand

This operation applies a partial update of a brand enabling the CSP to keep brand details updated in the registry. Please note that if vetting is successfully completed, the ein ein_issuing_country and entity_type fields will be locked and the associated values cannot be changed.

PATCH https://api-eu.vonage.com/v1/10dlc/brands/:brand_id
Host https://api-eu.vonage.com
PATCH /v1/10dlc/brands/:brand_id

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

Request body application/json

company_name
string

Legal company name.

first_name
string

First name of business contact.

last_name
string

Last name of business contact.

display_name
string

Display or marketing name of the brand.

ein
string

(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.

ein_issuing_country
string

ISO3166-Alpha2 country code.

entity_type
string

Entity type behind the brand. This is the form of business establishment. Please refer to the /enum endpoint for an update list of valid values.

website
string

Brand website URL.

phone
string

Valid phone number in E.164 international format without the + prefix.

street
string | Max: 100

Street number and name.

city
string | Max: 100

City name

state
string | Max: 20

State. Must be 2 letters code for U.S.A.

postal_code
string | Max: 10

Postal codes. Use 5 digit zipcode for United States

country
string

ISO3166-Alpha2 country code.

email
string | Max: 100

Valid email address of brand support contact.

stock_symbol
string

Stock Symbol - Required if entity_type=PUBLIC_PROFIT.

stock_exchange
string

Required if entity_type=PUBLIC_PROFIT.

Must be one of: NONE, AMEX, AMX, ASX, B3, BME, BSE, FRA, ICEX, JSE, KRX, LON, NASDAQ, NSE, NYSE, OMX, SEHK, SSE, STO, SWX, SZSE, TSX, TWSE or VSE
vertical
string

Business/industry segment of this campaign.

Responses

200 Return a single brand

Example Request

{
  "company_name": "Vonage",
  "first_name": "John",
  "last_name": "Smith",
  "display_name": "Vonage",
  "ein": "20-1111111",
  "ein_issuing_country": "US",
  "entity_type": "PUBLIC_PROFIT",
  "website": "https://vonage.com",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "stock_symbol": "VG",
  "stock_exchange": "NASDAQ",
  "vertical": "TECHNOLOGY"
}

Example Responses

200 400 401 404 422
{
  "account_id": "abcd1234",
  "primary_account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "first_name": "John",
  "last_name": "Smith",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "ein_issuing_country": "US",
  "universal_ein": "20-1111111",
  "alt_business_id_type": "DUNS",
  "alt_business_id": "150483782",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "stock_symbol": "VG",
  "stock_exchange": "NASDAQ",
  "website": "https://vonage.com",
  "vertical": "TECHNOLOGY",
  "campaign_count": 5,
  "brand_relationship": "BASIC_ACCOUNT",
  "partner": false,
  "shared": false,
  "owner": false,
  "status": "abc123",
  "reference_id": "abc123",
  "brand_id": "BLQKOPK",
  "created_date": "2020-01-02 05:12:14",
  "last_updated": "2020-02-02 14:12:00",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/10dlc/brands/BLQKOPK"
    },
    "campaigns": {
      "href": "https://api.nexmo.com/10dlc/brands/BLQKOPK/campaigns"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-vetting-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your vetting request, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "evp_id",
      "description": "Field 'evp_id' is not unique"
    }
  ]
}

Remove a specific brand from your account

This operation deletes a brand. A brand can be deleted if it does not have active campaigns. Once a brand is deleted, it will be in a DELETED state and it cannot be restored to an ACTIVE state. Deleted brands will remain in the system for a period of time and can be searched using the GET/brand endpoint with the query filter status = ACTIVE. While deleted brands are searchable, all other API endpoints involving a deleted brand will result in a 502 - Brand not found error.

DELETE https://api-eu.vonage.com/v1/10dlc/brands/:brand_id
Host https://api-eu.vonage.com
DELETE /v1/10dlc/brands/:brand_id

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

Example Responses

204 400 401 404 409 422
No content
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#brand-conflict",
  "title": "An error occurred with this brand while communicating with a third party",
  "detail": "An unknown error occurred while processing this brand with the carrier system. Please contact support or try again later.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-brand-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your brand, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "company_name",
      "description": "Field 'company_name' is not unique"
    }
  ]
}

Get feedback of a brand by Brand ID.

Retrieve feedback of a specific brand with Brand ID.

GET https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/feedback
Host https://api-eu.vonage.com
GET /v1/10dlc/brands/:brand_id/feedback

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

Responses

200 Return feedback for a brand
categories
array of objects
name
string
description
string
fields
array of strings

Example Responses

200 400 401 404 422
{
  "categories": [
    {
      "name": "abc123",
      "description": "abc123",
      "fields": [
        {}
      ]
    }
  ]
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-brand-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your brand, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "company_name",
      "description": "Field 'company_name' is not unique"
    }
  ]
}

Check Use Case Qualifications for a Brand

Check to see if a brand is qualified to run a campaign against a given use case. A brand must check this endpoint before attempting to generate a new campaign.

If the use case is not qualified, the brand may request additional third party vetting to see if the additional use cases can be added to their account.

GET https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/usecases/:usecase
Host https://api-eu.vonage.com
GET /v1/10dlc/brands/:brand_id/usecases/:usecase

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

usecase
string | Required

Name of a use case

Must be one of: CUSTOMER_CARE, POLLING_VOTING, HIGHER_EDUCATION, PUBLIC_SERVICE_ANNOUNCEMENT, MARKETING, SECURITY_ALERT, DELIVERY_NOTIFICATION, ACCOUNT_NOTIFICATION, 2FA, FRAUD_ALERT, TRIAL, CHARITY, POLITICAL, EMERGENCY, SWEEPSTAKE, CONVERSATIONAL, MIXED, CARRIER_EXEMPT, SOCIAL or LOW_VOLUME

Responses

200 A valid qualified use case for a brand
usecase
string
quarterly_fee
integer
annual_fee
integer
mno_metadata
array of objects
network_id
string
mno
string
mno_support
boolean
mno_review
boolean
qualify
boolean
min_msg_samples
integer
req_subscriber_opt_in
boolean
req_subscriber_opt_out
boolean
req_subscriber_help
boolean
boolean
no_embedded_phone
boolean
att_msg_class
string
att_tpm
integer
tmo_brand_tier
string
status
string
One of: UNKNOWN, REVIEW, REJECTED, APPROVED, SUSPENDED or REGISTERED
tmo_tpd
integer
att_number_based
integer
complaints
array of objects
description
string
dca
string
created_at
string

Example Responses

200 400 401 404 422
{
  "usecase": "POLITICAL",
  "quarterly_fee": 30,
  "annual_fee": 30,
  "mno_metadata": [
    {
      "network_id": "10017",
      "min_msg_samples": 2,
      "att_msg_class": "Q",
      "req_subscriber_opt_in": false,
      "req_subscriber_help": false,
      "req_subscriber_opt_out": false,
      "mno": "AT&T",
      "att_tpm": 2000,
      "mno_support": true,
      "mno_review": true,
      "no_embedded_link": true,
      "qualify": true,
      "tmo_brand_tier": null
    },
    {
      "network_id": "10035",
      "min_msg_samples": 2,
      "req_subscriber_opt_in": false,
      "req_subscriber_help": false,
      "req_subscriber_opt_out": false,
      "mno": "TMO",
      "mno_support": true,
      "mno_review": true,
      "no_embedded_link": true,
      "no_embedded_phone": true,
      "qualify": true,
      "tmo_brand_tier": "LOW",
      "att_tpm": null,
      "att_msg_class": null
    }
  ]
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-usecase-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors qualifying the use case for your brand, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "errors": [
    {
      "code": 501,
      "field": "usecase",
      "description": "Unrecognized Usecase"
    }
  ]
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-brand-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your brand, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "company_name",
      "description": "Field 'company_name' is not unique"
    }
  ]
}

Retrieve a list of vetting records for a brand

Retrieve a list of vetting records for a brand

GET https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/vetting/requests
Host https://api-eu.vonage.com
GET /v1/10dlc/brands/:brand_id/vetting/requests

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

Responses

200 Returns a list of vetting requests
account_id
string

The Vonage Account ID

evp_id
string

ID associated with a vetting request

vetting_id
string
vetting_token
string
vetting_score
integer
vetting_class
string
vetting_status
string
vetted_date
string
create_date
string

Example Responses

200 400 401 404 422
[
  {
    "account_id": "abcd1234",
    "evp_id": "abc123",
    "vetting_id": "abc123",
    "vetting_token": "abc123",
    "vetting_score": 1,
    "vetting_class": "abc123",
    "vetting_status": "abc123",
    "vetted_date": "abc123",
    "create_date": "abc123",
    "_links": {
      "self": {
        "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234"
      },
      "brand": {
        "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
      }
    }
  }
]
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-vetting-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your vetting request, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "evp_id",
      "description": "Field 'evp_id' is not unique"
    }
  ]
}

Request vetting for a brand

This operation requests the specific vetting provider to perform vetting on a brand. This authorizes Vonage to allow the vetting partner access to the particular brand information stored in The Campaign Registry (TCR). This request can take anywhere from a few minutes to 48 hours.

POST https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/vetting/requests
Host https://api-eu.vonage.com
POST /v1/10dlc/brands/:brand_id/vetting/requests

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

Request body application/json

evp_id
string | Required

This value must be the ID associated with one of the supported vetting providers.

Must be one of: Aegis, CV or WMC
vetting_class
string | Required

Type of vetting to perform.

Responses

200 Information about a vetting request
account_id
string

The Vonage Account ID

evp_id
string

ID associated with a vetting request

vetting_id
string
vetting_token
string
vetting_score
integer
vetting_class
string
vetting_status
string
vetted_date
string
create_date
string

Example Request

{
  "evp_id": "abcd123",
  "vetting_class": "abcd123"
}

Example Responses

200 422 429
{
  "account_id": "abcd1234",
  "evp_id": "abc123",
  "vetting_id": "abc123",
  "vetting_token": "abc123",
  "vetting_score": 1,
  "vetting_class": "abc123",
  "vetting_status": "abc123",
  "vetted_date": "abc123",
  "create_date": "abc123",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234"
    },
    "brand": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-vetting-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your vetting request, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "evp_id",
      "description": "Field 'evp_id' is not unique"
    }
  ]
}
{
  "type": "https://developer.vonage.com/api-errors#throttled",
  "title": "Too many requests",
  "detail": "Your account has reached it's API limit and has been throttled",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "retry_after": 30
}

Import an existing vetting request to Vonage

Vetting requests can either be automated or manual. In the case that a vetting request has been manually performed or was requested outside of Vonage, you can request that the request be imported. The vetting request will be validated and, if successful, saved with the brand in TCR and the vetting record will be considered for future campaign qualification. This validation process is not immediate.

PUT https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/vetting/requests
Host https://api-eu.vonage.com
PUT /v1/10dlc/brands/:brand_id/vetting/requests

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

Request body application/json

evp_id
string | Required

The identity of the vetting partner. This value must be the ID associated with one of the supported vetting providers.

Must be one of: Aegis, CV or WMC
vetting_token
string

Token verifying the vetting ID (only applicable to Aegis vetting).

vetting_id
string | Required

Unique ID that identifies a vetting transaction performed by a vetting provider. This ID is provided by the vetting provider at time of vetting.

Responses

200 Information about a vetting request
account_id
string

The Vonage Account ID

evp_id
string

ID associated with a vetting request

vetting_id
string
vetting_token
string
vetting_score
integer
vetting_class
string
vetting_status
string
vetted_date
string
create_date
string

Example Request

{
  "evp_id": "abcd123",
  "vetting_id": "abcd123"
}
{
  "evp_id": "abcd123",
  "vetting_token": "abcd123",
  "vetting_id": "abcd123"
}

Example Responses

200 409 422 429
{
  "account_id": "abcd1234",
  "evp_id": "abc123",
  "vetting_id": "abc123",
  "vetting_token": "abc123",
  "vetting_score": 1,
  "vetting_class": "abc123",
  "vetting_status": "abc123",
  "vetted_date": "abc123",
  "create_date": "abc123",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234"
    },
    "brand": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#vetting-conflict",
  "title": "An error occurred while requesting third party vetting",
  "detail": "An unknown error occurred while requesting vetting with the carrier system. Please contact support or try again later.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-vetting-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your vetting request, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "evp_id",
      "description": "Field 'evp_id' is not unique"
    }
  ]
}
{
  "type": "https://developer.vonage.com/api-errors#throttled",
  "title": "Too many requests",
  "detail": "Your account has reached it's API limit and has been throttled",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "retry_after": 30
}

Request a brand revetting

This operation allows you to revet the brand; however, revetting is allowed once after the successful brand registration. Search for campaigns you registered by any combination of brand_id, reseller_id, status, usecase, and vertical. This operation supports pagination with a maximum of 500 records per fetch. Values for brand_id, reseller_id, status, usecase, and vertical must be exact matches if supplied.

POST https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/revet
Host https://api-eu.vonage.com
POST /v1/10dlc/brands/:brand_id/revet

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

Responses

200 Return a single brand

Example Responses

200 401 404 422
{
  "account_id": "abcd1234",
  "primary_account_id": "abcd1234",
  "entity_type": "PUBLIC_PROFIT",
  "first_name": "John",
  "last_name": "Smith",
  "display_name": "Vonage",
  "company_name": "Vonage",
  "ein": "20-1111111",
  "ein_issuing_country": "US",
  "universal_ein": "20-1111111",
  "alt_business_id_type": "DUNS",
  "alt_business_id": "150483782",
  "phone": "+15556660001",
  "street": "23 Main Street",
  "city": "Holmdel",
  "state": "NJ",
  "postal_code": "07733",
  "country": "US",
  "email": "devrel@vonage.com",
  "stock_symbol": "VG",
  "stock_exchange": "NASDAQ",
  "website": "https://vonage.com",
  "vertical": "TECHNOLOGY",
  "campaign_count": 5,
  "brand_relationship": "BASIC_ACCOUNT",
  "partner": false,
  "shared": false,
  "owner": false,
  "status": "abc123",
  "reference_id": "abc123",
  "brand_id": "BLQKOPK",
  "created_date": "2020-01-02 05:12:14",
  "last_updated": "2020-02-02 14:12:00",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/10dlc/brands/BLQKOPK"
    },
    "campaigns": {
      "href": "https://api.nexmo.com/10dlc/brands/BLQKOPK/campaigns"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/#invalid-json",
  "title": "Unable to parse incoming request",
  "detail": "invalid character 'f' after object key:value pair",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Retrieve a list of vetting classifications that can be performed

When requesting brand vetting, a vetting class must be supplied. This determines the scope of the vetting to be performed by the vetting provider.

GET https://api-eu.vonage.com/v1/10dlc/enum/vetting/classes
Host https://api-eu.vonage.com
GET /v1/10dlc/enum/vetting/classes

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Responses

200 List of vetting classes
id
string
enabled
boolean
display_name
string
description
string
validity_months
integer

Example Responses

200
[
  {
    "id": "abc123",
    "enabled": false,
    "display_name": "abc123",
    "description": "abc123",
    "validity_months": 12
  }
]

Retrieve a list of vetting providers

When requesting external vetting, a user must select from a list of approved vetting providers.

GET https://api-eu.vonage.com/v1/10dlc/enum/vetting/providers
Host https://api-eu.vonage.com
GET /v1/10dlc/enum/vetting/providers

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Responses

200 List of vetting providers
evp_id
string
display_name
string
tcr_billable
boolean
vetting_classes
array of strings
vetting_instruction
string

Example Responses

200
[
  {
    "evp_id": "abc123",
    "display_name": "abc123",
    "tcr_billable": false,
    "vetting_classes": [
      "class1",
      "class2"
    ],
    "vetting_instruction": "abc123"
  }
]

Retrieve all of the campaigns associated with a brand

List campaigns

GET https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns
Host https://api-eu.vonage.com
GET /v1/10dlc/brands/:brand_id/campaigns

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

Query Parameter

page
integer

Page of results to jump to

page_size
integer

Number of results per page

Responses

200 List of campaigns that are associated with a brand
page_size
integer

Items per page

page
integer

Page Offset

total_pages
integer

Number of pages in the entire result set

total_items
integer

Number of items in the entire result set

_embedded
object
campaigns
array

Example Responses

200 400 401 404 422
{
  "page_size": 10,
  "page": 2,
  "total_pages": 100,
  "total_items": 100,
  "_embedded": {
    "campaigns": [
      {
        "account_id": "abcd1234",
        "vertical": "TECHNOLOGY",
        "usecase": "ACCOUNT_NOTIFICATION",
        "sub_usecases": [
          "2FA",
          "SECURITY_ALERT"
        ],
        "reseller_id": "string",
        "description": "User notifications",
        "embedded_link": false,
        "embedded_phone": false,
        "number_pool": false,
        "age_gated": true,
        "direct_lending": true,
        "subscriber_opt_in": false,
        "subscriber_opt_out": false,
        "subscriber_help": false,
        "sample_one": "Sample Message",
        "sample_two": "Additional Sample Message",
        "sample_three": "Additional Sample Message",
        "sample_four": "Additional Sample Message",
        "sample_five": "Additional Sample Message",
        "message_flow": "string",
        "partner": true,
        "help_message": "string",
        "affiliate_marketing": true,
        "label": "This is a sample campaign",
        "auto_renewal": true,
        "brand_id": "BLQKOPK",
        "mno_metadata": [
          {
            "network_id": "10017",
            "mno": "abc123",
            "mno_support": false,
            "mno_review": false,
            "qualify": false,
            "min_msg_samples": 2,
            "req_subscriber_opt_in": false,
            "req_subscriber_opt_out": false,
            "req_subscriber_help": false,
            "no_embedded_link": false,
            "no_embedded_phone": false,
            "att_msg_class": "Q",
            "att_tpm": 1,
            "tmo_brand_tier": "abc123",
            "status": "APPROVED",
            "tmo_tpd": 0,
            "att_number_based": 3000,
            "complaints": [
              {
                "description": "abc123",
                "dca": "SINCH",
                "created_at": "2022-08-01T14:26:25.862Z"
              }
            ]
          }
        ],
        "status": "ACTIVE",
        "campaign_id": "C1DEB879",
        "created_date": "abc123",
        "last_updated": "abc123",
        "_links": {
          "self": {
            "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879"
          },
          "brand": {
            "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
          },
          "numbers": {
            "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbers"
          }
        }
      }
    ]
  },
  "_links": {
    "brand": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
    },
    "self": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/?page=2"
    },
    "next": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/?page=1"
    },
    "previous": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/?page=1"
    },
    "first": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/?page=1"
    },
    "last": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/?page=10"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/#invalid-json",
  "title": "Unable to parse incoming request",
  "detail": "invalid character 'f' after object key:value pair",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Add a new campaign to a brand

Create Campaign

POST https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns
Host https://api-eu.vonage.com
POST /v1/10dlc/brands/:brand_id/campaigns

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

Request body application/json

account_id
string | Required

The Vonage Account ID

vertical
string | Max: 50

Business/industry segment of this campaign. (Required if entity_type != SOLE_PROPRIETOR). Please refer to the /enum endpoint for an update list of valid values.

Must be one of: UNKNOWN, REAL_ESTATE, HEALTHCARE, ENERGY, ENTERTAINMENT, RETAIL, AGRICULTURE, INSURANCE, EDUCATION, HOSPITALITY, FINANCIAL, GAMBLING, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY or COMMUNICATION
usecase
string | Required | Max: 50

Campaign usecase

Must be one of: CUSTOMER_CARE, POLLING_VOTING, HIGHER_EDUCATION, PUBLIC_SERVICE_ANNOUNCEMENT, MARKETING, SECURITY_ALERT, DELIVERY_NOTIFICATION, ACCOUNT_NOTIFICATION, 2FA, FRAUD_ALERT, TRIAL, CHARITY, POLITICAL, EMERGENCY, SWEEPSTAKE, CONVERSATIONAL, MIXED, CARRIER_EXEMPT, SOCIAL or LOW_VOLUME
sub_usecases
array of strings

Campaign sub-usecases

reseller_id
string | Max: 8

Alphanumeric identifier of the reseller that you want to associate with this campaign

description
string | Required

Summary description of this campaign

embedded_link
boolean

Does message generated by the campaign include URL link in SMS?

embedded_phone
boolean

Does message generated by the campaign include phone number in SMS?

number_pool
boolean

Does campaign utilize pool of phone numbers?

age_gated
boolean

Age gated message content in campaign.

direct_lending
boolean

Direct lending or loan arrangement

subscriber_opt_in
boolean | Required

Does campaign require subscriber to opt-in before SMS is sent to subscriber?

subscriber_opt_out
boolean | Required

Does campaign support subscriber opt-out keyword(s)?

subscriber_help
boolean | Required

Does campaign responds to help keyword(s)?

sample_one
string | Max: 1024

Message sample. Some campaign tiers require 1 or more message samples.

sample_two
string | Max: 1024

Message sample. Some campaign tiers require 2 or more message samples.

sample_three
string | Max: 1024

Message sample. Some campaign tiers require 3 or more message samples.

sample_four
string | Max: 1024

Message sample. Some campaign tiers require 4 or more message samples.

sample_five
string | Max: 1024

Message sample. Some campaign tiers require 5.

message_flow
string | Max: 2048

Message flow description

partner
boolean

Fields that are editable for a campaign

help_message
string | Max: 255

Help message of the campaign

affiliate_marketing
boolean

Does message content controlled by affiliate marketing other than the brand?

label
string

Fields that are editable for a campaign

auto_renewal
boolean

Fields that are editable for a campaign

Responses

201 Return a single campaign
account_id
string

The Vonage Account ID

vertical
string

Business/industry segment of this campaign. (Required if entity_type != SOLE_PROPRIETOR). Please refer to the /enum endpoint for an update list of valid values.

One of: UNKNOWN, REAL_ESTATE, HEALTHCARE, ENERGY, ENTERTAINMENT, RETAIL, AGRICULTURE, INSURANCE, EDUCATION, HOSPITALITY, FINANCIAL, GAMBLING, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY or COMMUNICATION
usecase
string

Campaign usecase

One of: CUSTOMER_CARE, POLLING_VOTING, HIGHER_EDUCATION, PUBLIC_SERVICE_ANNOUNCEMENT, MARKETING, SECURITY_ALERT, DELIVERY_NOTIFICATION, ACCOUNT_NOTIFICATION, 2FA, FRAUD_ALERT, TRIAL, CHARITY, POLITICAL, EMERGENCY, SWEEPSTAKE, CONVERSATIONAL, MIXED, CARRIER_EXEMPT, SOCIAL or LOW_VOLUME
sub_usecases
array of strings

Campaign sub-usecases

reseller_id
string

Alphanumeric identifier of the reseller that you want to associate with this campaign

description
string

Summary description of this campaign

embedded_link
boolean

Does message generated by the campaign include URL link in SMS?

embedded_phone
boolean

Does message generated by the campaign include phone number in SMS?

number_pool
boolean

Does campaign utilize pool of phone numbers?

age_gated
boolean

Age gated message content in campaign.

direct_lending
boolean

Direct lending or loan arrangement

subscriber_opt_in
boolean

Does campaign require subscriber to opt-in before SMS is sent to subscriber?

subscriber_opt_out
boolean

Does campaign support subscriber opt-out keyword(s)?

subscriber_help
boolean

Does campaign responds to help keyword(s)?

sample_one
string

Message sample. Some campaign tiers require 1 or more message samples.

sample_two
string

Message sample. Some campaign tiers require 2 or more message samples.

sample_three
string

Message sample. Some campaign tiers require 3 or more message samples.

sample_four
string

Message sample. Some campaign tiers require 4 or more message samples.

sample_five
string

Message sample. Some campaign tiers require 5.

message_flow
string

Message flow description

partner
boolean
help_message
string

Help message of the campaign

affiliate_marketing
boolean

Does message content controlled by affiliate marketing other than the brand?

label
string
auto_renewal
boolean
brand_id
string

Brand ID associated with a number

mno_metadata
array of objects
network_id
string
mno
string
mno_support
boolean
mno_review
boolean
qualify
boolean
min_msg_samples
integer
req_subscriber_opt_in
boolean
req_subscriber_opt_out
boolean
req_subscriber_help
boolean
no_embedded_link
boolean
no_embedded_phone
boolean
att_msg_class
string
att_tpm
integer
tmo_brand_tier
string
status
string
One of: UNKNOWN, REVIEW, REJECTED, APPROVED, SUSPENDED or REGISTERED
tmo_tpd
integer
att_number_based
integer
complaints
array of objects
description
string
dca
string
created_at
string
status
string
campaign_id
string

ID associated with a specific campaign

created_date
string
last_updated
string

Example Request

{
  "account_id": "abcd1234",
  "usecase": "ACCOUNT_NOTIFICATION",
  "description": "User notifications"
}
{
  "account_id": "abcd1234",
  "vertical": "TECHNOLOGY",
  "usecase": "ACCOUNT_NOTIFICATION",
  "sub_usecases": [
    "2FA",
    "SECURITY_ALERT"
  ],
  "reseller_id": "string",
  "description": "User notifications",
  "age_gated": true,
  "direct_lending": true,
  "sample_one": "Sample Message",
  "sample_two": "Additional Sample Message",
  "sample_three": "Additional Sample Message",
  "sample_four": "Additional Sample Message",
  "sample_five": "Additional Sample Message",
  "message_flow": "string",
  "partner": true,
  "help_message": "string",
  "affiliate_marketing": true,
  "label": "This is a sample campaign",
  "auto_renewal": true
}

Example Responses

201 400 401 404 409 422
{
  "account_id": "abcd1234",
  "vertical": "TECHNOLOGY",
  "usecase": "ACCOUNT_NOTIFICATION",
  "sub_usecases": [
    "2FA",
    "SECURITY_ALERT"
  ],
  "reseller_id": "string",
  "description": "User notifications",
  "embedded_link": false,
  "embedded_phone": false,
  "number_pool": false,
  "age_gated": true,
  "direct_lending": true,
  "subscriber_opt_in": false,
  "subscriber_opt_out": false,
  "subscriber_help": false,
  "sample_one": "Sample Message",
  "sample_two": "Additional Sample Message",
  "sample_three": "Additional Sample Message",
  "sample_four": "Additional Sample Message",
  "sample_five": "Additional Sample Message",
  "message_flow": "string",
  "partner": true,
  "help_message": "string",
  "affiliate_marketing": true,
  "label": "This is a sample campaign",
  "auto_renewal": true,
  "brand_id": "BLQKOPK",
  "mno_metadata": [
    {
      "network_id": "10017",
      "mno": "abc123",
      "mno_support": false,
      "mno_review": false,
      "qualify": false,
      "min_msg_samples": 2,
      "req_subscriber_opt_in": false,
      "req_subscriber_opt_out": false,
      "req_subscriber_help": false,
      "no_embedded_link": false,
      "no_embedded_phone": false,
      "att_msg_class": "Q",
      "att_tpm": 1,
      "tmo_brand_tier": "abc123",
      "status": "APPROVED",
      "tmo_tpd": 0,
      "att_number_based": 3000,
      "complaints": [
        {
          "description": "abc123",
          "dca": "SINCH",
          "created_at": "2022-08-01T14:26:25.862Z"
        }
      ]
    }
  ],
  "status": "ACTIVE",
  "campaign_id": "C1DEB879",
  "created_date": "abc123",
  "last_updated": "abc123",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879"
    },
    "brand": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
    },
    "numbers": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbers"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#brand-not-qualified",
  "title": "This brand has not been qualified for the given use case",
  "detail": "A campaign use case must be checked before a campaign can be created. Please verify the brand use case before submitting this campaign.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-campaign-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your campaign, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "usecase",
      "description": "Field 'usecase' is not a valid value"
    }
  ]
}

Retrieve a specific campaign

Get a campaign

GET https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns/:campaign_id
Host https://api-eu.vonage.com
GET /v1/10dlc/brands/:brand_id/campaigns/:campaign_id

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

campaign_id
string | Required

ID associated with a specific campaign

Responses

200 Return a single campaign
account_id
string

The Vonage Account ID

vertical
string

Business/industry segment of this campaign. (Required if entity_type != SOLE_PROPRIETOR). Please refer to the /enum endpoint for an update list of valid values.

One of: UNKNOWN, REAL_ESTATE, HEALTHCARE, ENERGY, ENTERTAINMENT, RETAIL, AGRICULTURE, INSURANCE, EDUCATION, HOSPITALITY, FINANCIAL, GAMBLING, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY or COMMUNICATION
usecase
string

Campaign usecase

One of: CUSTOMER_CARE, POLLING_VOTING, HIGHER_EDUCATION, PUBLIC_SERVICE_ANNOUNCEMENT, MARKETING, SECURITY_ALERT, DELIVERY_NOTIFICATION, ACCOUNT_NOTIFICATION, 2FA, FRAUD_ALERT, TRIAL, CHARITY, POLITICAL, EMERGENCY, SWEEPSTAKE, CONVERSATIONAL, MIXED, CARRIER_EXEMPT, SOCIAL or LOW_VOLUME
sub_usecases
array of strings

Campaign sub-usecases

reseller_id
string

Alphanumeric identifier of the reseller that you want to associate with this campaign

description
string

Summary description of this campaign

boolean

Does message generated by the campaign include URL link in SMS?

embedded_phone
boolean

Does message generated by the campaign include phone number in SMS?

number_pool
boolean

Does campaign utilize pool of phone numbers?

age_gated
boolean

Age gated message content in campaign.

direct_lending
boolean

Direct lending or loan arrangement

subscriber_opt_in
boolean

Does campaign require subscriber to opt-in before SMS is sent to subscriber?

subscriber_opt_out
boolean

Does campaign support subscriber opt-out keyword(s)?

subscriber_help
boolean

Does campaign responds to help keyword(s)?

sample_one
string

Message sample. Some campaign tiers require 1 or more message samples.

sample_two
string

Message sample. Some campaign tiers require 2 or more message samples.

sample_three
string

Message sample. Some campaign tiers require 3 or more message samples.

sample_four
string

Message sample. Some campaign tiers require 4 or more message samples.

sample_five
string

Message sample. Some campaign tiers require 5.

message_flow
string

Message flow description

partner
boolean
help_message
string

Help message of the campaign

affiliate_marketing
boolean

Does message content controlled by affiliate marketing other than the brand?

label
string
auto_renewal
boolean
brand_id
string

Brand ID associated with a number

mno_metadata
array of objects
network_id
string
mno
string
mno_support
boolean
mno_review
boolean
qualify
boolean
min_msg_samples
integer
req_subscriber_opt_in
boolean
req_subscriber_opt_out
boolean
req_subscriber_help
boolean
boolean
no_embedded_phone
boolean
att_msg_class
string
att_tpm
integer
tmo_brand_tier
string
status
string
One of: UNKNOWN, REVIEW, REJECTED, APPROVED, SUSPENDED or REGISTERED
tmo_tpd
integer
att_number_based
integer
complaints
array of objects
description
string
dca
string
created_at
string
status
string
campaign_id
string

ID associated with a specific campaign

created_date
string
last_updated
string

Example Responses

200 400 401 404 422
{
  "account_id": "abcd1234",
  "vertical": "TECHNOLOGY",
  "usecase": "ACCOUNT_NOTIFICATION",
  "sub_usecases": [
    "2FA",
    "SECURITY_ALERT"
  ],
  "reseller_id": "string",
  "description": "User notifications",
  "embedded_link": false,
  "embedded_phone": false,
  "number_pool": false,
  "age_gated": true,
  "direct_lending": true,
  "subscriber_opt_in": false,
  "subscriber_opt_out": false,
  "subscriber_help": false,
  "sample_one": "Sample Message",
  "sample_two": "Additional Sample Message",
  "sample_three": "Additional Sample Message",
  "sample_four": "Additional Sample Message",
  "sample_five": "Additional Sample Message",
  "message_flow": "string",
  "partner": true,
  "help_message": "string",
  "affiliate_marketing": true,
  "label": "This is a sample campaign",
  "auto_renewal": true,
  "brand_id": "BLQKOPK",
  "mno_metadata": [
    {
      "network_id": "10017",
      "mno": "abc123",
      "mno_support": false,
      "mno_review": false,
      "qualify": false,
      "min_msg_samples": 2,
      "req_subscriber_opt_in": false,
      "req_subscriber_opt_out": false,
      "req_subscriber_help": false,
      "no_embedded_link": false,
      "no_embedded_phone": false,
      "att_msg_class": "Q",
      "att_tpm": 1,
      "tmo_brand_tier": "abc123",
      "status": "APPROVED",
      "tmo_tpd": 0,
      "att_number_based": 3000,
      "complaints": [
        {
          "description": "abc123",
          "dca": "SINCH",
          "created_at": "2022-08-01T14:26:25.862Z"
        }
      ]
    }
  ],
  "status": "ACTIVE",
  "campaign_id": "C1DEB879",
  "created_date": "abc123",
  "last_updated": "abc123",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879"
    },
    "brand": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
    },
    "numbers": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbers"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-campaign-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your campaign, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "usecase",
      "description": "Field 'usecase' is not a valid value"
    }
  ]
}

Partially update a specific campaign

Partial update of a campaign

PATCH https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns/:campaign_id
Host https://api-eu.vonage.com
PATCH /v1/10dlc/brands/:brand_id/campaigns/:campaign_id

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

campaign_id
string | Required

ID associated with a specific campaign

Request body application/json

label
string

Fields that are editable for a campaign

reseller_id
string

Fields that are editable for a campaign

sample_one
string

Fields that are editable for a campaign

sample_two
string

Fields that are editable for a campaign

sample_three
string

Fields that are editable for a campaign

sample_four
string

Fields that are editable for a campaign

sample_five
string

Fields that are editable for a campaign

message_flow
string

Fields that are editable for a campaign

help_message
string

Fields that are editable for a campaign

auto_renewal
boolean

Fields that are editable for a campaign

Responses

200 Return a single campaign
account_id
string

The Vonage Account ID

vertical
string

Business/industry segment of this campaign. (Required if entity_type != SOLE_PROPRIETOR). Please refer to the /enum endpoint for an update list of valid values.

One of: UNKNOWN, REAL_ESTATE, HEALTHCARE, ENERGY, ENTERTAINMENT, RETAIL, AGRICULTURE, INSURANCE, EDUCATION, HOSPITALITY, FINANCIAL, GAMBLING, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY or COMMUNICATION
usecase
string

Campaign usecase

One of: CUSTOMER_CARE, POLLING_VOTING, HIGHER_EDUCATION, PUBLIC_SERVICE_ANNOUNCEMENT, MARKETING, SECURITY_ALERT, DELIVERY_NOTIFICATION, ACCOUNT_NOTIFICATION, 2FA, FRAUD_ALERT, TRIAL, CHARITY, POLITICAL, EMERGENCY, SWEEPSTAKE, CONVERSATIONAL, MIXED, CARRIER_EXEMPT, SOCIAL or LOW_VOLUME
sub_usecases
array of strings

Campaign sub-usecases

reseller_id
string

Alphanumeric identifier of the reseller that you want to associate with this campaign

description
string

Summary description of this campaign

boolean

Does message generated by the campaign include URL link in SMS?

embedded_phone
boolean

Does message generated by the campaign include phone number in SMS?

number_pool
boolean

Does campaign utilize pool of phone numbers?

age_gated
boolean

Age gated message content in campaign.

direct_lending
boolean

Direct lending or loan arrangement

subscriber_opt_in
boolean

Does campaign require subscriber to opt-in before SMS is sent to subscriber?

subscriber_opt_out
boolean

Does campaign support subscriber opt-out keyword(s)?

subscriber_help
boolean

Does campaign responds to help keyword(s)?

sample_one
string

Message sample. Some campaign tiers require 1 or more message samples.

sample_two
string

Message sample. Some campaign tiers require 2 or more message samples.

sample_three
string

Message sample. Some campaign tiers require 3 or more message samples.

sample_four
string

Message sample. Some campaign tiers require 4 or more message samples.

sample_five
string

Message sample. Some campaign tiers require 5.

message_flow
string

Message flow description

partner
boolean
help_message
string

Help message of the campaign

affiliate_marketing
boolean

Does message content controlled by affiliate marketing other than the brand?

label
string
auto_renewal
boolean
brand_id
string

Brand ID associated with a number

mno_metadata
array of objects
network_id
string
mno
string
mno_support
boolean
mno_review
boolean
qualify
boolean
min_msg_samples
integer
req_subscriber_opt_in
boolean
req_subscriber_opt_out
boolean
req_subscriber_help
boolean
boolean
no_embedded_phone
boolean
att_msg_class
string
att_tpm
integer
tmo_brand_tier
string
status
string
One of: UNKNOWN, REVIEW, REJECTED, APPROVED, SUSPENDED or REGISTERED
tmo_tpd
integer
att_number_based
integer
complaints
array of objects
description
string
dca
string
created_at
string
status
string
campaign_id
string

ID associated with a specific campaign

created_date
string
last_updated
string

Example Request

{
  "label": "This is a sample campaign",
  "reseller_id": "string",
  "sample_one": "Sample Message",
  "sample_two": "Additional Sample Message",
  "sample_three": "Additional Sample Message",
  "sample_four": "Additional Sample Message",
  "sample_five": "Additional Sample Message",
  "message_flow": "string",
  "help_message": "string",
  "auto_renewal": true
}

Example Responses

200 400 404 422
{
  "account_id": "abcd1234",
  "vertical": "TECHNOLOGY",
  "usecase": "ACCOUNT_NOTIFICATION",
  "sub_usecases": [
    "2FA",
    "SECURITY_ALERT"
  ],
  "reseller_id": "string",
  "description": "User notifications",
  "embedded_link": false,
  "embedded_phone": false,
  "number_pool": false,
  "age_gated": true,
  "direct_lending": true,
  "subscriber_opt_in": false,
  "subscriber_opt_out": false,
  "subscriber_help": false,
  "sample_one": "Sample Message",
  "sample_two": "Additional Sample Message",
  "sample_three": "Additional Sample Message",
  "sample_four": "Additional Sample Message",
  "sample_five": "Additional Sample Message",
  "message_flow": "string",
  "partner": true,
  "help_message": "string",
  "affiliate_marketing": true,
  "label": "This is a sample campaign",
  "auto_renewal": true,
  "brand_id": "BLQKOPK",
  "mno_metadata": [
    {
      "network_id": "10017",
      "mno": "abc123",
      "mno_support": false,
      "mno_review": false,
      "qualify": false,
      "min_msg_samples": 2,
      "req_subscriber_opt_in": false,
      "req_subscriber_opt_out": false,
      "req_subscriber_help": false,
      "no_embedded_link": false,
      "no_embedded_phone": false,
      "att_msg_class": "Q",
      "att_tpm": 1,
      "tmo_brand_tier": "abc123",
      "status": "APPROVED",
      "tmo_tpd": 0,
      "att_number_based": 3000,
      "complaints": [
        {
          "description": "abc123",
          "dca": "SINCH",
          "created_at": "2022-08-01T14:26:25.862Z"
        }
      ]
    }
  ],
  "status": "ACTIVE",
  "campaign_id": "C1DEB879",
  "created_date": "abc123",
  "last_updated": "abc123",
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879"
    },
    "brand": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
    },
    "numbers": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbers"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-campaign-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your campaign, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "code": 503,
      "field": "usecase",
      "description": "Field 'usecase' is not a valid value"
    }
  ]
}

Stop a specific campaign on a brand

Stop a brand

DELETE https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns/:campaign_id
Host https://api-eu.vonage.com
DELETE /v1/10dlc/brands/:brand_id/campaigns/:campaign_id

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

campaign_id
string | Required

ID associated with a specific campaign

Example Responses

204 400 401 404
No content
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Import a partner campaign to Vonage

Import a partner campaign by sharing it with Vonage. Your account needs a special capability to be able to carry on with this operation.

POST https://api-eu.vonage.com/v1/10dlc/partnercampaigns/import
Host https://api-eu.vonage.com
POST /v1/10dlc/partnercampaigns/import

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Request body application/json

account_id
string | Required

The Vonage Account ID

campaign_id
string | Required

ID associated with a specific campaign

label
string | Max: 50

Friendly name associated with this campaign.

Responses

201 Imported partner campaign summary
brand_id
string

Brand ID associated with a number

campaign_id
string

ID associated with a specific campaign

sharing_status
string

Sharing Status. Please refer to the /enum endpoint for an update list of valid values.

One of: PENDING, ACCEPTED or DECLINED
downstream_cnp_id
string

CNP ID. Please refer to the /enum endpoint for an update list of valid values.

upstream_cnp_id
string

CNP ID. Please refer to the /enum endpoint for an update list of valid values.

Example Request

{
  "account_id": "abcd1234",
  "campaign_id": "C1DEB879"
}

Example Responses

201 400 401 404
{
  "brand_id": "BLQKOPK",
  "campaign_id": "C1DEB879",
  "sharing_status": "abc123",
  "downstream_cnp_id": "abc123",
  "upstream_cnp_id": "abc123"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#error-type",
  "title": "There were some issues with your submission",
  "detail": "There were some errors submitting your brand, and a more detailed message would appear here",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Numbers

APIs relating to working with Numbers in Campaigns

Available Operations:

Retrieve Numbers associated with a campaign

Get numbers in campaign

GET https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns/:campaign_id/numbers
Host https://api-eu.vonage.com
GET /v1/10dlc/brands/:brand_id/campaigns/:campaign_id/numbers

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

campaign_id
string | Required

ID associated with a specific campaign

Query Parameter

page
integer

Page of results to jump to

page_size
integer

Number of results per page

Responses

200 List of numbers that are associated with a campaign
page_size
integer

Items per page

page
integer

Page Offset

total_pages
integer

Number of pages in the entire result set

total_items
integer

Number of items in the entire result set

_embedded
object
numbers
array of objects
number
string

Telephone Number

country
string

The two character country code in ISO 3166-1 alpha-2 format

status
string

Current status of a number in a campaign

One of: UNKNOWN, APPROVED, REJECTED or PENDING
compliance
array of strings

List of compliance flags.

Example Responses

200 401 404 422
{
  "page_size": 10,
  "page": 2,
  "total_pages": 100,
  "total_items": 100,
  "_embedded": {
    "numbers": [
      {
        "number": "14155550110",
        "country": "US",
        "status": "APPROVED",
        "compliance": [
          {}
        ],
        "_links": {
          "self": {
            "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbers/14155550110"
          },
          "campaign": {
            "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/"
          },
          "brand": {
            "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
          }
        }
      }
    ]
  }
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-number-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your campaign, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "field": "country",
      "description": "Field 'country' is not a valid value"
    }
  ]
}

Link number to a campaign

Links an existing Vonage number to a 10DLC campaign.

POST https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns/:campaign_id/numbers
Host https://api-eu.vonage.com
POST /v1/10dlc/brands/:brand_id/campaigns/:campaign_id/numbers

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

campaign_id
string | Required

ID associated with a specific campaign

Request body application/json

country
string | Required

The two character country code in ISO 3166-1 alpha-2 format

number
string | Required | Min: 7 | Max: 15

Telephone Number

Responses

202 Accepted
number
string

Telephone Number

country
string

The two character country code in ISO 3166-1 alpha-2 format

status
string

Current status of a number in a campaign

One of: UNKNOWN, APPROVED, REJECTED or PENDING
compliance
array of strings

List of compliance flags.

Example Request

{
  "country": "US",
  "number": "14155550110"
}

Example Responses

202 401 404 409 422
{
  "number": "14155550110",
  "country": "US",
  "status": "APPROVED",
  "compliance": [
    {}
  ],
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbers/14155550110"
    },
    "campaign": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/"
    },
    "brand": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#number-already-linked",
  "title": "Number Already Linked",
  "detail": "The number requested has already been linked to another campaign",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-number-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your campaign, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "field": "country",
      "description": "Field 'country' is not a valid value"
    }
  ]
}

Retrieve information about a number in a campaign

Retrieve information about a number in a campaign

GET https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns/:campaign_id/numbers/:number
Host https://api-eu.vonage.com
GET /v1/10dlc/brands/:brand_id/campaigns/:campaign_id/numbers/:number

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

campaign_id
string | Required

ID associated with a specific campaign

number
string | Required

Number to work with inside a campaign

Responses

200 Information about a number
number
string

Telephone Number

country
string

The two character country code in ISO 3166-1 alpha-2 format

status
string

Current status of a number in a campaign

One of: UNKNOWN, APPROVED, REJECTED or PENDING
compliance
array of strings

List of compliance flags.

Example Responses

200 401 404 422
{
  "number": "14155550110",
  "country": "US",
  "status": "APPROVED",
  "compliance": [
    {}
  ],
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbers/14155550110"
    },
    "campaign": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/"
    },
    "brand": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
    }
  }
}
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-number-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your campaign, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "field": "country",
      "description": "Field 'country' is not a valid value"
    }
  ]
}

Unlink a number from a campaign

Unlink a number from a campaign

DELETE https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns/:campaign_id/numbers/:number
Host https://api-eu.vonage.com
DELETE /v1/10dlc/brands/:brand_id/campaigns/:campaign_id/numbers/:number

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

brand_id
string | Required

Brand ID associated with a number

campaign_id
string | Required

ID associated with a specific campaign

number
string | Required

Number to work with inside a campaign

Example Responses

204 401 404 422
No Content
{
  "type": "https://developer.vonage.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "ID 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.vonage.com/api-errors/10dlc#invalid-number-data",
  "title": "There were some issues with the submitted data",
  "detail": "There were some errors submitting your campaign, please correct the requested fields",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c",
  "invalid_parameters": [
    {
      "field": "country",
      "description": "Field 'country' is not a valid value"
    }
  ]
}

Errors

The following is a non-exhaustive list of error codes that may occur while using this API. These codes are in addition to any of our generic error codes.

Code Details
brand-conflict

A conflict when a brand is being created or edited and there is an issue with a 3rd party vendor.

brand-parameters

There are errors in the brand data submitted.

invalid-usecase-data

There are errors in the data submitted for use case qualification.

use-case-denied

The use case requested has been denied for this brand.

vetting-conflict

A conflict during the brand vetting request has occurred.

invalid-vetting-data

There are errors in the vetting request data submitted.

invalid-json

Your request cannot be parsed.

brand-not-qualified

A conflict when a campaign is being created under a brand that hasn't qualified for the specified use case.

invalid-campaign-data

There are errors in the campaign data submitted.

numbers-already-linked

The number you are attempting to link is already linked to another campaign.

invalid-number-data

There are errors in the number data submitted.