Origination URIs

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

Parameter	Type	Required	Default	Description
`limit`	integer	No	20	Results per page (1-20)
`offset`	integer	No	0	Pagination offset

Response

api_id

string

Unique identifier for the API request.

Example

cURL

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

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).

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

Example

cURL

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

Parameter	Type	Required	Default	Description
`name`	string	No	-	Friendly name for the URI
`uri`	string	Yes	-	FQDN or IP address of your VoIP infrastructure
`authentication_needed`	boolean	No	`false`	Require authentication
`username`	string	Conditional	-	Username for auth. Required if `authentication_needed=true`
`password`	string	Conditional	-	Password for auth. Required if `authentication_needed=true`

Response

api_id

string

Unique identifier for the API request.

message

string

Status of the request. Returns Origination URI created successfully. on a successful creation.

uri_uuid

string

Unique identifier for the origination URI.

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

Error Codes

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

Without Authentication

cURL

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

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

Parameter	Type	Required	Default	Description
`name`	string	No	-	New friendly name
`uri`	string	No	-	New FQDN or IP address
`authentication_needed`	boolean	No	-	Enable/disable authentication
`username`	string	No	-	New username (if auth enabled)
`password`	string	No	-	New password (if auth enabled)

Response

api_id

string

Unique identifier for the API request.

message

string

Status of the request. Returns origination uri updated successfully. on a successful update.

uri_uuid

string

Unique identifier for the origination URI.

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

Example

cURL

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

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

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

Configure both for high availability:

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

URI Format Examples

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:pbx@example.com`

Trunks - Create and manage SIP trunks
Calls - View SIP trunk call records

​API Endpoint

​The Origination URI Object

​Attributes

​Example Object

​List All Origination URIs

​HTTP Request

​Query Parameters

​Response

​Example

​Retrieve an Origination URI

​HTTP Request

​Response

​Example

​Create an Origination URI

​HTTP Request

​Request Parameters

​Response

​Error Codes

​Without Authentication

​With Authentication

​Update an Origination URI

​HTTP Request

​Request Parameters

​Response

​Example

​Delete an Origination URI

​HTTP Request

​Response

​Example

​Usage with Inbound Trunks

​Example

​Primary vs Fallback URIs

​URI Format Examples

​Related

API Endpoint

The Origination URI Object

Attributes

Example Object

List All Origination URIs

HTTP Request

Query Parameters

Response

Example

Retrieve an Origination URI

HTTP Request

Response

Example

Create an Origination URI

HTTP Request

Request Parameters

Response

Error Codes

Without Authentication

With Authentication

Update an Origination URI

HTTP Request

Request Parameters

Response

Example

Delete an Origination URI

HTTP Request

Response

Example

Usage with Inbound Trunks

Example

Primary vs Fallback URIs

URI Format Examples

Related