Quick access:

• Step 1 - Qualify your brand for a specific use-case
• Step 2 - Register your campaign

Please make sure you have read our 10DLC campaign registration guide before proceeding.

Campaign applications go through several reviews to confirm that the required information is provided. These reviews have increased the processing time, so we advise you to submit your campaign applications two (2) weeks in advance to avoid disruption.

You can find the complete 10DLC API description on this page.

Step 1 - Qualify your brand for a specific use-case

When using our APIs, you need to complete a preliminary step to registering the campaign itself. If registering a new campaign for a use-case that has never been used on your brand, you must first make sure that your brand is allowed to create a campaign for this specific use case.

This is done by calling the following endpoint:

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

If successful, you will get a 200 - OK response containing a payload that comprises of the use case qualified, as well as JSON objects for each MNO (Mobile Network Operator, or carrier) throughputs you can expect:

{
  "usecase": "POLITICAL",
  "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,
      "att_mms_tpm": 2000,
      "mno_support": true,
      "mno_review": true,
      "no_embedded_link": true,
      "qualify": true,
      "tmo_brand_tier": null
    },
  ]
}

Step 2 - Register your campaign

Before proceeding, make sure you understand the 10DLC requirements and that all the information provided on your campaign application complies with those requirements.

POST 'https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns'
{
  "account_id" = "abcdef01",           // required
  "usecase" = "string",                // required
  "sub_usecases" = ["string"],
  "label" = "string",
  "description" = "string",            // required - min 40 characters
  "reseller_id" = "string",            // required if application on behalf of customer
  "message_flow" = "string",           // deprecating on January 4th 2024
  "message_flow_details" = {           // required - Replacing the older "message_flow" attribute
     "brand_name" = "string",                  // required, max 75 characters
     "consent_mechanism" = [{                  // requires between 1 and 5 items
       "method" = "string",                    // see Enum for available options
       "details" = "string"                    // max 255 characters
       }],
     "pricing_disclosure" = boolean,           // required true
     "frequency" = ["ONE_TIME", "RECURRING"],  // requires one of the options
     "privacy_policy" = "string.url",          // required
     "terms_and_conditions" = "string.url"     // required
     }
  "subscriber_opt_in" = boolean,       // required
  "opt_in_keywords" = "string",        // required if Text to Join opt-in available
  "opt_in_message" = "string",         // required if Text to Join opt-in available
  "subscriber_opt_out" = boolean,      // required
  "opt_out_keywords" = "string",       // default is "STOP"
  "opt_out_message" = "string",        // required
  "subscriber_help" = boolean,         // required
  "help_keywords" = "string",          // default is "HELP"
  "help_message" = "string",           // required
  "sample_one" = "string",             // required
  "sample_two" = "string",
  "sample_three" = "string",
  "sample_four" = "string",
  "sample_five" = "string",
  "number_pool" = boolean,
  "embedded_link" = boolean,
  "embedded_phone" = boolean,
  "age_gated" = boolean,
  "direct_lending" = boolean,
  "tc_agreed" = boolean.               // required
}

Note that we are deprecating the current attribute named "message_flow" on January 4th 2024. Please update your implementation to provide instead the new "message_flow_details" object.

Example of campaign application:

POST 'https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns'
{
  "account_id" = "abcdef01",
  "usecase" = "Low Volume Mixed",
  "sub_usecases" = ["Customer Care", "Account Notification"],
  "label" = "Geri's Limo app - ride notifications",
  "description" = "This campaign aims to provide schedules of Limousine meet ups",
  "message_flow_details" = {
     "brand_name" = "Geri's Limo",
     "consent_mechanism" = [{
       "method" = "POINT_OF_SALE",
       "details" = "Flyers promote the brand in coffee shops in the city."
       }],
     "pricing_disclosure" = true,
     "frequency" = "RECURRING",
     "privacy_policy" = "https://example.com/privacy.html",
     "terms_and_conditions" = "https://example.com/terms.html"
     }
  "subscriber_opt_in" = true,
  "subscriber_opt_out" = true,
  "opt_out_message" = "Geri’s Limo: You have successfully unsubscribed & will no longer receive any additional messages." [optional: "Text HELP for assistance or JOIN to rejoin.",
  "subscriber_help" = true,
  "help_message" = "Geri’s Limo: For support, please visit www.website.com, or contact us at care@email.com, or call 1-XXX-XXX-XXXX.",
  "sample_one" = "Geri's Limo: Your driver has arrived!",
  "number_pool" = true,
  "tc_agreed" = true.
}

When the request has been processed, you will receive a 200 - OK response with the payload containing the campaign ID, the attributes provided when creating the campaign as well as the campaign status.

From our example above, the response payload would look like:

{
  "account_id": "abcdef01",
  "brand_id": "string",
  "campaign_id": "VC987XYZ",
  "tcr_campaign_id": "C123ABC",
  "usecase": "Low Volume Mixed",
  "sub_usecases": [
    "Customer Care", 
    "Account Notification"
  ],
  "label": "Geri's Limo app - ride notifications",
  "description": "This campaign aims to provide schedules of Limousine meet ups",
  "message_flow": "Geri's Limo, Consent mechanism: - Point of Sale: Flyers promote the brand in coffee shops in the city. Msg & data rates may apply - Msg freq. varies T&C: https://example.com/terms.html PP: https://example.com/privacy.html", 
  "age_gated": false,
  "direct_lending": false,
  "subscriber_opt_in": true,
  "subscriber_opt_out": true,
  "opt_out_keywords": "STOP",
  "opt_out_message": "Geri’s Limo: You have successfully unsubscribed & will no longer receive any additional messages.",
  "subscriber_help": true,
  "help_keywords": "HELP",
  "help_message": "Geri’s Limo: For support, please visit www.website.com, or contact us at care@email.com, or call 1-XXX-XXX-XXXX.",
  "sample_one": "Geri's Limo: Your driver has arrived!",
  "number_pool": true,
  "embedded_link": false,
  "embedded_phone": false,
  "auto_renewal": true,
  "partner": false,
  "mno_metadata": [],
  "status": "PENDING_REVIEW",
  "tcr_status": "UNKNOWN",
  "created_date": "2023-03-14T13:12:37.183Z",
  "last_updated": "2023-03-14T13:12:37.183Z",
  "billed_date": "2023-03-14T13:12:37.183Z",
  "last_status_changes": [],
  "_links": {
    "self": {
      "href": "string"
    },
    "brand": {
      "href": "string"
    },
    "numbers": {
     "href": "string"
    }
  }
}

You have now completed the registration of your 10DLC campaign.

Back to 10DLC campaign registration guide

Back to Guide of guides