> ## 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.

# Incoming Carriers API

> Route calls from your own carrier through Plivo

Use this API if you own phone numbers from a carrier and want to route incoming calls on those numbers through Plivo.

**API Endpoint**

```
https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/
```

***

## The IncomingCarrier Object

| Attribute | Type | Description |
| - | - | - |
| `carrier_id` | string | Unique identifier for the carrier |
| `name` | string | Name of the incoming carrier |
| `ip_set` | string | Comma-separated list of IP addresses |
| `voice` | boolean | Supports voice calls |
| `sms` | boolean | Supports SMS messages |
| `resource_uri` | string | URI to the carrier resource |

### Example Object

```json theme={null}
{
  "carrier_id": "19381640842535",
  "ip_set": "10.20.10.20,10.10.10.10,10.20.10.30",
  "name": "Custom carrier 1",
  "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/IncomingCarrier/19381640842535/",
  "sms": false,
  "voice": true
}
```

***

## Create an Incoming Carrier

Add a new incoming carrier to your account.

```
POST https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/
```

### Arguments

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Carrier name. Allowed: letters, numbers, hyphen, underscore |
| `ip_set` | string | Yes | Comma-separated IP addresses for incoming calls |

### Example

```bash theme={null}
curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My_Carrier",
    "ip_set": "10.20.10.20,10.10.10.10"
  }'
```

### Response

```json theme={null}
{
    "api_id": "65368fb6-5060-11e4-8a4a-123140008edf",
    "carrier_id": "13455781930894",
    "message": "created"
}
```

***

## List All Incoming Carriers

Returns all incoming carriers for your account.

```
GET https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/
```

### Query Parameters

| Parameter | Type | Description |
| - | - | - |
| `name` | string | Filter by carrier name |
| `limit` | integer | Results per page (max 20) |
| `offset` | integer | Pagination offset |

### Example

```bash theme={null}
curl "https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/" \
  -u '<auth_id>:<auth_token>'
```

### Response

```json theme={null}
{
  "meta": {
    "previous": null,
    "total_count": 1,
    "offset": 0,
    "limit": 20,
    "next": null
  },
  "api_id": "a90cbe28-58d7-11e1-86da-adf28403fe48",
  "objects": [
    {
      "carrier_id": "19381640842535",
      "ip_set": "10.20.10.20,10.10.10.10,10.20.10.30",
      "name": "Custom carrier 1",
      "resource_uri": "/v1/Account/MA2025RK4E639VJFZAGV/IncomingCarrier/19381640842535/",
      "sms": false,
      "voice": true
    }
  ]
}
```

***

## Retrieve an Incoming Carrier

Get details of a specific incoming carrier.

```
GET https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/{carrier_id}/
```

### Example

```bash theme={null}
curl "https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/19381640842535/" \
  -u '<auth_id>:<auth_token>'
```

***

## Update an Incoming Carrier

Modify an existing incoming carrier.

```
POST https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/{carrier_id}/
```

### Arguments

| Parameter | Type | Description |
| - | - | - |
| `name` | string | New carrier name |
| `ip_set` | string | New comma-separated IP addresses (replaces existing) |

### Example

```bash theme={null}
curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/19381640842535/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"ip_set": "10.30.10.30,10.40.10.40"}'
```

***

## Delete an Incoming Carrier

Remove an incoming carrier from your account.

```
DELETE https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/{carrier_id}/
```

### Example

```bash theme={null}
curl -X DELETE "https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/19381640842535/" \
  -u '<auth_id>:<auth_token>'
```

### Response

```
HTTP Status Code: 204
```

***

## Add Number from Your Carrier

After creating an incoming carrier, add phone numbers from that carrier to your Plivo account.

```
POST https://api.plivo.com/v1/Account/{auth_id}/Number/
```

### Arguments

| Parameter | Type | Required | Description |
| - | - | - | - |
| `numbers` | string | Yes | Comma-separated phone numbers to add |
| `carrier` | string | Yes | The `carrier_id` of your incoming carrier |
| `region` | string | Yes | Region name (e.g., "United States") |
| `number_type` | string | No | `local`, `national`, `mobile`, or `tollfree` |
| `app_id` | string | No | Application to assign to numbers |

### Example

```bash theme={null}
curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/Number/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": "14155551234,14155551235",
    "carrier": "19381640842535",
    "region": "United States"
  }'
```

***

## Related

* [Account Phone Numbers](https://plivo.com/docs/numbers/account-phone-numbers.md) - Manage your numbers
* [Phone Numbers](https://plivo.com/docs/numbers/phone-numbers.md) - Search and buy Plivo numbers