Create or Update Lead
POST/v1/open-api/lead
Create a new lead, or update an existing one (distinguished by id). Processed
asynchronously — the endpoint returns a requestId to poll for the outcome.
Updates are partial down to the item level: absent keys (including keys inside
each contacts[] / fields[] item) are left unchanged, values update, and explicit
null clears. However, the contacts and fields lists themselves are sent in
full — when present they replace the whole set, so contacts/field-values missing
from the list are unlinked/deleted. See LeadCreateRequestDTO for the full rules.
Requires grant PERMISSION_OPEN_API_LEAD:SAVE.
Request
Responses
- 200
- 400
- 401
- 403
- 429
Request accepted and enqueued. Poll requestId for the result.
Validation error (400). Field-level failures are listed in errors[] and error is
null; a malformed / unparsable JSON body is the inverse — error.messageCode is
3705 and errors[] is empty.
Invalid, revoked or expired token (401) — also returned when the connection was
revoked or the company is blocked.
Produced by the authentication filter, so the body is a reduced envelope: no
error, no requestId, and errors is null rather than []. Every cause yields the
same fixed English message.
The token lacks the required permission:scope grant (403).
Rate limit of 60 requests/minute exceeded (429). Like 401, this comes from the
authentication filter: reduced envelope, fixed English message, no error object and no
Retry-After header.