MYmyclickfunnels
Contact

List Contacts

Changed on

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

Request

Path parameters

workspace_idstring required

Query parameters

afterstring

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

per_pageinteger

Records per page. Defaults to 20; raise it up to 100 for bulk reads. A larger value returns 100 records. Zero, a negative or a non-integer value is a 422. The Link next-page URL keeps the value, so a client following it keeps the page size. More 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), by the RefineFilter endpoints, or as a segment's filter_id. 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. Treat the returned token as opaque and let the HTTP client encode the complete query parameter value. With curl, use -G --data-urlencode "stable_id=$STABLE_ID"; do not decode the token or interpolate it directly into a raw URL. 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 contact filter (a segment's ContactsSegmentsFilter counts as one), or groups conditions with mixed and/or semantics. Flat filters and grouped filters using a single conjunction (including tokens copied from the filtered Contacts UI) are supported. 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

default_shipping_address_idinteger nullable

Read-only shipping entry ID; select it using default true on a shipping entry. Null when unset.

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 nullable

Whether the contact is active. Can be null immediately after creation. 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. Because it collapses several states into one flag, do not use it to detect deletion - check deleted_at instead.

deleted_atstring date-time nullable

When the contact was deleted. Deleting a contact is a soft delete: the record is excluded from list endpoints but remains readable by id, so a non-null value here is the only reliable way to tell that a contact returned by this endpoint has been deleted. Null when the contact has not been deleted.

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,
    "default_shipping_address_id": null,
    "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,
    "deleted_at": null,
    "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"
      }
    }
  }
]

Changes

  • 511d88b30aeaRevision changes
    • breaking

      the response property // became nullable for the status

    • info

      added the new optional query request parameter per_page

    • info

      for the path request parameter workspace_id, the type was generalized from integer to string

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      removed from the //// response property allOf list for the response status

    • info

      removed from the //// response property allOf list for the response status

    • info

      removed from the //// response property allOf list for the response status

    • info

      added subschema #2 to the //// response property anyOf list for the response status

    • info

      added subschema #2 to the //// response property anyOf list for the response status

    • info

      added subschema #2 to the //// response property anyOf list for the response status