Skip to main content
GET
/
api
/
contacts.list
List contacts with filtering and pagination
curl --request GET \
  --url https://{notifuseDomain}/api/contacts.list \
  --header 'Authorization: Bearer <token>'
{
  "contacts": [
    {
      "email": "[email protected]",
      "external_id": "user_12345",
      "timezone": "America/New_York",
      "language": "en-US",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "phone": "+15551234567",
      "address_line_1": "123 Main St",
      "address_line_2": "Apt 4B",
      "country": "US",
      "postcode": "10001",
      "state": "NY",
      "job_title": "Software Engineer",
      "custom_string_1": "Premium tier",
      "custom_string_2": "<string>",
      "custom_string_3": "<string>",
      "custom_string_4": "<string>",
      "custom_string_5": "<string>",
      "custom_number_1": 42,
      "custom_number_2": 123,
      "custom_number_3": 123,
      "custom_number_4": 123,
      "custom_number_5": 123,
      "custom_datetime_1": "2023-06-01T09:00:00Z",
      "custom_datetime_2": "2023-11-07T05:31:56Z",
      "custom_datetime_3": "2023-11-07T05:31:56Z",
      "custom_datetime_4": "2023-11-07T05:31:56Z",
      "custom_datetime_5": "2023-11-07T05:31:56Z",
      "custom_json_1": {
        "preferences": {
          "theme": "dark",
          "notifications": true
        }
      },
      "custom_json_2": {},
      "custom_json_3": {},
      "custom_json_4": {},
      "custom_json_5": {},
      "created_at": "2023-01-15T10:30:00Z",
      "updated_at": "2023-04-22T15:45:00Z",
      "contact_lists": [
        {
          "email": "[email protected]",
          "list_id": "newsletter",
          "list_name": "Newsletter",
          "status": "active",
          "created_at": "2023-01-15T10:30:00Z",
          "updated_at": "2023-01-15T10:30:00Z",
          "deleted_at": null
        }
      ],
      "contact_segments": [
        {
          "email": "[email protected]",
          "segment_id": "premium_users",
          "version": 1,
          "matched_at": "2023-01-15T10:30:00Z",
          "computed_at": "2023-01-15T10:30:00Z"
        }
      ]
    }
  ],
  "next_cursor": "MjAyMy0wMS0xNVQxMDozMDowMFp+dXNlckBleGFtcGxlLmNvbQ=="
}

Authorizations

​
Authorization
string
header
required

API token for authentication

Query Parameters

​
workspace_id
string
required

The ID of the workspace

​
email
string

Filter by email (case-insensitive partial match)

​
external_id
string

Filter by external ID (case-insensitive partial match)

​
first_name
string

Filter by first name (case-insensitive partial match)

​
last_name
string

Filter by last name (case-insensitive partial match)

​
full_name
string

Filter by full name (case-insensitive partial match)

​
phone
string

Filter by phone number (case-insensitive partial match)

​
country
string

Filter by country (case-insensitive partial match)

​
language
string

Filter by language (case-insensitive partial match)

​
list_id
string

Filter by list membership (contacts subscribed to this list)

​
contact_list_status
enum<string>

Filter by subscription status within the list

Available options:
active,
pending,
unsubscribed,
bounced,
complained
​
segments[]
string[]

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

​
with_contact_lists
boolean
default:false

Include contact list subscriptions in the response

​
limit
integer
default:20

Maximum number of contacts to return (1-100)

Required range: 1 <= x <= 100
​
cursor
string

Pagination cursor from previous response

Response

Contacts retrieved successfully

​
contacts
object[]

Array of contacts matching the query

​
next_cursor
string | null

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

Example:

"MjAyMy0wMS0xNVQxMDozMDowMFp+dXNlckBleGFtcGxlLmNvbQ=="