Incoming Carriers API

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

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

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"
  }'

Account Phone Numbers - Manage your numbers
Phone Numbers - Search and buy Plivo numbers

Getting Started

Concepts

API Reference

XML Reference

SDKs

Troubleshooting

Voice Tutorials

Migration Guides

Incoming Carriers API

The IncomingCarrier Object

Example Object

Create an Incoming Carrier

Arguments

Example

Response

List All Incoming Carriers

Query Parameters

Example

Response

Retrieve an Incoming Carrier

Example

Update an Incoming Carrier

Arguments

Example

Delete an Incoming Carrier

Example

Response

Add Number from Your Carrier

Arguments

Example

​The IncomingCarrier Object

​Example Object

​Create an Incoming Carrier

​Arguments

​Example

​Response

​List All Incoming Carriers

​Query Parameters

​Example

​Response

​Retrieve an Incoming Carrier

​Example

​Update an Incoming Carrier

​Arguments

​Example

​Delete an Incoming Carrier

​Example

​Response

​Add Number from Your Carrier

​Arguments

​Example

​Related

The IncomingCarrier Object

Example Object

Create an Incoming Carrier

Arguments

Example

Response

List All Incoming Carriers

Query Parameters

Example

Response

Retrieve an Incoming Carrier

Example

Update an Incoming Carrier

Arguments

Example

Delete an Incoming Carrier

Example

Response

Add Number from Your Carrier

Arguments

Example

Related