Expanding

Some API responses exclude certain properties by default to keep payloads smaller for faster and more efficient transmission. Use the expand[] query parameter to include these optional fields when you need them.

How it works

Add expand[]=field_name as a query parameter to any endpoint that supports it. You can expand multiple fields by repeating the parameter.

GET /api/v2/contacts/{id}?expand[]=email_engagement
GET /api/v2/funnels/{id}?expand[]=head_code&expand[]=footer_code

When a field is not expanded, its key is completely absent from the response — it does not appear as null. When expanded, the key and its value are included.

Available expandable fields

Check each endpoint's API reference to see which expand fields it supports.

Examples

Expanding a single field

curl 'https://myworkspace.myclickfunnels.com/api/v2/contacts/24359?expand[]=email_engagement' \
  -H 'Authorization: Bearer {token}'

Expanding multiple fields

curl 'https://myworkspace.myclickfunnels.com/api/v2/funnels/42?expand[]=head_code&expand[]=footer_code' \
  -H 'Authorization: Bearer {token}'

You can expand just one of the two — for example, expand[]=head_code alone will include head_code but omit footer_code.

Expanding on collection endpoints

Expand works on both single-resource and list endpoints. When used on a list endpoint, every resource in the response includes the expanded fields:

curl 'https://myworkspace.myclickfunnels.com/api/v2/workspaces/100/contacts?expand[]=email_engagement' \
  -H 'Authorization: Bearer {token}'

Combining with other query parameters

Expand works alongside filtering, sorting, and pagination:

curl 'https://myworkspace.myclickfunnels.com/api/v2/workspaces/100/contacts?filter[email_address][email protected]&expand[]=email_engagement&sort_order=asc&after=24350' \
  -H 'Authorization: Bearer {token}'

Expanding on create and update responses

You can also use expand[] on POST and PUT requests. The expanded fields will be included in the response after the resource is created or updated:

curl -X PUT 'https://myworkspace.myclickfunnels.com/api/v2/contacts/24359?expand[]=email_engagement' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{"contact": {"first_name": "Jane"}}'

Where expanding does not apply

Expanded fields are not included in:

• Webhook payloads — Objects sent in webhook events always use the minimal form. To access expanded data, make a separate API call within your webhook handler.
• Nested resources — When a resource appears nested inside another response (for example, an order embedded within an invoice), expanded fields are not included in the nested representation. Fetch the resource directly to get its expanded fields.

Performance and payload

Only expand fields you actually need when you need them. Expanding adds processing time to your requests, especially on collection endpoints where the cost applies to every item in the response.