ETK Pulse API

REST API for ETK Pulse - multi-tenant HR, payroll, attendance & double-entry finance. All tenant data is isolated by Postgres Row-Level Security; authentication is a NextAuth session cookie set by signing in. Money is always `Decimal` (string) - never float.

Base URL

https://your-host

Auth

NextAuth session cookie (sign in at /login)

Endpoints

110 operations across 19 groups

Back to home

Auth

Sign-in and password management.

get/api/auth/{nextauth}Public

NextAuth handler

Catch-all NextAuth route: session, CSRF, callbacks, sign-out.

Responses

200OK

Example request

❯ bash

curl -X GET 'https://your-host/api/auth/{nextauth}'

post/api/auth/{nextauth}Public

NextAuth handler (credentials sign-in, sign-out)

Responses

200OK

Example request

❯ bash

curl -X POST 'https://your-host/api/auth/{nextauth}'

post/api/auth/change-passwordAuthenticated

Change your password

Request body

Field	Type	Req	Notes
currentPassword	string	yes	-
newPassword	string	yes	min len 8

Responses

200OK

400Invalid request body

401Not authenticated

Example request

❯ bash

curl -X POST 'https://your-host/api/auth/change-password' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"currentPassword":"oldpass123","newPassword":"n3w-strong-pass"}'

Request payload

❯ request.json

{
  "currentPassword": "oldpass123",
  "newPassword": "n3w-strong-pass"
}

Example response · 200

❯ 200.json

{
  "ok": true
}

Attendance

Employee clock in/out, breaks, and self-service edits.

post/api/attendance/clock-inAuthenticated

Clock in

Starts a work session. Idempotent via `clientEventId` (offline replay-safe). Location captured only if the workspace enables it.

Request body

Field	Type	Req	Notes
lat	number	-	-
lng	number	-	-
clientEventId	string	-	min len 8
clientTime	string	-	format date-time

Responses

200OK

400Invalid request body

401Not authenticated

Example request

❯ bash

curl -X POST 'https://your-host/api/attendance/clock-in' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"clientEventId":"evt_3f9ab1c2d4","clientTime":"2026-06-09T08:30:00.000Z"}'

Request payload

❯ request.json

{
  "clientEventId": "evt_3f9ab1c2d4",
  "clientTime": "2026-06-09T08:30:00.000Z"
}

Example response · 200

❯ 200.json

{
  "session": {
    "id": "ckxyz",
    "clockInAt": "2026-06-09T08:30:00.000Z",
    "clockOutAt": null
  }
}

post/api/attendance/clock-outAuthenticated

Clock out

Request body

Field	Type	Req	Notes
lat	number	-	-
lng	number	-	-
clientEventId	string	-	min len 8
clientTime	string	-	format date-time

Responses

200OK

400Invalid request body

401Not authenticated

Example request

❯ bash

curl -X POST 'https://your-host/api/attendance/clock-out' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"clientEventId":"evt_9c1b7a","clientTime":"2026-06-09T17:00:00.000Z"}'

Request payload

❯ request.json

{
  "clientEventId": "evt_9c1b7a",
  "clientTime": "2026-06-09T17:00:00.000Z"
}

post/api/attendance/start-breakAuthenticated

Start a break

Request body

Field	Type	Req	Notes
clientEventId	string	-	min len 8
clientTime	string	-	format date-time

Responses

200OK

400Invalid request body

401Not authenticated

Example request

❯ bash

curl -X POST 'https://your-host/api/attendance/start-break' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/attendance/end-breakAuthenticated

End a break

Request body

Field	Type	Req	Notes
breakId	string	yes	-
clientEventId	string	-	min len 8
clientTime	string	-	format date-time

Responses

200OK

400Invalid request body

401Not authenticated

Example request

❯ bash

curl -X POST 'https://your-host/api/attendance/end-break' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"breakId":"brk_123"}'

Request payload

❯ request.json

{
  "breakId": "brk_123"
}

patch/api/attendance/sessions/{sessionId}Authenticated

Edit your own attendance session

Self-edit of clock in/out + note. Allowed **only** when the workspace has enabled “Allow manual time edits”; otherwise returns 403. Worked/overtime are recomputed server-side.

Parameters

Parameter	In	Req	Description
sessionId	path	yes	-

Request body

Field	Type	Req	Notes
clockInAt	string	-	format date-time
clockOutAt	string \| null	-	format date-time
note	string \| null	-	-

Responses

200OK

400Invalid request body

401Not authenticated

404Not found

Example request

❯ bash

curl -X PATCH 'https://your-host/api/attendance/sessions/{sessionId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"clockInAt":"2026-06-09T08:45:00.000Z","note":"Adjusted - badge reader was down"}'

Request payload

❯ request.json

{
  "clockInAt": "2026-06-09T08:45:00.000Z",
  "note": "Adjusted - badge reader was down"
}

get/api/attendance/exportAuthenticated

Export your attendance (CSV)

Parameters

Parameter	In	Req	Description
start	query	-	YYYY-MM-DD
end	query	-	YYYY-MM-DD

Responses

200OK· CSV download

401Not authenticated

Example request

❯ bash

curl -X GET 'https://your-host/api/attendance/export' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Admin · Attendance

Workspace-admin attendance management, import & export.

post/api/admin/attendance/sessionsAdmin

Create an attendance session

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
employeeId	string	yes	-
clockInAt	string	yes	format date-time
clockOutAt	string \| null	-	format date-time
timezone	string	-	-
note	string \| null	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/admin/attendance/sessions' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"employeeId":"emp_123","clockInAt":"2026-06-09T08:30:00.000Z","clockOutAt":"2026-06-09T17:00:00.000Z"}'

Request payload

❯ request.json

{
  "employeeId": "emp_123",
  "clockInAt": "2026-06-09T08:30:00.000Z",
  "clockOutAt": "2026-06-09T17:00:00.000Z"
}

patch/api/admin/attendance/sessions/{sessionId}Admin

Update an attendance session

Parameters

Parameter	In	Req	Description
sessionId	path	yes	-

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
clockInAt	string	-	format date-time
clockOutAt	string \| null	-	format date-time
timezone	string	-	-
note	string \| null	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X PATCH 'https://your-host/api/admin/attendance/sessions/{sessionId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

delete/api/admin/attendance/sessions/{sessionId}Admin

Delete an attendance session

Parameters

Parameter	In	Req	Description
sessionId	path	yes	-
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X DELETE 'https://your-host/api/admin/attendance/sessions/{sessionId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/admin/attendance/importAdmin

Bulk-import attendance rows

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
rows	array<object>	yes	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/admin/attendance/import' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"rows":[{"employeeEmail":"jane@acme.com","clockInAt":"2026-06-09T08:30:00Z","clockOutAt":"2026-06-09T17:00:00Z"}]}'

Request payload

❯ request.json

{
  "rows": [
    {
      "employeeEmail": "jane@acme.com",
      "clockInAt": "2026-06-09T08:30:00Z",
      "clockOutAt": "2026-06-09T17:00:00Z"
    }
  ]
}

get/api/admin/attendance/exportAdmin

Export company attendance (CSV)

Parameters

Parameter	In	Req	Description
orgId	query	-	-
teamId	query	-	-
employeeId	query	-	-
start	query	-	YYYY-MM-DD
end	query	-	YYYY-MM-DD
exceptions	query	-	1 = only exceptions
includeBreaks	query	-	0 to exclude

Responses

200OK· CSV download

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/admin/attendance/export' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Admin · People

Employees, teams, and positions.

get/api/admin/employeesAdmin

List employees

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/admin/employees' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Example response · 200

❯ 200.json

{
  "employees": [
    {
      "id": "emp_123",
      "fullName": "Jane Doe",
      "teamId": "team_1"
    }
  ]
}

patch/api/admin/employees/{employeeId}Admin

Update an employee

Parameters

Parameter	In	Req	Description
employeeId	path	yes	-

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
fullName	string	-	min len 1
email	string	-	format email
teamId	string \| null	-	-
positionId	string \| null	-	-
baseSalaryCurrency	string	-	USD · EGP
baseSalaryAmount	number	-	≥ 0
overtimeRateUsdPerHour	number	-	≥ 0
expectedHoursPerDay	number	-	> 0
expectedDaysPerWeek	integer	-	≥ 1 · ≤ 7
timezone	string	-	-
isActive	boolean	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X PATCH 'https://your-host/api/admin/employees/{employeeId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/admin/teamsAdmin

List teams

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/admin/teams' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/admin/teamsAdmin

Create a team

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
name	string	yes	min len 1

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/admin/teams' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Engineering"}'

Request payload

❯ request.json

{
  "name": "Engineering"
}

patch/api/admin/teams/{teamId}Admin

Rename a team

Parameters

Parameter	In	Req	Description
teamId	path	yes	-

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
name	string	-	min len 1

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X PATCH 'https://your-host/api/admin/teams/{teamId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

delete/api/admin/teams/{teamId}Admin

Delete a team

Parameters

Parameter	In	Req	Description
teamId	path	yes	-
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X DELETE 'https://your-host/api/admin/teams/{teamId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/admin/positionsAdmin

List positions

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/admin/positions' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/admin/positionsAdmin

Create a position

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
title	string	yes	min len 1
defaultOvertimeRateUsd	number	-	≥ 0

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/admin/positions' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Senior Engineer","defaultOvertimeRateUsd":25}'

Request payload

❯ request.json

{
  "title": "Senior Engineer",
  "defaultOvertimeRateUsd": 25
}

patch/api/admin/positions/{positionId}Admin

Update a position

Parameters

Parameter	In	Req	Description
positionId	path	yes	-

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
title	string	-	min len 1
defaultOvertimeRateUsd	number \| null	-	≥ 0

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X PATCH 'https://your-host/api/admin/positions/{positionId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

delete/api/admin/positions/{positionId}Admin

Delete a position

Parameters

Parameter	In	Req	Description
positionId	path	yes	-
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X DELETE 'https://your-host/api/admin/positions/{positionId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Admin · Shifts

Shift definitions and per-employee assignments.

get/api/admin/shiftsAdmin

List shifts (with teams)

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/admin/shifts' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/admin/shiftsAdmin

Create a shift

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
title	string	yes	min len 1
teamId	string \| null	-	-
type	string	-	FIXED · FLEXIBLE · ON_CALL
visibility	string	-	ALL · TEAM · PRIVATE
daysOfWeek	array<integer>	-	0=Sun … 6=Sat. Empty = every day.
startTimeLocal	string \| null	-	e.g. "09:00"
endTimeLocal	string \| null	-	e.g. "17:00"

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/admin/shifts' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Morning Shift","visibility":"TEAM","daysOfWeek":[1,2,3,4,5],"startTimeLocal":"09:00","endTimeLocal":"17:00"}'

Request payload

❯ request.json

{
  "title": "Morning Shift",
  "visibility": "TEAM",
  "daysOfWeek": [
    1,
    2,
    3,
    4,
    5
  ],
  "startTimeLocal": "09:00",
  "endTimeLocal": "17:00"
}

patch/api/admin/shifts/{shiftId}Admin

Update a shift

Parameters

Parameter	In	Req	Description
shiftId	path	yes	-

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
title	string	-	min len 1
teamId	string \| null	-	-
type	string	-	FIXED · FLEXIBLE · ON_CALL
visibility	string	-	ALL · TEAM · PRIVATE
daysOfWeek	array<integer>	-	-
startTimeLocal	string \| null	-	-
endTimeLocal	string \| null	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X PATCH 'https://your-host/api/admin/shifts/{shiftId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

delete/api/admin/shifts/{shiftId}Admin

Delete a shift

Parameters

Parameter	In	Req	Description
shiftId	path	yes	-
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X DELETE 'https://your-host/api/admin/shifts/{shiftId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/admin/shifts/{shiftId}/assignmentsAdmin

List assigned employees

Parameters

Parameter	In	Req	Description
shiftId	path	yes	-
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X GET 'https://your-host/api/admin/shifts/{shiftId}/assignments' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Example response · 200

❯ 200.json

{
  "employeeIds": [
    "emp_123",
    "emp_456"
  ]
}

post/api/admin/shifts/{shiftId}/assignmentsAdmin

Assign an employee to a shift

Parameters

Parameter	In	Req	Description
shiftId	path	yes	-

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
employeeId	string	yes	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X POST 'https://your-host/api/admin/shifts/{shiftId}/assignments' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"employeeId":"emp_123"}'

Request payload

❯ request.json

{
  "employeeId": "emp_123"
}

delete/api/admin/shifts/{shiftId}/assignmentsAdmin

Unassign an employee

Parameters

Parameter	In	Req	Description
shiftId	path	yes	-
employeeId	query	yes	Employee to unassign
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X DELETE 'https://your-host/api/admin/shifts/{shiftId}/assignments' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Admin · Time Off

Leave types and request approvals.

get/api/admin/timeoff/requestsAdmin

List time-off requests

Parameters

Parameter	In	Req	Description
status	query	-	PENDING \| APPROVED \| DENIED \| …
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/admin/timeoff/requests' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

patch/api/admin/timeoff/requestsAdmin

Approve / deny / postpone a request

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
requestId	string	yes	-
action	string	yes	APPROVE · DENY · POSTPONE
adminNote	string	-	-
postponedUntil	string	-	format date

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X PATCH 'https://your-host/api/admin/timeoff/requests' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"requestId":"to_1","action":"APPROVE"}'

Request payload

❯ request.json

{
  "requestId": "to_1",
  "action": "APPROVE"
}

get/api/admin/timeoff/typesAdmin

List leave types

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/admin/timeoff/types' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/admin/timeoff/typesAdmin

Create a leave type

Request body

Field	Type	Req	Notes
name	string	yes	min len 1
isPaid	boolean	-	-
requiresApproval	boolean	-	-
maxPerYearDays	number	-	> 0

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/admin/timeoff/types' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Vacation","isPaid":true,"requiresApproval":true}'

Request payload

❯ request.json

{
  "name": "Vacation",
  "isPaid": true,
  "requiresApproval": true
}

put/api/admin/timeoff/typesAdmin

Update a leave type

Request body

Field	Type	Req	Notes
id	string	yes	-
name	string	-	min len 1
isPaid	boolean	-	-
requiresApproval	boolean	-	-
maxPerYearDays	number	-	> 0

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X PUT 'https://your-host/api/admin/timeoff/types' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

delete/api/admin/timeoff/typesAdmin

Delete a leave type

Request body

Field	Type	Req	Notes
id	string	yes	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X DELETE 'https://your-host/api/admin/timeoff/types' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Admin · Settings

Workspace policy and finance settings.

get/api/admin/settingsAdmin

Get workspace settings

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/admin/settings' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

patch/api/admin/settingsAdmin

Update workspace settings

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
firstDayOfWeek	string	-	MONDAY · SUNDAY
defaultTimezone	string	-	-
allowedCurrencies	array<string>	-	-
allowPickOpenShifts	boolean	-	-
allowDropShifts	boolean	-	-
recordClockLocation	boolean	-	-
allowManualTimeEdits	boolean	-	-
enableFinance	boolean	-	-
defaultExpectedHoursPerDay	number	-	≤ 24 · > 0
overtimeGraceMinutes	integer	-	≥ 0 · ≤ 240
overtimeMultiplier	number	-	≥ 0.25 · ≤ 5
payrollRounding	string	-	NONE · NEAREST_1 · NEAREST_5 · NEAREST_10

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X PATCH 'https://your-host/api/admin/settings' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"recordClockLocation":true,"allowManualTimeEdits":false}'

Request payload

❯ request.json

{
  "recordClockLocation": true,
  "allowManualTimeEdits": false
}

get/api/admin/settings/financeAdmin

Get finance settings

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/admin/settings/finance' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

patch/api/admin/settings/financeAdmin

Update finance settings

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
baseCurrency	string	-	USD · EGP
fiscalYearStartMonth	integer	-	≥ 1 · ≤ 12

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X PATCH 'https://your-host/api/admin/settings/finance' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Me

Employee self-service (profile, time off, payslips).

patch/api/me/profileAuthenticated

Update your profile

Request body

Field	Type	Req	Notes
timezone	string	-	-

Responses

200OK

400Invalid request body

401Not authenticated

Example request

❯ bash

curl -X PATCH 'https://your-host/api/me/profile' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"timezone":"Africa/Cairo"}'

Request payload

❯ request.json

{
  "timezone": "Africa/Cairo"
}

get/api/me/timeoff/requestsAuthenticated

List your time-off requests

Responses

200OK

401Not authenticated

Example request

❯ bash

curl -X GET 'https://your-host/api/me/timeoff/requests' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/me/timeoff/requestsAuthenticated

Request time off

Request body

Field	Type	Req	Notes
typeId	string	yes	-
startDate	string	yes	format date
endDate	string	yes	format date
durationHours	number	-	> 0
reason	string	-	max len 500

Responses

200OK

400Invalid request body

401Not authenticated

Example request

❯ bash

curl -X POST 'https://your-host/api/me/timeoff/requests' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"typeId":"tot_1","startDate":"2026-07-01","endDate":"2026-07-05","reason":"Family trip"}'

Request payload

❯ request.json

{
  "typeId": "tot_1",
  "startDate": "2026-07-01",
  "endDate": "2026-07-05",
  "reason": "Family trip"
}

delete/api/me/timeoff/requests/{requestId}Authenticated

Cancel a pending request

Parameters

Parameter	In	Req	Description
requestId	path	yes	-

Responses

200OK

401Not authenticated

404Not found

Example request

❯ bash

curl -X DELETE 'https://your-host/api/me/timeoff/requests/{requestId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/me/timeoff/typesAuthenticated

List leave types available to you

Responses

200OK

401Not authenticated

Example request

❯ bash

curl -X GET 'https://your-host/api/me/timeoff/types' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/me/payslips/{payslipId}/exportAuthenticated

Download your payslip (PDF)

Parameters

Parameter	In	Req	Description
payslipId	path	yes	-

Responses

200OK· PDF download

401Not authenticated

404Not found

Example request

❯ bash

curl -X GET 'https://your-host/api/me/payslips/{payslipId}/export' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Payroll

Payroll runs, line items, and posting to the ledger.

get/api/payroll/runsAdmin

List payroll runs

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/payroll/runs' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/payroll/runsAdmin

Create a payroll run

Request body

Field	Type	Req	Notes
periodStart	string	yes	format date
periodEnd	string	yes	format date
defaultUsdToEgpRate	number	yes	> 0

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/payroll/runs' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"periodStart":"2026-06-01","periodEnd":"2026-06-30","defaultUsdToEgpRate":48.5}'

Request payload

❯ request.json

{
  "periodStart": "2026-06-01",
  "periodEnd": "2026-06-30",
  "defaultUsdToEgpRate": 48.5
}

get/api/payroll/runs/{runId}Admin

Get a payroll run

Parameters

Parameter	In	Req	Description
runId	path	yes	-
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X GET 'https://your-host/api/payroll/runs/{runId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/payroll/runs/{runId}Admin

Recalculate a payroll run

Parameters

Parameter	In	Req	Description
runId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X POST 'https://your-host/api/payroll/runs/{runId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

put/api/payroll/runs/{runId}/line-itemsAdmin

Override a run line item

Parameters

Parameter	In	Req	Description
runId	path	yes	-

Request body

Field	Type	Req	Notes
employeeId	string	yes	-
usdToEgpRateUsed	number	-	> 0
overtimeRateUsdPerHour	number	-	≥ 0
baseSalaryAmount	number	-	≥ 0

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X PUT 'https://your-host/api/payroll/runs/{runId}/line-items' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/payroll/runs/{runId}/post-to-ledgerAdmin

Post a payroll run to the ledger

Emits balanced double-entry journal entries tagged with the payroll source.

Parameters

Parameter	In	Req	Description
runId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X POST 'https://your-host/api/payroll/runs/{runId}/post-to-ledger' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Payslips

Payslip records and PDF export.

get/api/payslips/{payslipId}Admin

Get a payslip

Parameters

Parameter	In	Req	Description
payslipId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X GET 'https://your-host/api/payslips/{payslipId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/payslips/{payslipId}/exportAdmin

Download a payslip (PDF)

Parameters

Parameter	In	Req	Description
payslipId	path	yes	-

Responses

200OK· PDF download

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X GET 'https://your-host/api/payslips/{payslipId}/export' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Finance

Double-entry ledger: accounts, journals, periods, expenses, recurring items, banking.

get/api/finance/accountsAdmin

List chart of accounts

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/finance/accounts' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/finance/accountsAdmin

Create an account

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
code	string	yes	min len 1 · max len 32
name	string	yes	min len 1 · max len 200
type	string	yes	ASSET · LIABILITY · EQUITY · INCOME · EXPENSE
parentAccountId	string	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/accounts' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"code":"6000","name":"Office Supplies","type":"EXPENSE"}'

Request payload

❯ request.json

{
  "code": "6000",
  "name": "Office Supplies",
  "type": "EXPENSE"
}

get/api/finance/journalsAdmin

List journal entries

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/finance/journals' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/finance/journalsAdmin

Create a journal entry (draft)

Lines must balance (Σ debit = Σ credit). At least two lines.

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
entryDate	string	yes	format date
memo	string	-	max len 2000
lines	array<object>	yes	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/journals' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"entryDate":"2026-06-09","memo":"Office supplies","lines":[{"accountId":"acc_exp","debit":100},{"accountId":"acc_cash","credit":100}]}'

Request payload

❯ request.json

{
  "entryDate": "2026-06-09",
  "memo": "Office supplies",
  "lines": [
    {
      "accountId": "acc_exp",
      "debit": 100
    },
    {
      "accountId": "acc_cash",
      "credit": 100
    }
  ]
}

post/api/finance/journals/{journalEntryId}/postAdmin

Post a draft journal entry

Parameters

Parameter	In	Req	Description
journalEntryId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/journals/{journalEntryId}/post' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/finance/journals/{journalEntryId}/reverseAdmin

Reverse a posted journal entry

Parameters

Parameter	In	Req	Description
journalEntryId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/journals/{journalEntryId}/reverse' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/finance/periodsAdmin

List finance periods

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/finance/periods' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/finance/periodsAdmin

Open a finance period

Request body

Field	Type	Req	Notes
year	integer	yes	≥ 2000 · ≤ 2100
month	integer	yes	≥ 1 · ≤ 12

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/periods' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"year":2026,"month":6}'

Request payload

❯ request.json

{
  "year": 2026,
  "month": 6
}

delete/api/finance/periodsAdmin

Close / delete a period

Request body

Field	Type	Req	Notes
year	integer	yes	-
month	integer	yes	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X DELETE 'https://your-host/api/finance/periods' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/finance/expenseAdmin

Record an expense

Convenience endpoint that books a balanced expense entry.

Request body

Field	Type	Req	Notes
entryDate	string	yes	format date
amount	number	yes	> 0
expenseAccountId	string	yes	-
paymentAccountId	string	yes	-
memo	string	-	max len 2000

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/expense' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"entryDate":"2026-06-09","amount":250,"expenseAccountId":"acc_exp","paymentAccountId":"acc_bank"}'

Request payload

❯ request.json

{
  "entryDate": "2026-06-09",
  "amount": 250,
  "expenseAccountId": "acc_exp",
  "paymentAccountId": "acc_bank"
}

get/api/finance/recurringAdmin

List recurring items

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/finance/recurring' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/finance/recurringAdmin

Create a recurring item

Request body

Field	Type	Req	Notes
name	string	yes	min len 1 · max len 120
kind	string	yes	INCOME · EXPENSE
amount	number	yes	> 0
cadence	string	yes	MONTHLY · YEARLY
accountId	string	yes	-
counterAccountId	string	yes	-
nextRunOn	string	yes	format date

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/recurring' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Office rent","kind":"EXPENSE","amount":1200,"cadence":"MONTHLY","accountId":"acc_rent","counterAccountId":"acc_bank","nextRunOn":"2026-07-01"}'

Request payload

❯ request.json

{
  "name": "Office rent",
  "kind": "EXPENSE",
  "amount": 1200,
  "cadence": "MONTHLY",
  "accountId": "acc_rent",
  "counterAccountId": "acc_bank",
  "nextRunOn": "2026-07-01"
}

patch/api/finance/recurring/{itemId}Admin

Update a recurring item

Parameters

Parameter	In	Req	Description
itemId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X PATCH 'https://your-host/api/finance/recurring/{itemId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

delete/api/finance/recurring/{itemId}Admin

Delete a recurring item

Parameters

Parameter	In	Req	Description
itemId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X DELETE 'https://your-host/api/finance/recurring/{itemId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/finance/recurring/{itemId}/bookAdmin

Book a recurring item now

Parameters

Parameter	In	Req	Description
itemId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/recurring/{itemId}/book' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/finance/bank-accountsAdmin

List bank accounts

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/finance/bank-accounts' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/finance/bank-accountsAdmin

Create a bank account

Request body

Field	Type	Req	Notes
name	string	yes	min len 1 · max len 120
institution	string	-	max len 120
currency	string	-	USD · EGP

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/bank-accounts' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Operating - CIB","currency":"EGP"}'

Request payload

❯ request.json

{
  "name": "Operating - CIB",
  "currency": "EGP"
}

post/api/finance/bank-accounts/{bankAccountId}/importAdmin

Import bank transactions

Parameters

Parameter	In	Req	Description
bankAccountId	path	yes	-

Request body

Field	Type	Req	Notes
source	string	-	max len 120
rows	array<object>	yes	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/bank-accounts/{bankAccountId}/import' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

patch/api/finance/bank-transactions/{transactionId}Admin

Match / unmatch / ignore a transaction

Parameters

Parameter	In	Req	Description
transactionId	path	yes	-

Request body

Field	Type	Req	Notes
action	string	yes	MATCH · UNMATCH · IGNORE
journalEntryId	string	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X PATCH 'https://your-host/api/finance/bank-transactions/{transactionId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"action":"MATCH","journalEntryId":"je_1"}'

Request payload

❯ request.json

{
  "action": "MATCH",
  "journalEntryId": "je_1"
}

get/api/finance/reports/exportAdmin

Export a finance report (CSV)

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK· CSV download

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/finance/reports/export' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/finance/seedAdmin

Seed a default chart of accounts

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/finance/seed' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Contracts

Contract templates, generation, and e-signature.

get/api/contracts/templatesAdmin

List contract templates

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/contracts/templates' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/contracts/templatesAdmin

Create a template

Request body

Field	Type	Req	Notes
title	string	yes	min len 1
language	string	-	EN · AR · BOTH
direction	string	-	LTR · RTL
contentHtml	string	yes	min len 1
fieldsSchema	object	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/contracts/templates' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/contracts/templates/{templateId}Admin

Get a template

Parameters

Parameter	In	Req	Description
templateId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X GET 'https://your-host/api/contracts/templates/{templateId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

put/api/contracts/templates/{templateId}Admin

Update a template

Parameters

Parameter	In	Req	Description
templateId	path	yes	-

Request body

Field	Type	Req	Notes
title	string	-	-
language	string	-	EN · AR · BOTH
direction	string	-	LTR · RTL
contentHtml	string	-	-
fieldsSchema	object	-	-
overlaySchema	object	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X PUT 'https://your-host/api/contracts/templates/{templateId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

delete/api/contracts/templates/{templateId}Admin

Delete a template

Parameters

Parameter	In	Req	Description
templateId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X DELETE 'https://your-host/api/contracts/templates/{templateId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/contracts/templates/{templateId}/uploadAdmin

Upload a DOCX template

multipart/form-data DOCX, converted to HTML via mammoth.

Parameters

Parameter	In	Req	Description
templateId	path	yes	-

Responses

200OK

401Not authenticated

403Insufficient role

404Not found

Example request

❯ bash

curl -X POST 'https://your-host/api/contracts/templates/{templateId}/upload' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/contracts/createAdmin

Generate a contract from a template

Request body

Field	Type	Req	Notes
templateId	string	yes	-
employeeId	string	yes	-
allowEmployeeEdits	boolean	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/contracts/create' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"templateId":"tpl_1","employeeId":"emp_123"}'

Request payload

❯ request.json

{
  "templateId": "tpl_1",
  "employeeId": "emp_123"
}

get/api/contracts/{contractId}Authenticated

Get a contract

Parameters

Parameter	In	Req	Description
contractId	path	yes	-

Responses

200OK

401Not authenticated

404Not found

Example request

❯ bash

curl -X GET 'https://your-host/api/contracts/{contractId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

put/api/contracts/{contractId}Authenticated

Update field values

Parameters

Parameter	In	Req	Description
contractId	path	yes	-

Request body

Field	Type	Req	Notes
fieldValues	object	yes	-

Responses

200OK

400Invalid request body

401Not authenticated

404Not found

Example request

❯ bash

curl -X PUT 'https://your-host/api/contracts/{contractId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

patch/api/contracts/{contractId}Authenticated

Change contract status

Parameters

Parameter	In	Req	Description
contractId	path	yes	-

Request body

Field	Type	Req	Notes
status	string	yes	SENT · VOID

Responses

200OK

400Invalid request body

401Not authenticated

404Not found

Example request

❯ bash

curl -X PATCH 'https://your-host/api/contracts/{contractId}' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"status":"SENT"}'

Request payload

❯ request.json

{
  "status": "SENT"
}

post/api/contracts/{contractId}/signAuthenticated

Sign a contract

Parameters

Parameter	In	Req	Description
contractId	path	yes	-

Request body

Field	Type	Req	Notes
signatureType	string	yes	DRAWN · TYPED · UPLOADED
typedName	string	-	-
signatureImageDataUrl	string	-	-
consent	boolean	-	-

Responses

200OK

400Invalid request body

401Not authenticated

404Not found

Example request

❯ bash

curl -X POST 'https://your-host/api/contracts/{contractId}/sign' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"signatureType":"TYPED","typedName":"Jane Doe","consent":true}'

Request payload

❯ request.json

{
  "signatureType": "TYPED",
  "typedName": "Jane Doe",
  "consent": true
}

get/api/contracts/{contractId}/exportAuthenticated

Download a contract (PDF)

Parameters

Parameter	In	Req	Description
contractId	path	yes	-

Responses

200OK· PDF download

401Not authenticated

404Not found

Example request

❯ bash

curl -X GET 'https://your-host/api/contracts/{contractId}/export' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Notifications

In-app notification inbox.

get/api/notificationsAuthenticated

List your notifications

Responses

200OK

401Not authenticated

Example request

❯ bash

curl -X GET 'https://your-host/api/notifications' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

patch/api/notificationsAuthenticated

Mark read / archive / delete

Request body

Field	Type	Req	Notes
action	string	yes	MARK_ALL_READ · MARK_READ · ARCHIVE · DELETE
ids	array<string>	-	-

Responses

200OK

400Invalid request body

401Not authenticated

Example request

❯ bash

curl -X PATCH 'https://your-host/api/notifications' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"action":"MARK_READ","ids":["ntf_1"]}'

Request payload

❯ request.json

{
  "action": "MARK_READ",
  "ids": [
    "ntf_1"
  ]
}

Status

User presence (online/offline).

get/api/statusAuthenticated

Get your presence

Responses

200OK

401Not authenticated

Example request

❯ bash

curl -X GET 'https://your-host/api/status' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Example response · 200

❯ 200.json

{
  "status": "ONLINE"
}

put/api/statusAuthenticated

Set your presence

Request body

Field	Type	Req	Notes
status	string	yes	ONLINE · OFFLINE

Responses

200OK

400Invalid request body

401Not authenticated

Example request

❯ bash

curl -X PUT 'https://your-host/api/status' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"status":"ONLINE"}'

Request payload

❯ request.json

{
  "status": "ONLINE"
}

Billing

Stripe-ready billing (dark until keys exist).

post/api/billing/checkoutAdmin

Start a checkout session

Stripe-ready; returns a checkout URL once billing is enabled (otherwise dark).

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/billing/checkout' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/billing/webhookPublic

Stripe webhook

Verified by Stripe signature header (no session).

Responses

200OK

Example request

❯ bash

curl -X POST 'https://your-host/api/billing/webhook'

Integrations

Third-party connectors and inbound webhooks.

get/api/integrations/providersSuper Admin

List integration providers

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/integrations/providers' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/integrations/providersSuper Admin

Register a provider

Request body

Field	Type	Req	Notes
key	string	yes	min len 2 · max len 64
name	string	yes	min len 2 · max len 200
category	string	-	max len 64
capabilities	object	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/integrations/providers' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"key":"slack","name":"Slack"}'

Request payload

❯ request.json

{
  "key": "slack",
  "name": "Slack"
}

get/api/integrations/webhook-endpointsAdmin

List webhook endpoints

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/integrations/webhook-endpoints' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/integrations/webhook-endpointsAdmin

Create a webhook endpoint

Request body

Field	Type	Req	Notes
orgId	string	-	Super-admin only: act within this workspace.
providerKey	string	yes	min len 2 · max len 64
signingSecret	string	yes	min len 8 · max len 500

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/integrations/webhook-endpoints' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/integrations/webhooks/{providerKey}Public

Inbound provider webhook

Verified by the provider's signing secret (no session).

Parameters

Parameter	In	Req	Description
providerKey	path	yes	-

Responses

200OK

404Not found

Example request

❯ bash

curl -X POST 'https://your-host/api/integrations/webhooks/{providerKey}'

Super Admin

Platform operations: workspaces, users, audit.

get/api/super/orgsSuper Admin

List workspaces

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/super/orgs' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/super/orgsSuper Admin

Create a workspace

Request body

Field	Type	Req	Notes
name	string	-	min len 1

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/super/orgs' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Acme Inc."}'

Request payload

❯ request.json

{
  "name": "Acme Inc."
}

put/api/super/orgsSuper Admin

Update a workspace

Request body

Field	Type	Req	Notes
id	string	-	-
name	string	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X PUT 'https://your-host/api/super/orgs' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

delete/api/super/orgsSuper Admin

Delete a workspace

Request body

Field	Type	Req	Notes
id	string	yes	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X DELETE 'https://your-host/api/super/orgs' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/super/usersSuper Admin

List users across workspaces

Parameters

Parameter	In	Req	Description
orgId	query	-	-

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/super/users' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

post/api/super/usersSuper Admin

Create a user

Request body

Field	Type	Req	Notes
email	string	yes	format email
name	string	-	-
role	string	yes	SUPER_ADMIN · ADMIN · EMPLOYEE
organizationId	string	yes	-
tempPassword	string	yes	min len 8

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X POST 'https://your-host/api/super/users' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE' \
  -H 'Content-Type: application/json' \
  -d '{"email":"new@acme.com","role":"ADMIN","organizationId":"org_1","tempPassword":"temp-pass-123"}'

Request payload

❯ request.json

{
  "email": "new@acme.com",
  "role": "ADMIN",
  "organizationId": "org_1",
  "tempPassword": "temp-pass-123"
}

patch/api/super/usersSuper Admin

Update a user

Request body

Field	Type	Req	Notes
userId	string	yes	-
role	string	-	SUPER_ADMIN · ADMIN · EMPLOYEE
organizationId	string	-	-
name	string	-	-
tempPassword	string	-	min len 8
attendance	boolean	-	-
payroll	boolean	-	-
contracts	boolean	-	-
notifications	boolean	-	-
timeOff	boolean	-	-

Responses

200OK

400Invalid request body

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X PATCH 'https://your-host/api/super/users' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

get/api/super/auditSuper Admin

Query the audit log

Parameters

Parameter	In	Req	Description
actorEmail	query	-	-
targetEmail	query	-	-
action	query	-	-
take	query	-	Max rows

Responses

200OK

401Not authenticated

403Insufficient role

Example request

❯ bash

curl -X GET 'https://your-host/api/super/audit' \
  -b 'next-auth.session-token=YOUR_SESSION_COOKIE'

Support

Support tickets.

post/api/support/ticketsPublic

Submit a support ticket

Request body

Field	Type	Req	Notes
subject	string	yes	min len 4 · max len 200
bodyMarkdown	string	yes	min len 10 · max len 10000
category	string	-	max len 64
priority	string	-	max len 16

Responses

200OK

400Invalid request body

Example request

❯ bash

curl -X POST 'https://your-host/api/support/tickets' \
  -H 'Content-Type: application/json' \
  -d '{"subject":"Cannot clock in","bodyMarkdown":"The clock-in button is greyed out on iOS."}'

Request payload

❯ request.json

{
  "subject": "Cannot clock in",
  "bodyMarkdown": "The clock-in button is greyed out on iOS."
}

Help

Public knowledge-base search.

get/api/help/quickPublic

Quick help suggestions

Parameters

Parameter	In	Req	Description
q	query	-	Search query

Responses

200OK

Example request

❯ bash

curl -X GET 'https://your-host/api/help/quick'

get/api/help/searchPublic

Search the knowledge base

Parameters

Parameter	In	Req	Description
q	query	yes	Search query

Responses

200OK

Example request

❯ bash

curl -X GET 'https://your-host/api/help/search'