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

# List Contacts

> Retrieve a paginated, filterable list of contacts.

Returns a list of contacts for your team, with support for filtering by status, campaign, and search query. Results are paginated.

## Query Parameters

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="limit" type="number" default="25">
  Number of contacts to return per page.
</ParamField>

<ParamField query="status" type="string">
  Filter contacts by status (e.g., `active`, `fulfilled`, `paused`). Use [List Statuses](/api-reference/contacts/statuses) to retrieve all valid values for your team.
</ParamField>

<ParamField query="campaignId" type="string (UUID)">
  Filter by campaign ID. Accepts comma-separated values to filter by multiple campaigns at once (e.g., `uuid1,uuid2`).
</ParamField>

<ParamField query="search" type="string">
  Search contacts by name or phone number. Use with `searchBy` to narrow the field.
</ParamField>

<ParamField query="searchBy" type="string">
  Restrict the `search` parameter to a specific field. Accepted values: `name`, `phone`. If omitted, both fields are searched.
</ParamField>

<ParamField query="sortBy" type="string" default="createdAt">
  Field to sort results by. Accepted values: `createdAt`, `fulfilledAt`, `reAddedAt`.
</ParamField>

<ParamField query="sortOrder" type="string" default="desc">
  Sort direction. Accepted values: `asc`, `desc`.
</ParamField>

## Response

<ResponseField name="contacts" type="array">
  Array of contact objects.

  <Expandable title="Contact fields">
    <ResponseField name="id" type="string (UUID)">
      Contact unique identifier.
    </ResponseField>

    <ResponseField name="name" type="string">
      Contact name.
    </ResponseField>

    <ResponseField name="phoneNumber" type="string">
      Phone number in E.164 format.
    </ResponseField>

    <ResponseField name="timezone" type="string">
      IANA timezone string.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current contact status.
    </ResponseField>

    <ResponseField name="customVariables" type="object">
      Custom key-value data stored on the contact.
    </ResponseField>

    <ResponseField name="createdAt" type="string (ISO 8601)">
      Creation timestamp. If the contact was re-added, this reflects the `reAddedAt` timestamp.
    </ResponseField>

    <ResponseField name="fulfilledAt" type="string or null">
      Timestamp when the contact was fulfilled. `null` if not yet fulfilled.
    </ResponseField>

    <ResponseField name="reAddedAt" type="string or null">
      Timestamp when the contact was re-added. `null` if never re-added.
    </ResponseField>

    <ResponseField name="campaigns" type="array">
      List of campaigns the contact is associated with, each containing `id` and `name`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination fields">
    <ResponseField name="total" type="number">
      Total number of contacts matching the query.
    </ResponseField>

    <ResponseField name="page" type="number">
      Current page number.
    </ResponseField>

    <ResponseField name="limit" type="number">
      Items per page.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.guayaba.ai/contacts?status=active&page=1&limit=10" \
    -H "X-API-Key: gua_a1b2c3d4_your-api-key-here"
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    status: 'active',
    page: '1',
    limit: '10'
  });

  const response = await fetch(`https://api.guayaba.ai/contacts?${params}`, {
    headers: {
      'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'
    }
  });

  const data = await response.json();
  ```

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

  response = requests.get(
      'https://api.guayaba.ai/contacts',
      params={'status': 'active', 'page': 1, 'limit': 10},
      headers={'X-API-Key': 'gua_a1b2c3d4_your-api-key-here'}
  )

  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "contacts": [
      {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "name": "John Doe",
        "phoneNumber": "+11234567890",
        "timezone": "America/New_York",
        "status": "active",
        "customVariables": {
          "email": "john@example.com"
        },
        "createdAt": "2026-01-15T10:30:00.000Z",
        "fulfilledAt": null,
        "reAddedAt": null,
        "campaigns": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Q1 Outreach"
          }
        ]
      }
    ],
    "pagination": {
      "total": 150,
      "page": 1,
      "limit": 10
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid or missing API key"
  }
  ```
</ResponseExample>