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

# List contacts

`GET /contacts`

## Request

- Base URL: `https://api.parley.so/v1`
- URL: `https://api.parley.so/v1/contacts`
- Auth: HTTP bearer

List contacts (people, each optionally belonging to one account), newest first by default. Filter by name or email, account, linked project, and when contacts were created or updated.

## Query parameters

- `search` string: Case-insensitive. Every word must match the first name, last name, account name, an email address, or a text custom field.
- `email` string: Only the contact with exactly this email address.
- `accountId` string: Only contacts belonging to this account.
- `hasAccount` boolean: true for contacts that belong to an account, false for contacts that do not.
- `projectId` string: Only contacts linked to this project.
- `createdSince` string: Only records created at or after this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `createdBefore` string: Only records created before this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `updatedSince` string: Only records last updated at or after this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `updatedBefore` string: Only records last updated before this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `sort` 'name' | '-name' | 'createdAt' | '-createdAt' | 'updatedAt' | '-updatedAt': Sort order: a field name, prefixed with - for descending. name sorts by first name, then last name. Defaults to -createdAt.
- `cursor` string: Opaque cursor from nextCursor. Pass the same filters and sort. Omit for the first page.
- `limit` integer: Maximum number of items to return.

## Response `200`

OK

- object
  - `data` Contact[], required
    - `id` string, required: The contact ID.
    - `firstName` string, required: First name. Empty for some contacts created from email.
    - `lastName` string, required: Last name. Empty for some contacts created from email.
    - `emails` string[], required: Email addresses, lowercased. A contact has at most one address for now.
    - `account` AccountRef, required: The account's type, ID, and name.
      - `type` 'account', required
      - `id` string, required: Its ID.
      - `name` string, required: The account name.
    - `projectCount` integer, required: How many projects you can see are linked to the contact. List them by filtering projects by contactId. Linking or unlinking a project doesn't change the contact's updatedAt.
    - `createdAt` string, date-time, required: When the contact was created.
    - `updatedAt` string, date-time, required: When the contact was last updated, including changes to its email address. Links to projects and field value changes do not change it.
    - `fields` object, required: Custom field values, keyed by field name, with a key for every field defined for contacts (null when unset). The value's shape follows the field's type.
  - `nextCursor` string, nullable, required: Cursor for the next page, or null on the last page.

## Other responses

- `400`: The request was invalid. VALIDATION_FAILED, INVALID_CURSOR.
- `401`: Missing or invalid credentials. UNAUTHORIZED.
- `403`: You don't have permission. FORBIDDEN.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS.

---

[API](https://skmtc.dev/parley/apis/parley-api.md) - [All operations](https://skmtc.dev/parley/apis/parley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parley/apis/parley-api/revisions/6b78aeee07bc?raw)