Browse contacts with filters

POST

/api/v3/contacts/browse

const url = 'https://api.tryletterhead.com/api/v3/contacts/browse?api=true';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"tags":["engaged-readers"],"statuses":[1],"pageSize":25}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url 'https://api.tryletterhead.com/api/v3/contacts/browse?api=true' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "tags": [ "engaged-readers" ], "statuses": [ 1 ], "pageSize": 25 }'

Returns a filtered, paginated page of your company’s contacts — the same query the contacts table on your audience page runs. Unlike Search contacts, this endpoint accepts a fuller filter set: multiple channels and statuses (OR’d together), tag terms, typed custom-field comparisons, a saved segment to intersect with, and a created-date window. Results are cursor-paginated with searchAfter.

Each returned contact also carries the segments it currently belongs to.

This is a company-level (v3) read. Authenticate with a company API key as a Bearer token.

Authorizations

bearerAuth

Parameters

Query Parameters

api

required

boolean

Required. Set to true.

Request Body

application/json

object

query

Free-text search across email, first name, and last name. Max 500 characters.

string

channels

Restrict to contacts subscribed to any of these channel identifiers (slugs).

Array<string>

statuses

Restrict to contacts whose subscription status (on any matched channel) is one of these values. See the subscription status table on Add or update subscriptions in bulk.

Array<integer>

tags

Restrict to contacts carrying any of these tags.

Array<string>

untagged

Restrict to contacts with no tags at all. Mutually exclusive with a non-empty tags.

boolean

customFields

Typed custom-field comparisons, AND’d together with the rest of the filter.

Array<object>

object

key

The custom field’s name.

string

eq, ne, gt, gte, lt, lte, contains, or exists.

string

value

Comparison value. Omit when op is exists.

segmentId

A saved segment (see List segments) whose criteria are AND-merged with the rest of this filter set.

integer

createdAtFrom

Restrict to contacts created on or after this date (inclusive). Date-only (YYYY-MM-DD) or a full ISO 8601 timestamp.

string

createdAtTo

Restrict to contacts created on or before this date (inclusive).

string

sort

name, email, status, or dateAdded. Defaults to dateAdded.

string

direction

asc or desc. Defaults to desc.

string

pageSize

Page size, 1–100. Defaults to 25.

integer

searchAfter

Opaque cursor from the previous page’s searchAfter. Omit or send null for the first page.

string

nullable

channel

Narrow the browse to a single channel identifier (slug) — the shape the channel-level audience page uses.

string

Example

{
  "tags": [
    "engaged-readers"
  ],
  "statuses": [
    1
  ],
  "pageSize": 25
}

Responses

200

200 OK

application/json

object

items

object

contacts

The matched contacts for this page.

Array<object>

object

email

string

firstName

string

lastName

string

tags

Array<string>

customFields

object

endpoints

Array<object>

object

channelConsents

Array<object>

object

consents

Array<object>

object

createdAt

string

updatedAt

string

segments

The segments this contact currently belongs to.

Array<object>

object

integer

name

string

searchAfter

Opaque cursor for the next page — pass it back as searchAfter.

string

nullable

totalRelation

Whether the top-level total is exact (eq) or a lower bound (gte).

string

message

string

total

integer

Example

{
  "items": {
    "contacts": [
      {
        "email": "[email protected]",
        "firstName": "Avery",
        "lastName": "Chen",
        "tags": [
          "engaged-readers"
        ],
        "customFields": {
          "__lh.mailboxProvider": "gmail",
          "lastOpenDate": "2026-06-18 05:11:33"
        },
        "endpoints": [],
        "channelConsents": [],
        "consents": [],
        "createdAt": "2026-05-23T11:43:15+00:00",
        "updatedAt": "2026-06-18T09:12:04+00:00",
        "segments": [
          {
            "id": 7,
            "name": "Highly engaged readers"
          }
        ]
      }
    ],
    "searchAfter": "WzE3MTg3NTUxOTUwMDAsImF2ZXJ5LmNoZW5AZXhhbXBsZS5jb20iXQ==",
    "totalRelation": "eq"
  },
  "message": "Contacts retrieved.",
  "total": 842
}

Still can’t find what you need? Contact support.