Contacts

List contacts with filtering and pagination

GET https://demo.notifuse.com/api/contacts.list

Retrieves a paginated list of contacts with optional filtering. All contact fields are always returned.

Filtering: Use search to match email, names and external ID at once, or filters on single fields. Text filters (email, external_id, first_name, last_name, full_name, phone, country, language) use case-insensitive partial matching (ILIKE).

List filtering: Use list_id and/or contact_list_status to filter contacts by list membership.

Segment filtering: Use segments[] to filter contacts that belong to specific segments.

Contact lists: By default, contact_lists is not included in the response. Set with_contact_lists=true to include the contact's list subscriptions.

Pagination: Uses cursor-based pagination. Use the next_cursor from the response to fetch the next page.

Authorizations

Authorization string header required

Bearer authentication header of the form Bearer <token>, where <token> is your API key.

Query Parameters

workspace_id string required

The ID of the workspace

Example ws_1234567890
search string

Search across email, first name, last name, full name, first and last name together ("Jane Doe") and external ID (case-insensitive partial match). Leading and trailing spaces are ignored; % and _ are matched literally. At most 100 characters.

Max length 100 Example john
email string

Filter by email (case-insensitive partial match)

Example user@example
external_id string

Filter by external ID (case-insensitive partial match)

Example user_123
first_name string

Filter by first name (case-insensitive partial match)

Example John
last_name string

Filter by last name (case-insensitive partial match)

Example Doe
full_name string

Filter by full name (case-insensitive partial match)

Example John Doe
phone string

Filter by phone number (case-insensitive partial match)

Example +1555
country string

Filter by country (case-insensitive partial match)

Example US
language string

Filter by language (case-insensitive partial match)

Example en
list_id string

Filter by list membership (contacts subscribed to this list)

Example newsletter
contact_list_status string

Filter by subscription status within the list

Options active, pending, unsubscribed, bounced, complained Example active
tracking_opens_consent string

Filter by the contact's open tracking choice; unknown matches contacts with none recorded

Options granted, denied, unknown Example denied
tracking_clicks_consent string

Filter by the contact's click tracking choice; unknown matches contacts with none recorded

Options granted, denied, unknown Example unknown
segments[] string[]

Filter by segment membership (contacts in any of these segments)

with_contact_lists boolean

Include contact list subscriptions in the response

Default false Example true
limit integer

Maximum number of contacts to return (1-100)

Default 20 Min 1 Max 100 Example 50
cursor string

Pagination cursor from previous response

Example MjAyMy0wMS0xNVQxMDozMDowMFp+dXNlckBleGFtcGxlLmNvbQ==

Response

200 Contacts retrieved successfully object
contacts object[]

Array of contacts matching the query

Show 42 child attributes Hide 42 child attributes
email string<email> required

Email address of the contact. This is the contact's unique identifier.

Example user@example.com
external_id string | null

Identifier for the contact in your own system. Not unique — several contacts may share the same external_id.

Example user_12345
timezone string | null

Timezone of the contact

Example America/New_York
language string | null

Preferred language of the contact

Example en-US
first_name string | null

First name of the contact

Example John
last_name string | null

Last name of the contact

Example Doe
full_name string | null

Full name of the contact (for systems that don't have separate first/last names)

Example John Doe
phone string | null

Phone number of the contact

Example +15551234567
address_line_1 string | null

First line of address

Example 123 Main St
address_line_2 string | null

Second line of address

Example Apt 4B
country string | null

Country of the contact

Example US
postcode string | null

Postal code

Example 10001
state string | null

State or province

Example NY
job_title string | null

Job title of the contact

Example Software Engineer
tracking_opens_consent string | null

The contact's own choice about open tracking; null means unknown.

Options granted, denied, null
tracking_clicks_consent string | null

The contact's own choice about click tracking; null means unknown.

Options granted, denied, null
tracking_consent_updated_at string<date-time> | null

When a tracking choice last changed.

tracking_consent_source string | null

Where the last tracking choice came from (api, console, import, notification_center, email_link, subscribe_form).

custom_string_1 string | null

Custom string field 1

Example Premium tier
custom_string_2 string | null

Custom string field 2

custom_string_3 string | null

Custom string field 3

custom_string_4 string | null

Custom string field 4

custom_string_5 string | null

Custom string field 5

custom_number_1 number<float> | null

Custom number field 1

Example 42
custom_number_2 number<float> | null

Custom number field 2

custom_number_3 number<float> | null

Custom number field 3

custom_number_4 number<float> | null

Custom number field 4

custom_number_5 number<float> | null

Custom number field 5

custom_datetime_1 string<date-time> | null

Custom datetime field 1

Example 2023-06-01T09:00:00Z
custom_datetime_2 string<date-time> | null

Custom datetime field 2

custom_datetime_3 string<date-time> | null

Custom datetime field 3

custom_datetime_4 string<date-time> | null

Custom datetime field 4

custom_datetime_5 string<date-time> | null

Custom datetime field 5

custom_json_1 any

Custom JSON field 1. Any JSON value, or null.

custom_json_2 any

Custom JSON field 2. Any JSON value, or null.

custom_json_3 any

Custom JSON field 3. Any JSON value, or null.

custom_json_4 any

Custom JSON field 4. Any JSON value, or null.

custom_json_5 any

Custom JSON field 5. Any JSON value, or null.

created_at string<date-time> read-only

When the contact was created (read-only, set by server)

Example 2023-01-15T10:30:00Z
updated_at string<date-time> read-only

When the contact was last updated (read-only, set by server)

Example 2023-04-22T15:45:00Z
contact_lists object[] read-only

Lists the contact is subscribed to (read-only, included in GET responses only)

Show 7 child attributes Hide 7 child attributes
email string<email>

Email address of the contact

Example user@example.com
list_id string

ID of the list

Example newsletter
list_name string

Name of the list

Example Newsletter
status string

Subscription status

Options active, pending, unsubscribed, bounced, complained Example active
created_at string<date-time>

When the contact was subscribed to this list

Example 2023-01-15T10:30:00Z
updated_at string<date-time>

When the subscription was last updated

Example 2023-01-15T10:30:00Z
deleted_at string<date-time> | null

When the subscription was deleted (null if active)

contact_segments object[] read-only

Segments the contact belongs to (read-only, included in GET responses only)

Show 5 child attributes Hide 5 child attributes
email string<email>

Email address of the contact

Example user@example.com
segment_id string

ID of the segment

Example premium_users
version integer<int64>

Version of the segment computation

Example 1
matched_at string<date-time>

When the contact was matched to this segment

Example 2023-01-15T10:30:00Z
computed_at string<date-time>

When the segment was last computed

Example 2023-01-15T10:30:00Z
next_cursor string | null

Cursor for fetching the next page of results. Null if no more results.

Example MjAyMy0wMS0xNVQxMDozMDowMFp+dXNlckBleGFtcGxlLmNvbQ==
400 Bad request - invalid parameters object
error string required

Error message

401 Unauthorized - invalid or missing authentication token object
error string required

Error message

500 Internal server error object
error string required

Error message