Number Linking

Use the Number Linking API to associate phone numbers with your 10DLC campaigns. You must link a number to a campaign before using it to send messages. This API allows you to link numbers, retrieve linked numbers, check linking status, and unlink numbers from campaigns.

API Endpoint

BaseURI

https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/

The Number Object

Attributes

campaign_id

string

Unique identifier for a campaign.

campaign_alias

string

Friendly name for the campaign.

usecase

string

Use case of the campaign.

phone_numbers

array

Array containing status of each number linked to the campaign. Each entry includes number and status fields.

Example Object

{
  "campaign_alias": "ABC Campaign",
  "campaign_id": "CUOGHIN",
  "phone_numbers": [
    {
      "number": "12125557778",
      "status": "PROCESSING"
    }
  ],
  "usecase": "STARTER"
}

Link Number to Campaign

Link one or more phone numbers to an existing campaign.

POST https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/

Arguments

numbers

array

required

The numbers you want to link to a campaign. Numbers should be in E.164 format.

url

string

Fully qualified URL to which status update callbacks for the linking request should be sent.

method

string

The HTTP method to be used when calling the URL defined above. Allowed values: GET, POST. Defaults to POST.

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.campaign.number_link(
    campaign_id="<campaign_id>",
    url="https://example.com/callback",
    method="POST",
    numbers=["<phone_number>"],
)
print(response)

let plivo = require('plivo');

let client = new plivo.Client('<auth_id>', '<auth_token>');
var callback = {"url": "https://example.com/callback", "method": "POST"};

client.campaign.linkNumber("<campaign_id>", ["<number>"], callback)
    .then(function (response) {
        console.log(JSON.stringify(response));
    }).catch(function (error) {
        console.log(error);
    });

curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{
        "numbers": ["12025551111"],
        "url": "https://example.com/callback",
        "method": "POST"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/

Response

{
  "api_id": "0b2e010e-b4a1-11ec-a9f5-0242ac110003",
  "message": "Request to link 14156667778 to campaign CUOGHIN was received and is being processed"
}

Retrieve All Numbers Linked to a Campaign

Fetch all numbers linked to a particular campaign.

GET https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/

No arguments need to be passed.

The status field in the phone_numbers array can have the following values:

FAILED - The linking request failed
PROCESSING - The linking request is being processed
COMPLETED - The number has been successfully linked

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.campaign.list_number(campaign_id="<campaign_id>")
print(response)

let plivo = require('plivo');

let client = new plivo.Client('<auth_id>', '<auth_token>');

client.campaign.listNumber("<campaign_id>")
    .then(function (response) {
        console.log(JSON.stringify(response));
    }).catch(function (error) {
        console.log(error);
    });

curl -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/

Response

{
  "api_id": "8010803c-b4a1-11ec-8f25-0242ac110002",
  "campaign_alias": "ABC Campaign",
  "campaign_id": "CUOGHIN",
  "phone_numbers": [
    {
      "number": "12125557777",
      "status": "PROCESSING"
    },
    {
      "number": "12125557778",
      "status": "PROCESSING"
    },
    {
      "number": "12125557779",
      "status": "FAILED"
    }
  ],
  "usecase": "STARTER"
}

Retrieve Number Status

Fetch the status of a specific number linked to a campaign.

GET https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/{number}/

No arguments need to be passed.

The status field can have the values FAILED, PROCESSING, or COMPLETED.

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.campaign.get_number(
    campaign_id="<campaign_id>",
    number="<phone_number>"
)
print(response)

let plivo = require('plivo');

let client = new plivo.Client('<auth_id>', '<auth_token>');

client.campaign.getNumber("<campaign_id>", "<number>")
    .then(function (response) {
        console.log(JSON.stringify(response));
    }).catch(function (error) {
        console.log(error);
    });

curl -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/12025551111/

Response

{
  "api_id": "56df0724-b4a1-11ec-a357-0242ac110002",
  "campaign_alias": "ABC Campaign",
  "campaign_id": "CUOGHIN",
  "phone_numbers": [
    {
      "number": "12125557777",
      "status": "PROCESSING"
    }
  ],
  "usecase": "STARTER"
}

Unlink Number from Campaign

Unlink a phone number from a campaign.

DELETE https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/{number}/

Arguments

url

string

Fully qualified URL to which status update callbacks for the unlinking request should be sent.

method

string

The HTTP method to be used when calling the URL defined above. Allowed values: GET, POST. Defaults to POST.

import plivo

client = plivo.RestClient("<auth_id>", "<auth_token>")
response = client.campaign.number_unlink(
    campaign_id="<campaign_id>",
    number="<phone_number>",
    url="https://example.com/callback",
    method="POST",
)
print(response)

let plivo = require('plivo');

let client = new plivo.Client('<auth_id>', '<auth_token>');
var callback = {"url": "https://example.com/callback", "method": "POST"};

client.campaign.unlinkNumber("<campaign_id>", "<number>", callback)
    .then(function (response) {
        console.log(JSON.stringify(response));
    }).catch(function (error) {
        console.log(error);
    });

curl -X DELETE -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{
        "url": "https://example.com/callback",
        "method": "POST"
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/12025551111/

Response

{
  "api_id": "eba3f9aa-b4a1-11ec-85a1-0242ac110003",
  "message": "Request to unlink 12125557777 from campaign CUOGHIN was received and is being processed"
}

Getting Started

Concepts

API Reference

XML Reference

Tutorials

Migration Guides

Troubleshooting

Number Linking

API Endpoint

The Number Object

Attributes

Example Object

Link Number to Campaign

Arguments

Response

Retrieve All Numbers Linked to a Campaign

Response

Retrieve Number Status

Response

Unlink Number from Campaign

Arguments

Response

​API Endpoint

​The Number Object

​Attributes

​Example Object

​Link Number to Campaign

​Arguments

​Response

​Retrieve All Numbers Linked to a Campaign

​Response

​Retrieve Number Status

​Response

​Unlink Number from Campaign

​Arguments

​Response

API Endpoint

The Number Object

Attributes

Example Object

Link Number to Campaign

Arguments

Response

Retrieve All Numbers Linked to a Campaign

Response

Retrieve Number Status

Response

Unlink Number from Campaign

Arguments

Response