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
- Example: ws_1234567890
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.
- Maximum length: 100
- Example: john
Filter by email (case-insensitive partial match)
- Example: user@example
Filter by external ID (case-insensitive partial match)
- Example: user_123
Filter by first name (case-insensitive partial match)
- Example: John
Filter by last name (case-insensitive partial match)
- Example: Doe
Filter by full name (case-insensitive partial match)
- Example: John Doe
Filter by phone number (case-insensitive partial match)
- Example: +1555
Filter by country (case-insensitive partial match)
- Example: US
Filter by language (case-insensitive partial match)
- Example: en
Filter by list membership (contacts subscribed to this list)
- Example: newsletter
Filter by subscription status within the list
- Available options: active, pending, unsubscribed, bounced, complained
- Example: active
Filter by the contact's open tracking choice; unknown matches contacts with none recorded
- Available options: granted, denied, unknown
- Example: denied
Filter by the contact's click tracking choice; unknown matches contacts with none recorded
- Available options: granted, denied, unknown
- Example: unknown
Filter by segment membership (contacts in any of these segments)
Include contact list subscriptions in the response
- Default: false
- Example: true
Maximum number of contacts to return (1-100)
- Default: 20
- Required range: x >= 1
- Required range: x <= 100
- Example: 50
Pagination cursor from previous response
- Example: MjAyMy0wMS0xNVQxMDozMDowMFp+dXNlckBleGFtcGxlLmNvbQ==
Response
200 Contacts retrieved successfully object
Array of contacts matching the query
Show child attributes
Email address of the contact. This is the contact's unique identifier.
- Example: user@example.com
Identifier for the contact in your own system. Not unique — several contacts may share the same external_id.
- Example: user_12345
Timezone of the contact
- Example: America/New_York
Preferred language of the contact
- Example: en-US
First name of the contact
- Example: John
Last name of the contact
- Example: Doe
Full name of the contact (for systems that don't have separate first/last names)
- Example: John Doe
Phone number of the contact
- Example: +15551234567
First line of address
- Example: 123 Main St
Second line of address
- Example: Apt 4B
Country of the contact
- Example: US
Postal code
- Example: 10001
State or province
- Example: NY
Job title of the contact
- Example: Software Engineer
The contact's own choice about open tracking; null means unknown.
- Available options: granted, denied, null
The contact's own choice about click tracking; null means unknown.
- Available options: granted, denied, null
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
- Example: Premium tier
Custom string field 2
Custom string field 3
Custom string field 4
Custom string field 5
Custom number field 1
- Example: 42
Custom number field 2
Custom number field 3
Custom number field 4
Custom number field 5
Custom datetime field 1
- Example: 2023-06-01T09:00:00Z
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)
- Example: 2023-01-15T10:30:00Z
When the contact was last updated (read-only, set by server)
- Example: 2023-04-22T15:45:00Z
Lists the contact is subscribed to (read-only, included in GET responses only)
Show child attributes
Email address of the contact
- Example: user@example.com
ID of the list
- Example: newsletter
Name of the list
- Example: Newsletter
Subscription status
- Available options: active, pending, unsubscribed, bounced, complained
- Example: active
When the contact was subscribed to this list
- Example: 2023-01-15T10:30:00Z
When the subscription was last updated
- Example: 2023-01-15T10:30:00Z
When the subscription was deleted (null if active)
Segments the contact belongs to (read-only, included in GET responses only)
Show child attributes
Email address of the contact
- Example: user@example.com
ID of the segment
- Example: premium_users
Version of the segment computation
- Example: 1
When the contact was matched to this segment
- Example: 2023-01-15T10:30:00Z
When the segment was last computed
- Example: 2023-01-15T10:30:00Z
Cursor for fetching the next page of results. Null if no more results.
- Example: MjAyMy0wMS0xNVQxMDozMDowMFp+dXNlckBleGFtcGxlLmNvbQ==
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