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

# Responses

> Standard success-response envelope, pagination format, and common conventions for every Verbeo API endpoint.

Every successful Verbeo response follows the same envelope. This page is the canonical reference — individual endpoint pages document the resource-specific `data` payload but link here for the wrapper format.

## Success envelope

```json theme={null}
{
  "success": true,
  "data": { /* resource-specific payload */ }
}
```

<ResponseField name="success" type="boolean" required>
  Always `true` on success. See [Errors](/api-reference/errors) for the failure shape.
</ResponseField>

<ResponseField name="data" type="object | array" required>
  The resource the endpoint returns. Object for single-resource reads/writes (e.g. `GET /campaigns/{id}`), array for list endpoints (e.g. `GET /campaigns`).
</ResponseField>

## Status codes

| Status | When |
| - | - |
| `200` | Read or update succeeded |
| `201` | Resource created (`POST` to a collection) |
| `204` | Resource deleted, no body returned |

## List responses and pagination

List endpoints (e.g. `GET /campaigns`) return their items in `data` plus a `pagination` object describing the slice you received.

```json theme={null}
{
  "success": true,
  "data": [
    { "id": "…", "campaign_name": "Q2 Outreach", "status": "running", "…": "…" }
  ],
  "pagination": {
    "total": 42,
    "count": 1,
    "next_cursor": "20"
  }
}
```

<ResponseField name="pagination.total" type="number">
  Total number of resources matching the query, across all pages.
</ResponseField>

<ResponseField name="pagination.count" type="number" required>
  Number of items in the current response.
</ResponseField>

<ResponseField name="pagination.next_cursor" type="string | null" required>
  Cursor to fetch the next page. `null` when there is no further page.
</ResponseField>

How you pass the cursor back depends on the resource:

* **Campaigns** list with a `GET`. Pass the cursor as the `offset` query parameter:

  ```bash theme={null}
  curl "https://api.verbeo.ai/v1/campaigns?limit=20&offset=20" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

* **Assistants**, **phone numbers** and **tools** list with a `POST` whose body carries `page` and `size`. The cursor is the next page number: pass it as `page`.

  ```bash theme={null}
  curl -X POST "https://api.verbeo.ai/v1/phone-number/list" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "page": 2, "size": 20 }'
  ```

## Conventions

* **Identifiers** are UUID v4 strings unless stated otherwise.
* **Timestamps** are ISO 8601 in UTC, e.g. `"2026-05-04T15:00:00.000Z"`.
* **Phone numbers** are E.164 strings, e.g. `"+12125550001"`.
* **Money values** are decimal strings to avoid float rounding. (Reserved — no current endpoint returns money.)

## Backwards-compatibility policy

The API follows an additive compatibility policy: new fields may appear in `data` payloads without notice. Existing fields will not be removed or renamed without an advance deprecation announcement.

Branch on `error.code` for error handling, not on `error.message` — see [Errors](/api-reference/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.