Integrations & API

Lumina connects to the systems you already use.

REST API and webhooks for payroll software, biometric attendance devices, and custom ERP integrations. Scoped keys, signed events, documented endpoints. Built for teams that can't afford manual reconciliation.

Start free — get your first key in 2 minutesSee all features

Who connects to Lumina

💼

Payroll teams

Pull a complete payroll summary on pay day — leave days taken, penalty deductions, reward credits, and special shift earnings — all in one API call. No manual reconciliation.

🖥️

IT & developers

A documented REST API with scoped keys, versioned endpoints, and HMAC-signed webhook events. Integrate once, benefit every pay period.

📡

Device vendors

Fingerprint readers, access control systems, and time-clocks can POST attendance events directly. The penalty engine runs automatically — no manual data entry.

Payroll sync

One API call on pay day. Your salary sheet, done.

GET /api/v1/payroll/summary with a from and to date. You get back every employee's leave days taken (broken down by type), net penalty deductions, net reward credits, and special shift extra hours — in your tenant's currency. Pipe it directly into Sage, QuickBooks, or a custom salary sheet.

GET /api/v1/payroll/summary?from=2026-03-01&to=2026-03-31
response
{
  "period": { "from": "2026-03-01", "to": "2026-03-31" },
  "employees": [
    {
      "name": "Jane Nakato",
      "department": "Operations",
      "leaveDaysTaken": 3,
      "leaveBreakdown": [{ "type": "Annual Leave", "days": 3 }],
      "netPenaltyAmount": -15000,
      "netRewardAmount": 5000,
      "specialShiftExtraHours": 4,
      "currency": "UGX"
    }
  ]
}
Biometric attendance

Fingerprint machine fires the event. Lumina does the rest.

POST a single attendance event — clock_in, clock_out, absent, late, or early_leave — from any device or access control system. Lumina records the override, looks up the matching penalty or reward rule, and writes the ledger entry. No separate data entry. No spreadsheet. No lag.

POST /api/v1/attendance/event
response
{
  "success": true,
  "status": "absent",
  "penaltyTriggered": true,
  "penalty": {
    "category": "penalty",
    "monetaryAmount": -10000,
    "currency": "UGX"
  }
}
Webhook events

Your system knows the moment anything changes.

Register a URL and Lumina will POST to it whenever a leave request is approved or rejected, a penalty is applied, or a staff member is created. Every delivery is signed with HMAC-SHA256 so you can verify it's genuinely from Lumina. No polling. No missed updates.

POST /api/v1/webhooks
response
// Payload delivered to your URL:
{
  "event": "leave.approved",
  "timestamp": "2026-03-23T10:14:00Z",
  "data": {
    "employeeId": "jane@acme.com",
    "employeeName": "Jane Nakato",
    "leaveType": "Annual Leave",
    "startDate": "2026-04-07",
    "endDate": "2026-04-11"
  }
}

Every endpoint. Every scope.

All endpoints are prefixed /api/v1/ and require a Bearer token. Scopes are granted per key — request only what your integration needs.

MethodEndpointRequired scopeDescription
GET/api/v1/payroll/summarypayroll:readPer-employee payroll summary for a date range
GET/api/v1/leaves/activeleaves:readAll staff currently on approved leave
POST/api/v1/leaves/requestleaves:writeSubmit a leave request on behalf of any employee
POST/api/v1/attendance/eventattendance:writeIngest an attendance event; triggers penalty engine
GET/api/v1/staffstaff:readList employees with optional filters
POST/api/v1/staff/createstaff:writeCreate a new employee record
POST/api/v1/webhookswebhooks:writeRegister a webhook endpoint for real-time events
DELETE/api/v1/webhooks/{id}webhooks:writeRemove a registered webhook

Base URL: https://lumina.truthysystems.com · Rate limit: 120 req/min per key · All responses: Content-Type: application/json

Security model

Designed for integrations that handle sensitive payroll data.

Scoped API keys

Each key grants only the permissions it needs. A payroll key can read payroll data — nothing else. Keys that are compromised or no longer needed can be revoked instantly from the dashboard.

Tenant isolation

Every API call is scoped to the tenant that owns the key. It is architecturally impossible for one organisation's key to access another organisation's data, even if the tenant ID is known.

HMAC-signed webhooks

Every webhook delivery includes an X-Lumina-Signature header — a SHA-256 HMAC of the raw body signed with your webhook secret. Verify it on your server before processing.

Rate limiting

120 requests per minute per API key. Standard HTTP 429 response with a Retry-After header when exceeded. Designed for integration polling patterns, not high-frequency streaming.

Ready to connect your first system?

Create a free organisation, go to Settings → Integrations, generate a key, and make your first API call — in under five minutes.

Start freeSee pricing