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

string

Unique identifier for the origination URI.

string

Friendly name for the origination URI.

string

FQDN or IP address of your VoIP infrastructure.

boolean

Whether Plivo should authenticate when sending calls.

string

Username for authentication (if enabled).

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

string

Unique identifier for the API request.

object

Pagination metadata: limit (results per page), offset (items skipped), total_count (total matching origination URIs).

array

Array of origination URI objects — see The Origination URI Object.

{
  "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

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

string

Unique identifier for the origination URI.

string

Friendly name for the origination URI.

string

FQDN or IP address of your VoIP infrastructure.

boolean

Whether Plivo should authenticate when sending calls.

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

string

Unique identifier for the API request.

string

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

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

string

Unique identifier for the API request.

string

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

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

Concepts

SIP REFER

Security

API Reference

Troubleshooting

PBX Integration

Origination URIs

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

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