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
| Field | Type | Description |
|---|---|---|
after (query) | string | Only events with a sequence greater than this. Starts from the oldest retained event when omitted. |
cursor (query) | string | The next_cursor value of the previous response. It is opaque; send it with the same key and the same filter. |
limit (query) | integer | Page size; a value above the maximum is lowered to the maximum. |
Responses
200 Successful
A list response comes in the { data, next_cursor } envelope.
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | ID of the event; deduplicate with it. |
sequence | integerrequired | Increasing sequence inside the account. |
type | stringrequired | Event 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_ | string (date-time)required | |
company_ | string (uuid)requirednullable | Company of the event; null for an event without a company. |
subject | objectrequired | Subject of the event: resource type and ID. |
actor_ | stringrequired | Kind of the context that wrote the event (such as user, system, apikey); who it was is not recorded. |
payload | objectrequired | Thin 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_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout