Skip to main content

Upsert lead field values

POST 
/v1/open-api/lead/:leadId/field/list

Batch upsert of a lead's custom (CRM) field values — update or add one or more fields in a single request. Processed asynchronously — the endpoint returns a requestId to poll for the outcome.

Partial by design. Only the fields present in the array are updated or added; every other field value on the lead is left untouched. This is deliberately different from the fields list in POST /v1/open-api/lead, where the array is taken as the complete set and any value not listed is deleted. Use this endpoint whenever you only want to change some of a lead's fields.

⚠️ Lead fields only. This endpoint updates lead-level fields exclusively — fields whose infoType is LED (see GET /v1/open-api/crm-field). Items that reference a contact field (infoType: CONTACT) or an unknown field id are silently skipped: no error is returned and the request still completes as SUCCESS. To update a contact's fields, use the contacts[].fields key of POST /v1/open-api/lead instead.

Per-item rules:

  • id (the CRM field identifier) is required on every item; missing it returns 400 (NOT_NULL).
  • Send an explicit "value": null to clear (delete) that field's value.
  • For multi-select fields send the selected values in valueList ({ "id": 172, "valueList": ["A", "B"] }); the server expands each value into its own entry. The list fully replaces the field's previous selection.

See FieldValueRequestDTO for the full per-key semantics.

Requires grant PERMISSION_OPEN_API_LEAD:SAVE.

Request​

Responses​

Request accepted and enqueued. Poll requestId for the result.