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

# List contacts

`GET /v1/contacts`

Retrieve all contacts in your workspace's contacts database. Contacts represent people such as interview participants, customers, or research subjects.

Results can be filtered by name and sorted by creation date or name. They are paginated.

> 🚧 Permissions
>
> Please check you have the relevant permissions required to access this resource. This may include specific permissions on the object itself or its parent, or having the correct user role if you're making updates.

## Query parameters

- `page` object
  - `start_cursor` string
  - `limit` integer, nullable
- `filter` object
  - `name` object — Filter results based on string value. You can either provide a `contains` operator for substring matching or an `equal_to` operator for exact matching. These options are mutually exclusive.
    - `contains` string — Substring (case-insensitive) to search for within the target string
    - `equal_to` string — Equal to operator
- `sort` union
  - 'created_at:asc' | 'created_at:desc' | 'name:asc' | 'name:desc'
  - string[]

## Response `200`

200

- object
  - `data` object[], required
    - `id` string, required
    - `url` string — The URL of this resource in the Dovetail web app. This field is experimental and may change without notice.
    - `name` string, nullable, required
    - `created_at` string, required
    - `fields` object[], required
      - `label` string, required — The field's label (name). Must match an existing field label when updating, or will create a new field when creating.
      - `value` union, required — The field's value. Type depends on the field type: string for TEXT/EMAIL/URL/PHONE, boolean for BOOLEAN, number for NUMBER/NPS, string (ISO 8601) for DATETIME, string array for SELECT, or string (contact name) for PERSON. Null to clear the value.
        - string
        - boolean
        - number
        - string[]
      - `type` 'BOOLEAN' | 'DATETIME' | 'EMAIL' | 'NPS' | 'NUMBER' | 'PERSON' | 'PHONE' | 'SELECT' | 'TEXT' | 'URL' — Include the desired type when creating a new field. If omitted or left empty, the field type defaults to TEXT. Do not include this property when referencing an existing field.
  - `page` object, required
    - `total_count` number, required — Total number of items matching the query.
    - `has_more` boolean, required — Whether there are more items beyond the current page.
    - `next_cursor` string, nullable, required — Cursor to pass as `page[start_cursor]` to fetch the next page. Null when there are no more results.

## Other responses

- `400` — 400
- `401` — 401
- `403` — 403
- `404` — 404
- `422` — 422
- `429` — 429
- `500` — 500

---

[API](https://skmtc.net/dovetail/apis/dovetail-public-api.md) · [All operations](https://skmtc.net/dovetail/apis/dovetail-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dovetail/dovetail-public-api/versions/4107f5fdf8b2/schema)