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

# API Overview

> Introduction to Plivo's SIP Trunking (Zentrunk) API

The Plivo Zentrunk API lets you programmatically manage SIP trunks, authentication, and retrieve call records. The API uses standard HTTP methods and returns JSON responses.

## Base URL

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

***

## Authentication

All API requests use HTTP Basic Authentication with your Plivo credentials:

* **Username**: Your Auth ID
* **Password**: Your Auth Token

Find your credentials on the [Plivo Console Dashboard](https://cx.plivo.com/home).

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/
```

***

## Request Format

* **Content-Type**: `application/json` for POST requests
* All request parameters should be JSON-encoded

```bash theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"name": "my-trunk", "trunk_direction": "outbound"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/
```

***

## Response Format

All responses are JSON with an `api_id` for request tracking:

```json theme={null}
{
  "api_id": "4e1f954c-baf3-11ec-bafe-0242ac110003",
  "message": "Trunk created successfully.",
  "trunk_id": "986908123123411213"
}
```

### HTTP Status Codes

| Code  | Description                   |
| ----- | ----------------------------- |
| `200` | Request executed successfully |
| `201` | Resource created              |
| `202` | Resource modified             |
| `204` | Resource deleted              |
| `400` | Invalid or missing parameter  |
| `401` | Authentication failed         |
| `403` | Forbidden                     |
| `404` | Resource not found            |
| `405` | HTTP method not allowed       |
| `429` | Rate limit exceeded           |
| `500` | Server error                  |

### Troubleshooting Common Errors

| Code  | Common Causes                                | Solution                                                                      |
| ----- | -------------------------------------------- | ----------------------------------------------------------------------------- |
| `400` | Missing trunk name, invalid trunk\_direction | Check required parameters. Use `inbound` or `outbound` for direction          |
| `401` | Invalid Auth ID or Auth Token                | Verify credentials at Console → API Keys                                      |
| `403` | SIP trunking not enabled, geo permissions    | Contact support to enable SIP trunking. Check geo permissions                 |
| `404` | Invalid trunk ID, credential ID, or URI ID   | Verify the resource UUID exists                                               |
| `429` | Rate limit exceeded                          | Implement exponential backoff                                                 |
| `500` | Temporary server issue                       | Retry after a few seconds. Check [status.plivo.com](https://status.plivo.com) |

For call-level errors (SIP codes), see [Zentrunk Hangup Codes](/sip-trunking/troubleshooting/zentrunk-hangup-codes).

***

## Pagination

List endpoints return paginated results:

```json theme={null}
{
  "meta": {
    "limit": 20,
    "offset": 0,
    "total_count": 100,
    "previous": null,
    "next": "/v1/Account/{auth_id}/Zentrunk/Trunk/?limit=20&offset=20"
  },
  "objects": [...]
}
```

| Parameter | Description                           |
| --------- | ------------------------------------- |
| `limit`   | Results per page (1-20). Default: 20  |
| `offset`  | Number of results to skip. Default: 0 |

***

## API Resources

### Core Resources

| Resource                            | Description                            |
| ----------------------------------- | -------------------------------------- |
| [Trunks](/sip-trunking/api/trunks/) | Create and manage SIP trunks           |
| [Calls](/sip-trunking/api/calls/)   | Retrieve CDRs and call quality metrics |

### Authentication Resources

| Resource                                                              | Description                              |
| --------------------------------------------------------------------- | ---------------------------------------- |
| [Credentials](/sip-trunking/api/credentials/)                         | Manage username/password for digest auth |
| [IP Access Control Lists](/sip-trunking/api/ip-access-control-lists/) | Manage IP whitelists                     |

### Routing Resources

| Resource                                                | Description                      |
| ------------------------------------------------------- | -------------------------------- |
| [Origination URIs](/sip-trunking/api/origination-uris/) | Manage inbound call destinations |

***

## Trunk Configuration

### Outbound Trunks

Route calls from your PBX to Plivo's network:

1. Create [Credentials](/sip-trunking/api/credentials/) or [IP ACL](/sip-trunking/api/ip-access-control-lists/)
2. Create [Trunk](/sip-trunking/api/trunks/) with `trunk_direction: outbound`
3. Attach credentials or IP ACL to the trunk
4. Configure your PBX to send SIP INVITE to the trunk domain

### Inbound Trunks

Route calls from Plivo to your PBX:

1. Create [Origination URIs](/sip-trunking/api/origination-uris/) pointing to your servers
2. Create [Trunk](/sip-trunking/api/trunks/) with `trunk_direction: inbound`
3. Attach primary and optionally fallback URIs
4. Configure a Plivo number to use the trunk

***

## Rate Limits

API requests are rate limited. If you exceed the limit, you'll receive a `429` response.

***

## Related

* [Concepts](/sip-trunking) - SIP trunking fundamentals
* [Interconnection Guides](/sip-trunking/interconnection-guides/overview) - PBX setup guides
* [Troubleshooting](/sip-trunking/troubleshooting/zentrunk-hangup-codes) - Hangup codes and debugging