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

# List Contacts

> Retrieve a paginated list of contacts

## Authentication

Requires `contacts:read` scope.

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number to retrieve
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of items per page (max: 100)
</ParamField>

<ParamField query="search" type="string">
  Search by first name, last name, or email
</ParamField>

<ParamField query="email" type="string">
  Filter by exact email address
</ParamField>

<ParamField query="phone" type="string">
  Filter by phone number
</ParamField>

<ParamField query="location_id" type="string">
  Filter by location UUID
</ParamField>

## Response

<ResponseField name="data" type="array">
  <Expandable title="Contact Object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID)
    </ResponseField>

    <ResponseField name="email" type="string">
      Contact's email address
    </ResponseField>

    <ResponseField name="firstName" type="string">
      Contact's first name
    </ResponseField>

    <ResponseField name="lastName" type="string">
      Contact's last name
    </ResponseField>

    <ResponseField name="phone" type="string">
      Contact's phone number (E.164 format)
    </ResponseField>

    <ResponseField name="title" type="string">
      Contact's job title or salutation
    </ResponseField>

    <ResponseField name="preferredLanguage" type="string">
      Preferred language (en or fr)
    </ResponseField>

    <ResponseField name="locationId" type="string">
      Associated location UUID
    </ResponseField>

    <ResponseField name="contactOrganizationId" type="string">
      Associated organization UUID
    </ResponseField>

    <ResponseField name="customFields" type="object">
      Custom field values (key-value pairs)
    </ResponseField>

    <ResponseField name="tags" type="array">
      Array of tag strings
    </ResponseField>

    <ResponseField name="unsubscribed" type="boolean">
      Whether contact has unsubscribed
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="Pagination Meta">
    <ResponseField name="page" type="integer">
      Current page number
    </ResponseField>

    <ResponseField name="perPage" type="integer">
      Items per page
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of contacts
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://app.demeterrr.com/api/v1/contacts?page=1&limit=50 \
    -H "X-API-Key: dem_your_key_here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.demeterrr.com/api/v1/contacts?page=1&limit=50', {
    headers: {
      'X-API-Key': 'dem_your_key_here'
    }
  });

  const data = await response.json();
  console.log(`Found ${data.meta.total} contacts`);
  ```

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

  response = requests.get(
      'https://app.demeterrr.com/api/v1/contacts',
      headers={'X-API-Key': 'dem_your_key_here'},
      params={'page': 1, 'limit': 50}
  )

  data = response.json()
  print(f"Found {data['meta']['total']} contacts")
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "phone": "+15551234567",
        "title": "Mr.",
        "preferredLanguage": "en",
        "locationId": "660e8400-e29b-41d4-a716-446655440000",
        "contactOrganizationId": null,
        "customFields": {
          "birthday": "1990-01-15",
          "membershipTier": "Gold"
        },
        "tags": ["vip", "frequent-customer"],
        "unsubscribed": false,
        "createdAt": "2026-01-15T10:30:00.000Z",
        "updatedAt": "2026-02-10T14:20:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "perPage": 50,
      "total": 247,
      "totalPages": 5
    }
  }
  ```
</ResponseExample>