Changelog

Contact custom fields API and webhooks

Read your organization’s Contact custom field definitions and read and write custom field values directly on Contact records. Custom fields capture user-defined and organization-defined data (e.g. lead source, estimated contract value, customer segment, renewal date, fields mapped from event-type invitee questions). Values are returned as self-describing entries so a consumer can render a Contact without a second lookup, and they flow through the same Contact reads, writes, and lifecycle webhooks you already use.

New endpoints:

• GET /contacts/custom_field_definitions – List custom field definitions, including uri, label, field_type (text, number, currency, tags, date, single_select, or invitee_question), created_at, updated_at, and type-specific metadata such as options and currency.
• GET /contacts/custom_field_definitions/{uuid} – Retrieve a single custom field definition.

Updated Contact endpoints:

• GET /contacts and GET /contacts/{contact_uuid} – Now return a custom_fields array by default. Each entry carries the field’s uri, label, and value. Every defined field is included, with unset scalars as null and unset arrays as []. Pass exclude to trim custom_fields from the payload.
• POST /contacts – Now accepts custom_fields. Each entry sends only uuid and value; label and schema fields are ignored on write.
• PATCH /contacts/{contact_uuid} – Now accepts partial custom_fields updates using merge semantics. Include an entry only for fields you are changing, send value: null to clear a scalar, and value: [] to clear a tags field.

Updated webhook events:

• contact.created – Payload now includes the custom_fields array, with an entry for every defined field.
• contact.updated – Payload now includes the custom_fields array, so subscribers can distinguish a cleared value from an absent one. Treat the payload as a full representation.
• contact.deleted – Unchanged. Delete events carry no custom fields.

Notes:

• Custom fields use the existing contacts:read and contacts:write scopes. No new scopes are introduced.
• Values are validated against their definitions. Writes referencing an unknown or retired field uuid are rejected.
• Currency values are integer minor units (8500000 is $85,000.00), with the currency code held on the definition. Tags fields are free-form string arrays with no controlled vocabulary.