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
Bearer authentication header of the form Bearer <token>, where <token> is your API key.
Query Parameters
The ID of the workspace
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.
Filter by email (case-insensitive partial match)
Filter by external ID (case-insensitive partial match)
Filter by first name (case-insensitive partial match)
Filter by last name (case-insensitive partial match)
Filter by full name (case-insensitive partial match)
Filter by phone number (case-insensitive partial match)
Filter by country (case-insensitive partial match)
Filter by language (case-insensitive partial match)
Filter by list membership (contacts subscribed to this list)
Filter by subscription status within the list
Filter by the contact's open tracking choice; unknown matches contacts with none recorded
Filter by the contact's click tracking choice; unknown matches contacts with none recorded
Filter by segment membership (contacts in any of these segments)
Include contact list subscriptions in the response
Maximum number of contacts to return (1-100)
Pagination cursor from previous response
Response
200 Contacts retrieved successfully object
Array of contacts matching the query
Show 42 child attributes Hide 42 child attributes
Email address of the contact. This is the contact's unique identifier.
Identifier for the contact in your own system. Not unique — several contacts may share the same external_id.
Timezone of the contact
Preferred language of the contact
First name of the contact
Last name of the contact
Full name of the contact (for systems that don't have separate first/last names)
Phone number of the contact
First line of address
Second line of address
Country of the contact
Postal code
State or province
Job title of the contact
The contact's own choice about open tracking; null means unknown.
The contact's own choice about click tracking; null means unknown.
When a tracking choice last changed.
Where the last tracking choice came from (api, console, import, notification_center, email_link, subscribe_form).
Custom string field 1
Custom string field 2
Custom string field 3
Custom string field 4
Custom string field 5
Custom number field 1
Custom number field 2
Custom number field 3
Custom number field 4
Custom number field 5
Custom datetime field 1
Custom datetime field 2
Custom datetime field 3
Custom datetime field 4
Custom datetime field 5
Custom JSON field 1. Any JSON value, or null.
Custom JSON field 2. Any JSON value, or null.
Custom JSON field 3. Any JSON value, or null.
Custom JSON field 4. Any JSON value, or null.
Custom JSON field 5. Any JSON value, or null.
When the contact was created (read-only, set by server)
When the contact was last updated (read-only, set by server)
Lists the contact is subscribed to (read-only, included in GET responses only)
Show 7 child attributes Hide 7 child attributes
Email address of the contact
ID of the list
Name of the list
Subscription status
When the contact was subscribed to this list
When the subscription was last updated
When the subscription was deleted (null if active)
Segments the contact belongs to (read-only, included in GET responses only)
Show 5 child attributes Hide 5 child attributes
Email address of the contact
ID of the segment
Version of the segment computation
When the contact was matched to this segment
When the segment was last computed
Cursor for fetching the next page of results. Null if no more results.
400 Bad request - invalid parameters object
Error message
401 Unauthorized - invalid or missing authentication token object
Error message
500 Internal server error object
Error message