> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Number Linking

> Link and unlink phone numbers from 10DLC campaigns

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

```text BaseURI theme={null}
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

```json theme={null}
{
  "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](https://en.wikipedia.org/wiki/E.164).

**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`.

```python Python theme={null}
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)
```

```javascript Node.js theme={null}
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);
    });
```

```bash cURL theme={null}
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

```json theme={null}
{
  "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/
```

> [!NOTE]
>
> 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

```python Python theme={null}
import plivo

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

```javascript Node.js theme={null}
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);
    });
```

```bash cURL theme={null}
curl -i --user auth_id:auth_token \
    https://api.plivo.com/v1/Account/{auth_id}/10dlc/Campaign/{campaign_id}/Number/
```

### Response

```json theme={null}
{
  "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}/
```

> [!NOTE]
>
> No arguments need to be passed.

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

```python Python theme={null}
import plivo

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

```javascript Node.js theme={null}
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);
    });
```

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

### Response

```json theme={null}
{
  "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`.

```python Python theme={null}
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)
```

```javascript Node.js theme={null}
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);
    });
```

```bash cURL theme={null}
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

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