10DLC Brand and Campaign Provisioning
Overview
APIs relating to 10DLC brand and campaign management
For more information, please read the following documentation:
Changes
Upcoming changes
Reseller requirements
Date: Dec 1st 2024
The feature was postponed by TCR. In an effort to give more time to adapt to our customers, this change is being rescheduled and should be released around the 6th of January 2025.
TCR is making the reseller ID attribute mandatory on all new and updated campaigns starting on December 1st.
Customer campaigns (aka non reseller campaigns) will be assigned a default reseller ID R000000 by Vonage. Preventing any further modification to the reseller information for that campaign.
As a reminder, Vonage introduced the concept of reseller brands, handling automatically the reseller information for all its campaigns, by setting brand.reseller to true.
More information here.
message_flow deprecation
Date: Jan 6th 2025
The message_flow field in the POST /brands/{brand_id}/campaigns and PATCH /brands/{brand_id}/campaigns/{campaign_id} endpoints was deprecated in favor of message_flow_details. It will be removed on January 6th.
The message_flow will still exist and be readable. Its value will be computed by the API from the message_flow_details object.
Please make the appropriate changes in the time.
Changelog
Active campaign reviews
Date: Oct 28th 2024
Vonage is introducing a new traffic_enabled flag and will now trigger a new compliance review after campaign updates. Please remember that 10DLC campaign should adhere to 10DLC compliance requirements through their lifetime.
More information on:
Authentication+
Date: Oct 17th 2024
TCR is introduction a new brand verification process named "Authentication+" which involves a 2FA verification email. This new verification process is required for all new and existing PUBLIC_PROFIT brands. TCR will extend to more entity types in the future.
More information here.
Available Operations
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
This is the minimum number of message samples for a campaign's usecase. This does not account for additional samples needed by a campaign's sub usecases.
Example Response
{
"alt_business_id_type": [
{
"id": "string"
}
],
"brand_relationship": [
{
"id": "string"
}
],
"brand_status": [
{
"id": "string"
}
],
"campaign_status": [
{
"description": "string",
"id": "string"
}
],
"campaign_op_status": [
{
"id": "string"
}
],
"compliance": [
{
"id": "string"
}
],
"country": [
{
"description": "string",
"id": "string"
}
],
"cnp": [
{
"description": "string",
"id": "string"
}
],
"dca": [
{
"description": "string",
"id": "string"
}
],
"entity_type": [
{
"id": "string"
}
],
"event_category": [
{
"id": "string"
}
],
"identity_status": [
{
"id": "string"
}
],
"mno": [
{
"id": "string",
"mno": "string"
}
],
"nudge_intent": [
{
"id": "string"
}
],
"number_status": [
{
"id": "string"
}
],
"opt_attribute_name": [
{
"description": "string",
"id": "string",
"type": "string"
}
],
"sharing_status": [
{
"id": "string"
}
],
"stock_exchange": [
{
"country": "string",
"description": "string",
"id": "string"
}
],
"tcr_campaign_status": [
{
"id": "string"
}
],
"tmo_brand_tier": [
{
"id": "string"
}
],
"usecase": [
{
"classification": "string",
"description": "string",
"display_name": "string",
"id": "string",
"max_sub_usecases": 0,
"min_sub_usecases": 0,
"valid_sub_usecase": 0,
"min_msg_samples": 0
}
],
"usstate": [
{
"description": "string",
"id": "string"
}
],
"vertical": [
{
"description": "string",
"display_name": "string",
"id": "string",
"industry_id": "string"
}
],
"vetting_class": [
{
"description": "string",
"display_name": "string",
"enabled": 0,
"id": "string",
"validity_months": 0
}
],
"vetting_provider": [
{
"display_name": "string",
"id": "string",
"vetting_classes": "string"
}
],
"vetting_status": [
{
"id": "string"
}
],
"vetting_appeal_category": [
{
"id": "string",
"display_name": "string",
"description": "string"
}
]
}Available Operations
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
trueSpecifies whether opt-out assist is enabled for this account.
It is only possible to enable opt out assist. To disable, please reach out to support.
Example Response
{
"opt_out_assist": true
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
trueSpecifies whether opt-out assist is enabled for this account.
It is only possible to enable opt out assist. To disable, please reach out to support.
Example Request
{
"opt_out_assist": true
}{
"opt_out_assist": true
}Brands
This section outlines the endpoints to register and manage your 10DLC brands.
Recently updated:
reseller(boolean): designates a brand as reseller brand
Updating the reseller boolean on existing brands will attempt to update all existing campaigns with the reseller ID information.
All campaigns registered on reseller brands will be designated as reseller campaigns automatically.PUBLIC_PROFITbrands onlyverification_email(string): Email address used for the Authentication+ verificationverification_email_completion_date(string): Completion date of the Authentication+ verification
- Only registered 10DLC Resellers (
PENDINGorAPPROVED) can register reseller brands
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Query Parameters
12Page of results to jump to
10Number of results per page
Narrow down results based on matching conditions. Follow the comprehensive guide to learn how to craft filter queries.
One or multiple status can be given. Thus ACTIVE and SUSPENDED. The endpoint then returns the brands with the chosen status. If no status is chosen, both ACTIVE and SUSPENDED brands would be returned.
ACTIVESUSPENDEDTERMINATEDDELETED10Items per page
12Page Offset
1100Number of pages in the entire result set
100Number of items in the entire result set
abcd1234The Vonage Account ID
abcd1234The Vonage Primary Account ID (the parent account of account_id).
PUBLIC_PROFITEntity type behind the brand. This is the form of business establishment. NB: The GOVERNMENT entity_type is ONLY applicable to US governmental agencies (FBI, CIA, Department of defence etc.) Other countries’ governmental agencies must use NON_PROFIT entity type. Please refer to the /enum endpoint for an update list of valid values.
PRIVATE_PROFITPUBLIC_PROFITNON_PROFITSOLE_PROPRIETORGOVERNMENT100JohnFirst name of business contact. NB: Required for SOLE_PROPRIETOR entity type
100Smithlast name of business contact. NB: Required for SOLE_PROPRIETOR entity type
255VonageDisplay or marketing name of the brand.
255VonageLegal company name.
2120-1111111(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.
USISO3166-Alpha2 country code.
5020-1111111Universal EIN of Brand, Read-Only
50DUNSRequired if alt_business_id is provided.
DUNSGIINLEI50150483782Required if alt_business_id_type is provided.
15556660001Valid phone number in E.164 international format without the + prefix.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
10023 Main StreetStreet number and name.
100HolmdelCity name
20NJState. Must be 2 letters code for U.S.A.
1007733Postal codes. Use 5 digit zipcode for United States
USISO3166-Alpha2 country code.
100devrel@vonage.comValid email address of brand support contact.
10VGStock Symbol - Required if entity_type=PUBLIC_PROFIT.
10NASDAQRequired if entity_type=PUBLIC_PROFIT.
NONEAMEXAMXASXB3BMEBSEFRAICEXJSEKRXLONNASDAQNSENYSEOMXSEHKSSESTOSWXSZSETSXTWSEVSEhttps://vonage.comBrand website URL.
TECHNOLOGYBusiness/industry segment of this campaign. Use the /enum endpoint to get an updated list of verticals
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATION100verification_email@vonage.comValid verification email address of brand. Required if entity_type=PUBLIC_PROFIT.
2019-08-24 14:15:22Completion date when verification email address has been successfully verified.
Indicates if a brand is a reseller brand.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
Campaigns created on a reseller brand will automatically have their reseller_id field set with the primary account's reseller id.
50BLQKOPKTCR Brand ID.
5Number of campaigns associated with the brand
Summarize the reason of the suspension.
Detailed explanation of the cause of the suspension.
BASIC_ACCOUNTBrand relationship level.
BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNTFlag indicating the brand is related to a partner customer (brand & campaigns registered directly on TCR and shared with Vonage)
True when the brand is shared with the current Account ID.
True when the brand is owned by the requesting account.
Brand status.
Unique identifier for preventing duplicate brand registration into TCR.
Date-time when brand mobile phone was verified.
2019-08-24 14:15:222019-09-24 14:15:22https://api.nexmo.com/10dlc/brands/BLQKOPKhttps://api.nexmo.com/10dlc/brands/BLQKOPK/campaignshttps://api.nexmo.com/v1/10dlc/brands/BLQKOPK?page=2https://api.nexmo.com/v1/10dlc/brands/?page=3https://api.nexmo.com/v1/10dlc/brands/?page=1https://api.nexmo.com/v1/10dlc/brands/?page=1https://api.nexmo.com/v1/10dlc/brands/?page=10Example Response
{
"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",
"mobile_phone": "123123222334",
"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",
"verification_email": "verification_email@vonage.com",
"verification_email_completion_date": "2019-08-24 14:15:22",
"reseller": true,
"brand_id": "BLQKOPK",
"campaign_count": 5,
"carrier_suspensions": [
[
{}
]
],
"brand_relationship": "BASIC_ACCOUNT",
"partner": true,
"shared": true,
"owner": true,
"status": "string",
"reference_id": "string",
"verified_date": "2019-08-24T14:15:22Z",
"created_date": "2019-08-24 14:15:22",
"last_updated": "2019-09-24 14:15:22",
"_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=3"
},
"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"
}
}
}Create a new brand for your account
Create a new brand for your account. A brand is a business or individual identity behind the campaign. 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.`
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
abcd1234The Vonage Account ID
abcd1234The Vonage Primary Account ID (the parent account of account_id).
PUBLIC_PROFITEntity type behind the brand. This is the form of business establishment. NB: The GOVERNMENT entity_type is ONLY applicable to US governmental agencies (FBI, CIA, Department of defence etc.) Other countries’ governmental agencies must use NON_PROFIT entity type. Please refer to the /enum endpoint for an update list of valid values.
PRIVATE_PROFITPUBLIC_PROFITNON_PROFITSOLE_PROPRIETORGOVERNMENT100JohnFirst name of business contact. NB: Required for SOLE_PROPRIETOR entity type
100Smithlast name of business contact. NB: Required for SOLE_PROPRIETOR entity type
255VonageDisplay or marketing name of the brand.
255VonageLegal company name.
2120-1111111(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.
USISO3166-Alpha2 country code.
5020-1111111Universal EIN of Brand, Read-Only
50DUNSRequired if alt_business_id is provided.
DUNSGIINLEI50150483782Required if alt_business_id_type is provided.
15556660001Valid phone number in E.164 international format without the + prefix.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
10023 Main StreetStreet number and name.
100HolmdelCity name
20NJState. Must be 2 letters code for U.S.A.
1007733Postal codes. Use 5 digit zipcode for United States
USISO3166-Alpha2 country code.
100devrel@vonage.comValid email address of brand support contact.
10VGStock Symbol - Required if entity_type=PUBLIC_PROFIT.
10NASDAQRequired if entity_type=PUBLIC_PROFIT.
NONEAMEXAMXASXB3BMEBSEFRAICEXJSEKRXLONNASDAQNSENYSEOMXSEHKSSESTOSWXSZSETSXTWSEVSEhttps://vonage.comBrand website URL.
TECHNOLOGYBusiness/industry segment of this campaign. Use the /enum endpoint to get an updated list of verticals
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATION100verification_email@vonage.comValid verification email address of brand. Required if entity_type=PUBLIC_PROFIT.
2019-08-24 14:15:22Completion date when verification email address has been successfully verified.
Indicates if a brand is a reseller brand.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
Campaigns created on a reseller brand will automatically have their reseller_id field set with the primary account's reseller id.
Example Request»Fields required to create a brand with type other than PUBLIC_PROFIT or SOLE_PROPRIETOR.
{
"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",
"mobile_phone": "123123222334",
"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",
"verification_email": "verification_email@vonage.com",
"verification_email_completion_date": "2019-08-24 14:15:22",
"reseller": true
}{
"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",
"mobile_phone": "123123222334",
"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",
"verification_email": "verification_email@vonage.com",
"verification_email_completion_date": "2019-08-24 14:15:22",
"reseller": true
}abcd1234The Vonage Account ID
abcd1234The Vonage Primary Account ID (the parent account of account_id).
PUBLIC_PROFITEntity type behind the brand. This is the form of business establishment. NB: The GOVERNMENT entity_type is ONLY applicable to US governmental agencies (FBI, CIA, Department of defence etc.) Other countries’ governmental agencies must use NON_PROFIT entity type. Please refer to the /enum endpoint for an update list of valid values.
PRIVATE_PROFITPUBLIC_PROFITNON_PROFITSOLE_PROPRIETORGOVERNMENT100JohnFirst name of business contact. NB: Required for SOLE_PROPRIETOR entity type
100Smithlast name of business contact. NB: Required for SOLE_PROPRIETOR entity type
255VonageDisplay or marketing name of the brand.
255VonageLegal company name.
2120-1111111(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.
USISO3166-Alpha2 country code.
5020-1111111Universal EIN of Brand, Read-Only
50DUNSRequired if alt_business_id is provided.
DUNSGIINLEI50150483782Required if alt_business_id_type is provided.
15556660001Valid phone number in E.164 international format without the + prefix.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
10023 Main StreetStreet number and name.
100HolmdelCity name
20NJState. Must be 2 letters code for U.S.A.
1007733Postal codes. Use 5 digit zipcode for United States
USISO3166-Alpha2 country code.
100devrel@vonage.comValid email address of brand support contact.
10VGStock Symbol - Required if entity_type=PUBLIC_PROFIT.
10NASDAQRequired if entity_type=PUBLIC_PROFIT.
NONEAMEXAMXASXB3BMEBSEFRAICEXJSEKRXLONNASDAQNSENYSEOMXSEHKSSESTOSWXSZSETSXTWSEVSEhttps://vonage.comBrand website URL.
TECHNOLOGYBusiness/industry segment of this campaign. Use the /enum endpoint to get an updated list of verticals
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATION100verification_email@vonage.comValid verification email address of brand. Required if entity_type=PUBLIC_PROFIT.
2019-08-24 14:15:22Completion date when verification email address has been successfully verified.
Indicates if a brand is a reseller brand.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
Campaigns created on a reseller brand will automatically have their reseller_id field set with the primary account's reseller id.
50BLQKOPKTCR Brand ID.
5Number of campaigns associated with the brand
Summarize the reason of the suspension.
Detailed explanation of the cause of the suspension.
BASIC_ACCOUNTBrand relationship level.
BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNTFlag indicating the brand is related to a partner customer (brand & campaigns registered directly on TCR and shared with Vonage)
True when the brand is shared with the current Account ID.
True when the brand is owned by the requesting account.
Brand status.
Unique identifier for preventing duplicate brand registration into TCR.
Date-time when brand mobile phone was verified.
2019-08-24 14:15:222019-09-24 14:15:22https://api.nexmo.com/10dlc/brands/BLQKOPKhttps://api.nexmo.com/10dlc/brands/BLQKOPK/campaignsExample Response
{
"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",
"mobile_phone": "123123222334",
"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",
"verification_email": "verification_email@vonage.com",
"verification_email_completion_date": "2019-08-24 14:15:22",
"reseller": true,
"brand_id": "BLQKOPK",
"campaign_count": 5,
"carrier_suspensions": [
[
{}
]
],
"brand_relationship": "BASIC_ACCOUNT",
"partner": true,
"shared": true,
"owner": true,
"status": "string",
"reference_id": "string",
"verified_date": "2019-08-24T14:15:22Z",
"created_date": "2019-08-24 14:15:22",
"last_updated": "2019-09-24 14:15:22",
"_links": {
"self": {
"href": "https://api.nexmo.com/10dlc/brands/BLQKOPK"
},
"campaigns": {
"href": "https://api.nexmo.com/10dlc/brands/BLQKOPK/campaigns"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
abcd1234The Vonage Account ID
abcd1234The Vonage Primary Account ID (the parent account of account_id).
PUBLIC_PROFITEntity type behind the brand. This is the form of business establishment. NB: The GOVERNMENT entity_type is ONLY applicable to US governmental agencies (FBI, CIA, Department of defence etc.) Other countries’ governmental agencies must use NON_PROFIT entity type. Please refer to the /enum endpoint for an update list of valid values.
PRIVATE_PROFITPUBLIC_PROFITNON_PROFITSOLE_PROPRIETORGOVERNMENT100JohnFirst name of business contact. NB: Required for SOLE_PROPRIETOR entity type
100Smithlast name of business contact. NB: Required for SOLE_PROPRIETOR entity type
255VonageDisplay or marketing name of the brand.
255VonageLegal company name.
2120-1111111(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.
USISO3166-Alpha2 country code.
5020-1111111Universal EIN of Brand, Read-Only
50DUNSRequired if alt_business_id is provided.
DUNSGIINLEI50150483782Required if alt_business_id_type is provided.
15556660001Valid phone number in E.164 international format without the + prefix.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
10023 Main StreetStreet number and name.
100HolmdelCity name
20NJState. Must be 2 letters code for U.S.A.
1007733Postal codes. Use 5 digit zipcode for United States
USISO3166-Alpha2 country code.
100devrel@vonage.comValid email address of brand support contact.
10VGStock Symbol - Required if entity_type=PUBLIC_PROFIT.
10NASDAQRequired if entity_type=PUBLIC_PROFIT.
NONEAMEXAMXASXB3BMEBSEFRAICEXJSEKRXLONNASDAQNSENYSEOMXSEHKSSESTOSWXSZSETSXTWSEVSEhttps://vonage.comBrand website URL.
TECHNOLOGYBusiness/industry segment of this campaign. Use the /enum endpoint to get an updated list of verticals
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATION100verification_email@vonage.comValid verification email address of brand. Required if entity_type=PUBLIC_PROFIT.
2019-08-24 14:15:22Completion date when verification email address has been successfully verified.
Indicates if a brand is a reseller brand.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
Campaigns created on a reseller brand will automatically have their reseller_id field set with the primary account's reseller id.
50BLQKOPKTCR Brand ID.
5Number of campaigns associated with the brand
Summarize the reason of the suspension.
Detailed explanation of the cause of the suspension.
BASIC_ACCOUNTBrand relationship level.
BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNTFlag indicating the brand is related to a partner customer (brand & campaigns registered directly on TCR and shared with Vonage)
True when the brand is shared with the current Account ID.
True when the brand is owned by the requesting account.
Brand status.
Unique identifier for preventing duplicate brand registration into TCR.
Date-time when brand mobile phone was verified.
2019-08-24 14:15:222019-09-24 14:15:22https://api.nexmo.com/10dlc/brands/BLQKOPKhttps://api.nexmo.com/10dlc/brands/BLQKOPK/campaignsExample Response
{
"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",
"mobile_phone": "123123222334",
"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",
"verification_email": "verification_email@vonage.com",
"verification_email_completion_date": "2019-08-24 14:15:22",
"reseller": true,
"brand_id": "BLQKOPK",
"campaign_count": 5,
"carrier_suspensions": [
[
{}
]
],
"brand_relationship": "BASIC_ACCOUNT",
"partner": true,
"shared": true,
"owner": true,
"status": "string",
"reference_id": "string",
"verified_date": "2019-08-24T14:15:22Z",
"created_date": "2019-08-24 14:15:22",
"last_updated": "2019-09-24 14:15:22",
"_links": {
"self": {
"href": "https://api.nexmo.com/10dlc/brands/BLQKOPK"
},
"campaigns": {
"href": "https://api.nexmo.com/10dlc/brands/BLQKOPK/campaigns"
}
}
}Partially update a 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.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
255VonageLegal company name.
100JohnFirst name of business contact. NB: Required for SOLE_PROPRIETOR entity type
100Smithlast name of business contact. NB: Required for SOLE_PROPRIETOR entity type
255VonageDisplay or marketing name of the brand.
2120-1111111(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.
USISO3166-Alpha2 country code.
PUBLIC_PROFITEntity type behind the brand. This is the form of business establishment. NB: The GOVERNMENT entity_type is ONLY applicable to US governmental agencies (FBI, CIA, Department of defence etc.) Other countries’ governmental agencies must use NON_PROFIT entity type. Please refer to the /enum endpoint for an update list of valid values.
PRIVATE_PROFITPUBLIC_PROFITNON_PROFITSOLE_PROPRIETORGOVERNMENThttps://vonage.comBrand website URL.
15556660001Valid phone number in E.164 international format without the + prefix.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
10023 Main StreetStreet number and name.
100HolmdelCity name
20NJState. Must be 2 letters code for U.S.A.
1007733Postal codes. Use 5 digit zipcode for United States
USISO3166-Alpha2 country code.
100devrel@vonage.comValid email address of brand support contact.
10VGStock Symbol - Required if entity_type=PUBLIC_PROFIT.
10NASDAQRequired if entity_type=PUBLIC_PROFIT.
NONEAMEXAMXASXB3BMEBSEFRAICEXJSEKRXLONNASDAQNSENYSEOMXSEHKSSESTOSWXSZSETSXTWSEVSETECHNOLOGYBusiness/industry segment of this campaign. Use the /enum endpoint to get an updated list of verticals
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATIONIndicates if a brand is a reseller brand.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
Campaigns created on a reseller brand will automatically have their reseller_id field set with the primary account's reseller id.
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",
"mobile_phone": "123123222334",
"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",
"reseller": true
}{
"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",
"mobile_phone": "123123222334",
"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",
"reseller": true
}abcd1234The Vonage Account ID
abcd1234The Vonage Primary Account ID (the parent account of account_id).
PUBLIC_PROFITEntity type behind the brand. This is the form of business establishment. NB: The GOVERNMENT entity_type is ONLY applicable to US governmental agencies (FBI, CIA, Department of defence etc.) Other countries’ governmental agencies must use NON_PROFIT entity type. Please refer to the /enum endpoint for an update list of valid values.
PRIVATE_PROFITPUBLIC_PROFITNON_PROFITSOLE_PROPRIETORGOVERNMENT100JohnFirst name of business contact. NB: Required for SOLE_PROPRIETOR entity type
100Smithlast name of business contact. NB: Required for SOLE_PROPRIETOR entity type
255VonageDisplay or marketing name of the brand.
255VonageLegal company name.
2120-1111111(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.
USISO3166-Alpha2 country code.
5020-1111111Universal EIN of Brand, Read-Only
50DUNSRequired if alt_business_id is provided.
DUNSGIINLEI50150483782Required if alt_business_id_type is provided.
15556660001Valid phone number in E.164 international format without the + prefix.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
10023 Main StreetStreet number and name.
100HolmdelCity name
20NJState. Must be 2 letters code for U.S.A.
1007733Postal codes. Use 5 digit zipcode for United States
USISO3166-Alpha2 country code.
100devrel@vonage.comValid email address of brand support contact.
10VGStock Symbol - Required if entity_type=PUBLIC_PROFIT.
10NASDAQRequired if entity_type=PUBLIC_PROFIT.
NONEAMEXAMXASXB3BMEBSEFRAICEXJSEKRXLONNASDAQNSENYSEOMXSEHKSSESTOSWXSZSETSXTWSEVSEhttps://vonage.comBrand website URL.
TECHNOLOGYBusiness/industry segment of this campaign. Use the /enum endpoint to get an updated list of verticals
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATION100verification_email@vonage.comValid verification email address of brand. Required if entity_type=PUBLIC_PROFIT.
2019-08-24 14:15:22Completion date when verification email address has been successfully verified.
Indicates if a brand is a reseller brand.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
Campaigns created on a reseller brand will automatically have their reseller_id field set with the primary account's reseller id.
50BLQKOPKTCR Brand ID.
5Number of campaigns associated with the brand
Summarize the reason of the suspension.
Detailed explanation of the cause of the suspension.
BASIC_ACCOUNTBrand relationship level.
BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNTFlag indicating the brand is related to a partner customer (brand & campaigns registered directly on TCR and shared with Vonage)
True when the brand is shared with the current Account ID.
True when the brand is owned by the requesting account.
Brand status.
Unique identifier for preventing duplicate brand registration into TCR.
Date-time when brand mobile phone was verified.
2019-08-24 14:15:222019-09-24 14:15:22https://api.nexmo.com/10dlc/brands/BLQKOPKhttps://api.nexmo.com/10dlc/brands/BLQKOPK/campaignsExample Response
{
"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",
"mobile_phone": "123123222334",
"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",
"verification_email": "verification_email@vonage.com",
"verification_email_completion_date": "2019-08-24 14:15:22",
"reseller": true,
"brand_id": "BLQKOPK",
"campaign_count": 5,
"carrier_suspensions": [
[
{}
]
],
"brand_relationship": "BASIC_ACCOUNT",
"partner": true,
"shared": true,
"owner": true,
"status": "string",
"reference_id": "string",
"verified_date": "2019-08-24T14:15:22Z",
"created_date": "2019-08-24 14:15:22",
"last_updated": "2019-09-24 14:15:22",
"_links": {
"self": {
"href": "https://api.nexmo.com/10dlc/brands/BLQKOPK"
},
"campaigns": {
"href": "https://api.nexmo.com/10dlc/brands/BLQKOPK/campaigns"
}
}
}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.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Get feedback of a brand by Brand ID.
Retrieve feedback of a specific brand with Brand ID.
The endpoint will only respond correctly if the brand's identity status is already checked. If the brand's identity status is still PENDING, it will answer with a 422 error.
Also, if the brand's identity status is not UNVERIFIED, the response should be empty.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
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.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Path Parameters
50BLQKOPKTCR Brand ID
Name of a use case
CUSTOMER_CAREPOLLING_VOTINGHIGHER_EDUCATIONPUBLIC_SERVICE_ANNOUNCEMENTMARKETINGSECURITY_ALERTDELIVERY_NOTIFICATIONACCOUNT_NOTIFICATION2FAFRAUD_ALERTTRIALCHARITYPOLITICALEMERGENCYSWEEPSTAKECONVERSATIONALMIXEDCARRIER_EXEMPTSOCIALLOW_VOLUMEPOLITICAL303010017Network ID of the MNO.
AT&TName of the MNO.
MNO campaign operation status. Please refer to the campaign_op_status property of the /enum endpoint response for an updated list of valid values.
If 'false', then the desired usecase cannot be supported by the MNO.
If 'true', then the submitted campaign is subject to the MNO (manual) review process.
If 'false', then the brand does not qualify for the desired usecase on the MNO.
2The minimum number of message samples required by MNO for submission of the desired usecase.
If 'true' then MNO requires the subscriber to opt-into the campaign before the message may be sent to the subscriber. The opt-in mechanism can be mobile or web opt-in.
If 'true' then MNO requires a campaign to support an opt-out mechanism through MO stop keywords such as 'STOP', 'QUIT'. Upon receive the STOP message from a subscriber, the campaign must stop sending messages to the subscriber immediately.
If 'true' then MNO requires a campaign to support a 'help' mechanism through MO help key words such as 'HELP', 'INFO'.
If 'true' then MNO forbids call-to-action link/URL to be embedded in all messages sent to the subscriber.
If 'true' then MNO forbids call-to-action phone number to be embedded in all messages sent to the subscriber.
Q(Only for AT&T). Message class assigned to the campaign by MNO. Please refer to the AT&T 10DLC guide for a complete list of available message class and definition.
3000(Only for AT&T). SMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
3000(Only for AT&T). MMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
(Only for AT&T). Whether is the MNO applying the TPM per number or per campaign.
LOW(Only for T-Mobile). Daily message volume is restricted based on brand tier or brand qualification. The daily volume restriction applies to brand across campaigns and CSPs. Please refer to the /enum endpoint for an updated list of valid values.
LOWLOWER_MIDUPPER_MIDTOPUNCAPPED(Only for TMobile). Message TPD (throughput per day) qualified by the brand for the desired usecase.
65535Description of this MNO complaint.
SINCHdca name
Date-time when this record was created.
Example Response
{
"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
}
]
}Brand verification
This section outlines the endpoints to verify your brand. Please read this guide for more information.
Brand verification
Brand vetting
- Standard vet
- Enhanced vet
- Political vet
Verification and vetting appeals
Available Operations
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Your verification code is @OTP_PIN@Template OTP message to be sent to the brand's mobilePhone. Must contain either @OTP_PIN@ or @OTP_YES@ macro element. If @OTP_YES@ macro is only with SMS reply confirmation flow.
Your verification code has been confirmed successfullySMS to be sent to the brand's mobile phone upon successful SMS reply OTP confirmation.
Example Request
{
"verify_sms": "Your verification code is @OTP_PIN@",
"success_sms": "Your verification code has been confirmed successfully"
}{
"verify_sms": "Your verification code is @OTP_PIN@",
"success_sms": "Your verification code has been confirmed successfully"
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
66Code received by the brand's registered mobile phone number after starting the OTP verification process.
Example Request
{
"otp_pin": "string"
}{
"otp_pin": "string"
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
50BLQKOPKTCR Brand ID.
OTP1234567Reference ID for tracking the status of the OTP request.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
SMS OTP initial requested timestamp.
OTP verification complete timestamp.
The most recent SMS delivery status as provided by an SMS service provider, if supported by the SMS service provider. The delivery status information is not guaranteed to be timely or consistent with OTP verify status. This information should only be used to facilitate triaging SMS derivability issue.
DELIVERED_HANDSETDELIVERED_GATEWAYFAILED_ROUTINGFAILED_BLOCKEDFAILED_EXPIREDFAILED_UNKNOWNUNKNOWN_STATUSIN_TRANSITTimestamp corresponding to the updated SMS OTP delivery status. This field is null if delivery_status is null.
1024OTP SMS delivery status details provided by the OTP SMS service provider, if supported by the SMS service provider.
Example Response
{
"brand_id": "BLQKOPK",
"reference_id": "OTP1234567",
"mobile_phone": "123123222334",
"request_date": "2019-08-24T14:15:22Z",
"verity_date": "2019-08-24T14:15:22Z",
"delivery_status": "DELIVERED_HANDSET",
"delivery_status_date": "2019-08-24T14:15:22Z",
"delivery_status_details": "2019-08-24T14:15:22Z"
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
abcd1234The Vonage Account ID
ID associated with a vetting request
100Vetting score ranging from 0-100.
Identifies a vetting request status. Please refer to the /enum endpoint for an updated list of valid values.
PENDINGUNSCOREACTIVEFAILEDEXPIREDCollection of non-standard attributes (key-value pairs), applicable to some vetting records.
Vetting effective date. This is the date when vetting was completed, or the starting effective date. If this date is missing, then the vetting was not complete or not valid.
The list of reasons for a FAILED external vetting.
Additional brand information in json format. Required for POLITICAL type vets.
JohnFirst name of vetting requester.
DoeLast name of vetting requester.
FederalLocale.
FederalStateLocalTribalCCommittee type codes.
CDEHINOPQSUVWXYZ00000Free text field. The committee/campaign ID issued for Federal and any other locale - if not issued, enter "00000".
PACFree text field. Required for campaigns. If committee is not candidate-specific, enter "PAC".
FEDERALFree text field. Required for State, Local, and Tribal -- if Federal, enter "FEDERAL".
AZIf Federal Congress, enter the state(2 letter code) to be represented; if President, enter "US".
USFree text field. If Federal Congress, enter district to be represented; if President, enter "US".
USFree text field. If non-tribal, enter "US".
https://example.comShould be a valid URL format. Election authority website URL where the filing information can be found.
Additional instructionsFree text field. Additional instructions to aid in locating the filing record.
John@email.comFree text field. Exactly as filed with election authority. If not supplied, PIN cannot be sent via email.
2022-31-10Date string in the format yyyy-dd-mm. Must be in the future.
RegularPin preference.
RegularExpressEmailhttps://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234https://api.nexmo.com/v1/10dlc/brands/BLQKOPKExample Response
[
{
"account_id": "abcd1234",
"evp_id": "string",
"vetting_id": "string",
"vetting_token": "string",
"vetting_score": 100,
"vetting_class": "string",
"vetting_status": "PENDING",
"vetting_details": {},
"vetted_date": "2019-08-24T14:15:22Z",
"created_date": "2019-08-24T14:15:22Z",
"failed_reasons": [
"string"
],
"additional_info": {
"requestor_first_name": "John",
"requestor_last_name": "Doe",
"locale": "Federal",
"fec_committee_type_code": "C",
"committee_id": "00000",
"candidate_type": "PAC",
"state_local_committee_type": "FEDERAL",
"local_committee_state": "AZ",
"local_committee_municipality": "US",
"tribal_location": "US",
"filing_url": "https://example.com",
"filing_record_url_instructions": "Additional instructions",
"filing_email": "John@email.com",
"election_date": "2022-31-10",
"pin_preference": "Regular"
},
"_links": {
"self": {
"href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234"
},
"brand": {
"href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
}
}
}
]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.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
abcd123This value must be the ID associated with one of the supported vetting providers.
AegisCVWMCabcd123Type of vetting to perform.
Additional political details in json format, required for POLITICAL type vetting. If non-POLITICAL type its neglected.
JohnFirst name of vetting requester.
DoeLast name of vetting requester.
FederalLocale.
FederalStateLocalTribalCCommittee type codes.
CDEHINOPQSUVWXYZ00000Free text field. The committee/campaign ID issued for Federal and any other locale - if not issued, enter "00000".
PACFree text field. Required for campaigns. If committee is not candidate-specific, enter "PAC".
FEDERALFree text field. Required for State, Local, and Tribal -- if Federal, enter "FEDERAL".
AZIf Federal Congress, enter the state(2 letter code) to be represented; if President, enter "US".
USFree text field. If Federal Congress, enter district to be represented; if President, enter "US".
USFree text field. If non-tribal, enter "US".
https://example.comShould be a valid URL format. Election authority website URL where the filing information can be found.
Additional instructionsFree text field. Additional instructions to aid in locating the filing record.
john@email.comFree text field. Exactly as filed with election authority. If not supplied, PIN cannot be sent via email.
2022-10-31Date string in the format yyyy-mm-dd. Must be in the future.
RegularPin preference.
RegularExpressEmailContains vetting appeals, if any has been submitted.
Explanation that was given when creating the appeal.
The status of the appeal. Please refer to the /enum endpoint for an updated list of valid values.
PENDINGCOMPLETEAn array of categories that the appeal applies to. Please refer to the /enum endpoint for an updated list of valid values.
The list of evidence files that were sent with this appeal.
ID of the evidence. To be used in the appeal process.
The name of the uploaded file.
The mime type of the uploaded file.
The outcome of the appeal. This is filled only when the appeal is completed.
Identifies a vetting request status. Please refer to the /enum endpoint for an updated list of valid values.
PENDINGUNSCOREACTIVEFAILEDEXPIRED100Vetting score ranging from 0-100.
Feedback given by the provider to explain the vetting outcome.
Date-time when this record was created.
Date-time when this record was last updated.
Example Request
{
"evp_id": "abcd123",
"vetting_class": "abcd123",
"vetting_political_details": {
"requestor_first_name": "John",
"requestor_last_name": "Doe",
"locale": "Federal",
"fec_committee_type_code": "C",
"committee_id": "00000",
"candidate_type": "PAC",
"state_local_committee_type": "FEDERAL",
"local_committee_state": "AZ",
"local_committee_municipality": "US",
"tribal_location": "US",
"filing_url": "https://example.com",
"filing_record_url_instructions": "Additional instructions",
"filing_email": "john@email.com",
"election_date": "2022-10-31",
"pin_preference": "Regular"
},
"appeals": [
{
"explanation": "Please find attached the evidence proving our tax ID.",
"status": "COMPLETE",
"categories": [
"VERIFY_TAX_ID"
],
"evidences": [
{
"id": "c94eea77-1494-4b8f-99dc-63a036126368",
"file_name": "tax_registration.pdf",
"mime_type": "application/pdf"
}
],
"outcome": {
"vetting_status": "ACTIVE",
"vetting_score": 100,
"feedback": {
"reasons": [
"Provided evidence match the tax id."
]
}
},
"created_date": {},
"last_updated": {}
},
{
"explanation": "We think the low score is not warranted because ...",
"status": "PENDING",
"categories": [
"LOW_SCORE"
],
"evidences": [
{
"id": "b4513738-72c3-4720-bd73-47919ddde812",
"file_name": "explanation_details.txt",
"mime_type": "text/plain"
}
],
"created_date": {},
"last_updated": {}
}
]
}{
"evp_id": "abcd123",
"vetting_class": "abcd123",
"vetting_political_details": {
"requestor_first_name": "John",
"requestor_last_name": "Doe",
"locale": "Federal",
"fec_committee_type_code": "C",
"committee_id": "00000",
"candidate_type": "PAC",
"state_local_committee_type": "FEDERAL",
"local_committee_state": "AZ",
"local_committee_municipality": "US",
"tribal_location": "US",
"filing_url": "https://example.com",
"filing_record_url_instructions": "Additional instructions",
"filing_email": "john@email.com",
"election_date": "2022-10-31",
"pin_preference": "Regular"
},
"appeals": [
{
"explanation": "Please find attached the evidence proving our tax ID.",
"status": "COMPLETE",
"categories": [
"VERIFY_TAX_ID"
],
"evidences": [
{
"id": "c94eea77-1494-4b8f-99dc-63a036126368",
"file_name": "tax_registration.pdf",
"mime_type": "application/pdf"
}
],
"outcome": {
"vetting_status": "ACTIVE",
"vetting_score": 100,
"feedback": {
"reasons": [
"Provided evidence match the tax id."
]
}
},
"created_date": {},
"last_updated": {}
},
{
"explanation": "We think the low score is not warranted because ...",
"status": "PENDING",
"categories": [
"LOW_SCORE"
],
"evidences": [
{
"id": "b4513738-72c3-4720-bd73-47919ddde812",
"file_name": "explanation_details.txt",
"mime_type": "text/plain"
}
],
"created_date": {},
"last_updated": {}
}
]
}abcd1234The Vonage Account ID
ID associated with a vetting request
100Vetting score ranging from 0-100.
Identifies a vetting request status. Please refer to the /enum endpoint for an updated list of valid values.
PENDINGUNSCOREACTIVEFAILEDEXPIREDCollection of non-standard attributes (key-value pairs), applicable to some vetting records.
Vetting effective date. This is the date when vetting was completed, or the starting effective date. If this date is missing, then the vetting was not complete or not valid.
The list of reasons for a FAILED external vetting.
Additional brand information in json format. Required for POLITICAL type vets.
JohnFirst name of vetting requester.
DoeLast name of vetting requester.
FederalLocale.
FederalStateLocalTribalCCommittee type codes.
CDEHINOPQSUVWXYZ00000Free text field. The committee/campaign ID issued for Federal and any other locale - if not issued, enter "00000".
PACFree text field. Required for campaigns. If committee is not candidate-specific, enter "PAC".
FEDERALFree text field. Required for State, Local, and Tribal -- if Federal, enter "FEDERAL".
AZIf Federal Congress, enter the state(2 letter code) to be represented; if President, enter "US".
USFree text field. If Federal Congress, enter district to be represented; if President, enter "US".
USFree text field. If non-tribal, enter "US".
https://example.comShould be a valid URL format. Election authority website URL where the filing information can be found.
Additional instructionsFree text field. Additional instructions to aid in locating the filing record.
John@email.comFree text field. Exactly as filed with election authority. If not supplied, PIN cannot be sent via email.
2022-31-10Date string in the format yyyy-dd-mm. Must be in the future.
RegularPin preference.
RegularExpressEmailhttps://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234https://api.nexmo.com/v1/10dlc/brands/BLQKOPKExample Response
{
"account_id": "abcd1234",
"evp_id": "string",
"vetting_id": "string",
"vetting_token": "string",
"vetting_score": 100,
"vetting_class": "string",
"vetting_status": "PENDING",
"vetting_details": {},
"vetted_date": "2019-08-24T14:15:22Z",
"created_date": "2019-08-24T14:15:22Z",
"failed_reasons": [
"string"
],
"additional_info": {
"requestor_first_name": "John",
"requestor_last_name": "Doe",
"locale": "Federal",
"fec_committee_type_code": "C",
"committee_id": "00000",
"candidate_type": "PAC",
"state_local_committee_type": "FEDERAL",
"local_committee_state": "AZ",
"local_committee_municipality": "US",
"tribal_location": "US",
"filing_url": "https://example.com",
"filing_record_url_instructions": "Additional instructions",
"filing_email": "John@email.com",
"election_date": "2022-31-10",
"pin_preference": "Regular"
},
"_links": {
"self": {
"href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234"
},
"brand": {
"href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
}
}
}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.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
abcd123The identity of the vetting partner. This value must be the ID associated with one of the supported vetting providers.
AegisCVWMCabcd123Token verifying the vetting ID (only applicable to Aegis vetting).
abcd123Unique ID that identifies a vetting transaction performed by a vetting provider. This ID is provided by the vetting provider at time of vetting.
Example Request
{
"evp_id": "abcd123",
"vetting_token": "abcd123",
"vetting_id": "abcd123"
}{
"evp_id": "abcd123",
"vetting_token": "abcd123",
"vetting_id": "abcd123"
}abcd1234The Vonage Account ID
ID associated with a vetting request
100Vetting score ranging from 0-100.
Identifies a vetting request status. Please refer to the /enum endpoint for an updated list of valid values.
PENDINGUNSCOREACTIVEFAILEDEXPIREDCollection of non-standard attributes (key-value pairs), applicable to some vetting records.
Vetting effective date. This is the date when vetting was completed, or the starting effective date. If this date is missing, then the vetting was not complete or not valid.
The list of reasons for a FAILED external vetting.
Additional brand information in json format. Required for POLITICAL type vets.
JohnFirst name of vetting requester.
DoeLast name of vetting requester.
FederalLocale.
FederalStateLocalTribalCCommittee type codes.
CDEHINOPQSUVWXYZ00000Free text field. The committee/campaign ID issued for Federal and any other locale - if not issued, enter "00000".
PACFree text field. Required for campaigns. If committee is not candidate-specific, enter "PAC".
FEDERALFree text field. Required for State, Local, and Tribal -- if Federal, enter "FEDERAL".
AZIf Federal Congress, enter the state(2 letter code) to be represented; if President, enter "US".
USFree text field. If Federal Congress, enter district to be represented; if President, enter "US".
USFree text field. If non-tribal, enter "US".
https://example.comShould be a valid URL format. Election authority website URL where the filing information can be found.
Additional instructionsFree text field. Additional instructions to aid in locating the filing record.
John@email.comFree text field. Exactly as filed with election authority. If not supplied, PIN cannot be sent via email.
2022-31-10Date string in the format yyyy-dd-mm. Must be in the future.
RegularPin preference.
RegularExpressEmailhttps://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234https://api.nexmo.com/v1/10dlc/brands/BLQKOPKExample Response
{
"account_id": "abcd1234",
"evp_id": "string",
"vetting_id": "string",
"vetting_token": "string",
"vetting_score": 100,
"vetting_class": "string",
"vetting_status": "PENDING",
"vetting_details": {},
"vetted_date": "2019-08-24T14:15:22Z",
"created_date": "2019-08-24T14:15:22Z",
"failed_reasons": [
"string"
],
"additional_info": {
"requestor_first_name": "John",
"requestor_last_name": "Doe",
"locale": "Federal",
"fec_committee_type_code": "C",
"committee_id": "00000",
"candidate_type": "PAC",
"state_local_committee_type": "FEDERAL",
"local_committee_state": "AZ",
"local_committee_municipality": "US",
"tribal_location": "US",
"filing_url": "https://example.com",
"filing_record_url_instructions": "Additional instructions",
"filing_email": "John@email.com",
"election_date": "2022-31-10",
"pin_preference": "Regular"
},
"_links": {
"self": {
"href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234"
},
"brand": {
"href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
}
}
}Request vetting appeal for a brand
This creates an appeal for the selected vetting.
Evidence files, previously uploaded with endpoint POST /v1/10dlc/brands/{brand_id}/appeal/evidence can be attached to the appeal.
Limitations:
- A maximum of 10 evidence files can be submitted with the appeal
- The total size of the evidence files cannot exceed 30MB
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
An array of categories that the appeal applies to. Please refer to the /enum endpoint for an updated list of valid values.
An array referencing previously uploaded evidence files IDs.
1024Explanation of why the appeal should be granted.
Example Request
{
"categories": [
"string"
],
"evidence_ids": [
"string"
],
"explanation": "string"
}{
"categories": [
"string"
],
"evidence_ids": [
"string"
],
"explanation": "string"
}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.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
abcd1234The Vonage Account ID
abcd1234The Vonage Primary Account ID (the parent account of account_id).
PUBLIC_PROFITEntity type behind the brand. This is the form of business establishment. NB: The GOVERNMENT entity_type is ONLY applicable to US governmental agencies (FBI, CIA, Department of defence etc.) Other countries’ governmental agencies must use NON_PROFIT entity type. Please refer to the /enum endpoint for an update list of valid values.
PRIVATE_PROFITPUBLIC_PROFITNON_PROFITSOLE_PROPRIETORGOVERNMENT100JohnFirst name of business contact. NB: Required for SOLE_PROPRIETOR entity type
100Smithlast name of business contact. NB: Required for SOLE_PROPRIETOR entity type
255VonageDisplay or marketing name of the brand.
255VonageLegal company name.
2120-1111111(Required for Non-profit) Government assigned corporate tax ID. EIN is 9-digits in U.S.A.
USISO3166-Alpha2 country code.
5020-1111111Universal EIN of Brand, Read-Only
50DUNSRequired if alt_business_id is provided.
DUNSGIINLEI50150483782Required if alt_business_id_type is provided.
15556660001Valid phone number in E.164 international format without the + prefix.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
10023 Main StreetStreet number and name.
100HolmdelCity name
20NJState. Must be 2 letters code for U.S.A.
1007733Postal codes. Use 5 digit zipcode for United States
USISO3166-Alpha2 country code.
100devrel@vonage.comValid email address of brand support contact.
10VGStock Symbol - Required if entity_type=PUBLIC_PROFIT.
10NASDAQRequired if entity_type=PUBLIC_PROFIT.
NONEAMEXAMXASXB3BMEBSEFRAICEXJSEKRXLONNASDAQNSENYSEOMXSEHKSSESTOSWXSZSETSXTWSEVSEhttps://vonage.comBrand website URL.
TECHNOLOGYBusiness/industry segment of this campaign. Use the /enum endpoint to get an updated list of verticals
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATION100verification_email@vonage.comValid verification email address of brand. Required if entity_type=PUBLIC_PROFIT.
2019-08-24 14:15:22Completion date when verification email address has been successfully verified.
Indicates if a brand is a reseller brand.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
Campaigns created on a reseller brand will automatically have their reseller_id field set with the primary account's reseller id.
50BLQKOPKTCR Brand ID.
5Number of campaigns associated with the brand
Summarize the reason of the suspension.
Detailed explanation of the cause of the suspension.
BASIC_ACCOUNTBrand relationship level.
BASIC_ACCOUNTSMALL_ACCOUNTMEDIUM_ACCOUNTLARGE_ACCOUNTKEY_ACCOUNTFlag indicating the brand is related to a partner customer (brand & campaigns registered directly on TCR and shared with Vonage)
True when the brand is shared with the current Account ID.
True when the brand is owned by the requesting account.
Brand status.
Unique identifier for preventing duplicate brand registration into TCR.
Date-time when brand mobile phone was verified.
2019-08-24 14:15:222019-09-24 14:15:22https://api.nexmo.com/10dlc/brands/BLQKOPKhttps://api.nexmo.com/10dlc/brands/BLQKOPK/campaignsExample Response
{
"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",
"mobile_phone": "123123222334",
"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",
"verification_email": "verification_email@vonage.com",
"verification_email_completion_date": "2019-08-24 14:15:22",
"reseller": true,
"brand_id": "BLQKOPK",
"campaign_count": 5,
"carrier_suspensions": [
[
{}
]
],
"brand_relationship": "BASIC_ACCOUNT",
"partner": true,
"shared": true,
"owner": true,
"status": "string",
"reference_id": "string",
"verified_date": "2019-08-24T14:15:22Z",
"created_date": "2019-08-24 14:15:22",
"last_updated": "2019-09-24 14:15:22",
"_links": {
"self": {
"href": "https://api.nexmo.com/10dlc/brands/BLQKOPK"
},
"campaigns": {
"href": "https://api.nexmo.com/10dlc/brands/BLQKOPK/campaigns"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Query Parameters
12Page of results to jump to
10Number of results per page
Narrow down results based on matching conditions. Follow the comprehensive guide to learn how to craft filter queries.
1512page_token to access the next page.
1512page_token to access the previous page.
1512page_token to access the last page.
1512page_token to access the first page.
Link to the next page.
Link to the previous page.
Link to the first page.
Link to the last page.
ID of the evidence. To be used in the appeal process.
The name of the uploaded file.
The mime type of the uploaded file.
Example Response
{
"next_page": "string",
"previous_page": "string",
"last_page": "string",
"first_page": "string",
"_links": {
"next": {
"href": "string"
},
"previous": {
"href": "string"
},
"first": {
"href": "string"
},
"last": {
"href": "string"
}
},
"_embedded": {
"evidences": [
{
"id": "OWUwZTA5MmUtOGNjYS00ZGI0LWFkNWUtZTg4MmUwNzhjMDUy",
"file_name": "evidence.txt",
"mime_type": "text/plain"
}
]
}
}Upload evidence for a vetting appeal
This operation allows you to import evidence files to be used to appeal an existing vetting.
Multiple files can be uploaded at once, with following limitations:
- The size of each file cannot exceed 10MB
- The total size of the HTTP request cannot exceed 100MB
- Supported file types are: jpg jpeg png bmp raw tiff pdf docx htm odt rtf txt xml
We expect the filename to be populated in the Content-Disposition header and the Content-Type to be set in each subpart.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Query Parameters
12Page of results to jump to
10Number of results per page
Narrow down results based on matching conditions. Follow the comprehensive guide to learn how to craft filter queries.
Example Request
POST /v1/10dlc/brands/:brand_id/appeal/evidence HTTP/1.1
Host: api-eu.vonage.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 11
file=stringPOST /v1/10dlc/brands/:brand_id/appeal/evidence HTTP/1.1
Host: api-eu.vonage.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 11
file=stringDownload appeal evidence file
This operation allows you to download an evidence file. The Content-Type header might vary and will reflect the Mime-Type of the file. The Content-Disposition header will hold the filename.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Campaigns
This section outlines the endpoints to register and manage your 10DLC campaigns.
Important information:
- Unverified brands cannot register campaigns.
- Verified brands can only register:
SOLE_PROPRIETORcampaigns for Sole Proprietor brandsCHARITYcampaigns for recognized non-profit brandsPOLITICALcampaigns for recognized non-profit brands or brands with a successful political vetLOW_VOLUME_MIXEDcampaigns
- A successful standard or enhanced vet is required for most other use-cases
- For some special use-cases, a pre-approval is required (reach out to your AM or open a support ticket)
- Only registered 10DLC Resellers (
PENDINGorAPPROVED) can register reseller campaigns - Only approved 10DLC Partners can use the campaign importation endpoint
Available Operations
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Query Parameters
12Page of results to jump to
10Number of results per page
Narrow down results based on matching conditions. Follow the comprehensive guide to learn how to craft filter queries.
ACTIVEYou can choose one or multiple statuses i.e: ACTIVE or CANCELED. If no status is given, then no filter would be applied and any campaign would be returned.
PENDING_REVIEWUPDATES_REQUIREDCARRIERS_REVIEWACTIVEPENDING_CANCELLATIONSUSPENDEDTERMINATEDCANCELEDREJECTEDCNP_CANCELEDPORTED_OUT10Items per page
12Page Offset
1100Number of pages in the entire result set
100Number of items in the entire result set
abcd1234The Vonage Primary Account ID (the parent account of account_id).
abcd1234The Vonage Account ID
50BLQKOPKTCR Brand ID.
50VC987XYZVonage Campaign ID.
50C123ABCTCR Campaign ID.
8R123456Alphanumeric TCR identifier of the reseller associated with this campaign. R000000 is a special value meaning this is not a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
In POST and PATCH endpoints, this is ignored if the reseller field on the same call. It will also be ignored if the brand's reseller field is true.
If tcr_campaign_id and reseller_id are set (not an empty string) then this field cannot be changed anymore.
Indicates if a campaign is a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
In POST and PATCH endpoints, this is ignored if the brand's reseller field is true.
50This is a sample campaignFriendly name associated with this campaign.
ACTIVECampaign Status.
PENDING_REVIEW: This is the initial status of a campaign. This implies that the campaign has been submitted for an internal review and cannot be used yet.UPDATES_REQUIRED: The campaign has been reviewed but requires changes before it can be approved.CARRIERS_REVIEW: The campaign has been approved by our internal process. It has been created in the registry and but pending approval from third parties i.e: mobile carrier.ACTIVE: The campaign has been approved by every party and traffic can now be sent.PENDING_CANCELLATION: The campaign is active but will not be renewed. It will be canceled at the next renewal date.SUSPENDED: The campaign has been suspended, along with any traffic it's used to send. This can happen if suspicious traffic has been detected (e.g.: spam) or after an MNO complaint. This triggers an internal review process which can lead to the un-suspension or termination of the campaign.TERMINATED: The campaign has been terminated. A campaign cannot be recovered after it's been terminated.EXPIRED: The campaign has expired.REJECTED: This implies the campaign was rejected by the compliance team as it is not compliant with 10DLC requirements. Further reasons can be found in the description of the rejection event received from TCR. You may update the campaign using TCR’s API or dashboard, and re-share the campaign with Vonage for a new review.CNP_CANCELED: The campaign has been canceled during a CNP migration. You are required to restart a CNP migration.PORTED_OUT: The campaign has been ported out from Vonage. You are required to start a CNP migration.
PENDING_REVIEWUPDATES_REQUIREDCARRIERS_REVIEWACTIVEPENDING_CANCELLATIONSUSPENDEDTERMINATEDCANCELEDREJECTEDCNP_CANCELEDPORTED_OUTIndicates if traffic is enabled for this campaign.
Traffic first becomes enabled when the campaign's status becomes ACTIVE. It can be suspended later due to a number of reasons (campaign suspension, expiration, termination, ...).
NB This is only a requirement for traffic to be allowed but not is not the only requirement. Traffic can also be stopped due to brand suspensions, number not linked properly, ...
50ACCOUNT_NOTIFICATIONCampaign usecase. Please refer to the /enum endpoint for an updated list of valid values.
CUSTOMER_CAREPOLLING_VOTINGHIGHER_EDUCATIONPUBLIC_SERVICE_ANNOUNCEMENTMARKETINGSECURITY_ALERTDELIVERY_NOTIFICATIONACCOUNT_NOTIFICATION2FAFRAUD_ALERTTRIALCHARITYPOLITICALEMERGENCYSWEEPSTAKECONVERSATIONALMIXEDCARRIER_EXEMPTSOCIALLOW_VOLUME404096User notificationsSummary description of this campaign
404096Brand: My brand \
Consent mechanisms: \
- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \
- ONLINE_FORM: This is an online form \
Link: https://mybrand.com/optin \
Message & data rates may apply. - Message frequency varies \
Carriers are not liable for delayed or undelivered messages. \
Text HELP for help. Text STOP to opt-out. \
Terms & Conditions: https://mybrand.com/terms_and_conditions \
Privacy Policy: https://mybrand.com/privacy_policy
Message flow, also known as Call to Action, of the campaign. It will always be filled with data computed from message_flow_details.
This field should describe how a consumer opts-in to the campaign, therefore giving consent to the sender to receive their messages. The call-to-action must be explicitly clear and inform the consumer of the nature of the program.
- Entering a telephone number through a website;
- Clicking a button on a mobile webpage;
- Sending a message from the Consumer’s mobile device that contains an advertising keyword;
- Initiating the text message exchange in which the Message Sender replies to the Consumer only with responsive information;
- Signing up at a point-of-sale (POS) or other Message Sender on-site location; or
- Opting-in over the phone using interactive voice response (IVR) technology.
If multiple opt-in methods can be used for the same campaign, you must list them all.
Describes what the opt_in option was used for.
Message flow details specifies the message_flow field as a structured object instead of a single text field.
When creating or updating a campaign:
- either
message_flowormessage_flow_detailsmay be specified, but not both. - if
message_flow_detailsis specified, the object's fields will be used to fill a template. The resulting templated text will be used to fill themessage_flowfield of the campaign.
When reading a campaign message_flow_details will only be filled if it's been used to create or update the campaign.
For more information on Campaign message flows, please see this campaign requirements article.
A brand name associated with the campaign. This can be different from the name of the brand the campaign belongs to (e.g. for subsidiaries, ...).
NB: This is optional for sole proprietors.
Describe the different mechanisms a customer may use to consent to the campaign.
It is required to provide an attachment for all consent methods, except TEXT_TO_JOIN.
ONLINE_FORMLIVE_OPERATORPOINT_OF_SALETEXT_TO_JOINOTHERDetails on the consent mechanism.
An HTTP(S) link to the resource describing the mechanism.
This field needs to be true to consent to adding the pricing disclosure to the template.
The following will be added: Message and Data rates may apply
trueWhether to add the following disclaimer: Carriers are not liable for delayed or undelivered messages.
trueThe frequency of the messages sent by the campaign.
ONE_TIMERECURRINGLink to the campaign's privacy policy.
Link to the campaign's terms and conditions.
trueDoes campaign require subscriber to opt-in before SMS is sent to subscriber?
255START,SUBSCRIBEOpt in keywords of the campaign, separated by comas.
20320<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP
Opt in message sent to confirmation enrollment to a recurring message campaign. Also provide information on how to get HELP or undo enrollment. If consumers can text in a keyword,the response should include the Brand name.
NB: This field is mandatory if opt_in_keywords is set.
trueDoes campaign support subscriber opt-out keyword(s)?
255STOPSTOP,QUITOpt out keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the STOP keyword if set.
20320<Brand Name>: You are now opted-out and will receive no further messages.
Opt out message of the campaign. The response to the STOP keyword may include the Brand name but should include an acknowledgement of the opt-out request and confirmation that no further messages will be sent.
NB: Required for all recurring campaigns or for SMS opt-in.
trueDoes campaign responds to help keyword(s)?
255HELPHELP,INFOHelp keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the HELP keyword if set.
20320<Brand Name>: For help, email support@example.com. To opt-out, reply STOP
Help message of the campaign.
The response to HELP keyword may include the Brand name and additional support contact information.
201024Hi
This is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.
Message sample. Some campaign tiers require 1 or more message samples.
201024Hello,
Your order, number XXXXXXX, has been shipped.
Message sample. Some campaign tiers require 2 or more message samples.
201024Here is you unique PIN number to access the application: 123456
Message sample. Some campaign tiers require 3 or more message samples.
201024Hello Mr Doe,
Your payment of 9.99$ was authorized. You can find your invoice in your customer account.
Message sample. Some campaign tiers require 4 or more message samples.
201024Your delivery is scheduled for tomorrow between 8am and 2pm.
If you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.
Message sample. Some campaign tiers require 5.
trueSubscribers will be required to provide their age to opt-in if set to true. NB: Sex, Hate, Alcohol, Firearms, and Tobacco related (S.H.A.F.T) messages are prohibited.
trueSet to true if messages are related to money lending or loan arrangements.
Set to true if the campaign message includes links. NB: Shortened URLs are forbidden.
Does message generated by the campaign include phone number in SMS?
trueIndicates the brand or campaign belong to a partner campaign.
Campaign subscription auto-renewal option.
Defines the behaviour at the end of the billing cycle:
- if
true, the campaign will automatically renewed - if
false, the campaign will expire and its status will becomeCANCELED
Indicates if HIPAA is enabled for this campaign.
This is kept nullable to avoid breaking changes, but it is best to set it when creating the campaign. Otherwise, this will be set when attempting to link the first number of the campaign, whether the attempt is successful or not. After that, it will not be possible to update that field anymore.
Campaign TCR status.
UNKNOWNACTIVECANCELEDTECHNOLOGYBusiness/industry segment of this campaign. Please refer to the vertical property of the /enum endpoint for an updated list of valid values.
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATIONtrueSet to true if campaign uses a pool of numbers.
Date-time when campaign was registered with TCR.
Date when the campaign will be renewed and billed, if auto_renewal is true.
Date when this record was created.
Date-time when this record was last updated.
Date-time when this campaign was billed.
Specifies whether opt out assist is enabled for this account.
On a campaign, indicates whether it's enabled on the primary account of the campaign's brand.
Lists the last changes of the status field.
Note: this is only an extract. Not all changes are listed here.
ACTIVECampaign Status.
PENDING_REVIEW: This is the initial status of a campaign. This implies that the campaign has been submitted for an internal review and cannot be used yet.UPDATES_REQUIRED: The campaign has been reviewed but requires changes before it can be approved.CARRIERS_REVIEW: The campaign has been approved by our internal process. It has been created in the registry and but pending approval from third parties i.e: mobile carrier.ACTIVE: The campaign has been approved by every party and traffic can now be sent.PENDING_CANCELLATION: The campaign is active but will not be renewed. It will be canceled at the next renewal date.SUSPENDED: The campaign has been suspended, along with any traffic it's used to send. This can happen if suspicious traffic has been detected (e.g.: spam) or after an MNO complaint. This triggers an internal review process which can lead to the un-suspension or termination of the campaign.TERMINATED: The campaign has been terminated. A campaign cannot be recovered after it's been terminated.EXPIRED: The campaign has expired.REJECTED: This implies the campaign was rejected by the compliance team as it is not compliant with 10DLC requirements. Further reasons can be found in the description of the rejection event received from TCR. You may update the campaign using TCR’s API or dashboard, and re-share the campaign with Vonage for a new review.CNP_CANCELED: The campaign has been canceled during a CNP migration. You are required to restart a CNP migration.PORTED_OUT: The campaign has been ported out from Vonage. You are required to start a CNP migration.
PENDING_REVIEWUPDATES_REQUIREDCARRIERS_REVIEWACTIVEPENDING_CANCELLATIONSUSPENDEDTERMINATEDCANCELEDREJECTEDCNP_CANCELEDPORTED_OUTDescribes why the status changed how it did.
Date-time when the status changed.
10017Network ID of the MNO.
AT&TName of the MNO.
MNO campaign operation status. Please refer to the campaign_op_status property of the /enum endpoint response for an updated list of valid values.
If 'false', then the desired usecase cannot be supported by the MNO.
If 'true', then the submitted campaign is subject to the MNO (manual) review process.
If 'false', then the brand does not qualify for the desired usecase on the MNO.
2The minimum number of message samples required by MNO for submission of the desired usecase.
If 'true' then MNO requires the subscriber to opt-into the campaign before the message may be sent to the subscriber. The opt-in mechanism can be mobile or web opt-in.
If 'true' then MNO requires a campaign to support an opt-out mechanism through MO stop keywords such as 'STOP', 'QUIT'. Upon receive the STOP message from a subscriber, the campaign must stop sending messages to the subscriber immediately.
If 'true' then MNO requires a campaign to support a 'help' mechanism through MO help key words such as 'HELP', 'INFO'.
If 'true' then MNO forbids call-to-action link/URL to be embedded in all messages sent to the subscriber.
If 'true' then MNO forbids call-to-action phone number to be embedded in all messages sent to the subscriber.
Q(Only for AT&T). Message class assigned to the campaign by MNO. Please refer to the AT&T 10DLC guide for a complete list of available message class and definition.
3000(Only for AT&T). SMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
3000(Only for AT&T). MMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
(Only for AT&T). Whether is the MNO applying the TPM per number or per campaign.
LOW(Only for T-Mobile). Daily message volume is restricted based on brand tier or brand qualification. The daily volume restriction applies to brand across campaigns and CSPs. Please refer to the /enum endpoint for an updated list of valid values.
LOWLOWER_MIDUPPER_MIDTOPUNCAPPED(Only for TMobile). Message TPD (throughput per day) qualified by the brand for the desired usecase.
65535Description of this MNO complaint.
SINCHdca name
Date-time when this record was created.
Summarize the reason of the suspension.
Detailed explanation of the cause of the suspension.
https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879https://api.nexmo.com/v1/10dlc/brands/BLQKOPKhttps://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbershttps://api.nexmo.com/v1/10dlc/brands/BLQKOPKhttps://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/?page=2https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/?page=1https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/?page=1https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/?page=1https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/?page=10Example Response
{
"page_size": 10,
"page": 2,
"total_pages": 100,
"total_items": 100,
"_embedded": {
"campaigns": [
{
"primary_account_id": "abcd1234",
"account_id": "abcd1234",
"brand_id": "BLQKOPK",
"campaign_id": "VC987XYZ",
"tcr_campaign_id": "C123ABC",
"reseller_id": "R123456",
"reseller": true,
"label": "This is a sample campaign",
"status": "ACTIVE",
"traffic_enabled": true,
"usecase": "ACCOUNT_NOTIFICATION",
"sub_usecases": [
"2FA",
"SECURITY_ALERT"
],
"description": "User notifications",
"message_flow": "Brand: My brand \\\nConsent mechanisms: \\\n- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \\\n- ONLINE_FORM: This is an online form \\\n Link: https://mybrand.com/optin \\\nMessage & data rates may apply. - Message frequency varies \\\nCarriers are not liable for delayed or undelivered messages. \\\nText HELP for help. Text STOP to opt-out. \\\nTerms & Conditions: https://mybrand.com/terms_and_conditions \\\nPrivacy Policy: https://mybrand.com/privacy_policy\n",
"message_flow_details": {
"brand_name": "My brand",
"consent_mechanisms": [
{
"method": "TEXT_TO_JOIN",
"details": "A text will be sent to the customer. He can reply yes to consent and opt in."
},
{
"method": "ONLINE_FORM",
"details": "An online form allows the customer to subscribe.",
"attachment": "https://mybrand.com/optin"
}
],
"pricing_disclosure": true,
"frequency": "RECURRING",
"privacy_policy": "https://mybrand.com/privacy_policy",
"terms_and_conditions": "https://mybrand.com/terms_and_conditions"
},
"subscriber_opt_in": false,
"opt_in_keywords": "START,SUBSCRIBE",
"opt_in_message": "<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP\n",
"subscriber_opt_out": false,
"opt_out_keywords": "STOP,QUIT",
"opt_out_message": "<Brand Name>: You are now opted-out and will receive no further messages.\n",
"subscriber_help": false,
"help_keywords": "HELP,INFO",
"help_message": "<Brand Name>: For help, email support@example.com. To opt-out, reply STOP\n",
"sample_one": "Hi\nThis is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.\n",
"sample_two": "Hello,\nYour order, number XXXXXXX, has been shipped.\n",
"sample_three": "Here is you unique PIN number to access the application: 123456\n",
"sample_four": "Hello Mr Doe,\nYour payment of 9.99$ was authorized. You can find your invoice in your customer account.\n",
"sample_five": "Your delivery is scheduled for tomorrow between 8am and 2pm.\nIf you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.\n",
"age_gated": true,
"direct_lending": true,
"embedded_link": false,
"embedded_phone": false,
"partner": true,
"auto_renewal": true,
"hipaa": true,
"tcr_status": "UNKNOWN",
"vertical": "TECHNOLOGY",
"number_pool": false,
"registration_date": "2019-08-24T14:15:22Z",
"renewal_date": "2019-08-24",
"created_date": "2019-08-24T14:15:22Z",
"last_updated": "2019-08-24T14:15:22Z",
"billed_date": "2019-08-24T14:15:22Z",
"opt_out_assist": false,
"last_status_changes": [
{
"status": "APPROVED",
"reason": "Approved after internal review.",
"change_date": "2022-01-01 01:01:01"
}
],
"mno_metadata": [
{
"network_id": "10017",
"mno": "AT&T",
"status": "string",
"mno_support": true,
"mno_review": true,
"qualify": true,
"min_msg_samples": 2,
"req_subscriber_opt_in": true,
"req_subscriber_opt_out": true,
"req_subscriber_help": true,
"no_embedded_link": true,
"no_embedded_phone": true,
"att_msg_class": "Q",
"att_tpm": 3000,
"att_mms_tpm": 3000,
"att_number_based": true,
"tmo_brand_tier": "LOW",
"tmo_tpd": 0,
"complaints": [
{
"complaints": [
{
"description": "string",
"dca": "SINCH",
"created_at": "2019-08-24T14:15:22Z"
}
]
}
]
}
],
"carrier_brand_suspensions": [
[
{}
]
],
"_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"
}
}
}Add a new campaign to a brand
Create Campaign
Message samples
The number of required message samples on the maximum of these 3 values:
- The number of
min_msg_samplesfor the usecase, as returned by the /enum endpoint. - The number of entries in the
sub_usecasesfield. - The maximum of min_msg_samples asked by MNOs on the brand qualification endpoint.
Notes:
opt_in_messageis mandatory ifopt_in_keywordsis set.- Either
message_flowormessage_flow_detailsis required, but only one of them may be specified.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
abcd1234The Vonage Account ID
TECHNOLOGYBusiness/industry segment of this campaign. Please refer to the vertical property of the /enum endpoint for an updated list of valid values.
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATION50ACCOUNT_NOTIFICATIONCampaign usecase. Please refer to the /enum endpoint for an updated list of valid values.
CUSTOMER_CAREPOLLING_VOTINGHIGHER_EDUCATIONPUBLIC_SERVICE_ANNOUNCEMENTMARKETINGSECURITY_ALERTDELIVERY_NOTIFICATIONACCOUNT_NOTIFICATION2FAFRAUD_ALERTTRIALCHARITYPOLITICALEMERGENCYSWEEPSTAKECONVERSATIONALMIXEDCARRIER_EXEMPTSOCIALLOW_VOLUME8R123456Alphanumeric TCR identifier of the reseller associated with this campaign. R000000 is a special value meaning this is not a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
In POST and PATCH endpoints, this is ignored if the reseller field on the same call. It will also be ignored if the brand's reseller field is true.
If tcr_campaign_id and reseller_id are set (not an empty string) then this field cannot be changed anymore.
Indicates if a campaign is a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
In POST and PATCH endpoints, this is ignored if the brand's reseller field is true.
404096User notificationsSummary description of this campaign
trueSubscribers will be required to provide their age to opt-in if set to true. NB: Sex, Hate, Alcohol, Firearms, and Tobacco related (S.H.A.F.T) messages are prohibited.
trueSet to true if messages are related to money lending or loan arrangements.
201024Hi
This is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.
Message sample. Some campaign tiers require 1 or more message samples.
201024Hello,
Your order, number XXXXXXX, has been shipped.
Message sample. Some campaign tiers require 2 or more message samples.
201024Here is you unique PIN number to access the application: 123456
Message sample. Some campaign tiers require 3 or more message samples.
201024Hello Mr Doe,
Your payment of 9.99$ was authorized. You can find your invoice in your customer account.
Message sample. Some campaign tiers require 4 or more message samples.
201024Your delivery is scheduled for tomorrow between 8am and 2pm.
If you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.
Message sample. Some campaign tiers require 5.
404096Brand: My brand \
Consent mechanisms: \
- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \
- ONLINE_FORM: This is an online form \
Link: https://mybrand.com/optin \
Message & data rates may apply. - Message frequency varies \
Carriers are not liable for delayed or undelivered messages. \
Text HELP for help. Text STOP to opt-out. \
Terms & Conditions: https://mybrand.com/terms_and_conditions \
Privacy Policy: https://mybrand.com/privacy_policy
Message flow, also known as Call to Action, of the campaign.
This field should describe how a consumer opts-in to the campaign, therefore giving consent to the sender to receive their messages. The call-to-action must be explicitly clear and inform the consumer of the nature of the program.
- Entering a telephone number through a website;
- Clicking a button on a mobile webpage;
- Sending a message from the Consumer’s mobile device that contains an advertising keyword;
- Initiating the text message exchange in which the Message Sender replies to the Consumer only with responsive information;
- Signing up at a point-of-sale (POS) or other Message Sender on-site location; or
- Opting-in over the phone using interactive voice response (IVR) technology.
If multiple opt-in methods can be used for the same campaign, you must list them all.
When creating or updating a campaign, either message_flow or message_flow_details may be specified, but not both. When reading a campaign, message_flow will always be filled with data computed from message_flow_details.
Describes what the opt_in option was used for. NBThis attribute will be deprecated on POST and PATCH endpoint. Please update your application to use the message_flow_details property instead.
Message flow details specifies the message_flow field as a structured object instead of a single text field.
When creating or updating a campaign:
- either
message_flowormessage_flow_detailsmay be specified, but not both. - if
message_flow_detailsis specified, the object's fields will be used to fill a template. The resulting templated text will be used to fill themessage_flowfield of the campaign.
When reading a campaign message_flow_details will only be filled if it's been used to create or update the campaign.
For more information on Campaign message flows, please see this campaign requirements article.
A brand name associated with the campaign. This can be different from the name of the brand the campaign belongs to (e.g. for subsidiaries, ...).
NB: This is optional for sole proprietors.
Describe the different mechanisms a customer may use to consent to the campaign.
It is required to provide an attachment for all consent methods, except TEXT_TO_JOIN.
ONLINE_FORMLIVE_OPERATORPOINT_OF_SALETEXT_TO_JOINOTHERDetails on the consent mechanism.
An HTTP(S) link to the resource describing the mechanism.
This field needs to be true to consent to adding the pricing disclosure to the template.
The following will be added: Message and Data rates may apply
trueWhether to add the following disclaimer: Carriers are not liable for delayed or undelivered messages.
trueThe frequency of the messages sent by the campaign.
ONE_TIMERECURRINGLink to the campaign's privacy policy.
Link to the campaign's terms and conditions.
20320<Brand Name>: For help, email support@example.com. To opt-out, reply STOP
Help message of the campaign.
The response to HELP keyword may include the Brand name and additional support contact information.
20320<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP
Opt in message sent to confirmation enrollment to a recurring message campaign. Also provide information on how to get HELP or undo enrollment. If consumers can text in a keyword,the response should include the Brand name.
NB: This field is mandatory if opt_in_keywords is set.
20320<Brand Name>: You are now opted-out and will receive no further messages.
Opt out message of the campaign. The response to the STOP keyword may include the Brand name but should include an acknowledgement of the opt-out request and confirmation that no further messages will be sent.
NB: Required for all recurring campaigns or for SMS opt-in.
255HELPHELP,INFOHelp keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the HELP keyword if set.
255START,SUBSCRIBEOpt in keywords of the campaign, separated by comas.
255STOPSTOP,QUITOpt out keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the STOP keyword if set.
trueSet to true to accept 10DLC's terms and conditions. T&Cs are determined by The Campaign Registry (TCR). You may retrieve the latest version of those terms and conditions using the campaign T&C endpoint.
Set to true if the campaign message includes links. NB: Shortened URLs are forbidden.
Does message generated by the campaign include phone number in SMS?
50This is a sample campaignFriendly name associated with this campaign.
Indicates if HIPAA is enabled for this campaign.
This is kept nullable to avoid breaking changes, but it is best to set it when creating the campaign. Otherwise, this will be set when attempting to link the first number of the campaign, whether the attempt is successful or not. After that, it will not be possible to update that field anymore.
Example Request
{
"account_id": "abcd1234",
"vertical": "TECHNOLOGY",
"usecase": "ACCOUNT_NOTIFICATION",
"sub_usecases": [
"ACCOUNT_NOTIFICATION"
],
"reseller_id": "R123456",
"reseller": true,
"description": "User notifications",
"age_gated": true,
"direct_lending": true,
"sample_one": "Hi\nThis is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.\n",
"sample_two": "Hello,\nYour order, number XXXXXXX, has been shipped.\n",
"sample_three": "Here is you unique PIN number to access the application: 123456\n",
"sample_four": "Hello Mr Doe,\nYour payment of 9.99$ was authorized. You can find your invoice in your customer account.\n",
"sample_five": "Your delivery is scheduled for tomorrow between 8am and 2pm.\nIf you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.\n",
"message_flow": "Brand: My brand \\\nConsent mechanisms: \\\n- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \\\n- ONLINE_FORM: This is an online form \\\n Link: https://mybrand.com/optin \\\nMessage & data rates may apply. - Message frequency varies \\\nCarriers are not liable for delayed or undelivered messages. \\\nText HELP for help. Text STOP to opt-out. \\\nTerms & Conditions: https://mybrand.com/terms_and_conditions \\\nPrivacy Policy: https://mybrand.com/privacy_policy\n",
"message_flow_details": {
"brand_name": "My brand",
"consent_mechanisms": [
{
"method": "TEXT_TO_JOIN",
"details": "A text will be sent to the customer. He can reply yes to consent and opt in."
},
{
"method": "ONLINE_FORM",
"details": "An online form allows the customer to subscribe.",
"attachment": "https://mybrand.com/optin"
}
],
"pricing_disclosure": true,
"frequency": "RECURRING",
"privacy_policy": "https://mybrand.com/privacy_policy",
"terms_and_conditions": "https://mybrand.com/terms_and_conditions"
},
"help_message": "<Brand Name>: For help, email support@example.com. To opt-out, reply STOP\n",
"opt_in_message": "<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP\n",
"opt_out_message": "<Brand Name>: You are now opted-out and will receive no further messages.\n",
"help_keywords": "HELP,INFO",
"opt_in_keywords": "START,SUBSCRIBE",
"opt_out_keywords": "STOP,QUIT",
"tc_agreed": true,
"embedded_link": false,
"embedded_phone": false,
"label": "This is a sample campaign",
"hipaa": true
}{
"account_id": "abcd1234",
"vertical": "TECHNOLOGY",
"usecase": "ACCOUNT_NOTIFICATION",
"sub_usecases": [
"ACCOUNT_NOTIFICATION"
],
"reseller_id": "R123456",
"reseller": true,
"description": "User notifications",
"age_gated": true,
"direct_lending": true,
"sample_one": "Hi\nThis is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.\n",
"sample_two": "Hello,\nYour order, number XXXXXXX, has been shipped.\n",
"sample_three": "Here is you unique PIN number to access the application: 123456\n",
"sample_four": "Hello Mr Doe,\nYour payment of 9.99$ was authorized. You can find your invoice in your customer account.\n",
"sample_five": "Your delivery is scheduled for tomorrow between 8am and 2pm.\nIf you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.\n",
"message_flow": "Brand: My brand \\\nConsent mechanisms: \\\n- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \\\n- ONLINE_FORM: This is an online form \\\n Link: https://mybrand.com/optin \\\nMessage & data rates may apply. - Message frequency varies \\\nCarriers are not liable for delayed or undelivered messages. \\\nText HELP for help. Text STOP to opt-out. \\\nTerms & Conditions: https://mybrand.com/terms_and_conditions \\\nPrivacy Policy: https://mybrand.com/privacy_policy\n",
"message_flow_details": {
"brand_name": "My brand",
"consent_mechanisms": [
{
"method": "TEXT_TO_JOIN",
"details": "A text will be sent to the customer. He can reply yes to consent and opt in."
},
{
"method": "ONLINE_FORM",
"details": "An online form allows the customer to subscribe.",
"attachment": "https://mybrand.com/optin"
}
],
"pricing_disclosure": true,
"frequency": "RECURRING",
"privacy_policy": "https://mybrand.com/privacy_policy",
"terms_and_conditions": "https://mybrand.com/terms_and_conditions"
},
"help_message": "<Brand Name>: For help, email support@example.com. To opt-out, reply STOP\n",
"opt_in_message": "<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP\n",
"opt_out_message": "<Brand Name>: You are now opted-out and will receive no further messages.\n",
"help_keywords": "HELP,INFO",
"opt_in_keywords": "START,SUBSCRIBE",
"opt_out_keywords": "STOP,QUIT",
"tc_agreed": true,
"embedded_link": false,
"embedded_phone": false,
"label": "This is a sample campaign",
"hipaa": true
}abcd1234The Vonage Primary Account ID (the parent account of account_id).
abcd1234The Vonage Account ID
50BLQKOPKTCR Brand ID.
50VC987XYZVonage Campaign ID.
50C123ABCTCR Campaign ID.
8R123456Alphanumeric TCR identifier of the reseller associated with this campaign. R000000 is a special value meaning this is not a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
In POST and PATCH endpoints, this is ignored if the reseller field on the same call. It will also be ignored if the brand's reseller field is true.
If tcr_campaign_id and reseller_id are set (not an empty string) then this field cannot be changed anymore.
Indicates if a campaign is a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
In POST and PATCH endpoints, this is ignored if the brand's reseller field is true.
50This is a sample campaignFriendly name associated with this campaign.
ACTIVECampaign Status.
PENDING_REVIEW: This is the initial status of a campaign. This implies that the campaign has been submitted for an internal review and cannot be used yet.UPDATES_REQUIRED: The campaign has been reviewed but requires changes before it can be approved.CARRIERS_REVIEW: The campaign has been approved by our internal process. It has been created in the registry and but pending approval from third parties i.e: mobile carrier.ACTIVE: The campaign has been approved by every party and traffic can now be sent.PENDING_CANCELLATION: The campaign is active but will not be renewed. It will be canceled at the next renewal date.SUSPENDED: The campaign has been suspended, along with any traffic it's used to send. This can happen if suspicious traffic has been detected (e.g.: spam) or after an MNO complaint. This triggers an internal review process which can lead to the un-suspension or termination of the campaign.TERMINATED: The campaign has been terminated. A campaign cannot be recovered after it's been terminated.EXPIRED: The campaign has expired.REJECTED: This implies the campaign was rejected by the compliance team as it is not compliant with 10DLC requirements. Further reasons can be found in the description of the rejection event received from TCR. You may update the campaign using TCR’s API or dashboard, and re-share the campaign with Vonage for a new review.CNP_CANCELED: The campaign has been canceled during a CNP migration. You are required to restart a CNP migration.PORTED_OUT: The campaign has been ported out from Vonage. You are required to start a CNP migration.
PENDING_REVIEWUPDATES_REQUIREDCARRIERS_REVIEWACTIVEPENDING_CANCELLATIONSUSPENDEDTERMINATEDCANCELEDREJECTEDCNP_CANCELEDPORTED_OUTIndicates if traffic is enabled for this campaign.
Traffic first becomes enabled when the campaign's status becomes ACTIVE. It can be suspended later due to a number of reasons (campaign suspension, expiration, termination, ...).
NB This is only a requirement for traffic to be allowed but not is not the only requirement. Traffic can also be stopped due to brand suspensions, number not linked properly, ...
50ACCOUNT_NOTIFICATIONCampaign usecase. Please refer to the /enum endpoint for an updated list of valid values.
CUSTOMER_CAREPOLLING_VOTINGHIGHER_EDUCATIONPUBLIC_SERVICE_ANNOUNCEMENTMARKETINGSECURITY_ALERTDELIVERY_NOTIFICATIONACCOUNT_NOTIFICATION2FAFRAUD_ALERTTRIALCHARITYPOLITICALEMERGENCYSWEEPSTAKECONVERSATIONALMIXEDCARRIER_EXEMPTSOCIALLOW_VOLUME404096User notificationsSummary description of this campaign
404096Brand: My brand \
Consent mechanisms: \
- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \
- ONLINE_FORM: This is an online form \
Link: https://mybrand.com/optin \
Message & data rates may apply. - Message frequency varies \
Carriers are not liable for delayed or undelivered messages. \
Text HELP for help. Text STOP to opt-out. \
Terms & Conditions: https://mybrand.com/terms_and_conditions \
Privacy Policy: https://mybrand.com/privacy_policy
Message flow, also known as Call to Action, of the campaign. It will always be filled with data computed from message_flow_details.
This field should describe how a consumer opts-in to the campaign, therefore giving consent to the sender to receive their messages. The call-to-action must be explicitly clear and inform the consumer of the nature of the program.
- Entering a telephone number through a website;
- Clicking a button on a mobile webpage;
- Sending a message from the Consumer’s mobile device that contains an advertising keyword;
- Initiating the text message exchange in which the Message Sender replies to the Consumer only with responsive information;
- Signing up at a point-of-sale (POS) or other Message Sender on-site location; or
- Opting-in over the phone using interactive voice response (IVR) technology.
If multiple opt-in methods can be used for the same campaign, you must list them all.
Describes what the opt_in option was used for.
Message flow details specifies the message_flow field as a structured object instead of a single text field.
When creating or updating a campaign:
- either
message_flowormessage_flow_detailsmay be specified, but not both. - if
message_flow_detailsis specified, the object's fields will be used to fill a template. The resulting templated text will be used to fill themessage_flowfield of the campaign.
When reading a campaign message_flow_details will only be filled if it's been used to create or update the campaign.
For more information on Campaign message flows, please see this campaign requirements article.
A brand name associated with the campaign. This can be different from the name of the brand the campaign belongs to (e.g. for subsidiaries, ...).
NB: This is optional for sole proprietors.
Describe the different mechanisms a customer may use to consent to the campaign.
It is required to provide an attachment for all consent methods, except TEXT_TO_JOIN.
ONLINE_FORMLIVE_OPERATORPOINT_OF_SALETEXT_TO_JOINOTHERDetails on the consent mechanism.
An HTTP(S) link to the resource describing the mechanism.
This field needs to be true to consent to adding the pricing disclosure to the template.
The following will be added: Message and Data rates may apply
trueWhether to add the following disclaimer: Carriers are not liable for delayed or undelivered messages.
trueThe frequency of the messages sent by the campaign.
ONE_TIMERECURRINGLink to the campaign's privacy policy.
Link to the campaign's terms and conditions.
trueDoes campaign require subscriber to opt-in before SMS is sent to subscriber?
255START,SUBSCRIBEOpt in keywords of the campaign, separated by comas.
20320<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP
Opt in message sent to confirmation enrollment to a recurring message campaign. Also provide information on how to get HELP or undo enrollment. If consumers can text in a keyword,the response should include the Brand name.
NB: This field is mandatory if opt_in_keywords is set.
trueDoes campaign support subscriber opt-out keyword(s)?
255STOPSTOP,QUITOpt out keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the STOP keyword if set.
20320<Brand Name>: You are now opted-out and will receive no further messages.
Opt out message of the campaign. The response to the STOP keyword may include the Brand name but should include an acknowledgement of the opt-out request and confirmation that no further messages will be sent.
NB: Required for all recurring campaigns or for SMS opt-in.
trueDoes campaign responds to help keyword(s)?
255HELPHELP,INFOHelp keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the HELP keyword if set.
20320<Brand Name>: For help, email support@example.com. To opt-out, reply STOP
Help message of the campaign.
The response to HELP keyword may include the Brand name and additional support contact information.
201024Hi
This is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.
Message sample. Some campaign tiers require 1 or more message samples.
201024Hello,
Your order, number XXXXXXX, has been shipped.
Message sample. Some campaign tiers require 2 or more message samples.
201024Here is you unique PIN number to access the application: 123456
Message sample. Some campaign tiers require 3 or more message samples.
201024Hello Mr Doe,
Your payment of 9.99$ was authorized. You can find your invoice in your customer account.
Message sample. Some campaign tiers require 4 or more message samples.
201024Your delivery is scheduled for tomorrow between 8am and 2pm.
If you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.
Message sample. Some campaign tiers require 5.
trueSubscribers will be required to provide their age to opt-in if set to true. NB: Sex, Hate, Alcohol, Firearms, and Tobacco related (S.H.A.F.T) messages are prohibited.
trueSet to true if messages are related to money lending or loan arrangements.
Set to true if the campaign message includes links. NB: Shortened URLs are forbidden.
Does message generated by the campaign include phone number in SMS?
trueIndicates the brand or campaign belong to a partner campaign.
Campaign subscription auto-renewal option.
Defines the behaviour at the end of the billing cycle:
- if
true, the campaign will automatically renewed - if
false, the campaign will expire and its status will becomeCANCELED
Indicates if HIPAA is enabled for this campaign.
This is kept nullable to avoid breaking changes, but it is best to set it when creating the campaign. Otherwise, this will be set when attempting to link the first number of the campaign, whether the attempt is successful or not. After that, it will not be possible to update that field anymore.
Campaign TCR status.
UNKNOWNACTIVECANCELEDTECHNOLOGYBusiness/industry segment of this campaign. Please refer to the vertical property of the /enum endpoint for an updated list of valid values.
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATIONtrueSet to true if campaign uses a pool of numbers.
Date-time when campaign was registered with TCR.
Date when the campaign will be renewed and billed, if auto_renewal is true.
Date when this record was created.
Date-time when this record was last updated.
Date-time when this campaign was billed.
Specifies whether opt out assist is enabled for this account.
On a campaign, indicates whether it's enabled on the primary account of the campaign's brand.
Lists the last changes of the status field.
Note: this is only an extract. Not all changes are listed here.
ACTIVECampaign Status.
PENDING_REVIEW: This is the initial status of a campaign. This implies that the campaign has been submitted for an internal review and cannot be used yet.UPDATES_REQUIRED: The campaign has been reviewed but requires changes before it can be approved.CARRIERS_REVIEW: The campaign has been approved by our internal process. It has been created in the registry and but pending approval from third parties i.e: mobile carrier.ACTIVE: The campaign has been approved by every party and traffic can now be sent.PENDING_CANCELLATION: The campaign is active but will not be renewed. It will be canceled at the next renewal date.SUSPENDED: The campaign has been suspended, along with any traffic it's used to send. This can happen if suspicious traffic has been detected (e.g.: spam) or after an MNO complaint. This triggers an internal review process which can lead to the un-suspension or termination of the campaign.TERMINATED: The campaign has been terminated. A campaign cannot be recovered after it's been terminated.EXPIRED: The campaign has expired.REJECTED: This implies the campaign was rejected by the compliance team as it is not compliant with 10DLC requirements. Further reasons can be found in the description of the rejection event received from TCR. You may update the campaign using TCR’s API or dashboard, and re-share the campaign with Vonage for a new review.CNP_CANCELED: The campaign has been canceled during a CNP migration. You are required to restart a CNP migration.PORTED_OUT: The campaign has been ported out from Vonage. You are required to start a CNP migration.
PENDING_REVIEWUPDATES_REQUIREDCARRIERS_REVIEWACTIVEPENDING_CANCELLATIONSUSPENDEDTERMINATEDCANCELEDREJECTEDCNP_CANCELEDPORTED_OUTDescribes why the status changed how it did.
Date-time when the status changed.
10017Network ID of the MNO.
AT&TName of the MNO.
MNO campaign operation status. Please refer to the campaign_op_status property of the /enum endpoint response for an updated list of valid values.
If 'false', then the desired usecase cannot be supported by the MNO.
If 'true', then the submitted campaign is subject to the MNO (manual) review process.
If 'false', then the brand does not qualify for the desired usecase on the MNO.
2The minimum number of message samples required by MNO for submission of the desired usecase.
If 'true' then MNO requires the subscriber to opt-into the campaign before the message may be sent to the subscriber. The opt-in mechanism can be mobile or web opt-in.
If 'true' then MNO requires a campaign to support an opt-out mechanism through MO stop keywords such as 'STOP', 'QUIT'. Upon receive the STOP message from a subscriber, the campaign must stop sending messages to the subscriber immediately.
If 'true' then MNO requires a campaign to support a 'help' mechanism through MO help key words such as 'HELP', 'INFO'.
If 'true' then MNO forbids call-to-action link/URL to be embedded in all messages sent to the subscriber.
If 'true' then MNO forbids call-to-action phone number to be embedded in all messages sent to the subscriber.
Q(Only for AT&T). Message class assigned to the campaign by MNO. Please refer to the AT&T 10DLC guide for a complete list of available message class and definition.
3000(Only for AT&T). SMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
3000(Only for AT&T). MMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
(Only for AT&T). Whether is the MNO applying the TPM per number or per campaign.
LOW(Only for T-Mobile). Daily message volume is restricted based on brand tier or brand qualification. The daily volume restriction applies to brand across campaigns and CSPs. Please refer to the /enum endpoint for an updated list of valid values.
LOWLOWER_MIDUPPER_MIDTOPUNCAPPED(Only for TMobile). Message TPD (throughput per day) qualified by the brand for the desired usecase.
65535Description of this MNO complaint.
SINCHdca name
Date-time when this record was created.
Summarize the reason of the suspension.
Detailed explanation of the cause of the suspension.
https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879https://api.nexmo.com/v1/10dlc/brands/BLQKOPKhttps://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbersExample Response
{
"primary_account_id": "abcd1234",
"account_id": "abcd1234",
"brand_id": "BLQKOPK",
"campaign_id": "VC987XYZ",
"tcr_campaign_id": "C123ABC",
"reseller_id": "R123456",
"reseller": true,
"label": "This is a sample campaign",
"status": "ACTIVE",
"traffic_enabled": true,
"usecase": "ACCOUNT_NOTIFICATION",
"sub_usecases": [
"2FA",
"SECURITY_ALERT"
],
"description": "User notifications",
"message_flow": "Brand: My brand \\\nConsent mechanisms: \\\n- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \\\n- ONLINE_FORM: This is an online form \\\n Link: https://mybrand.com/optin \\\nMessage & data rates may apply. - Message frequency varies \\\nCarriers are not liable for delayed or undelivered messages. \\\nText HELP for help. Text STOP to opt-out. \\\nTerms & Conditions: https://mybrand.com/terms_and_conditions \\\nPrivacy Policy: https://mybrand.com/privacy_policy\n",
"message_flow_details": {
"brand_name": "My brand",
"consent_mechanisms": [
{
"method": "TEXT_TO_JOIN",
"details": "A text will be sent to the customer. He can reply yes to consent and opt in."
},
{
"method": "ONLINE_FORM",
"details": "An online form allows the customer to subscribe.",
"attachment": "https://mybrand.com/optin"
}
],
"pricing_disclosure": true,
"frequency": "RECURRING",
"privacy_policy": "https://mybrand.com/privacy_policy",
"terms_and_conditions": "https://mybrand.com/terms_and_conditions"
},
"subscriber_opt_in": false,
"opt_in_keywords": "START,SUBSCRIBE",
"opt_in_message": "<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP\n",
"subscriber_opt_out": false,
"opt_out_keywords": "STOP,QUIT",
"opt_out_message": "<Brand Name>: You are now opted-out and will receive no further messages.\n",
"subscriber_help": false,
"help_keywords": "HELP,INFO",
"help_message": "<Brand Name>: For help, email support@example.com. To opt-out, reply STOP\n",
"sample_one": "Hi\nThis is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.\n",
"sample_two": "Hello,\nYour order, number XXXXXXX, has been shipped.\n",
"sample_three": "Here is you unique PIN number to access the application: 123456\n",
"sample_four": "Hello Mr Doe,\nYour payment of 9.99$ was authorized. You can find your invoice in your customer account.\n",
"sample_five": "Your delivery is scheduled for tomorrow between 8am and 2pm.\nIf you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.\n",
"age_gated": true,
"direct_lending": true,
"embedded_link": false,
"embedded_phone": false,
"partner": true,
"auto_renewal": true,
"hipaa": true,
"tcr_status": "UNKNOWN",
"vertical": "TECHNOLOGY",
"number_pool": false,
"registration_date": "2019-08-24T14:15:22Z",
"renewal_date": "2019-08-24",
"created_date": "2019-08-24T14:15:22Z",
"last_updated": "2019-08-24T14:15:22Z",
"billed_date": "2019-08-24T14:15:22Z",
"opt_out_assist": false,
"last_status_changes": [
{
"status": "APPROVED",
"reason": "Approved after internal review.",
"change_date": "2022-01-01 01:01:01"
}
],
"mno_metadata": [
{
"network_id": "10017",
"mno": "AT&T",
"status": "string",
"mno_support": true,
"mno_review": true,
"qualify": true,
"min_msg_samples": 2,
"req_subscriber_opt_in": true,
"req_subscriber_opt_out": true,
"req_subscriber_help": true,
"no_embedded_link": true,
"no_embedded_phone": true,
"att_msg_class": "Q",
"att_tpm": 3000,
"att_mms_tpm": 3000,
"att_number_based": true,
"tmo_brand_tier": "LOW",
"tmo_tpd": 0,
"complaints": [
{
"complaints": [
{
"description": "string",
"dca": "SINCH",
"created_at": "2019-08-24T14:15:22Z"
}
]
}
]
}
],
"carrier_brand_suspensions": [
[
{}
]
],
"_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"
}
}
}Preview message flow
Creates a message flow text, based on the structured object given.
The result is the same text that would be computed from field message_flow_details to fill message_flow when creating a campaign.
Note: if the resulting message_flow length is not in the allowed range (40 to 4096), the endpoint will return a 422 error.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
A brand name associated with the campaign. This can be different from the name of the brand the campaign belongs to (e.g. for subsidiaries, ...).
NB: This is optional for sole proprietors.
Describe the different mechanisms a customer may use to consent to the campaign.
It is required to provide an attachment for all consent methods, except TEXT_TO_JOIN.
ONLINE_FORMLIVE_OPERATORPOINT_OF_SALETEXT_TO_JOINOTHERDetails on the consent mechanism.
An HTTP(S) link to the resource describing the mechanism.
This field needs to be true to consent to adding the pricing disclosure to the template.
The following will be added: Message and Data rates may apply
trueWhether to add the following disclaimer: Carriers are not liable for delayed or undelivered messages.
trueThe frequency of the messages sent by the campaign.
ONE_TIMERECURRINGLink to the campaign's privacy policy.
Link to the campaign's terms and conditions.
255START,SUBSCRIBEOpt in keywords of the campaign, separated by comas.
Example Request
{
"brand_name": "string",
"consent_mechanisms": [
{
"method": "ONLINE_FORM",
"details": "string",
"attachment": "http://example.com"
}
],
"pricing_disclosure": true,
"carrier_disclaimer": true,
"frequency": "ONE_TIME",
"privacy_policy": "http://example.com",
"terms_and_conditions": "http://example.com",
"opt_in_keywords": "START,SUBSCRIBE"
}{
"brand_name": "string",
"consent_mechanisms": [
{
"method": "ONLINE_FORM",
"details": "string",
"attachment": "http://example.com"
}
],
"pricing_disclosure": true,
"carrier_disclaimer": true,
"frequency": "ONE_TIME",
"privacy_policy": "http://example.com",
"terms_and_conditions": "http://example.com",
"opt_in_keywords": "START,SUBSCRIBE"
}404096Brand: My brand \
Consent mechanisms: \
- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \
- ONLINE_FORM: This is an online form \
Link: https://mybrand.com/optin \
Message & data rates may apply. - Message frequency varies \
Carriers are not liable for delayed or undelivered messages. \
Text HELP for help. Text STOP to opt-out. \
Terms & Conditions: https://mybrand.com/terms_and_conditions \
Privacy Policy: https://mybrand.com/privacy_policy
Message flow, also known as Call to Action, of the campaign. It will always be filled with data computed from message_flow_details.
This field should describe how a consumer opts-in to the campaign, therefore giving consent to the sender to receive their messages. The call-to-action must be explicitly clear and inform the consumer of the nature of the program.
- Entering a telephone number through a website;
- Clicking a button on a mobile webpage;
- Sending a message from the Consumer’s mobile device that contains an advertising keyword;
- Initiating the text message exchange in which the Message Sender replies to the Consumer only with responsive information;
- Signing up at a point-of-sale (POS) or other Message Sender on-site location; or
- Opting-in over the phone using interactive voice response (IVR) technology.
If multiple opt-in methods can be used for the same campaign, you must list them all.
Describes what the opt_in option was used for.
Example Response
{
"message_flow": "Brand: My brand \\\nConsent mechanisms: \\\n- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \\\n- ONLINE_FORM: This is an online form \\\n Link: https://mybrand.com/optin \\\nMessage & data rates may apply. - Message frequency varies \\\nCarriers are not liable for delayed or undelivered messages. \\\nText HELP for help. Text STOP to opt-out. \\\nTerms & Conditions: https://mybrand.com/terms_and_conditions \\\nPrivacy Policy: https://mybrand.com/privacy_policy\n"
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
abcd1234The Vonage Primary Account ID (the parent account of account_id).
abcd1234The Vonage Account ID
50BLQKOPKTCR Brand ID.
50VC987XYZVonage Campaign ID.
50C123ABCTCR Campaign ID.
8R123456Alphanumeric TCR identifier of the reseller associated with this campaign. R000000 is a special value meaning this is not a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
In POST and PATCH endpoints, this is ignored if the reseller field on the same call. It will also be ignored if the brand's reseller field is true.
If tcr_campaign_id and reseller_id are set (not an empty string) then this field cannot be changed anymore.
Indicates if a campaign is a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
In POST and PATCH endpoints, this is ignored if the brand's reseller field is true.
50This is a sample campaignFriendly name associated with this campaign.
ACTIVECampaign Status.
PENDING_REVIEW: This is the initial status of a campaign. This implies that the campaign has been submitted for an internal review and cannot be used yet.UPDATES_REQUIRED: The campaign has been reviewed but requires changes before it can be approved.CARRIERS_REVIEW: The campaign has been approved by our internal process. It has been created in the registry and but pending approval from third parties i.e: mobile carrier.ACTIVE: The campaign has been approved by every party and traffic can now be sent.PENDING_CANCELLATION: The campaign is active but will not be renewed. It will be canceled at the next renewal date.SUSPENDED: The campaign has been suspended, along with any traffic it's used to send. This can happen if suspicious traffic has been detected (e.g.: spam) or after an MNO complaint. This triggers an internal review process which can lead to the un-suspension or termination of the campaign.TERMINATED: The campaign has been terminated. A campaign cannot be recovered after it's been terminated.EXPIRED: The campaign has expired.REJECTED: This implies the campaign was rejected by the compliance team as it is not compliant with 10DLC requirements. Further reasons can be found in the description of the rejection event received from TCR. You may update the campaign using TCR’s API or dashboard, and re-share the campaign with Vonage for a new review.CNP_CANCELED: The campaign has been canceled during a CNP migration. You are required to restart a CNP migration.PORTED_OUT: The campaign has been ported out from Vonage. You are required to start a CNP migration.
PENDING_REVIEWUPDATES_REQUIREDCARRIERS_REVIEWACTIVEPENDING_CANCELLATIONSUSPENDEDTERMINATEDCANCELEDREJECTEDCNP_CANCELEDPORTED_OUTIndicates if traffic is enabled for this campaign.
Traffic first becomes enabled when the campaign's status becomes ACTIVE. It can be suspended later due to a number of reasons (campaign suspension, expiration, termination, ...).
NB This is only a requirement for traffic to be allowed but not is not the only requirement. Traffic can also be stopped due to brand suspensions, number not linked properly, ...
50ACCOUNT_NOTIFICATIONCampaign usecase. Please refer to the /enum endpoint for an updated list of valid values.
CUSTOMER_CAREPOLLING_VOTINGHIGHER_EDUCATIONPUBLIC_SERVICE_ANNOUNCEMENTMARKETINGSECURITY_ALERTDELIVERY_NOTIFICATIONACCOUNT_NOTIFICATION2FAFRAUD_ALERTTRIALCHARITYPOLITICALEMERGENCYSWEEPSTAKECONVERSATIONALMIXEDCARRIER_EXEMPTSOCIALLOW_VOLUME404096User notificationsSummary description of this campaign
404096Brand: My brand \
Consent mechanisms: \
- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \
- ONLINE_FORM: This is an online form \
Link: https://mybrand.com/optin \
Message & data rates may apply. - Message frequency varies \
Carriers are not liable for delayed or undelivered messages. \
Text HELP for help. Text STOP to opt-out. \
Terms & Conditions: https://mybrand.com/terms_and_conditions \
Privacy Policy: https://mybrand.com/privacy_policy
Message flow, also known as Call to Action, of the campaign. It will always be filled with data computed from message_flow_details.
This field should describe how a consumer opts-in to the campaign, therefore giving consent to the sender to receive their messages. The call-to-action must be explicitly clear and inform the consumer of the nature of the program.
- Entering a telephone number through a website;
- Clicking a button on a mobile webpage;
- Sending a message from the Consumer’s mobile device that contains an advertising keyword;
- Initiating the text message exchange in which the Message Sender replies to the Consumer only with responsive information;
- Signing up at a point-of-sale (POS) or other Message Sender on-site location; or
- Opting-in over the phone using interactive voice response (IVR) technology.
If multiple opt-in methods can be used for the same campaign, you must list them all.
Describes what the opt_in option was used for.
Message flow details specifies the message_flow field as a structured object instead of a single text field.
When creating or updating a campaign:
- either
message_flowormessage_flow_detailsmay be specified, but not both. - if
message_flow_detailsis specified, the object's fields will be used to fill a template. The resulting templated text will be used to fill themessage_flowfield of the campaign.
When reading a campaign message_flow_details will only be filled if it's been used to create or update the campaign.
For more information on Campaign message flows, please see this campaign requirements article.
A brand name associated with the campaign. This can be different from the name of the brand the campaign belongs to (e.g. for subsidiaries, ...).
NB: This is optional for sole proprietors.
Describe the different mechanisms a customer may use to consent to the campaign.
It is required to provide an attachment for all consent methods, except TEXT_TO_JOIN.
ONLINE_FORMLIVE_OPERATORPOINT_OF_SALETEXT_TO_JOINOTHERDetails on the consent mechanism.
An HTTP(S) link to the resource describing the mechanism.
This field needs to be true to consent to adding the pricing disclosure to the template.
The following will be added: Message and Data rates may apply
trueWhether to add the following disclaimer: Carriers are not liable for delayed or undelivered messages.
trueThe frequency of the messages sent by the campaign.
ONE_TIMERECURRINGLink to the campaign's privacy policy.
Link to the campaign's terms and conditions.
trueDoes campaign require subscriber to opt-in before SMS is sent to subscriber?
255START,SUBSCRIBEOpt in keywords of the campaign, separated by comas.
20320<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP
Opt in message sent to confirmation enrollment to a recurring message campaign. Also provide information on how to get HELP or undo enrollment. If consumers can text in a keyword,the response should include the Brand name.
NB: This field is mandatory if opt_in_keywords is set.
trueDoes campaign support subscriber opt-out keyword(s)?
255STOPSTOP,QUITOpt out keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the STOP keyword if set.
20320<Brand Name>: You are now opted-out and will receive no further messages.
Opt out message of the campaign. The response to the STOP keyword may include the Brand name but should include an acknowledgement of the opt-out request and confirmation that no further messages will be sent.
NB: Required for all recurring campaigns or for SMS opt-in.
trueDoes campaign responds to help keyword(s)?
255HELPHELP,INFOHelp keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the HELP keyword if set.
20320<Brand Name>: For help, email support@example.com. To opt-out, reply STOP
Help message of the campaign.
The response to HELP keyword may include the Brand name and additional support contact information.
201024Hi
This is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.
Message sample. Some campaign tiers require 1 or more message samples.
201024Hello,
Your order, number XXXXXXX, has been shipped.
Message sample. Some campaign tiers require 2 or more message samples.
201024Here is you unique PIN number to access the application: 123456
Message sample. Some campaign tiers require 3 or more message samples.
201024Hello Mr Doe,
Your payment of 9.99$ was authorized. You can find your invoice in your customer account.
Message sample. Some campaign tiers require 4 or more message samples.
201024Your delivery is scheduled for tomorrow between 8am and 2pm.
If you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.
Message sample. Some campaign tiers require 5.
trueSubscribers will be required to provide their age to opt-in if set to true. NB: Sex, Hate, Alcohol, Firearms, and Tobacco related (S.H.A.F.T) messages are prohibited.
trueSet to true if messages are related to money lending or loan arrangements.
Set to true if the campaign message includes links. NB: Shortened URLs are forbidden.
Does message generated by the campaign include phone number in SMS?
trueIndicates the brand or campaign belong to a partner campaign.
Campaign subscription auto-renewal option.
Defines the behaviour at the end of the billing cycle:
- if
true, the campaign will automatically renewed - if
false, the campaign will expire and its status will becomeCANCELED
Indicates if HIPAA is enabled for this campaign.
This is kept nullable to avoid breaking changes, but it is best to set it when creating the campaign. Otherwise, this will be set when attempting to link the first number of the campaign, whether the attempt is successful or not. After that, it will not be possible to update that field anymore.
Campaign TCR status.
UNKNOWNACTIVECANCELEDTECHNOLOGYBusiness/industry segment of this campaign. Please refer to the vertical property of the /enum endpoint for an updated list of valid values.
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATIONtrueSet to true if campaign uses a pool of numbers.
Date-time when campaign was registered with TCR.
Date when the campaign will be renewed and billed, if auto_renewal is true.
Date when this record was created.
Date-time when this record was last updated.
Date-time when this campaign was billed.
Specifies whether opt out assist is enabled for this account.
On a campaign, indicates whether it's enabled on the primary account of the campaign's brand.
Lists the last changes of the status field.
Note: this is only an extract. Not all changes are listed here.
ACTIVECampaign Status.
PENDING_REVIEW: This is the initial status of a campaign. This implies that the campaign has been submitted for an internal review and cannot be used yet.UPDATES_REQUIRED: The campaign has been reviewed but requires changes before it can be approved.CARRIERS_REVIEW: The campaign has been approved by our internal process. It has been created in the registry and but pending approval from third parties i.e: mobile carrier.ACTIVE: The campaign has been approved by every party and traffic can now be sent.PENDING_CANCELLATION: The campaign is active but will not be renewed. It will be canceled at the next renewal date.SUSPENDED: The campaign has been suspended, along with any traffic it's used to send. This can happen if suspicious traffic has been detected (e.g.: spam) or after an MNO complaint. This triggers an internal review process which can lead to the un-suspension or termination of the campaign.TERMINATED: The campaign has been terminated. A campaign cannot be recovered after it's been terminated.EXPIRED: The campaign has expired.REJECTED: This implies the campaign was rejected by the compliance team as it is not compliant with 10DLC requirements. Further reasons can be found in the description of the rejection event received from TCR. You may update the campaign using TCR’s API or dashboard, and re-share the campaign with Vonage for a new review.CNP_CANCELED: The campaign has been canceled during a CNP migration. You are required to restart a CNP migration.PORTED_OUT: The campaign has been ported out from Vonage. You are required to start a CNP migration.
PENDING_REVIEWUPDATES_REQUIREDCARRIERS_REVIEWACTIVEPENDING_CANCELLATIONSUSPENDEDTERMINATEDCANCELEDREJECTEDCNP_CANCELEDPORTED_OUTDescribes why the status changed how it did.
Date-time when the status changed.
10017Network ID of the MNO.
AT&TName of the MNO.
MNO campaign operation status. Please refer to the campaign_op_status property of the /enum endpoint response for an updated list of valid values.
If 'false', then the desired usecase cannot be supported by the MNO.
If 'true', then the submitted campaign is subject to the MNO (manual) review process.
If 'false', then the brand does not qualify for the desired usecase on the MNO.
2The minimum number of message samples required by MNO for submission of the desired usecase.
If 'true' then MNO requires the subscriber to opt-into the campaign before the message may be sent to the subscriber. The opt-in mechanism can be mobile or web opt-in.
If 'true' then MNO requires a campaign to support an opt-out mechanism through MO stop keywords such as 'STOP', 'QUIT'. Upon receive the STOP message from a subscriber, the campaign must stop sending messages to the subscriber immediately.
If 'true' then MNO requires a campaign to support a 'help' mechanism through MO help key words such as 'HELP', 'INFO'.
If 'true' then MNO forbids call-to-action link/URL to be embedded in all messages sent to the subscriber.
If 'true' then MNO forbids call-to-action phone number to be embedded in all messages sent to the subscriber.
Q(Only for AT&T). Message class assigned to the campaign by MNO. Please refer to the AT&T 10DLC guide for a complete list of available message class and definition.
3000(Only for AT&T). SMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
3000(Only for AT&T). MMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
(Only for AT&T). Whether is the MNO applying the TPM per number or per campaign.
LOW(Only for T-Mobile). Daily message volume is restricted based on brand tier or brand qualification. The daily volume restriction applies to brand across campaigns and CSPs. Please refer to the /enum endpoint for an updated list of valid values.
LOWLOWER_MIDUPPER_MIDTOPUNCAPPED(Only for TMobile). Message TPD (throughput per day) qualified by the brand for the desired usecase.
65535Description of this MNO complaint.
SINCHdca name
Date-time when this record was created.
Summarize the reason of the suspension.
Detailed explanation of the cause of the suspension.
https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879https://api.nexmo.com/v1/10dlc/brands/BLQKOPKhttps://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbersExample Response
{
"primary_account_id": "abcd1234",
"account_id": "abcd1234",
"brand_id": "BLQKOPK",
"campaign_id": "VC987XYZ",
"tcr_campaign_id": "C123ABC",
"reseller_id": "R123456",
"reseller": true,
"label": "This is a sample campaign",
"status": "ACTIVE",
"traffic_enabled": true,
"usecase": "ACCOUNT_NOTIFICATION",
"sub_usecases": [
"2FA",
"SECURITY_ALERT"
],
"description": "User notifications",
"message_flow": "Brand: My brand \\\nConsent mechanisms: \\\n- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \\\n- ONLINE_FORM: This is an online form \\\n Link: https://mybrand.com/optin \\\nMessage & data rates may apply. - Message frequency varies \\\nCarriers are not liable for delayed or undelivered messages. \\\nText HELP for help. Text STOP to opt-out. \\\nTerms & Conditions: https://mybrand.com/terms_and_conditions \\\nPrivacy Policy: https://mybrand.com/privacy_policy\n",
"message_flow_details": {
"brand_name": "My brand",
"consent_mechanisms": [
{
"method": "TEXT_TO_JOIN",
"details": "A text will be sent to the customer. He can reply yes to consent and opt in."
},
{
"method": "ONLINE_FORM",
"details": "An online form allows the customer to subscribe.",
"attachment": "https://mybrand.com/optin"
}
],
"pricing_disclosure": true,
"frequency": "RECURRING",
"privacy_policy": "https://mybrand.com/privacy_policy",
"terms_and_conditions": "https://mybrand.com/terms_and_conditions"
},
"subscriber_opt_in": false,
"opt_in_keywords": "START,SUBSCRIBE",
"opt_in_message": "<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP\n",
"subscriber_opt_out": false,
"opt_out_keywords": "STOP,QUIT",
"opt_out_message": "<Brand Name>: You are now opted-out and will receive no further messages.\n",
"subscriber_help": false,
"help_keywords": "HELP,INFO",
"help_message": "<Brand Name>: For help, email support@example.com. To opt-out, reply STOP\n",
"sample_one": "Hi\nThis is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.\n",
"sample_two": "Hello,\nYour order, number XXXXXXX, has been shipped.\n",
"sample_three": "Here is you unique PIN number to access the application: 123456\n",
"sample_four": "Hello Mr Doe,\nYour payment of 9.99$ was authorized. You can find your invoice in your customer account.\n",
"sample_five": "Your delivery is scheduled for tomorrow between 8am and 2pm.\nIf you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.\n",
"age_gated": true,
"direct_lending": true,
"embedded_link": false,
"embedded_phone": false,
"partner": true,
"auto_renewal": true,
"hipaa": true,
"tcr_status": "UNKNOWN",
"vertical": "TECHNOLOGY",
"number_pool": false,
"registration_date": "2019-08-24T14:15:22Z",
"renewal_date": "2019-08-24",
"created_date": "2019-08-24T14:15:22Z",
"last_updated": "2019-08-24T14:15:22Z",
"billed_date": "2019-08-24T14:15:22Z",
"opt_out_assist": false,
"last_status_changes": [
{
"status": "APPROVED",
"reason": "Approved after internal review.",
"change_date": "2022-01-01 01:01:01"
}
],
"mno_metadata": [
{
"network_id": "10017",
"mno": "AT&T",
"status": "string",
"mno_support": true,
"mno_review": true,
"qualify": true,
"min_msg_samples": 2,
"req_subscriber_opt_in": true,
"req_subscriber_opt_out": true,
"req_subscriber_help": true,
"no_embedded_link": true,
"no_embedded_phone": true,
"att_msg_class": "Q",
"att_tpm": 3000,
"att_mms_tpm": 3000,
"att_number_based": true,
"tmo_brand_tier": "LOW",
"tmo_tpd": 0,
"complaints": [
{
"complaints": [
{
"description": "string",
"dca": "SINCH",
"created_at": "2019-08-24T14:15:22Z"
}
]
}
]
}
],
"carrier_brand_suspensions": [
[
{}
]
],
"_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"
}
}
}Partially update a specific campaign
Update campaign parameters
What can be updated depends on the campaign's state:
- If the campaign's status is
TERMINATEDorCANCELED, the campaign may not be updated. - If the campaign's status is
PENDING_REVIEWorUPDATES_REQUIRED, all fields may be updated. - For other statuses, the following fields may not be updated since they are read only after the initial approval of the campaign by Vonage compliance team:
- vertical
- usecase
- sub_usecases
- age_gated
- direct_lending
- embedded_link
- embedded_phone
- status
- The
hipaafield can only be updated if no number was ever linked to that campaign.
Forced values
statuscan only be set to“CANCELED”, to cancel a campaign, Otherwise, it must be left out, or set to null.
NB:
opt_in_messageis mandatory ifopt_in_keywordsis set.message_flowandmessage_flow_detailsare mutually exclusive.
- if
message_flowis passed, it will erase any storedmessage_flow_details. - if
message_flow_detailsis passed, it will be stored and used to computemessage_flow.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
50This is a sample campaignFriendly name associated with this campaign.
404096User notificationsSummary description of this campaign
8R123456Alphanumeric TCR identifier of the reseller associated with this campaign. R000000 is a special value meaning this is not a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
In POST and PATCH endpoints, this is ignored if the reseller field on the same call. It will also be ignored if the brand's reseller field is true.
If tcr_campaign_id and reseller_id are set (not an empty string) then this field cannot be changed anymore.
Indicates if a campaign is a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
In POST and PATCH endpoints, this is ignored if the brand's reseller field is true.
201024Hi
This is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.
Message sample. Some campaign tiers require 1 or more message samples.
201024Hello,
Your order, number XXXXXXX, has been shipped.
Message sample. Some campaign tiers require 2 or more message samples.
201024Here is you unique PIN number to access the application: 123456
Message sample. Some campaign tiers require 3 or more message samples.
201024Hello Mr Doe,
Your payment of 9.99$ was authorized. You can find your invoice in your customer account.
Message sample. Some campaign tiers require 4 or more message samples.
201024Your delivery is scheduled for tomorrow between 8am and 2pm.
If you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.
Message sample. Some campaign tiers require 5.
404096Brand: My brand \
Consent mechanisms: \
- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \
- ONLINE_FORM: This is an online form \
Link: https://mybrand.com/optin \
Message & data rates may apply. - Message frequency varies \
Carriers are not liable for delayed or undelivered messages. \
Text HELP for help. Text STOP to opt-out. \
Terms & Conditions: https://mybrand.com/terms_and_conditions \
Privacy Policy: https://mybrand.com/privacy_policy
Message flow, also known as Call to Action, of the campaign.
This field should describe how a consumer opts-in to the campaign, therefore giving consent to the sender to receive their messages. The call-to-action must be explicitly clear and inform the consumer of the nature of the program.
- Entering a telephone number through a website;
- Clicking a button on a mobile webpage;
- Sending a message from the Consumer’s mobile device that contains an advertising keyword;
- Initiating the text message exchange in which the Message Sender replies to the Consumer only with responsive information;
- Signing up at a point-of-sale (POS) or other Message Sender on-site location; or
- Opting-in over the phone using interactive voice response (IVR) technology.
If multiple opt-in methods can be used for the same campaign, you must list them all.
When creating or updating a campaign, either message_flow or message_flow_details may be specified, but not both. When reading a campaign, message_flow will always be filled with data computed from message_flow_details.
Describes what the opt_in option was used for. NBThis attribute will be deprecated on POST and PATCH endpoint. Please update your application to use the message_flow_details property instead.
Message flow details specifies the message_flow field as a structured object instead of a single text field.
When creating or updating a campaign:
- either
message_flowormessage_flow_detailsmay be specified, but not both. - if
message_flow_detailsis specified, the object's fields will be used to fill a template. The resulting templated text will be used to fill themessage_flowfield of the campaign.
When reading a campaign message_flow_details will only be filled if it's been used to create or update the campaign.
For more information on Campaign message flows, please see this campaign requirements article.
A brand name associated with the campaign. This can be different from the name of the brand the campaign belongs to (e.g. for subsidiaries, ...).
NB: This is optional for sole proprietors.
Describe the different mechanisms a customer may use to consent to the campaign.
It is required to provide an attachment for all consent methods, except TEXT_TO_JOIN.
ONLINE_FORMLIVE_OPERATORPOINT_OF_SALETEXT_TO_JOINOTHERDetails on the consent mechanism.
An HTTP(S) link to the resource describing the mechanism.
This field needs to be true to consent to adding the pricing disclosure to the template.
The following will be added: Message and Data rates may apply
trueWhether to add the following disclaimer: Carriers are not liable for delayed or undelivered messages.
trueThe frequency of the messages sent by the campaign.
ONE_TIMERECURRINGLink to the campaign's privacy policy.
Link to the campaign's terms and conditions.
20320<Brand Name>: For help, email support@example.com. To opt-out, reply STOP
Help message of the campaign.
The response to HELP keyword may include the Brand name and additional support contact information.
20320<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP
Opt in message sent to confirmation enrollment to a recurring message campaign. Also provide information on how to get HELP or undo enrollment. If consumers can text in a keyword,the response should include the Brand name.
NB: This field is mandatory if opt_in_keywords is set.
20320<Brand Name>: You are now opted-out and will receive no further messages.
Opt out message of the campaign. The response to the STOP keyword may include the Brand name but should include an acknowledgement of the opt-out request and confirmation that no further messages will be sent.
NB: Required for all recurring campaigns or for SMS opt-in.
255HELPHELP,INFOHelp keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the HELP keyword if set.
255START,SUBSCRIBEOpt in keywords of the campaign, separated by comas.
255STOPSTOP,QUITOpt out keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the STOP keyword if set.
Campaign subscription auto-renewal option.
Campaign status. Only status CANCELED may be manually set.
CANCELEDTECHNOLOGYBusiness/industry segment of this campaign. Please refer to the vertical property of the /enum endpoint for an updated list of valid values.
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATION50ACCOUNT_NOTIFICATIONCampaign usecase. Please refer to the /enum endpoint for an updated list of valid values.
CUSTOMER_CAREPOLLING_VOTINGHIGHER_EDUCATIONPUBLIC_SERVICE_ANNOUNCEMENTMARKETINGSECURITY_ALERTDELIVERY_NOTIFICATIONACCOUNT_NOTIFICATION2FAFRAUD_ALERTTRIALCHARITYPOLITICALEMERGENCYSWEEPSTAKECONVERSATIONALMIXEDCARRIER_EXEMPTSOCIALLOW_VOLUMEtrueSubscribers will be required to provide their age to opt-in if set to true. NB: Sex, Hate, Alcohol, Firearms, and Tobacco related (S.H.A.F.T) messages are prohibited.
trueSet to true if messages are related to money lending or loan arrangements.
Set to true if the campaign message includes links. NB: Shortened URLs are forbidden.
Does message generated by the campaign include phone number in SMS?
Indicates if HIPAA is enabled for this campaign.
This is kept nullable to avoid breaking changes, but it is best to set it when creating the campaign. Otherwise, this will be set when attempting to link the first number of the campaign, whether the attempt is successful or not. After that, it will not be possible to update that field anymore.
Example Request
{
"label": "This is a sample campaign",
"description": "User notifications",
"reseller_id": "R123456",
"reseller": true,
"sample_one": "Hi\nThis is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.\n",
"sample_two": "Hello,\nYour order, number XXXXXXX, has been shipped.\n",
"sample_three": "Here is you unique PIN number to access the application: 123456\n",
"sample_four": "Hello Mr Doe,\nYour payment of 9.99$ was authorized. You can find your invoice in your customer account.\n",
"sample_five": "Your delivery is scheduled for tomorrow between 8am and 2pm.\nIf you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.\n",
"message_flow": "Brand: My brand \\\nConsent mechanisms: \\\n- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \\\n- ONLINE_FORM: This is an online form \\\n Link: https://mybrand.com/optin \\\nMessage & data rates may apply. - Message frequency varies \\\nCarriers are not liable for delayed or undelivered messages. \\\nText HELP for help. Text STOP to opt-out. \\\nTerms & Conditions: https://mybrand.com/terms_and_conditions \\\nPrivacy Policy: https://mybrand.com/privacy_policy\n",
"message_flow_details": {
"brand_name": "My brand",
"consent_mechanisms": [
{
"method": "TEXT_TO_JOIN",
"details": "A text will be sent to the customer. He can reply yes to consent and opt in."
},
{
"method": "ONLINE_FORM",
"details": "An online form allows the customer to subscribe.",
"attachment": "https://mybrand.com/optin"
}
],
"pricing_disclosure": true,
"frequency": "RECURRING",
"privacy_policy": "https://mybrand.com/privacy_policy",
"terms_and_conditions": "https://mybrand.com/terms_and_conditions"
},
"help_message": "<Brand Name>: For help, email support@example.com. To opt-out, reply STOP\n",
"opt_in_message": "<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP\n",
"opt_out_message": "<Brand Name>: You are now opted-out and will receive no further messages.\n",
"help_keywords": "HELP,INFO",
"opt_in_keywords": "START,SUBSCRIBE",
"opt_out_keywords": "STOP,QUIT",
"auto_renewal": true,
"status": "CANCELED",
"vertical": "TECHNOLOGY",
"usecase": "ACCOUNT_NOTIFICATION",
"sub_usecases": [
"ACCOUNT_NOTIFICATION"
],
"age_gated": true,
"direct_lending": true,
"embedded_link": false,
"embedded_phone": false,
"hipaa": true
}{
"label": "This is a sample campaign",
"description": "User notifications",
"reseller_id": "R123456",
"reseller": true,
"sample_one": "Hi\nThis is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.\n",
"sample_two": "Hello,\nYour order, number XXXXXXX, has been shipped.\n",
"sample_three": "Here is you unique PIN number to access the application: 123456\n",
"sample_four": "Hello Mr Doe,\nYour payment of 9.99$ was authorized. You can find your invoice in your customer account.\n",
"sample_five": "Your delivery is scheduled for tomorrow between 8am and 2pm.\nIf you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.\n",
"message_flow": "Brand: My brand \\\nConsent mechanisms: \\\n- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \\\n- ONLINE_FORM: This is an online form \\\n Link: https://mybrand.com/optin \\\nMessage & data rates may apply. - Message frequency varies \\\nCarriers are not liable for delayed or undelivered messages. \\\nText HELP for help. Text STOP to opt-out. \\\nTerms & Conditions: https://mybrand.com/terms_and_conditions \\\nPrivacy Policy: https://mybrand.com/privacy_policy\n",
"message_flow_details": {
"brand_name": "My brand",
"consent_mechanisms": [
{
"method": "TEXT_TO_JOIN",
"details": "A text will be sent to the customer. He can reply yes to consent and opt in."
},
{
"method": "ONLINE_FORM",
"details": "An online form allows the customer to subscribe.",
"attachment": "https://mybrand.com/optin"
}
],
"pricing_disclosure": true,
"frequency": "RECURRING",
"privacy_policy": "https://mybrand.com/privacy_policy",
"terms_and_conditions": "https://mybrand.com/terms_and_conditions"
},
"help_message": "<Brand Name>: For help, email support@example.com. To opt-out, reply STOP\n",
"opt_in_message": "<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP\n",
"opt_out_message": "<Brand Name>: You are now opted-out and will receive no further messages.\n",
"help_keywords": "HELP,INFO",
"opt_in_keywords": "START,SUBSCRIBE",
"opt_out_keywords": "STOP,QUIT",
"auto_renewal": true,
"status": "CANCELED",
"vertical": "TECHNOLOGY",
"usecase": "ACCOUNT_NOTIFICATION",
"sub_usecases": [
"ACCOUNT_NOTIFICATION"
],
"age_gated": true,
"direct_lending": true,
"embedded_link": false,
"embedded_phone": false,
"hipaa": true
}abcd1234The Vonage Primary Account ID (the parent account of account_id).
abcd1234The Vonage Account ID
50BLQKOPKTCR Brand ID.
50VC987XYZVonage Campaign ID.
50C123ABCTCR Campaign ID.
8R123456Alphanumeric TCR identifier of the reseller associated with this campaign. R000000 is a special value meaning this is not a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
In POST and PATCH endpoints, this is ignored if the reseller field on the same call. It will also be ignored if the brand's reseller field is true.
If tcr_campaign_id and reseller_id are set (not an empty string) then this field cannot be changed anymore.
Indicates if a campaign is a reseller campaign.
This is required when creating a campaign on behalf of another company or entity.
This can only be enabled if a valid reseller (status PENDING or APPROVED) is linked to the primary account of the brand.
In POST and PATCH endpoints, this is ignored if the brand's reseller field is true.
50This is a sample campaignFriendly name associated with this campaign.
ACTIVECampaign Status.
PENDING_REVIEW: This is the initial status of a campaign. This implies that the campaign has been submitted for an internal review and cannot be used yet.UPDATES_REQUIRED: The campaign has been reviewed but requires changes before it can be approved.CARRIERS_REVIEW: The campaign has been approved by our internal process. It has been created in the registry and but pending approval from third parties i.e: mobile carrier.ACTIVE: The campaign has been approved by every party and traffic can now be sent.PENDING_CANCELLATION: The campaign is active but will not be renewed. It will be canceled at the next renewal date.SUSPENDED: The campaign has been suspended, along with any traffic it's used to send. This can happen if suspicious traffic has been detected (e.g.: spam) or after an MNO complaint. This triggers an internal review process which can lead to the un-suspension or termination of the campaign.TERMINATED: The campaign has been terminated. A campaign cannot be recovered after it's been terminated.EXPIRED: The campaign has expired.REJECTED: This implies the campaign was rejected by the compliance team as it is not compliant with 10DLC requirements. Further reasons can be found in the description of the rejection event received from TCR. You may update the campaign using TCR’s API or dashboard, and re-share the campaign with Vonage for a new review.CNP_CANCELED: The campaign has been canceled during a CNP migration. You are required to restart a CNP migration.PORTED_OUT: The campaign has been ported out from Vonage. You are required to start a CNP migration.
PENDING_REVIEWUPDATES_REQUIREDCARRIERS_REVIEWACTIVEPENDING_CANCELLATIONSUSPENDEDTERMINATEDCANCELEDREJECTEDCNP_CANCELEDPORTED_OUTIndicates if traffic is enabled for this campaign.
Traffic first becomes enabled when the campaign's status becomes ACTIVE. It can be suspended later due to a number of reasons (campaign suspension, expiration, termination, ...).
NB This is only a requirement for traffic to be allowed but not is not the only requirement. Traffic can also be stopped due to brand suspensions, number not linked properly, ...
50ACCOUNT_NOTIFICATIONCampaign usecase. Please refer to the /enum endpoint for an updated list of valid values.
CUSTOMER_CAREPOLLING_VOTINGHIGHER_EDUCATIONPUBLIC_SERVICE_ANNOUNCEMENTMARKETINGSECURITY_ALERTDELIVERY_NOTIFICATIONACCOUNT_NOTIFICATION2FAFRAUD_ALERTTRIALCHARITYPOLITICALEMERGENCYSWEEPSTAKECONVERSATIONALMIXEDCARRIER_EXEMPTSOCIALLOW_VOLUME404096User notificationsSummary description of this campaign
404096Brand: My brand \
Consent mechanisms: \
- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \
- ONLINE_FORM: This is an online form \
Link: https://mybrand.com/optin \
Message & data rates may apply. - Message frequency varies \
Carriers are not liable for delayed or undelivered messages. \
Text HELP for help. Text STOP to opt-out. \
Terms & Conditions: https://mybrand.com/terms_and_conditions \
Privacy Policy: https://mybrand.com/privacy_policy
Message flow, also known as Call to Action, of the campaign. It will always be filled with data computed from message_flow_details.
This field should describe how a consumer opts-in to the campaign, therefore giving consent to the sender to receive their messages. The call-to-action must be explicitly clear and inform the consumer of the nature of the program.
- Entering a telephone number through a website;
- Clicking a button on a mobile webpage;
- Sending a message from the Consumer’s mobile device that contains an advertising keyword;
- Initiating the text message exchange in which the Message Sender replies to the Consumer only with responsive information;
- Signing up at a point-of-sale (POS) or other Message Sender on-site location; or
- Opting-in over the phone using interactive voice response (IVR) technology.
If multiple opt-in methods can be used for the same campaign, you must list them all.
Describes what the opt_in option was used for.
Message flow details specifies the message_flow field as a structured object instead of a single text field.
When creating or updating a campaign:
- either
message_flowormessage_flow_detailsmay be specified, but not both. - if
message_flow_detailsis specified, the object's fields will be used to fill a template. The resulting templated text will be used to fill themessage_flowfield of the campaign.
When reading a campaign message_flow_details will only be filled if it's been used to create or update the campaign.
For more information on Campaign message flows, please see this campaign requirements article.
A brand name associated with the campaign. This can be different from the name of the brand the campaign belongs to (e.g. for subsidiaries, ...).
NB: This is optional for sole proprietors.
Describe the different mechanisms a customer may use to consent to the campaign.
It is required to provide an attachment for all consent methods, except TEXT_TO_JOIN.
ONLINE_FORMLIVE_OPERATORPOINT_OF_SALETEXT_TO_JOINOTHERDetails on the consent mechanism.
An HTTP(S) link to the resource describing the mechanism.
This field needs to be true to consent to adding the pricing disclosure to the template.
The following will be added: Message and Data rates may apply
trueWhether to add the following disclaimer: Carriers are not liable for delayed or undelivered messages.
trueThe frequency of the messages sent by the campaign.
ONE_TIMERECURRINGLink to the campaign's privacy policy.
Link to the campaign's terms and conditions.
trueDoes campaign require subscriber to opt-in before SMS is sent to subscriber?
255START,SUBSCRIBEOpt in keywords of the campaign, separated by comas.
20320<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP
Opt in message sent to confirmation enrollment to a recurring message campaign. Also provide information on how to get HELP or undo enrollment. If consumers can text in a keyword,the response should include the Brand name.
NB: This field is mandatory if opt_in_keywords is set.
trueDoes campaign support subscriber opt-out keyword(s)?
255STOPSTOP,QUITOpt out keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the STOP keyword if set.
20320<Brand Name>: You are now opted-out and will receive no further messages.
Opt out message of the campaign. The response to the STOP keyword may include the Brand name but should include an acknowledgement of the opt-out request and confirmation that no further messages will be sent.
NB: Required for all recurring campaigns or for SMS opt-in.
trueDoes campaign responds to help keyword(s)?
255HELPHELP,INFOHelp keywords of the campaign, separated by comas. This field must not contain any spaces, and must contain the HELP keyword if set.
20320<Brand Name>: For help, email support@example.com. To opt-out, reply STOP
Help message of the campaign.
The response to HELP keyword may include the Brand name and additional support contact information.
201024Hi
This is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.
Message sample. Some campaign tiers require 1 or more message samples.
201024Hello,
Your order, number XXXXXXX, has been shipped.
Message sample. Some campaign tiers require 2 or more message samples.
201024Here is you unique PIN number to access the application: 123456
Message sample. Some campaign tiers require 3 or more message samples.
201024Hello Mr Doe,
Your payment of 9.99$ was authorized. You can find your invoice in your customer account.
Message sample. Some campaign tiers require 4 or more message samples.
201024Your delivery is scheduled for tomorrow between 8am and 2pm.
If you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.
Message sample. Some campaign tiers require 5.
trueSubscribers will be required to provide their age to opt-in if set to true. NB: Sex, Hate, Alcohol, Firearms, and Tobacco related (S.H.A.F.T) messages are prohibited.
trueSet to true if messages are related to money lending or loan arrangements.
Set to true if the campaign message includes links. NB: Shortened URLs are forbidden.
Does message generated by the campaign include phone number in SMS?
trueIndicates the brand or campaign belong to a partner campaign.
Campaign subscription auto-renewal option.
Defines the behaviour at the end of the billing cycle:
- if
true, the campaign will automatically renewed - if
false, the campaign will expire and its status will becomeCANCELED
Indicates if HIPAA is enabled for this campaign.
This is kept nullable to avoid breaking changes, but it is best to set it when creating the campaign. Otherwise, this will be set when attempting to link the first number of the campaign, whether the attempt is successful or not. After that, it will not be possible to update that field anymore.
Campaign TCR status.
UNKNOWNACTIVECANCELEDTECHNOLOGYBusiness/industry segment of this campaign. Please refer to the vertical property of the /enum endpoint for an updated list of valid values.
REAL_ESTATEHEALTHCAREENERGYENTERTAINMENTRETAILAGRICULTUREINSURANCEEDUCATIONHOSPITALITYFINANCIALGAMBLINGCONSTRUCTIONNGOMANUFACTURINGGOVERNMENTTECHNOLOGYCOMMUNICATIONtrueSet to true if campaign uses a pool of numbers.
Date-time when campaign was registered with TCR.
Date when the campaign will be renewed and billed, if auto_renewal is true.
Date when this record was created.
Date-time when this record was last updated.
Date-time when this campaign was billed.
Specifies whether opt out assist is enabled for this account.
On a campaign, indicates whether it's enabled on the primary account of the campaign's brand.
Lists the last changes of the status field.
Note: this is only an extract. Not all changes are listed here.
ACTIVECampaign Status.
PENDING_REVIEW: This is the initial status of a campaign. This implies that the campaign has been submitted for an internal review and cannot be used yet.UPDATES_REQUIRED: The campaign has been reviewed but requires changes before it can be approved.CARRIERS_REVIEW: The campaign has been approved by our internal process. It has been created in the registry and but pending approval from third parties i.e: mobile carrier.ACTIVE: The campaign has been approved by every party and traffic can now be sent.PENDING_CANCELLATION: The campaign is active but will not be renewed. It will be canceled at the next renewal date.SUSPENDED: The campaign has been suspended, along with any traffic it's used to send. This can happen if suspicious traffic has been detected (e.g.: spam) or after an MNO complaint. This triggers an internal review process which can lead to the un-suspension or termination of the campaign.TERMINATED: The campaign has been terminated. A campaign cannot be recovered after it's been terminated.EXPIRED: The campaign has expired.REJECTED: This implies the campaign was rejected by the compliance team as it is not compliant with 10DLC requirements. Further reasons can be found in the description of the rejection event received from TCR. You may update the campaign using TCR’s API or dashboard, and re-share the campaign with Vonage for a new review.CNP_CANCELED: The campaign has been canceled during a CNP migration. You are required to restart a CNP migration.PORTED_OUT: The campaign has been ported out from Vonage. You are required to start a CNP migration.
PENDING_REVIEWUPDATES_REQUIREDCARRIERS_REVIEWACTIVEPENDING_CANCELLATIONSUSPENDEDTERMINATEDCANCELEDREJECTEDCNP_CANCELEDPORTED_OUTDescribes why the status changed how it did.
Date-time when the status changed.
10017Network ID of the MNO.
AT&TName of the MNO.
MNO campaign operation status. Please refer to the campaign_op_status property of the /enum endpoint response for an updated list of valid values.
If 'false', then the desired usecase cannot be supported by the MNO.
If 'true', then the submitted campaign is subject to the MNO (manual) review process.
If 'false', then the brand does not qualify for the desired usecase on the MNO.
2The minimum number of message samples required by MNO for submission of the desired usecase.
If 'true' then MNO requires the subscriber to opt-into the campaign before the message may be sent to the subscriber. The opt-in mechanism can be mobile or web opt-in.
If 'true' then MNO requires a campaign to support an opt-out mechanism through MO stop keywords such as 'STOP', 'QUIT'. Upon receive the STOP message from a subscriber, the campaign must stop sending messages to the subscriber immediately.
If 'true' then MNO requires a campaign to support a 'help' mechanism through MO help key words such as 'HELP', 'INFO'.
If 'true' then MNO forbids call-to-action link/URL to be embedded in all messages sent to the subscriber.
If 'true' then MNO forbids call-to-action phone number to be embedded in all messages sent to the subscriber.
Q(Only for AT&T). Message class assigned to the campaign by MNO. Please refer to the AT&T 10DLC guide for a complete list of available message class and definition.
3000(Only for AT&T). SMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
3000(Only for AT&T). MMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
(Only for AT&T). Whether is the MNO applying the TPM per number or per campaign.
LOW(Only for T-Mobile). Daily message volume is restricted based on brand tier or brand qualification. The daily volume restriction applies to brand across campaigns and CSPs. Please refer to the /enum endpoint for an updated list of valid values.
LOWLOWER_MIDUPPER_MIDTOPUNCAPPED(Only for TMobile). Message TPD (throughput per day) qualified by the brand for the desired usecase.
65535Description of this MNO complaint.
SINCHdca name
Date-time when this record was created.
Summarize the reason of the suspension.
Detailed explanation of the cause of the suspension.
https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879https://api.nexmo.com/v1/10dlc/brands/BLQKOPKhttps://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbersExample Response
{
"primary_account_id": "abcd1234",
"account_id": "abcd1234",
"brand_id": "BLQKOPK",
"campaign_id": "VC987XYZ",
"tcr_campaign_id": "C123ABC",
"reseller_id": "R123456",
"reseller": true,
"label": "This is a sample campaign",
"status": "ACTIVE",
"traffic_enabled": true,
"usecase": "ACCOUNT_NOTIFICATION",
"sub_usecases": [
"2FA",
"SECURITY_ALERT"
],
"description": "User notifications",
"message_flow": "Brand: My brand \\\nConsent mechanisms: \\\n- TEXT_TO_JOIN: Opt-in Keywords: START,JOIN. A text will be sent to the customer. He can reply yes to consent and opt in. \\\n- ONLINE_FORM: This is an online form \\\n Link: https://mybrand.com/optin \\\nMessage & data rates may apply. - Message frequency varies \\\nCarriers are not liable for delayed or undelivered messages. \\\nText HELP for help. Text STOP to opt-out. \\\nTerms & Conditions: https://mybrand.com/terms_and_conditions \\\nPrivacy Policy: https://mybrand.com/privacy_policy\n",
"message_flow_details": {
"brand_name": "My brand",
"consent_mechanisms": [
{
"method": "TEXT_TO_JOIN",
"details": "A text will be sent to the customer. He can reply yes to consent and opt in."
},
{
"method": "ONLINE_FORM",
"details": "An online form allows the customer to subscribe.",
"attachment": "https://mybrand.com/optin"
}
],
"pricing_disclosure": true,
"frequency": "RECURRING",
"privacy_policy": "https://mybrand.com/privacy_policy",
"terms_and_conditions": "https://mybrand.com/terms_and_conditions"
},
"subscriber_opt_in": false,
"opt_in_keywords": "START,SUBSCRIBE",
"opt_in_message": "<Brand Name>: You are now opted-in. For help, reply HELP. To opt-out, reply STOP\n",
"subscriber_opt_out": false,
"opt_out_keywords": "STOP,QUIT",
"opt_out_message": "<Brand Name>: You are now opted-out and will receive no further messages.\n",
"subscriber_help": false,
"help_keywords": "HELP,INFO",
"help_message": "<Brand Name>: For help, email support@example.com. To opt-out, reply STOP\n",
"sample_one": "Hi\nThis is a reminder that you have a scheduled appointment with Dr. Doe tomorrow at 4:00PM.\n",
"sample_two": "Hello,\nYour order, number XXXXXXX, has been shipped.\n",
"sample_three": "Here is you unique PIN number to access the application: 123456\n",
"sample_four": "Hello Mr Doe,\nYour payment of 9.99$ was authorized. You can find your invoice in your customer account.\n",
"sample_five": "Your delivery is scheduled for tomorrow between 8am and 2pm.\nIf you wish to change the delivery date please reply by typing 1 (tomorrow), 2 (Thursday) or 3 (deliver to post office) below.\n",
"age_gated": true,
"direct_lending": true,
"embedded_link": false,
"embedded_phone": false,
"partner": true,
"auto_renewal": true,
"hipaa": true,
"tcr_status": "UNKNOWN",
"vertical": "TECHNOLOGY",
"number_pool": false,
"registration_date": "2019-08-24T14:15:22Z",
"renewal_date": "2019-08-24",
"created_date": "2019-08-24T14:15:22Z",
"last_updated": "2019-08-24T14:15:22Z",
"billed_date": "2019-08-24T14:15:22Z",
"opt_out_assist": false,
"last_status_changes": [
{
"status": "APPROVED",
"reason": "Approved after internal review.",
"change_date": "2022-01-01 01:01:01"
}
],
"mno_metadata": [
{
"network_id": "10017",
"mno": "AT&T",
"status": "string",
"mno_support": true,
"mno_review": true,
"qualify": true,
"min_msg_samples": 2,
"req_subscriber_opt_in": true,
"req_subscriber_opt_out": true,
"req_subscriber_help": true,
"no_embedded_link": true,
"no_embedded_phone": true,
"att_msg_class": "Q",
"att_tpm": 3000,
"att_mms_tpm": 3000,
"att_number_based": true,
"tmo_brand_tier": "LOW",
"tmo_tpd": 0,
"complaints": [
{
"complaints": [
{
"description": "string",
"dca": "SINCH",
"created_at": "2019-08-24T14:15:22Z"
}
]
}
]
}
],
"carrier_brand_suspensions": [
[
{}
]
],
"_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"
}
}
}Stop a specific campaign on a brand
Deprecated
Cancels the campaign auto-renewal. The cancellation of renewal cannot be reverted.
The actual deletion will happen after campaign's expiration date.
NB: Will soon be deprecated. Use the Campaign PATCH with the auto_renewal property set to false to achieve a similar outcome.
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Example Request
{
"mno_ids": [
"10017"
]
}{
"mno_ids": [
"10017"
]
}50VC987XYZVonage Campaign ID.
50BLQKOPKTCR Brand ID.
10017Network ID of the MNO.
AT&TName of the MNO.
MNO campaign operation status. Please refer to the campaign_op_status property of the /enum endpoint response for an updated list of valid values.
If 'false', then the desired usecase cannot be supported by the MNO.
If 'true', then the submitted campaign is subject to the MNO (manual) review process.
If 'false', then the brand does not qualify for the desired usecase on the MNO.
2The minimum number of message samples required by MNO for submission of the desired usecase.
If 'true' then MNO requires the subscriber to opt-into the campaign before the message may be sent to the subscriber. The opt-in mechanism can be mobile or web opt-in.
If 'true' then MNO requires a campaign to support an opt-out mechanism through MO stop keywords such as 'STOP', 'QUIT'. Upon receive the STOP message from a subscriber, the campaign must stop sending messages to the subscriber immediately.
If 'true' then MNO requires a campaign to support a 'help' mechanism through MO help key words such as 'HELP', 'INFO'.
If 'true' then MNO forbids call-to-action link/URL to be embedded in all messages sent to the subscriber.
If 'true' then MNO forbids call-to-action phone number to be embedded in all messages sent to the subscriber.
Q(Only for AT&T). Message class assigned to the campaign by MNO. Please refer to the AT&T 10DLC guide for a complete list of available message class and definition.
3000(Only for AT&T). SMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
3000(Only for AT&T). MMS Message TPM (throughput per minute) qualified by the brand for the desired usecase.
(Only for AT&T). Whether is the MNO applying the TPM per number or per campaign.
LOW(Only for T-Mobile). Daily message volume is restricted based on brand tier or brand qualification. The daily volume restriction applies to brand across campaigns and CSPs. Please refer to the /enum endpoint for an updated list of valid values.
LOWLOWER_MIDUPPER_MIDTOPUNCAPPED(Only for TMobile). Message TPD (throughput per day) qualified by the brand for the desired usecase.
65535Description of this MNO complaint.
SINCHdca name
Date-time when this record was created.
https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234https://api.nexmo.com/v1/10dlc/brands/BLQKOPKExample Response
{
"campaign_id": "VC987XYZ",
"brand_id": "BLQKOPK",
"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
}
],
"_links": {
"self": {
"href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/vetting/requests/abcd1234"
},
"brand": {
"href": "https://api.nexmo.com/v1/10dlc/brands/BLQKOPK"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
abcd1234The Vonage Account ID
50C123ABCTCR Campaign ID.
50This is a sample campaignFriendly name associated with this campaign.
Indicates if the campaign is part of the CNP migration. It must be set to true, if a CNP migration has been initiated.
Example Request
{
"account_id": "abcd1234",
"campaign_id": "C123ABC",
"label": "This is a sample campaign",
"cnp_migration": true
}{
"account_id": "abcd1234",
"campaign_id": "C123ABC",
"label": "This is a sample campaign",
"cnp_migration": true
}50BLQKOPKTCR Brand ID.
50VC987XYZVonage Campaign ID.
50Sharing Status. Please refer to the /enum endpoint for an update list of valid values.
PENDINGACCEPTEDDECLINED50CNP ID. Please refer to the /enum endpoint for an update list of valid values.
50CNP ID. Please refer to the /enum endpoint for an update list of valid values.
Example Response
{
"brand_id": "BLQKOPK",
"campaign_id": "VC987XYZ",
"sharing_status": "PENDING",
"downstream_cnp_id": "string",
"upstream_cnp_id": "string"
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
50VC987XYZVonage Campaign ID.
50Sharing Status. Please refer to the /enum endpoint for an update list of valid values.
PENDINGACCEPTEDDECLINED50CNP ID. Please refer to the /enum endpoint for an update list of valid values.
50CNP ID. Please refer to the /enum endpoint for an update list of valid values.
Example Response
{
"campaign_id": "VC987XYZ",
"sharing_status": "PENDING",
"downstream_cnp_id": "string",
"upstream_cnp_id": "string"
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
1512page_token to access the next page.
1512page_token to access the previous page.
1512page_token to access the last page.
1512page_token to access the first page.
Link to the next page.
Link to the previous page.
Link to the first page.
Link to the last page.
91cd871e-ce9e-4f4d-a792-23277cbc287dThroughput ID.
50BLQKOPKTCR Brand ID.
50VC987XYZVonage Campaign ID.
List of carriers to which the throughput applies.
1000Shared throughput value for both SMS and MMS.
The period for which the throughput applies.
minutedayThe scope of the throughput.
campaignbrandnumberExample Response
{
"next_page": "string",
"previous_page": "string",
"last_page": "string",
"first_page": "string",
"_links": {
"next": {
"href": "string"
},
"previous": {
"href": "string"
},
"first": {
"href": "string"
},
"last": {
"href": "string"
}
},
"_embedded": {
"throughputs": [
{
"id": "91cd871e-ce9e-4f4d-a792-23277cbc287d",
"brand_id": "BLQKOPK",
"campaign_id": "VC987XYZ",
"carriers": [
"AT&T",
"ClearSky"
],
"value": {
"shared": 1000
},
"period": "minute",
"scope": "campaign"
}
]
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Query Parameters
Narrow down results based on matching conditions. Follow the comprehensive guide to learn how to craft filter queries.
12Page of results to jump to
10Number of results per page
10Items per page
12Page Offset
1100Number of pages in the entire result set
100Number of items in the entire result set
71514155550110Telephone Number
USThe two character country code in ISO 3166-1 alpha-2 format
LINKINGCurrent status of a number in a campaign. Only LINKED allows traffic.
LINKINGLINKEDREJECTEDUNLINKINGUNLINKEDList of compliance flags.
https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbers/14155550110https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/https://api.nexmo.com/v1/10dlc/brands/BLQKOPKExample Response
{
"page_size": 10,
"page": 2,
"total_pages": 100,
"total_items": 100,
"_embedded": {
"numbers": [
{
"number": "14155550110",
"country": "US",
"status": "LINKING",
"compliance": [
"HIPPA"
],
"_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"
}
}
}
]
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Query Parameters
Narrow down results based on matching conditions. Follow the comprehensive guide to learn how to craft filter queries.
USThe two character country code in ISO 3166-1 alpha-2 format
71514155550110Telephone Number
Example Request
{
"country": "US",
"number": "14155550110"
}{
"country": "US",
"number": "14155550110"
}71514155550110Telephone Number
USThe two character country code in ISO 3166-1 alpha-2 format
LINKINGCurrent status of a number in a campaign. Only LINKED allows traffic.
LINKINGLINKEDREJECTEDUNLINKINGUNLINKEDList of compliance flags.
https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbers/14155550110https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/https://api.nexmo.com/v1/10dlc/brands/BLQKOPKExample Response
{
"number": "14155550110",
"country": "US",
"status": "LINKING",
"compliance": [
"HIPPA"
],
"_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"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
71514155550110Telephone Number
USThe two character country code in ISO 3166-1 alpha-2 format
LINKINGCurrent status of a number in a campaign. Only LINKED allows traffic.
LINKINGLINKEDREJECTEDUNLINKINGUNLINKEDList of compliance flags.
https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/numbers/14155550110https://api.nexmo.com/v1/10dlc/brands/BLQKOPK/campaigns/C1DEB879/https://api.nexmo.com/v1/10dlc/brands/BLQKOPKExample Response
{
"number": "14155550110",
"country": "US",
"status": "LINKING",
"compliance": [
"HIPPA"
],
"_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"
}
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
Available Operations
Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
100MicrosoftCompany name of the reseller.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
100john.doe@microsoft.comValid email address of reseller contact.
Example Request
{
"company_name": "Microsoft",
"phone": "123123222334",
"email": "john.doe@microsoft.com"
}{
"company_name": "Microsoft",
"phone": "123123222334",
"email": "john.doe@microsoft.com"
}5782db87-a867-4ccd-a0b5-1b7203cc438cUnique identifier assigned to the reseller.
Unique identifier assigned to the reseller by the registry. This field is only present if the reseller is APPROVED.
100MicrosoftCompany name of the reseller.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
100john.doe@microsoft.comValid email address of reseller contact.
APPROVEDApproval status of the reseller. Upon submitting a creation of a reseller, the status is set to PENDING. After review of your request, the status of the reseller will be set to either APPROVED or REJECTED. If the status is REJECTED, you should have the detailed reason of the rejection in the rejection_reason field.
PENDINGAPPROVEDREJECTEDYou are not allowed to register a reseller with this company name.The reason why the reseller was rejected. This field is only populated when the status is REJECTED.
Example Response
{
"id": "5782db87-a867-4ccd-a0b5-1b7203cc438c",
"tcr_reseller_id": "string",
"company_name": "Microsoft",
"phone": "123123222334",
"email": "john.doe@microsoft.com",
"status": "APPROVED",
"rejection_reason": "You are not allowed to register a reseller with this company name."
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
1512page_token to access the next page.
1512page_token to access the previous page.
1512page_token to access the last page.
1512page_token to access the first page.
Link to the next page.
Link to the previous page.
Link to the first page.
Link to the last page.
5782db87-a867-4ccd-a0b5-1b7203cc438cUnique identifier assigned to the reseller.
Unique identifier assigned to the reseller by the registry. This field is only present if the reseller is APPROVED.
100MicrosoftCompany name of the reseller.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
100john.doe@microsoft.comValid email address of reseller contact.
APPROVEDApproval status of the reseller. Upon submitting a creation of a reseller, the status is set to PENDING. After review of your request, the status of the reseller will be set to either APPROVED or REJECTED. If the status is REJECTED, you should have the detailed reason of the rejection in the rejection_reason field.
PENDINGAPPROVEDREJECTEDYou are not allowed to register a reseller with this company name.The reason why the reseller was rejected. This field is only populated when the status is REJECTED.
Example Response
{
"next_page": "string",
"previous_page": "string",
"last_page": "string",
"first_page": "string",
"_links": {
"next": {
"href": "string"
},
"previous": {
"href": "string"
},
"first": {
"href": "string"
},
"last": {
"href": "string"
}
},
"_embedded": {
"resellers": [
{
"id": "5782db87-a867-4ccd-a0b5-1b7203cc438c",
"tcr_reseller_id": "string",
"company_name": "Microsoft",
"phone": "123123222334",
"email": "john.doe@microsoft.com",
"status": "APPROVED",
"rejection_reason": "You are not allowed to register a reseller with this company name."
}
]
}
}Authentication
| Key | Description | Where | Example |
|---|---|---|---|
| Authorization | Base64 encoded API key and secret joined by a colon. | Headers | Basic <base64> |
5782db87-a867-4ccd-a0b5-1b7203cc438cUnique identifier assigned to the reseller.
Unique identifier assigned to the reseller by the registry. This field is only present if the reseller is APPROVED.
100MicrosoftCompany name of the reseller.
123123222334Valid mobile phone number in E.164 international format without the + prefix. It is required field for SoleProprietor brand.
100john.doe@microsoft.comValid email address of reseller contact.
APPROVEDApproval status of the reseller. Upon submitting a creation of a reseller, the status is set to PENDING. After review of your request, the status of the reseller will be set to either APPROVED or REJECTED. If the status is REJECTED, you should have the detailed reason of the rejection in the rejection_reason field.
PENDINGAPPROVEDREJECTEDYou are not allowed to register a reseller with this company name.The reason why the reseller was rejected. This field is only populated when the status is REJECTED.
Example Response
{
"id": "5782db87-a867-4ccd-a0b5-1b7203cc438c",
"tcr_reseller_id": "string",
"company_name": "Microsoft",
"phone": "123123222334",
"email": "john.doe@microsoft.com",
"status": "APPROVED",
"rejection_reason": "You are not allowed to register a reseller with this company name."
}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 | Information |
|---|---|
| brand-conflict | Description A conflict when a brand is being created or edited and there is an issue with a 3rd party vendor. Resolution Ensure all required fields have values and there are no errors in those values. If the error persists, contact support. |
| brand-parameters | Description There are errors in the brand data submitted. Resolution Ensure all required fields have values included and correct any errors to values in the specified fields. |
| invalid-usecase-data | Description There are errors in the data submitted for use case qualification. Resolution Ensure all required fields have values included and correct any errors to values in the specified fields. |
| use-case-denied | Description The use case requested has been denied for this brand. Resolution Ensure your use case does not require additional brand vetting or pre/post Mobile Network Operator approval. |
| vetting-conflict | Description A conflict during the brand vetting request has occurred. Resolution If the error persists, contact support. |
| invalid-vetting-data | Description There are errors in the vetting request data submitted. Resolution Ensure all required fields have values and correct any errors to values in the specified fields. |
| invalid-json | Description Your request cannot be parsed. Resolution Ensure there are no invalid characters or values in your request. |
| brand-not-qualified | Description A conflict when a campaign is being created under a brand that hasn't qualified for the specified use case. Resolution Verify the brand use case qualifies before submitting the campaign. |
| invalid-campaign-data | Description There are errors in the campaign data submitted. Resolution Ensure all required fields have values and correct any errors to values in the specified fields. |
| numbers-already-linked | Description The number you are attempting to link is already linked to another campaign. Resolution You must link a unique number to a campaign. Link a different number to this campaign. |
| invalid-number-data | Description There are errors in the number data submitted. Resolution Ensure all required fields have values and correct any errors to values in the specified fields. |