> Calendly developer docs. For page Markdown, append .md to any URL.
> Index: https://developer.calendly.com/llms.txt
> API catalog: https://developer.calendly.com/.well-known/api-catalog
> OpenAPI: https://developer.calendly.com/openapi/calendly-api.yaml
> OAuth authorization server: https://calendly.com/.well-known/oauth-authorization-server
> MCP protected resource: https://mcp.calendly.com/.well-known/oauth-protected-resource
> Scheduling MCP endpoint: https://mcp.calendly.com
> Docs search MCP: https://developer.calendly.com/_mcp/server

# August 25, 2026

## 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.