Skip to content

Events

Events endpoints: parameters, fields and example responses.

Developer documentation

Reads the event feed

GET /api/v1/events

Scope: events:read

The events of the account, in order. The payload is thin (IDs, status, days); the detail is read from the endpoint of the resource. Only an account-wide key can read it. A key receives only the events it can see: a type that needs a resource scope (employee, unit, leave, shift, roster) also needs that scope; every type arrives only when its module is on in the account and the role of the key can view that module. The days of the physician availability type come from leave: it also needs the leave:read scope, the leave module on and a role that can view leave. An event that is not visible is skipped: a gap between sequence values tells the total number of events not visible in between, not their type. Pages are read with next_cursor; after the last page, continue by sending the last sequence you saw in after. Events are kept for 30 days and order is not guaranteed: deduplicate by id. A request scans a bounded range of sequences: a page can be short or empty; keep reading while next_cursor is set. In the event of a leave request with a hidden type the type is empty, "awaiting document" shows as pending and a rejection shows as a cancellation event.

Parameters

events.list: Parameters
FieldTypeDescription
after (query)stringOnly events with a sequence greater than this. Starts from the oldest retained event when omitted.
cursor (query)stringThe next_cursor value of the previous response. It is opaque; send it with the same key and the same filter.
limit (query)integerPage size; a value above the maximum is lowered to the maximum.

Responses

200 Successful

A list response comes in the { data, next_cursor } envelope.

events.list: Each item in the list (data[])
FieldTypeDescription
idstring (uuid)requiredID of the event; deduplicate with it.
sequenceintegerrequiredIncreasing sequence inside the account.
typestringrequiredEvent type (event catalogue). Values: employee.created, employee.updated, employee.started, employee.terminated, org_unit.changed, leave.request.created, leave.request.approved, leave.request.rejected, leave.request.cancelled, overtime.request.approved, shift.plan.published, shift.assignment.changed, roster.published, roster.assignment.changed, physician.availability.changed, payroll.period.approved, expense.claim.approved, signature.envelope.completed, recruiting.application.hired, approval.task.created
occurred_atstring (date-time)required
company_idstring (uuid)requirednullableCompany of the event; null for an event without a company.
subjectobjectrequiredSubject of the event: resource type and ID.
actor_kindstringrequiredKind of the context that wrote the event (such as user, system, apikey); who it was is not recorded.
payloadobjectrequiredThin payload of the type: IDs, status, days. It carries no names, amounts or free text.
Example response
{
  "data": [
    {
      "id": "6f5e4d3c-2b1a-4c9d-8e7f-6a5b4c3d2e1f",
      "sequence": 4182,
      "type": "leave.request.approved",
      "occurred_at": "2026-06-16T08:05:00.412Z",
      "company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
      "subject": {
        "type": "leave_request",
        "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
      },
      "actor_kind": "user",
      "payload": {
        "leave_request_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
        "employee_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "leave_type_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
        "start_date": "2026-07-06",
        "end_date": "2026-07-10",
        "status": "approved"
      }
    }
  ],
  "next_cursor": null
}

Error codes

  • 400: bad_request, validation_failed, key_in_query, cookie_with_key, idempotency_key_required, idempotency_key_invalid, cursor_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout