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.

  • Maximum 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

  • Available 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

  • Available options: granted, denied, unknown
  • Example: denied
tracking_clicks_consent string

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

  • Available 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
  • Required range: x >= 1
  • Required range: x <= 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 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.

  • Available options: granted, denied, null
tracking_clicks_consent string | null

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

  • Available 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 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

  • Available 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 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