Quick access:

• Link a number to a campaign
• Retrieve the numbers linked to a campaign
• Unlink a number to a campaign

This article is a step by step guide to linking and unlinking numbers to a 10DLC campaign.

Please make sure that you have followed all the previous steps of registering your 10DLC brand, registering your 10DLC campaign linked to our Guide of guides. Please also consult our 10DLC API description for more details on the endpoints.

Note also the different requirements of throughputs for 10DLC campaigns and numbers, as well as the requirements of using Vonage account number pools with 10DLC numbers (different from 10DLC campaigns number pool feature).

Link a number to a campaign

POST https://api-eu.vonage.com/v1/10dlc/brands/:brand_id/campaigns/:campaign_id/numbers
{
  "country": "US",
  "number": "14155550110",
  "compliance": [ "HIPAA" ] // only possible if the api_key is enabled for HIPAA
}

A success full response would typically be

{
  "number": "14155550110",
  "country": "US",
  "status": "PENDING",
  "compliance": [ "HIPAA" ],
  "_links": {
    "self": {
       "href": "https://api.nexmo.com/v1/10dlc/brands/[brand_id]/campaigns/[campaign_id]/numbers/14155550110"
    },
    "brand": {
       "href": "https://api.nexmo.com/v1/10dlc/brands/[brand_id]"
    },
   "campaign": {
       "href": "https://api.nexmo.com/v1/10dlc/brands/[brand_id]/campaigns/[campaign_id]"
  }
}

Typically, number linking requests will take from a few minutes to a few hours to be processed. This is due to a limitation from T-Mobile that only allows them to link one number per second across the entire US messaging industry. A request pending for more than 36 hours may time out. 

Retrieve the numbers linked to a campaign

Retrieve all the numbers linked to a campaign

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

You will get the following response:

{
  "page_size": 10,
  "page": 1,
  "total_pages": 1,
  "total_items": 1,
  "_embedded": {
    "numbers": [
    {
      "country": "US",
      "number": "14155550110",
      "status": "APPROVED",
      "compliance": [],
      "_links": {
        "self": {
           "href": "https://api.nexmo.com/v1/10dlc/brands/[brand_id]/campaigns/[campaign_id]/numbers/14155550110"
         },
         "brand": {
           "href": "https://api.nexmo.com/v1/10dlc/brands/[brand_id]"
         },
        "campaign": {
          "href": "https://api.nexmo.com/v1/10dlc/brands/[brand_id]/campaigns/[campaign_id]"
        }
      }
    }]
  },
  "_links": {
    "first": {
      "href": "https://api-eu.vonage.com/v1/10dlc/brands/[brand_id]/campaigns/[campaign_id]/numbers?page=1&page_size=10"
    },
    "last": {
      "href": "https://api-eu.vonage.com/v1/10dlc/brands/[brand_id]/campaigns/[campaign_id]/numbers?page=1&page_size=10"
    },
    "self": {
      "href": "https://api-eu.vonage.com/v1/10dlc/brands/[brand_id]/campaigns/[campaign_id]/numbers?page=1&page_size=10"
    }
  }
}

Retrieve information of a specific number linked to a campaign

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

{
  "country": "US",
  "number": "14155550110",
  "status": "APPROVED",
  "compliance": [],
  "_links": {
    "self": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/[brand_id]/campaigns/[campaign_id]/numbers/14155550110"
    },
    "brand": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/[brand_id]"
    },
    "campaign": {
      "href": "https://api.nexmo.com/v1/10dlc/brands/[brand_id]/campaigns/[campaign_id]"
    }
  }
}

Filtering feature

We offer the option to filter the results of GET requests on our 10DLC API endpoints.

For example, this allows you to make a GET request to list all the campaigns registered under your 10DLC brand, and filter through the campaigns which satisfy certain conditions such as the campaign use case, campaign status, or even the campaign registration date.

We limit each API call to a maximum combination of 3 filters.

If you would like to review the detailed information on how to use this feature, please check this page.

Unlink a number to a campaign

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

When successful, the request response will be a 200 - OK

Back to Guide of guides