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

# List tickets

> Retrieve a paginated list of conversation tickets filtered by status or contact ID

Retrieve conversation tickets for your active organization. Results can be filtered by ticket status (`open` or `closed`) or restricted to a specific contact ID.

***

### Authentication

This endpoint requires Bearer token authentication.

```http theme={null}
Authorization: Bearer <token>
```

| Header          | Type     | Required | Description                                     | Format           |
| :-------------- | :------- | :------- | :---------------------------------------------- | :--------------- |
| `Authorization` | `string` | **Yes**  | Scoped organization API key or Bearer JWT token | `Bearer <token>` |

***

### Query Parameters

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer <token>`.
</ParamField>

<ParamField query="status" type="string">
  Filter tickets by state. Allowed values: `open`, `closed`.
</ParamField>

<ParamField query="contact_id" type="string">
  Filter tickets associated with a specific contact UUID.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Maximum number of tickets to retrieve (1 to 100).
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of tickets to skip for pagination (minimum `0`).
</ParamField>

***

### Response Fields

<ResponseField name="total" type="integer">
  Total number of tickets matching query criteria.
</ResponseField>

<ResponseField name="page" type="integer">
  Computed page number based on offset and limit.
</ResponseField>

<ResponseField name="size" type="integer">
  Batch size returned.
</ResponseField>

<ResponseField name="inboxes" type="object[]">
  Array of ticket objects.

  <Expandable title="InboxResponse Fields">
    <ResponseField name="id" type="string">
      UUID of the inbox ticket.
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      UUID of the owning organization.
    </ResponseField>

    <ResponseField name="contact_id" type="string">
      UUID of the contact.
    </ResponseField>

    <ResponseField name="whatsapp_phone_number_id" type="string">
      UUID of the assigned WhatsApp phone number, or `null`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Ticket state (`open` or `closed`).
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 last update timestamp.
    </ResponseField>

    <ResponseField name="contact" type="object">
      Contact profile brief (name, phone number, tags).
    </ResponseField>
  </Expandable>
</ResponseField>

***

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.sayvy.ai/api/v1/inbox/tickets?status=open&limit=25&offset=0" \
    -H "Authorization: Bearer <token>"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.sayvy.ai/api/v1/inbox/tickets"
  headers = {
      "Authorization": "Bearer <token>"
  }
  params = {
      "status": "open",
      "limit": 25,
      "offset": 0
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.status_code)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.sayvy.ai/api/v1/inbox/tickets?status=open&limit=25&offset=0", {
    method: "GET",
    headers: {
      "Authorization": "Bearer <token>"
    }
  });

  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "total": 1,
    "page": 1,
    "size": 25,
    "inboxes": [
      {
        "id": "e4f3a2b1-9c8d-7e6f-5a4b-3c2d1e0f9a8b",
        "organization_id": "e0b973dc-13a8-4c9f-861a-03e5b4b1a8d9",
        "contact_id": "8a7c2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
        "whatsapp_phone_number_id": "11a22b33-44c5-5d6e-7f8a-9b0c1d2e3f4a",
        "status": "open",
        "created_at": "2026-09-07T15:30:00Z",
        "updated_at": "2026-09-07T15:35:00Z",
        "contact": {
          "id": "8a7c2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
          "name": "Sarah Connor",
          "phone_number": "+14155552671",
          "tags": ["vip", "enterprise"],
          "notes": "Key account representative",
          "custom_fields": {
            "tier": "enterprise"
          }
        }
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "detail": "Status filter must be either 'open' or 'closed'"
  }
  ```
</ResponseExample>