Skip to main content

Update lead custom fields

Set custom field values on one existing Lead.

PATCH/api/leads/{lead_id}/custom-fields
HTTP referenceScope leads:writeUpdated September 27, 2026

This page documents the canonical HTTP contract for this endpoint.

Each provenance entry has required basis (source_evidence, model_inference, user_assumption, unknown) and nonblank rationale (max 2,000 chars), plus optional sources (up to 20; default []). A source requires kind (url, crm_record, user_statement, tool_result, model_run) and nonblank reference (max 2,000 chars); optional excerpt is max 2,000 chars. source_evidence requires at least one source. Extra nested properties are rejected (malformed nested input receives 422). Provenance keys must be value keys, and null values cannot include provenance (semantic errors return 400). Empty values are accepted. The route validates custom field keys and values against this organization’s Lead definitions. The response is a normalized Lead record (including fields beyond this excerpt).

Path parameters

  • lead_idrequired

    string

    Lead ID.

Body parameters

  • valuesrequired

    object

    Map of defined custom field keys to JSON values; an empty map is accepted, and empty strings clear a field.

  • provenance · optional

    object

    Optional keyed assertions. Each has basis (source_evidence, model_inference, user_assumption, unknown), required rationale, and optional sources array; defaults to {}.

Errors

StatusMeaning
400Invalid custom field values or provenance relationship.
401Invalid API key or missing auth.
403Missing leads:write scope.
404Lead not found.
422Request model or nested provenance is invalid.

Docs