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

# List Contacts

> Retrieve contacts for a project with optional filtering and pagination

## Headers

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY`
</ParamField>

<ParamField header="X-Project-ID" type="string">
  Your project UUID. Not required if the API key already encodes the project.
</ParamField>

## Query Parameters

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

<ParamField query="limit" type="number" default="50">
  Results per page (max 200)
</ParamField>

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

<ParamField query="status" type="string">
  Filter by status: `new` · `active` · `inactive` · `archived`
</ParamField>

<ParamField query="tags" type="string">
  Comma-separated tag names to filter by (e.g. `VIP,Newsletter`)
</ParamField>

<ParamField query="segment_id" type="string">
  Return only contacts that match a specific segment
</ParamField>

## Response

<ResponseField name="contacts" type="Contact[]">
  Array of contact objects with resolved tags
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination fields">
    <ResponseField name="page" type="number">Current page</ResponseField>
    <ResponseField name="limit" type="number">Results per page</ResponseField>
    <ResponseField name="total" type="number">Total matching contacts</ResponseField>
    <ResponseField name="pages" type="number">Total pages</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.usegately.com/api/v1/contacts?status=active&limit=50" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "X-Project-ID: YOUR_PROJECT_ID"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    'https://api.usegately.com/api/v1/contacts?status=active&limit=50',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'X-Project-ID': 'YOUR_PROJECT_ID',
      }
    }
  )
  const { contacts, pagination } = await res.json()
  ```

  ```typescript SDK theme={null}
  import { GatelyContacts } from '@gately/sdk'

  const crm = new GatelyContacts({ projectId: 'YOUR_PROJECT_ID' })

  const { contacts, pagination } = await crm.list({
    status: 'active',
    search: 'jane',
    page: 1,
    limit: 50,
  })
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "contacts": [
      {
        "id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
        "project_id": "proj-uuid-here",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "company": "Acme Corp",
        "status": "active",
        "unsubscribed": false,
        "tags": [
          { "id": "tag-uuid", "name": "VIP", "color": "#ff6600" }
        ],
        "custom_fields": { "plan": "pro" },
        "last_contacted_at": "2025-05-10T09:00:00.000Z",
        "created_at": "2025-01-15T12:00:00.000Z",
        "updated_at": "2025-05-10T09:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "pages": 1
    }
  }
  ```
</ResponseExample>