API reference
Endpoints
Base URL https://kumohr.com. Responses use a { data } / { error: { code, message } } envelope with X-RateLimit-* headers. The machine-readable version of this reference lives at /api/v1/openapi.json.
GET/api/v1/meany token
Introspect the token
Returns the authenticated user, workspace (tenant), role, employee id, and the scopes this token carries. Use it to verify a token before wiring anything else.
curl https://kumohr.com/api/v1/me \
-H "Authorization: Bearer kumo_…"
// 2xx response
{
"data": {
"token": {
"name": "Zapier integration",
"scopes": [
"leave:read",
"reports:read"
]
},
"user": {
"id": "uuid",
"name": "Amara Okafor",
"email": "amara@acme.com",
"role": "HR_MANAGER"
},
"tenant": {
"id": "uuid",
"name": "Acme Ltd"
},
"employee_id": 214
}
}
GET/api/v1/leave/requestsleave:read
List leave requests
Lists leave requests you are allowed to see — your own for self-service roles, your team’s for line managers, your department’s for directors, the whole workspace for HR and admins. Filter by status and date range.
ParameterTypeDescription
statusstringFilter by status. One of: PENDING, APPROVED, REJECTED, CANCELLED, IN_PROGRESS, COMPLETED.
fromstringOnly requests ending on or after this date (YYYY-MM-DD).
tostringOnly requests starting on or before this date (YYYY-MM-DD).
limitnumberMax rows to return (1–200, default 50).
curl https://kumohr.com/api/v1/leave/requests?status=…&from=… \
-H "Authorization: Bearer kumo_…"
// 2xx response
{
"data": {
"requests": [
{
"id": "uuid",
"employee_id": 214,
"employee_name": "Amara Okafor",
"policy": "Annual Leave",
"start_date": "2026-09-07",
"end_date": "2026-09-11",
"total_days": 5,
"half_day": false,
"status": "APPROVED",
"reason": "Family trip",
"created_at": "2026-08-30T09:15:00.000Z"
}
]
}
}
POST/api/v1/leave/requestsleave:write
Create a leave request
Books time off for the token’s user through the platform’s own leave engine — policy validation, balance movement, approval routing, and notifications all run exactly as from the app. Pass start_date plus either end_date or days; the policy defaults to annual leave.
ParameterTypeDescription
start_daterequiredstringFirst day off (YYYY-MM-DD).
end_datestringLast day off, inclusive (YYYY-MM-DD). Use this OR days.
daysnumberNumber of consecutive calendar days off. Use this OR end_date.
policystringLeave policy name, e.g. "Annual Leave". Defaults to the annual policy.
policy_idstringExact policy id (overrides policy).
reasonstringOptional short reason.
half_daybooleanTrue for a single half-day request.
curl -X POST https://kumohr.com/api/v1/leave/requests \
-H "Authorization: Bearer kumo_…" \
-H "Content-Type: application/json" \
-d '{"start_date":"2026-09-07","days":2}'
// 2xx response
{
"data": {
"id": "uuid",
"status": "PENDING",
"policy": "Annual Leave",
"start_date": "2026-09-07",
"end_date": "2026-09-08",
"total_days": 2,
"warnings": []
}
}
GET/api/v1/reports/untaken-leavereports:read
Untaken leave report
Per-employee untaken leave for a year: allocated, used, and remaining days with department and manager, sorted by most untaken first. Runs through the same permission-gated reporting tool Kumo’s agent uses — your role decides whose rows you see.
ParameterTypeDescription
yearnumberBalance year (defaults to the current year).
min_untaken_daysnumberOnly employees with at least this many untaken days.
policystringLeave policy name filter (defaults to annual policies).
curl https://kumohr.com/api/v1/reports/untaken-leave?year=…&min_untaken_days=… \
-H "Authorization: Bearer kumo_…"
// 2xx response
{
"data": {
"year": 2026,
"employees": [
{
"employee": "Amara Okafor",
"department": "Engineering",
"manager": "Lena Fischer",
"allocated_days": 25,
"used_days": 6,
"untaken_days": 19
}
],
"totals": {
"employees": 42,
"untakenDays": 512
}
}
}