The Origination URIs API lets you create and manage destination endpoints (your PBX/infrastructure) where Plivo sends inbound calls.
API Endpoint
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/
The Origination URI Object
| Attribute | Type | Description |
|---|
uri_uuid | string | Unique identifier for the origination URI |
name | string | Friendly name for the origination URI |
uri | string | FQDN or IP address of your VoIP infrastructure |
authentication_needed | boolean | Whether Plivo should authenticate when sending calls |
username | string | Username for authentication (if enabled) |
password | string | Password for authentication (only set on create/update) |
Example Response
{
"uri_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
"name": "primary-pbx",
"uri": "sip.example.com",
"authentication_needed": true,
"username": "plivo_inbound"
}
Create an Origination URI
Create a new destination endpoint for inbound calls.
POST https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/
Parameters
| Parameter | Type | Required | Description |
|---|
name | string | No | Friendly name for the URI |
uri | string | Yes | FQDN or IP address of your VoIP infrastructure |
authentication_needed | boolean | No | Require authentication. Default: false |
username | string | Conditional | Username for auth. Required if authentication_needed=true |
password | string | Conditional | Password for auth. Required if authentication_needed=true |
Without Authentication
curl -i --user AUTH_ID:AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"name": "primary-pbx",
"uri": "sip.example.com:5060"
}' \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/
With Authentication
curl -i --user AUTH_ID:AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"name": "secure-pbx",
"uri": "sip.example.com:5060",
"authentication_needed": true,
"username": "plivo_inbound",
"password": "securepassword123!"
}' \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/
Response
{
"api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
"message": "Origination URI created successfully.",
"uri_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}
Retrieve an Origination URI
Get details of a specific origination URI.
GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/{uri_uuid}/
curl -i --user AUTH_ID:AUTH_TOKEN \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/f19c4773-4ae6-4b75-92ea-9cf3ea4227d6/
Response
{
"uri_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
"name": "primary-pbx",
"uri": "sip.example.com:5060",
"authentication_needed": true,
"username": "plivo_inbound"
}
List All Origination URIs
Get all origination URIs for your account.
GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/
Query Parameters
| Parameter | Type | Description |
|---|
limit | integer | Results per page (1-20). Default: 20 |
offset | integer | Pagination offset. Default: 0 |
curl -i --user AUTH_ID:AUTH_TOKEN \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/
Response
{
"api_id": "a04ad809-3b78-4bbe-9baf-acfc7800b10f",
"meta": {
"limit": 20,
"offset": 0,
"total_count": 109,
"previous": null,
"next": "v1/Account/{auth_id}/Zentrunk/URI/?limit=20&offset=20"
},
"objects": [
{
"uri_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
"name": "primary-pbx",
"uri": "sip.example.com",
"authentication_needed": true,
"username": "plivo_inbound"
},
{
"uri_uuid": "aec4773-4ae6-4b75-92ea-9cf3ea4227d6",
"name": "backup-pbx",
"uri": "sip-backup.example.com",
"authentication_needed": false,
"username": null
}
]
}
Update an Origination URI
Modify an existing origination URI’s properties.
POST https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/{uri_uuid}/
Parameters
| Parameter | Type | Description |
|---|
name | string | New friendly name |
uri | string | New FQDN or IP address |
authentication_needed | boolean | Enable/disable authentication |
username | string | New username (if auth enabled) |
password | string | New password (if auth enabled) |
curl -i --user AUTH_ID:AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"uri": "new-sip.example.com:5060",
"authentication_needed": true,
"username": "new_user",
"password": "new_password123!"
}' \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/f19c4773-4ae6-4b75-92ea-9cf3ea4227d6/
Response
{
"api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
"message": "origination uri updated successfully.",
"uri_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}
Delete an Origination URI
Permanently delete an origination URI.
DELETE https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/{uri_uuid}/
curl -X DELETE -i --user AUTH_ID:AUTH_TOKEN \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/f19c4773-4ae6-4b75-92ea-9cf3ea4227d6/
Deleting an origination URI that is attached to an active trunk as primary or fallback will cause inbound calls to fail.
Usage with Inbound Trunks
After creating origination URIs, attach them to an inbound trunk:
curl -i --user AUTH_ID:AUTH_TOKEN \
-H "Content-Type: application/json" \
-d '{
"name": "inbound-trunk",
"trunk_direction": "inbound",
"primary_uri_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
"fallback_uri_uuid": "aec4773-4ae6-4b75-92ea-9cf3ea4227d6"
}' \
https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/
Primary vs Fallback URIs
| Type | Purpose |
|---|
| Primary URI | Default destination for inbound calls |
| Fallback URI | Used when primary is unreachable or returns error |
- Create two origination URIs pointing to different servers
- Assign one as
primary_uri_uuid and the other as fallback_uri_uuid
- If primary fails, Plivo automatically routes to fallback
| Format | Example |
|---|
| IP address | 192.168.1.100 |
| IP with port | 192.168.1.100:5060 |
| FQDN | sip.example.com |
| FQDN with port | sip.example.com:5060 |
| SIP URI | sip:[email protected] |
- Trunks - Create and manage SIP trunks
- Calls - View SIP trunk call records
