> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Origination URIs

> Manage destination endpoints for inbound SIP trunks

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

```json theme={null}
{
  "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.

**meta** `object`

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

**objects** `array`

Array of origination URI objects — see [The Origination URI Object](#the-origination-uri-object).

```json theme={null}
{
  "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

```bash cURL theme={null}
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).

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

### Example

```bash cURL theme={null}
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.

```json theme={null}
{
  "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

```bash cURL theme={null}
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

```bash cURL theme={null}
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.

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

### Example

```bash cURL theme={null}
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

> [!WARNING]
>
> Deleting an origination URI that is attached to an active trunk as primary or fallback will cause inbound calls to fail.

### Example

```bash cURL theme={null}
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

```bash cURL theme={null}
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:

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

| 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` |

***

## Related

* [Trunks](https://plivo.com/docs/sip-trunking/api/trunks.md) - Create and manage SIP trunks
* [Calls](https://plivo.com/docs/sip-trunking/api/calls.md) - View SIP trunk call records