openapi: 3.2.0 info: title: ClickFunnels Contact API termsOfService: https://www.clickfunnels.com/terms-of-service contact: name: ClickFunnels API Team url: https://developers.myclickfunnels.com x-logo: url: https://statics.myclickfunnels.com/image/1126065/file/31edf05760fafe41a82f16a668ab251f.png description: 'The ClickFunnels REST API that powers webhooks, native integrations, and Zapier lets you manage your ClickFunnels data, automate your workflows, and recreate ClickFunnels functionality in your own apps. ' license: name: MIT url: https://opensource.org/licenses/MIT version: 2.0.0 servers: - url: https://{subdomain}.myclickfunnels.com/api/v2 description: ClickFunnels API variables: subdomain: default: myworkspace security: - BearerAuth: [] tags: - name: Contact description: Contact paths: /workspaces/{workspace_id}/contacts: get: tags: - Contact summary: List Contacts description: List contacts for the given workspace. By default, only identified contacts are shown so you won't see anonymous or GDPR-redacted contacts. operationId: listContacts parameters: - name: workspace_id in: path required: true schema: type: string - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/sort_order' - $ref: '#/components/parameters/sort_property' - name: filter in: query description: '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](https://developers.myclickfunnels.com/docs/filtering). ' required: false schema: type: object properties: email_address: type: string description: A comma-separated list of email addresses to filter by. example: russel@clickfunnels.com,todd@clickfunnels.com id: type: string description: A comma-separated list of contact IDs to filter by. example: 1,42 tag_ids: type: string description: A comma-separated list of Contacts::Tag IDs to filter contacts that had those tags applied to them. example: 1,42 is_active: type: boolean description: Filter contacts by their active status. Pass true to return only active contacts, or false to return only inactive contacts. example: true style: deepObject explode: true - name: stored_filter_id in: query required: false schema: type: string description: '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.' - name: stable_id in: query required: false schema: type: string description: '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 ContactsFilter, 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.' - $ref: '#/components/parameters/ExpandContactFields' responses: '200': description: OK headers: Pagination-Next: $ref: '#/components/headers/PaginationNext' Link: $ref: '#/components/headers/Link' content: application/json: schema: type: array items: $ref: '#/components/schemas/ContactAttributes' example: - 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' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: error: API key missing or invalid '404': description: Not Found content: application/json: schema: type: object properties: error: type: string description: Not found - This usually happens when you try to access a record that does not exist in your account. It can also happen when the provided parent record is missing, e.g. you have put in a non-existent Workspaces parent ID. example: error: 'Not found: Record missing' '422': description: Unprocessable Entity — `stored_filter_id` is unknown, invalid, or belongs to a different workspace; or `stable_id` is not a valid Refine token, is not a ContactsFilter, or groups conditions with mixed `and`/`or` semantics. Flat and single-conjunction grouped stable-id filters are supported. content: application/json: schema: type: object properties: error: type: string example: error: stored_filter_id is invalid or does not belong to this workspace post: tags: - Contact summary: Create Contact description: Add a new contact to the workspace operationId: createContacts parameters: - name: workspace_id in: path required: true schema: type: string - $ref: '#/components/parameters/ExpandContactFields' requestBody: description: Information about a new Contact required: true content: application/json: schema: type: object properties: contact: type: object $ref: '#/components/schemas/ContactParameters' example: contact: email_address: test-4059727ec8e173ce4648@example.com first_name: Sol last_name: Jones phone_number: (224) 508-1342 x59891 time_zone: Pacific Time (US & Canada) fb_url: https://www.facebook.com/example twitter_url: https://twitter.com/example instagram_url: null linkedin_url: https://www.linkedin.com/in/example website_url: https://example.com responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ContactAttributes' example: 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' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: error: 'Bad request: HTTP body must be valid JSON' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: error: API key missing or invalid /contacts/{id}: get: tags: - Contact summary: Fetch Contact description: Retrieve a contact operationId: getContacts parameters: - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/ExpandContactFields' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ContactAttributes' example: 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' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: error: API key missing or invalid '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: error: 'Not found: Record missing' put: tags: - Contact summary: Update Contact description: Update a contact operationId: updateContacts parameters: - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/ExpandContactFields' requestBody: description: Information about updated fields in Contact required: true content: application/json: schema: type: object properties: contact: type: object $ref: '#/components/schemas/ContactParametersUpdate' example: contact: email_address: test-4059727ec8e173ce4648@example.com first_name: Sol last_name: Jones phone_number: (224) 508-1342 x59891 time_zone: Pacific Time (US & Canada) fb_url: https://www.facebook.com/example twitter_url: https://twitter.com/example instagram_url: null linkedin_url: https://www.linkedin.com/in/example website_url: https://example.com responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ContactAttributes' example: 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' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: error: 'Bad request: HTTP body must be valid JSON' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: error: API key missing or invalid '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: error: 'Not found: Record missing' delete: tags: - Contact summary: Remove Contact description: Delete a contact operationId: removeContacts parameters: - $ref: '#/components/parameters/id' responses: '204': description: No Content '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: error: API key missing or invalid '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: error: 'Not found: Record missing' /contacts/{id}/gdpr_destroy: delete: tags: - Contact summary: Redact Contact description: This will destroy all personally identifiable information for a contact, including their name and phone number, but does not delete the contact record itself. This cannot be undone. operationId: gdpr_destroyContacts parameters: - $ref: '#/components/parameters/id' responses: '200': description: OK '404': description: Not Found /workspaces/{workspace_id}/contacts/upsert: post: tags: - Contact summary: Upsert a Contact description: Creates or updates a Contact, matching on the email address. If the Contact does not exist, it will be created. If the Contact does exist, it will be updated. It is not possible to delete a Contact via this endpoint. It is not possible to reset properties of a Contact by passing empty values. E.g. passing `null` for `first_name` or an empty array for `tag_ids` won't update previous values. To do that you would instead need to use the `Update Contact` endpoint. operationId: upsertContacts parameters: - name: workspace_id in: path required: true schema: type: string - $ref: '#/components/parameters/ExpandContactFields' requestBody: description: Contact to create or update, matching on the email address. Note that properties of a Contact are not reset when passed empty values, e.g. passing `null` for `first_name` or an empty array for `tag_ids` won't update previous values. To do that you would instead use the `Update Contact` endpoint. required: true content: application/json: schema: type: object properties: contact: type: object $ref: '#/components/schemas/ContactParameters' example: contact: email_address: test-4059727ec8e173ce4648@example.com first_name: Sol last_name: Jones phone_number: (224) 508-1342 x59891 time_zone: Pacific Time (US & Canada) fb_url: https://www.facebook.com/example twitter_url: https://twitter.com/example instagram_url: null linkedin_url: https://www.linkedin.com/in/example website_url: https://example.com responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ContactAttributes' example: 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' '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ContactAttributes' example: 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' '400': description: Bad Request content: application/json: schema: type: object properties: error: type: string example: error: 'Bad request: HTTP body must be valid JSON' '401': description: Unauthorized content: application/json: schema: type: object properties: error: type: string example: error: API key missing or invalid '404': description: Not Found content: application/json: schema: type: object properties: error: type: string example: error: 'Not found: Record missing' components: parameters: id: name: id in: path required: true schema: type: string sort_property: name: sort_property in: query description: '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. ' required: false schema: type: string enum: - id - updated_at sort_order: name: sort_order in: query description: Sort order of a list response. Use 'desc' to reverse the default 'asc' (ascending) sort order. Examples [in our guides](https://developers.myclickfunnels.com/docs/pagination). required: false schema: type: string enum: - asc - desc ExpandContactFields: name: expand[] in: query description: Expand additional data in the response. Use `expand[]=field_name` to include optional fields (e.g., `expand[]=email_engagement`). See the [Expanding guide](https://developers.myclickfunnels.com/docs/expand) for available fields and examples. required: false schema: type: array items: type: string enum: - email_engagement after: name: after in: query required: false schema: type: string description: ID of item after which the collection should be returned. More examples and info about pagination [in our guides](https://developers.myclickfunnels.com/docs/pagination). schemas: VisitAttributes: type: object title: Visit description: Visit tracking information including UTM parameters and device data properties: uuid: type: string description: Unique identifier for the visit utm_source: type: - string - 'null' description: UTM source parameter from the visit URL utm_medium: type: - string - 'null' description: UTM medium parameter from the visit URL utm_campaign: type: - string - 'null' description: UTM campaign parameter from the visit URL utm_term: type: - string - 'null' description: UTM term parameter from the visit URL utm_content: type: - string - 'null' description: UTM content parameter from the visit URL ip: type: - string - 'null' description: IP address of the visitor user_agent: type: - string - 'null' description: User agent string from the visitor's browser referrer: type: - string - 'null' description: HTTP referrer URL referring_domain: type: - string - 'null' description: Domain extracted from the referrer URL landing_page: type: - string - 'null' description: The first page URL visited in this session browser: type: - string - 'null' description: Browser name detected from user agent os: type: - string - 'null' description: Operating system detected from user agent device_type: type: - string - 'null' description: Device type (e.g., desktop, mobile, tablet) started_at: type: - string - 'null' format: date-time description: Timestamp when the visit session started created_at: type: string format: date-time description: Timestamp when the visit record was created updated_at: type: string format: date-time description: Timestamp when the visit record was last updated example: 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' required: - browser - created_at - device_type - ip - landing_page - os - referrer - referring_domain - started_at - updated_at - user_agent - utm_campaign - utm_content - utm_medium - utm_source - utm_term - uuid ContactParametersUpdate: type: object title: Contacts description: Contacts required: [] properties: email_address: type: - string - 'null' description: Email address first_name: type: - string - 'null' description: First name last_name: type: - string - 'null' description: Last name phone_number: type: - string - 'null' description: Phone number time_zone: type: - string - 'null' description: '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.](https://dash.readme.com/project/cf2/v2/docs/timezones). ' fb_url: type: - string - 'null' description: Facebook URL twitter_url: type: - string - 'null' description: Twitter URL instagram_url: type: - string - 'null' description: Instagram URL linkedin_url: type: - string - 'null' description: LinkedIn URL website_url: type: - string - 'null' description: Website URL tag_ids: type: array items: type: integer description: Contact Tag IDs. Any valid array, empty or with valid tags will overwrite existing values. To avoid losing existing tags first use the Fetch Contact endpoint, then be sure to include the existing tags in your payload along with any new addition(s). custom_attributes: type: object additionalProperties: type: string description: 'Custom attributes are usually added in ClickFunnels to a contact when they submit forms that contain custom contact attributes. Here you can directly create them during contact modification. Custom attributes are provided as key-value pairs: A key that does not exist, will create a new custom contact attribute. A key that already exists, will update the value of an existing custom contact attribute. Empty or null values, will set the custom attribute values to empty strings. A key that has special characters or spaces will be automatically converted to `snake_case` (For example, ''Favorite Food! 🥑'' will be converted to ''favorite_food''). Empty keys will trigger a bad request response. Also, non-object inputs for custom_attributes (e.g. an array or string), it will be ignored. Keys that are default properties on the Contact resource or variations of it will result in an error. E.g., ''first_name'', ''First Name'', etc. are not valid inputs. ' example: contact: email_address: test-4059727ec8e173ce4648@example.com first_name: Sol last_name: Jones phone_number: (224) 508-1342 x59891 time_zone: Pacific Time (US & Canada) fb_url: https://www.facebook.com/example twitter_url: https://twitter.com/example instagram_url: null linkedin_url: https://www.linkedin.com/in/example website_url: https://example.com VisitsAttributes: type: object title: Visits description: Collection of visit tracking records for a contact, including first visit, last visit, and last visit with UTM parameters properties: first_visit: description: The first visit associated with this contact. anyOf: - $ref: '#/components/schemas/VisitAttributes' - type: 'null' last_visit: description: The most recent visit. May be null if it is identical to first_visit (to avoid duplication). anyOf: - $ref: '#/components/schemas/VisitAttributes' - type: 'null' last_visit_with_utm: description: The most recent visit that contains UTM parameters. anyOf: - $ref: '#/components/schemas/VisitAttributes' - type: 'null' required: - first_visit - last_visit - last_visit_with_utm ContactBaseAttributes: type: object title: Contacts description: Contacts properties: id: type: integer description: Contact ID public_id: type: string description: Contact public ID workspace_id: type: integer description: Workspace ID anonymous: type: - integer - 'null' description: Anonymous email_address: type: - string - 'null' description: The contact's email address. It is currently not expected to be null and is the main identifier for a contact. first_name: type: - string - 'null' description: First name last_name: type: - string - 'null' description: Last name phone_number: type: - string - 'null' description: Phone number time_zone: type: - string - 'null' description: '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.](https://dash.readme.com/project/cf2/v2/docs/timezones). ' uuid: type: string description: UUID unsubscribed_at: type: - string - 'null' description: Unsubscribed last_notification_email_sent_at: type: - string - 'null' description: Last notification email sent email_suppression_reason: type: - string - 'null' description: The reason the contact's email address is suppressed from receiving emails. Null when no suppression exists. is_active: type: boolean description: 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_url: type: - string - 'null' description: Facebook URL twitter_url: type: - string - 'null' description: Twitter URL instagram_url: type: - string - 'null' description: Instagram URL linkedin_url: type: - string - 'null' description: LinkedIn URL website_url: type: - string - 'null' description: Website URL created_at: type: string format: date-time description: Date added updated_at: type: string format: date-time description: Last updated tags: type: - array - 'null' items: type: object title: Contact Tags description: Contact Tags properties: id: type: integer description: Tag ID public_id: type: string description: Tag public ID name: type: string description: Name color: type: string description: Color applied_at: type: - string - 'null' description: The datetime the tag was applied by creating a Contacts::AppliedTag that maps the tag to the contact. description: Contact Tags custom_attributes: type: object additionalProperties: type: string description: 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. visits: allOf: - $ref: '#/components/schemas/VisitsAttributes' description: Visit tracking information for this contact, including first visit, last visit, and last visit with UTM parameters example: 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' required: - anonymous - created_at - custom_attributes - email_address - email_suppression_reason - fb_url - first_name - id - instagram_url - is_active - last_name - last_notification_email_sent_at - linkedin_url - phone_number - public_id - tags - time_zone - twitter_url - unsubscribed_at - updated_at - uuid - visits - website_url - workspace_id ContactParameters: type: object title: Contacts description: Contacts required: [] properties: email_address: type: - string - 'null' description: Email address first_name: type: - string - 'null' description: First name last_name: type: - string - 'null' description: Last name phone_number: type: - string - 'null' description: Phone number time_zone: type: - string - 'null' description: '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.](https://dash.readme.com/project/cf2/v2/docs/timezones). ' fb_url: type: - string - 'null' description: Facebook URL twitter_url: type: - string - 'null' description: Twitter URL instagram_url: type: - string - 'null' description: Instagram URL linkedin_url: type: - string - 'null' description: LinkedIn URL website_url: type: - string - 'null' description: Website URL tag_ids: type: array items: type: integer description: Contact Tag IDs. Any valid array, empty or with valid tags will overwrite existing values. To avoid losing existing tags first use the Fetch Contact endpoint, then be sure to include the existing tags in your payload along with any new addition(s). custom_attributes: type: object additionalProperties: type: string description: 'Custom attributes are usually added in ClickFunnels to a contact when they submit forms that contain custom contact attributes. Here you can directly create them during contact modification. Custom attributes are provided as key-value pairs: A key that does not exist, will create a new custom contact attribute. A key that already exists, will update the value of an existing custom contact attribute. Empty or null values, will set the custom attribute values to empty strings. A key that has special characters or spaces will be automatically converted to `snake_case` (For example, ''Favorite Food! 🥑'' will be converted to ''favorite_food''). Empty keys will trigger a bad request response. Also, non-object inputs for custom_attributes (e.g. an array or string), it will be ignored. Keys that are default properties on the Contact resource or variations of it will result in an error. E.g., ''first_name'', ''First Name'', etc. are not valid inputs. ' example: contact: email_address: test-4059727ec8e173ce4648@example.com first_name: Sol last_name: Jones phone_number: (224) 508-1342 x59891 time_zone: Pacific Time (US & Canada) fb_url: https://www.facebook.com/example twitter_url: https://twitter.com/example instagram_url: null linkedin_url: https://www.linkedin.com/in/example website_url: https://example.com ContactAttributes: allOf: - $ref: '#/components/schemas/ContactBaseAttributes' type: object title: Contacts description: Contacts properties: email_engagement: type: object description: '**Expandable** Email engagement timestamps. Only included when `expand[]=email_engagement` is passed. See the [Expanding guide](https://developers.myclickfunnels.com/docs/expand) for details.' properties: last_email_sent_at: type: - string - 'null' format: date-time description: The datetime of the last email sent to this contact. last_email_opened_at: type: - string - 'null' format: date-time description: The datetime of the last email opened by this contact. last_email_clicked_at: type: - string - 'null' format: date-time description: The datetime of the last email link clicked by this contact. example: 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' required: - anonymous - created_at - custom_attributes - email_address - email_suppression_reason - fb_url - first_name - id - instagram_url - is_active - last_name - last_notification_email_sent_at - linkedin_url - phone_number - public_id - tags - time_zone - twitter_url - unsubscribed_at - updated_at - uuid - visits - website_url - workspace_id headers: Link: description: A direct link to the next page for the cursor-based pagination. It includes the `after` and the Pagination-Next ID value. schema: type: string PaginationNext: description: ID of the last item in the current response after which more records exist. You can use it in an `after` query parameter for cursor-based pagination to get to the next page. schema: type: string securitySchemes: BearerAuth: type: http scheme: bearer externalDocs: description: More in-depth guides and further resources url: https://developers.myclickfunnels.com