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

# List contacts

> Return a paginated list of contacts in the workspace.

Returns a Laravel-paginated list of contacts belonging to your workspace.

## Endpoint

```
GET /api/v1/{subdomain}/contacts
```

Required ability: `contacts.read`.

## Headers

| Header          | Value                        |
| --------------- | ---------------------------- |
| `Authorization` | `Bearer <your-64-hex-token>` |
| `Accept`        | `application/json`           |

## Path parameters

<ParamField path="subdomain" type="string" required={true}>
  Your workspace subdomain.
</ParamField>

## Query parameters

<ParamField query="page" type="integer" required={false}>
  1-indexed page number. Defaults to `1`.
</ParamField>

<ParamField query="per_page" type="integer" required={false}>
  Items per page. Defaults to `15`, maximum `100`.
</ParamField>

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://dash.xobito.com/api/v1/acme/contacts?page=1&per_page=15" \
    -H "Authorization: Bearer <your_token>" \
    -H "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://dash.xobito.com/api/v1/acme/contacts?page=1&per_page=15",
    {
      headers: {
        Authorization: "Bearer <your_token>",
        Accept: "application/json",
      },
    }
  );
  const body = await res.json();
  ```

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

  r = requests.get(
      "https://dash.xobito.com/api/v1/acme/contacts",
      params={"page": 1, "per_page": 15},
      headers={
          "Authorization": "Bearer <your_token>",
          "Accept": "application/json",
      },
  )
  body = r.json()
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://dash.xobito.com/api/v1/acme/contacts?page=1&per_page=15');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer <your_token>',
          'Accept: application/json',
      ],
  ]);
  $body = json_decode(curl_exec($ch), true);
  curl_close($ch);
  ```
</CodeGroup>

## Example response

```json 200 OK theme={null}
{
  "status": "success",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 25,
        "tenant_id": 13,
        "firstname": "John",
        "lastname": "Doe",
        "company": "Demo Co",
        "type": "lead",
        "email": "john@example.com",
        "phone": "+1234567890",
        "source_id": 2,
        "status_id": 1,
        "country_id": 101,
        "group_id": [1, 2],
        "is_enabled": 1,
        "is_opted_out": 0,
        "created_at": "2026-04-08T14:30:25.000000Z",
        "updated_at": "2026-04-08T14:30:25.000000Z"
      }
    ],
    "per_page": 15,
    "total": 100,
    "last_page": 7,
    "first_page_url": "https://dash.xobito.com/api/v1/acme/contacts?page=1",
    "next_page_url": "https://dash.xobito.com/api/v1/acme/contacts?page=2",
    "prev_page_url": null,
    "from": 1,
    "to": 15,
    "path": "https://dash.xobito.com/api/v1/acme/contacts",
    "links": []
  }
}
```

See [Data Types → Contact](/developers/data-types#contact) for every field.

## Error responses

| Status | When                                  | Body                                                                                     |
| ------ | ------------------------------------- | ---------------------------------------------------------------------------------------- |
| `400`  | Invalid subdomain                     | `{"status":"error","message":"Validation failed","errors":"Invalid tenant subdomain"}`   |
| `401`  | Missing or invalid token              | `{"status":"error","message":"API token is required"}`                                   |
| `403`  | Token missing `contacts.read` ability | `{"status":"error","message":"Token does not have the required ability: contacts.read"}` |
| `429`  | Rate limit exceeded                   | `{"message":"Too many requests","retry_after":45}`                                       |
| `500`  | Server error                          | `{"status":"error","message":"Failed to list contacts"}`                                 |