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.
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
{
"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
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
{
"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
curl "https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/" \
-u "{auth_id}:{auth_token}"
Response
{
"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
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
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
curl -X DELETE "https://api.plivo.com/v1/Account/{auth_id}/IncomingCarrier/19381640842535/" \
-u "{auth_id}:{auth_token}"
Response
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
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"
}'
