<Intro>

<EndpointHeader />

<Description>

Returns a paginated list of contacts in the workspace, newest first. Look up a single contact by its exact `email` or `external_id`, or search by email substring with `q`.

</Description>

</Intro>

<Parameters in="query">

<Parameter name="email" type="string">

<Description>

Return the contact with exactly this email address (case-insensitive). Email is unique within a workspace, so this matches at most one contact.

</Description>

</Parameter>

<Parameter name="external_id" type="string">

<Description>

Return the contact with exactly this external_id (your own identifier for the contact). Unique within a workspace, so this matches at most one contact.

</Description>

</Parameter>

<Parameter name="q" type="string">

<Description>

Case-insensitive substring match against the contact's email address.

</Description>

</Parameter>

<Parameter name="limit" type="integer">

<Description>

Maximum number of items to return per page.

</Description>

</Parameter>

<Parameter name="starting_after" type="string">

<Description>

Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.

</Description>

</Parameter>

<Parameter name="ending_before" type="string">

<Description>

Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="data" type="array of object" required>

<Description>

Page of contact objects.

</Description>

<FieldChildren kind="response">

<Field name="id" type="string" prefix="data." required>

<Description>

ID of the contact (`con_`-prefixed), accepted by every operation that takes a `contact_id`.

</Description>

</Field>

<Field name="email" type="string" prefix="data." required>

<Description>

The contact's email address, stored trimmed and lowercased. Unique within the workspace.

</Description>

</Field>

<Field name="first_name" type="nullable string" prefix="data.">

<Description>

The contact's first name. Available in broadcast templates as the `contact.first_name` variable.

</Description>

</Field>

<Field name="last_name" type="nullable string" prefix="data.">

<Description>

The contact's last name. Available in broadcast templates as the `contact.last_name` variable.

</Description>

</Field>

<Field name="external_id" type="nullable string" prefix="data.">

<Description>

Your own identifier for this contact, such as a user ID in your system. Unique within the workspace when set.

</Description>

</Field>

<Field name="data" type="object" prefix="data.">

<Description>

Custom property values for this contact, available as template variables in broadcasts. Each key is a property created via the contact properties API, and each value is a string, number, or boolean matching the property's declared type (strings up to 500 characters). Total size is capped at 2 KB serialized. Values stored under a property that was later archived remain readable here.

</Description>

</Field>

<Field name="channels" type="array of string" prefix="data.">

<Description>

Channels this contact can be reached on, derived from the identifiers it has. A contact with an email address includes `email`. More values are added as a contact gains identifiers for other channels.

</Description>

</Field>

<Field name="created_at" type="string" prefix="data." required />

<Field name="updated_at" type="string" prefix="data." required />

</FieldChildren>

</Field>

<Field name="next_cursor" type="nullable string" required>

<Description>

Cursor for the next page. Pass back as `starting_after` to advance forward. Null when no next page exists.

</Description>

</Field>

<Field name="prev_cursor" type="nullable string" required>

<Description>

Cursor for the previous page. Pass back as `ending_before` to step backward. Null when no previous page exists.

</Description>

</Field>

<Field name="refresh_cursor" type="nullable string" required>

<Description>

Refresh anchor. Pass back as `ending_before` later to fetch items that have appeared since this response. Non-null whenever `data` is non-empty; null only on an empty page. Distinct from `prev_cursor`.

</Description>

</Field>

</Payload>