---
title: "POST /list-contacts"
method: POST
path: "/list-contacts"
---

# POST /list-contacts

`POST /list-contacts`

## Request

- Base URL: `https://api.retellai.com`
- URL: `https://api.retellai.com/list-contacts`
- Auth: HTTP bearer

List contacts, newest created first by default, with the total count of matches alongside the page. Page through results with `pagination_key`; `skip` is available for offset-style paging but is slower on large contact sets and can repeat or miss rows as contacts are added or deleted.

## Request body

- ListContactsRequest
  - `limit` number: Maximum number of contacts to return.
  - `skip` number: Number of records to skip for offset-based pagination.
  - `sort_order` 'asc' | 'desc': Sort contacts by `created_timestamp` in ascending or descending order (newest first by default). Ties are broken by contact ID in the same direction.
  - `pagination_key` string: Base64url-encoded pagination key from a previous response.
  - `filter_criteria` ContactFilter: Filter criteria for contacts. All conditions are implicitly connected with AND. first_name and last_name are not filterable here; use search_query to match on those.
    - `contact_id` StringFilter
      - `type` 'string', required
      - `op` 'eq' | 'ne' | 'sw' | 'ew' | 'co', required: eq: equal, ne: not equal, sw: starts with, ew: ends with, co: contains
      - `value` string, required
    - `phone_number` StringFilter
      - `type` 'string', required
      - `op` 'eq' | 'ne' | 'sw' | 'ew' | 'co', required: eq: equal, ne: not equal, sw: starts with, ew: ends with, co: contains
      - `value` string, required
    - `external_id` union: Filter by the record id in the connected CRM. Use a `present` filter to separate synced from unsynced contacts.
      - StringFilter
        - `type` 'string', required
        - `op` 'eq' | 'ne' | 'sw' | 'ew' | 'co', required: eq: equal, ne: not equal, sw: starts with, ew: ends with, co: contains
        - `value` string, required
      - PresentFilter
        - `type` 'present', required
        - `op` 'pr' | 'np', required: pr: present (has value), np: not present
    - `do_not_call` BooleanFilter
      - `type` 'boolean', required
      - `op` 'eq', required
      - `value` boolean, required
    - `contact_tag_ids` EnumFilter
      - `type` 'enum', required
      - `op` 'in', required: in: value is one of the listed values
      - `value` string[], required
    - `last_conversation_timestamp` union: Filter by when the contact was last spoken to, in epoch milliseconds.
      - NumberFilter
        - `type` 'number', required
        - `op` 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le', required: eq: equal, ne: not equal, gt: greater than, ge: greater than or equal, lt: less than, le: less than or equal
        - `value` number, required
      - RangeFilter
        - `type` 'range', required
        - `op` 'bt', required: bt: between
        - `value` number[], required: [lower_bound, upper_bound]
    - `custom_fields` CustomFieldFilter[]: Filter by custom contact fields defined in CRM config.
      - union
        - object: A filter on a custom field, identified by key.
          - `type` 'string', required
          - `op` 'eq' | 'ne' | 'sw' | 'ew' | 'co', required: eq: equal, ne: not equal, sw: starts with, ew: ends with, co: contains
          - `value` string, required
          - `key` string, required: The field name to filter on.
        - object: A filter on a custom field, identified by key.
          - `type` 'number', required
          - `op` 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le', required: eq: equal, ne: not equal, gt: greater than, ge: greater than or equal, lt: less than, le: less than or equal
          - `value` number, required
          - `key` string, required: The field name to filter on.
        - object: A filter on a custom field, identified by key.
          - `type` 'boolean', required
          - `op` 'eq', required
          - `value` boolean, required
          - `key` string, required: The field name to filter on.
        - object: A filter on a custom field, identified by key.
          - `type` 'range', required
          - `op` 'bt', required: bt: between
          - `value` number[], required: [lower_bound, upper_bound]
          - `key` string, required: The field name to filter on.
        - object: A filter on a custom field, identified by key.
          - `type` 'enum', required
          - `op` 'in', required: in: value is one of the listed values
          - `value` string[], required
          - `key` string, required: The field name to filter on.
        - object: A filter on a custom field, identified by key.
          - `type` 'present', required
          - `op` 'pr' | 'np', required: pr: present (has value), np: not present
          - `key` string, required: The field name to filter on.
  - `search_query` string: Case-insensitive substring match against phone number, first name, last name, external ID, and custom field values. This is the only way to match on a contact's name.
  - `excluded_contact_ids` string[]: Contact IDs to leave out of both the results and `total`, at most 1,000.

## Response `200`

Paginated list of contacts.

- ContactListResponse
  - `pagination_key` string: Pagination key for the next page.
  - `has_more` boolean, required: Whether more results are available.
  - `items` Contact[], required
    - `contact_id` string, required: Unique identifier for the contact.
    - `org_id` string, required: Organization this contact belongs to.
    - `phone_number` string, required: Phone number of the contact.
    - `first_name` string: First name of the contact.
    - `last_name` string: Last name of the contact.
    - `do_not_call` boolean: Whether this contact should not be called.
    - `contact_memory` string: Running brief shared across this contact's phone calls and SMS chats. Omitted when unset.
    - `external_id` string: CRM record ID from the external provider.
    - `contact_tags` ContactTag[]: Assigned tag IDs and labels from the organization's CRM config. IDs absent from the config are omitted.
      - `id` string, required: Unique identifier for the tag.
      - `label` string, required: Human-readable label for the tag.
    - `custom_fields` object: Custom fields defined in CRM config.
    - `conversation_count` number: Number of conversations (calls and chats) associated with this contact.
    - `last_conversation_timestamp` number: Epoch milliseconds of the most recent conversation with this contact.
    - `created_timestamp` number, required: Epoch milliseconds when the contact was created.
    - `user_modified_timestamp` number: Epoch milliseconds when the contact was last modified.
  - `total` number: Total count of contacts matching the filter.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

- **2026-10-16** `ca41f0dbb297`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/retellai/apis/retell-sdk/changes/list-contacts/post.md)

---

[API](https://skmtc.dev/retellai/apis/retell-sdk.md) - [All operations](https://skmtc.dev/retellai/apis/retell-sdk/llms.txt) - [OpenAPI document](https://skmtc.dev/retellai/apis/retell-sdk/revisions/e482acaa292c?raw)