> ## 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](/numbers/account-phone-numbers) - Manage your numbers
* [Phone Numbers](/numbers/phone-numbers) - Search and buy Plivo numbers