Sign in

v1

latestOpenAPI 3.1.0MIT2026-07-243952451019.0 KB
Contact

List Contacts

List contacts for the given workspace. By default, only identified contacts are shown so you won't see anonymous or GDPR-redacted contacts.

get/workspaces/{workspace_id}/contacts

Path parameters

workspace_idinteger required

Query parameters

afterstring

ID of item after which the collection should be returned. More examples and info about pagination in our guides.

sort_order'asc' | 'desc'

Sort order of a list response. Use 'desc' to reverse the default 'asc' (ascending) sort order. Examples in our guides.

sort_property'id' | 'updated_at'

Sort property of a list response. The default is id and thus the created_at order. If you sort by other properties, we additionally sort by id implicitly as a secondary sort property, so that you can rely on the sort order to be deterministic even if the main sort property ends up with the same values.

email_addressstring

A comma-separated list of email addresses to filter by.

idstring

A comma-separated list of contact IDs to filter by.

tag_idsstring

A comma-separated list of Contacts::Tag IDs to filter contacts that had those tags applied to them.

is_activeboolean

Filter contacts by their active status. Pass true to return only active contacts, or false to return only inactive contacts.

Filter by available properties in query params, like this: api/v2/resources?filter[id]=value&filter[another_property]=value1,value2. Check our Filtering guide for examples and all about filtering here.

{
  "email_address": "russel@clickfunnels.com,todd@clickfunnels.com",
  "id": "1,42",
  "tag_ids": "1,42",
  "is_active": true
}
stored_filter_idstring

The id (integer) or public_id (string) of a saved Refine::StoredFilter scoped to this workspace. Returned by POST /api/v2/workspaces/{workspace_id}/contacts/filters (with save: true) or by the RefineFilter endpoints. Applies the saved filter's criteria to the results, composed (AND) with any filter[…] params. Returns 422 if the filter is unknown, invalid, or belongs to a different workspace. When both stored_filter_id and stable_id are supplied, stable_id takes precedence.

stable_idstring

A URL-encoded Refine stable_id token — the standard gzip+base64 full-state format used by both the contacts/filters API endpoint and the server-rendered filter UI, making the tokens interoperable. Returned by POST /api/v2/workspaces/{workspace_id}/contacts/filters in the stable_id field. Applies the encoded filter criteria to the results, composed (AND) with any filter[…] params. Returns 422 if the token is not a valid Refine stable_id, is not a ContactsFilter, or uses grouped/nested or or conditions disallowed by the public-API SafeConditionPolicy. When both stored_filter_id and stable_id are supplied, stable_id takes precedence.

expand[]string[]

Expand additional data in the response. Use expand[]=field_name to include optional fields (e.g., expand[]=email_engagement). See the Expanding guide for available fields and examples.

Response

OK

idinteger

Contact ID

public_idstring

Contact public ID

workspace_idinteger

Workspace ID

anonymousinteger nullable

Anonymous

email_addressstring nullable

The contact's email address. It is currently not expected to be null and is the main identifier for a contact.

first_namestring nullable

First name

last_namestring nullable

Last name

phone_numberstring nullable

Phone number

time_zonestring nullable

The human-readable time zone, usually set dynamically by the app for the contact, for example, during opt-in. Read more about time zones and how to map them back to the TZ standard in our Time Zones guide..

uuidstring

UUID

unsubscribed_atstring nullable

Unsubscribed

last_notification_email_sent_atstring nullable

Last notification email sent

email_suppression_reasonstring nullable

The reason the contact's email address is suppressed from receiving emails. Null when no suppression exists.

is_activeboolean

Whether the contact is active. A contact is considered active when they have a valid email address, have not unsubscribed, have not been deleted, and have no email suppression reason.

fb_urlstring nullable

Facebook URL

twitter_urlstring nullable

Twitter URL

instagram_urlstring nullable

Instagram URL

linkedin_urlstring nullable

LinkedIn URL

website_urlstring nullable

Website URL

created_atstring date-time

Date added

updated_atstring date-time

Last updated

custom_attributesobject

A dynamic key-value pair object where both the key and value are strings. Custom attributes are usually added to the contact when they submit forms that contain custom contact attributes. But you can also add them via the API using the modifying endpoints like Create/Update/Upsert Contact.

Example response

[
  {
    "id": 24359,
    "public_id": "vQxYMj",
    "workspace_id": 4,
    "anonymous": 0,
    "email_address": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone_number": "+18005550199",
    "time_zone": "Madrid",
    "uuid": "80b7f903-76cd-4edf-94bf-fc34c13ee654",
    "unsubscribed_at": null,
    "last_notification_email_sent_at": null,
    "email_suppression_reason": null,
    "is_active": true,
    "fb_url": null,
    "twitter_url": null,
    "instagram_url": null,
    "linkedin_url": null,
    "website_url": null,
    "created_at": "2026-01-09T15:27:56.647Z",
    "updated_at": "2026-01-09T15:28:08.075Z",
    "tags": [],
    "custom_attributes": {},
    "visits": {
      "first_visit": {
        "uuid": "9f2e8a22-1b65-4414-95f3-5caf0bbd11da",
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "spring_sale",
        "utm_term": "running shoes",
        "utm_content": "ad_variant_a",
        "ip": "192.168.1.1",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        "referrer": "https://www.google.com/search?q=example",
        "referring_domain": "google.com",
        "landing_page": "https://example.com/products/shoes",
        "browser": "Chrome",
        "os": "Mac OS X",
        "device_type": "desktop",
        "started_at": "2026-01-09T14:23:45.123Z",
        "created_at": "2026-01-09T14:23:45.123Z",
        "updated_at": "2026-01-09T14:23:45.123Z"
      },
      "last_visit": null,
      "last_visit_with_utm": {
        "uuid": "9f2e8a22-1b65-4414-95f3-5caf0bbd11da",
        "utm_source": "google",
        "utm_medium": "cpc",
        "utm_campaign": "spring_sale",
        "utm_term": "running shoes",
        "utm_content": "ad_variant_a",
        "ip": "192.168.1.1",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
        "referrer": "https://www.google.com/search?q=example",
        "referring_domain": "google.com",
        "landing_page": "https://example.com/products/shoes",
        "browser": "Chrome",
        "os": "Mac OS X",
        "device_type": "desktop",
        "started_at": "2026-01-09T14:23:45.123Z",
        "created_at": "2026-01-09T14:23:45.123Z",
        "updated_at": "2026-01-09T14:23:45.123Z"
      }
    }
  }
]