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

An origination URI represents a destination endpoint where Plivo forwards inbound calls on your SIP trunk.

​
Attributes

​
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, never returned in responses).

​
Example Object

{
  "uri_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
  "name": "primary-pbx",
  "uri": "sip.example.com",
  "authentication_needed": true,
  "username": "plivo_inbound"
}

​
List All Origination URIs

Get all origination URIs for your account.

​
HTTP Request

GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/

​
Query Parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo20Results per page (1-20)
offsetintegerNo0Pagination offset

​
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
    }
  ]
}

​
Example

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/

​
Retrieve an Origination URI

Get details of a specific origination URI.

​
HTTP Request

GET https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/{uri_uuid}/

​
Response

{
  "uri_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6",
  "name": "primary-pbx",
  "uri": "sip.example.com:5060",
  "authentication_needed": true,
  "username": "plivo_inbound"
}

​
Example

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/f19c4773-4ae6-4b75-92ea-9cf3ea4227d6/

​
Create an Origination URI

Create a new destination endpoint for inbound calls.

​
HTTP Request

POST https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/

​
Request Parameters

ParameterTypeRequiredDefaultDescription
namestringNo-Friendly name for the URI
uristringYes-FQDN or IP address of your VoIP infrastructure
authentication_neededbooleanNofalseRequire authentication
usernamestringConditional-Username for auth. Required if authentication_needed=true
passwordstringConditional-Password for auth. Required if authentication_needed=true

​
Response

{
  "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
  "message": "Origination URI created successfully.",
  "uri_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}

​
Error Codes

CodeDescription
400Invalid request parameters
401Authentication failed
422Missing required parameters (uri, or username/password when auth enabled)

​
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/

​
Update an Origination URI

Modify an existing origination URI’s properties.

​
HTTP Request

POST https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/{uri_uuid}/

​
Request Parameters

ParameterTypeRequiredDefaultDescription
namestringNo-New friendly name
uristringNo-New FQDN or IP address
authentication_neededbooleanNo-Enable/disable authentication
usernamestringNo-New username (if auth enabled)
passwordstringNo-New password (if auth enabled)

​
Response

{
  "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
  "message": "origination uri updated successfully.",
  "uri_uuid": "f19c4773-4ae6-4b75-92ea-9cf3ea4227d6"
}

​
Example

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/

​
Delete an Origination URI

Permanently delete an origination URI.

​
HTTP Request

DELETE https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/{uri_uuid}/

​
Response

HTTP 204 No Content
Deleting an origination URI that is attached to an active trunk as primary or fallback will cause inbound calls to fail.

​
Example

curl -X DELETE -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/f19c4773-4ae6-4b75-92ea-9cf3ea4227d6/

​
Usage with Inbound Trunks

After creating origination URIs, attach them to an inbound trunk.

​
Example

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

TypePurpose
Primary URIDefault destination for inbound calls
Fallback URIUsed when primary is unreachable or returns error
Configure both for high availability:
  1. Create two origination URIs pointing to different servers
  2. Assign one as primary_uri_uuid and the other as fallback_uri_uuid
  3. If primary fails, Plivo automatically routes to fallback

​
URI Format Examples

FormatExample
IP address192.168.1.100
IP with port192.168.1.100:5060
FQDNsip.example.com
FQDN with portsip.example.com:5060
SIP URIsip:[email protected]
  • Trunks - Create and manage SIP trunks
  • Calls - View SIP trunk call records