---
title: "List contacts"
method: GET
path: "/contacts"
tags: ["Objects"]
---

# List contacts

`GET /contacts`

Returns a paginated list of contact records. Supports cursor pagination, full-text search, structured filters (stage, owner, tags, dates), and sorting. Results respect the API key user's ownership permissions. See the [Listing & filters](/api-v2/listing-and-filters) guide for filter syntax.

## Query parameters

- `cursor` string
- `pageSize` integer
- `search` string
- `orderBy` 'createdAt' | 'name' | 'number'
- `orderDir` 'asc' | 'desc'
- `filters` object — Structured filters. Each key is a filter field with operator and values. Option fields use string IDs; date fields use ISO 8601 date-time strings. See the Listing & filters guide.
  - `stageId` object
    - `operator` 'is' | 'is_not' | 'is_any_of' | 'is_none_of'
    - `values` string[]
  - `leadStageId` object
    - `operator` 'is' | 'is_not' | 'is_any_of' | 'is_none_of'
    - `values` string[]
  - `ownerUserId` object
    - `operator` 'is' | 'is_not' | 'is_any_of' | 'is_none_of'
    - `values` string[]
  - `createdById` object
    - `operator` 'is' | 'is_not' | 'is_any_of' | 'is_none_of'
    - `values` string[]
  - `listId` object
    - `operator` 'is' | 'is_not' | 'is_any_of' | 'is_none_of'
    - `values` string[]
  - `tagId` object
    - `operator` 'include' | 'exclude' | 'include_any_of' | 'include_all_of' | 'exclude_if_any_of' | 'exclude_if_all'
    - `values` string[]
  - `createdAt` object
    - `operator` 'is' | 'is_not' | 'is_before' | 'is_after' | 'is_on_or_before' | 'is_on_or_after' | 'is_between' | 'is_not_between'
    - `values` string[]

## Response `200`

OK

- object
  - `data` Contact[], required
    - `id` string, required — Contact person's ID (clt_ prefix)
    - `name` string, required — Display name
    - `number` string, required — Auto-generated contact number
    - `type` 'contact' | 'company', nullable — Record type (always contact for this endpoint)
    - `firstName` string, required — First name
    - `lastName` string, nullable — Last name
    - `email` string, nullable — Email address
    - `phone` string, nullable — Phone number
    - `salutation` string, nullable — Salutation
    - `jobTitle` string, nullable — Job title
    - `description` string, nullable — Description
    - `taxNumber` string, nullable — Tax number
    - `website` string, nullable — Website URL
    - `companyId` string, nullable — Parent company ID
    - `companyName` string, nullable — Parent company name
    - `parentClientId` string, nullable — Parent client ID (same as companyId for contacts)
    - `stageId` string, nullable — Client stage ID
    - `stageName` string, nullable — Client stage label
    - `leadStageId` string, nullable — Lead stage ID
    - `ownerUserId` string, nullable — Owner user ID
    - `crmSourceId` string, nullable — CRM source ID
    - `sourceName` string, nullable — CRM source name
    - `currency` string, nullable — Currency code
    - `openingBalance` number, required — Opening balance
    - `showJobAmountToWorker` boolean, required — Whether job amounts are visible to field workers
    - `isClientPortalEnabled` boolean, required — Whether the client portal is enabled
    - `internalNotes` string, nullable — Internal notes
    - `profileImage` string, nullable — Profile image URL
    - `instagram` string, nullable — Instagram handle or URL
    - `facebook` string, nullable — Facebook handle or URL
    - `linkedin` string, nullable — LinkedIn handle or URL
    - `twitter` string, nullable — Twitter handle or URL
    - `createdAt` string, date-time — When the contact was created
    - `updatedAt` string, date-time — When the contact was last updated
  - `meta` object, required
    - `nextCursor` string, nullable — Cursor to fetch the next page
    - `hasMore` boolean, required — Whether additional results are available

## Other responses

- `400` — Validation error or bad request
- `401` — Missing or invalid API key
- `403` — Insufficient permission
- `404` — Resource not found
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/heffl/apis/heffl-api-v2-beta.md) · [All operations](https://skmtc.net/heffl/apis/heffl-api-v2-beta/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heffl/heffl-api-v2-beta/versions/27006cfef4d8/schema)