Skip to main content
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

AttributeTypeDescription
carrier_idstringUnique identifier for the carrier
namestringName of the incoming carrier
ip_setstringComma-separated list of IP addresses
voicebooleanSupports voice calls
smsbooleanSupports SMS messages
resource_uristringURI 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

ParameterTypeRequiredDescription
namestringYesCarrier name. Allowed: letters, numbers, hyphen, underscore
ip_setstringYesComma-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

ParameterTypeDescription
namestringFilter by carrier name
limitintegerResults per page (max 20)
offsetintegerPagination 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

ParameterTypeDescription
namestringNew carrier name
ip_setstringNew 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

ParameterTypeRequiredDescription
numbersstringYesComma-separated phone numbers to add
carrierstringYesThe carrier_id of your incoming carrier
regionstringYesRegion name (e.g., “United States”)
number_typestringNolocal, national, mobile, or tollfree
app_idstringNoApplication 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"
  }'