API reference

The BizFlow API is a NestJS service behind the global prefix /api/v1. All routes below are relative to that prefix.

Base URL & authentication

text
https://<your-bizflow-host>/api/v1

Every request must include:

text
Authorization: Bearer <Clerk JWT>
x-organization-id: <active organization id>   (for multi-tenant routes)

Authentication is Clerk JWT bearer tokens. Role and permission checks run server-side with @Roles / @Permissions guards; tenant scope is enforced from the x-organization-id header.

Response envelope

Responses are wrapped:

json
{
  "success": true,
  "statusCode": 200,
  "message": "OK",
  "data": { }
}

Clients read data. Errors return success: false with a status code and message.

Health & monitoring

Endpoint	Purpose
`GET /health`	Public health probe (database, Redis, Clerk, email, queues, heap) — not under `/api/v1`
`GET /api/v1/metrics`	Prometheus metrics

People & tenancy

Endpoint group	Notes
`/users`	`GET /users/me`, `GET /users`, `GET /users/all-users`, `POST /users`, `PUT/DELETE /users/:id`
`/organizations`	CRUD + `POST/GET /:id/users`, `PATCH/DELETE /:id/users/:userId`
`/tenants`	CRUD + `/:id/users`, `/:id/storage`, `/:id/plan-usage`, `PATCH /:id/plan`
`/subscription-plans`	`GET /subscription-plans`
`/activity-log`	`GET /`, `GET /entity/:type/:id`

HR & attendance

Endpoint group	Notes
`/employees`	CRUD + `/:id/qr-authorization`, `/:id/push-token`, contact/personal/health-safety updates
`/freelancers`	CRUD + `/:id/reliable`, `/:id/convert`, QR authorization
`/trainees`	CRUD + `/:id/reliable`, `/:id/periods`, QR authorization
`/leaves`	CRUD + `/employee/:employeeId/used-days`
`/attendance`	check-in, check-out, break, records, bypass, location, callout, overtime, summary, day-off-overtime, bulk-past
`/emergency-callouts`	CRUD + leader/assistant responses, check-in/check-out
`/payroll`	Runs + `/calculate`, `/check`, `/draft`, `/history`, `/payments/:id`, `/email`, revert
`/performance`	`GET /unified`, `GET /me`
`/warnings`	CRUD
`/departments`	CRUD + `/detailed`
`/institutions`	CRUD
`/biometrics`	`POST /enroll`, `/verify`, `/test-verify`

Financials

Endpoint group	Notes
`/quotations`	CRUD + `/:id/pdf`, `/:id/convert`, `/:id/duplicate`, `/:id/send-email`, `/:id/cancel`
`/invoices`	CRUD + `/recurring`, `/:id/pdf`, `/:id/send-email`, `/:id/convert-to-credit-note`
`/invoice-documents`	`POST /generate`, `/:id/email`, `/items/:id/tick`
`/payments`	`POST /expenses/:id`, `POST /invoices/:id`, deletes for both
`/expenses`	CRUD + `/export`, `/recurring`, `/:id/attachments`, `/:id/payments`
`/transactions`	CRUD
`/transactions-ceo`	CEO dashboard ledger
`/loans` + `/lenders`	CRUD + `/loans/:id/payments`
`/banks`	CRUD
`/refunds`	`POST /sale/:saleId`, `/:id/approve`, `/:id/reject`, `PUT /:id/notes`

Sales & catalog

Endpoint group	Notes
`/shop/products`	CRUD + `/brands`, `/stats`, `/export`, `/export-catalog`, `/:id/sales`, `/:id/documents`
`/shop/sales`	CRUD + `/export`, `/send-receipt`, `/:id/create-order`, `/:id/stock-awaits`
`/shop/orders`	CRUD + `/export`, `/:id/receipt`
`/shop/quotations`	CRUD + `/:id/convert`, `/:id/transfer`
`/shop/customers`, `/shop/vendors`, `/shop/categories`, `/shop/documents`	CRUD
`/shop/stock-movements`	CRUD + `/export`
`/shop/stock-awaits`	CRUD + `/bulk-update`, `/:id/resolve`
`/products`, `/services`, `/coupons`, `/clients`	CRUD
`/package-categories`, `/packages`, `/subpackages`	CRUD + duplicate/convert helpers

Projects & tasks

Endpoint group	Notes
`/tasks`	CRUD + `/:id/status`, `/:id/due-date`, `/:id/commencement`, `/:taskId/job-card`
`/subtasks`, `/task-types`, `/time-entries`	CRUD
`/projects`	CRUD + `/:id/members`, `/invoices/link`, `/:id/star`
`/work-logs`	CRUD
`/comments`, `/documents`, `/folders`, `/notes`	Collaboration
`/time-entries-mobile`, `/subtasks-mobile`	Mobile task time + subtasks

Fleet & tools

Endpoint group	Notes
`/fleet/vehicles`	CRUD + `/:id/media`, `/:id/qr`, `/:id/stats`
`/fleet/trips`	CRUD + `/stops`, `/:id/end`, `/:id/location`, `/:id/stops`
`/fleet/fuel`, `/fleet/expenses`, `/fleet/maintenance`, `/fleet/compliance`	CRUD
`/fleet/vehicle-claims`, `/fleet/vehicle-instalments`, `/fleet/vehicle-licensing`	CRUD
`/fleet/fleet-stats`	Stats
`/tools`	CRUD + `/:id/duplicate`, `/:id/interuse`, `/:id/maintenance`, `/:id/movements`, `/export`
`/worker-tools`	`/allocate`, `/check`, `/return`, `/stats/*`
`/tool-rentals`	CRUD + `/:id/accept`, `/:id/damage`
`/tool-requests`, `/tool-checks`, `/tool-maintenance`	CRUD

AI, notifications & utilities

Endpoint group	Notes
`/ai-chat`	`POST /`, `POST /stream`
`/chat-sessions`	CRUD
`/ai`	`POST /tasks`, `POST /subtasks`, `POST /compose-job-card-email`
`/notifications`	CRUD + `/read-all`, `/:id/read`
`/upload`	`POST /`, `POST /trip`, `POST /cleanup-email-attachments`
`/send-email`, `/send-custom-email`	Email sending
`/generate-pdf`	Server-side PDF generation
`/search`	Global search
`/sidebar/stats`	Pending-count badges
`/mobile/calendar`	Unified mobile calendar
`/driver-tasks`	Fleet driver tasks
`/dashboard`	Dashboard stats

Rate limits & errors

Throttling: 100 requests / 60 seconds per client by default.
Validation: unknown fields are rejected (whitelist + forbidNonWhitelisted).
Errors: 401 (unauthenticated), 403 (permission denied), 429 (rate limited), 500 (server error).