Filter Lead History
POST/v1/open-api/lead-event/filter
A combined timeline: changes on a lead, changes on its contacts, notes written
on it, and its closed/overdue tasks — all merged onto one time axis. This is the
data behind the "history" feed on a lead's card in the uysot app.
Same page/size/orders shape as every other POST .../filter endpoint — the
lead is not in the URL, it is the optional leadIds field of
LeadEventFilterDTO. Omit it (or send an empty array) to get company-wide
history: every lead's events, contact events, notes and tasks on one time axis.
Records are gathered from four sources into one set first, then paginated with a
plain COUNT + LIMIT/OFFSET — same two-phase pattern as /lead/filter.
Returns a paginated PageableData of records.
Narrow the timeline with leadIds, dataTypes, employeeIds, actionTypes and
the eventTimestampFrom/eventTimestampTo range — all combined with AND, each one skipped
when omitted or empty. Note that actionTypes only exists on event records, so
using it leaves notes and tasks out of the response.
⚠️ A page can hold fewer than size elements without that meaning history has
ended — a row whose payload could not be resolved (e.g. a lead_event row with no
matching change record) is silently dropped from the page, though
totalElements/totalPages still count it.
Requires grant PERMISSION_OPEN_API_LEAD:READ — the history belongs to the lead,
no separate grant is required.
Request
Responses
- 200
- 400
- 401
- 403
- 429
Page of matching history records.
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.