Machine access

API & webhooks

A v1 REST API for external systems to read and write HR data, and webhooks for FincoHR to tell you when something happened.

Authentication

Tokens, not somebody's password

External systems authenticate with an API token rather than a person's account. Tokens are minted in settings and can be revoked at any time without affecting anyone's ability to log in.

  • The tenant comes from the token — a request cannot carry or choose a schema
  • Rate limits are counted per token, so one busy integration cannot starve the others
  • Revocation keeps the row: access ends, but the record that this system once had it survives
curl https://console.example.com/api/v1/employees \ -H "Authorization: Bearer $FINCOHR_TOKEN" \ -H "Accept: application/json"
Scopes

One token opens only the doors it needs

Read and write are separate scopes. A system that only needs to push schedules should not thereby be able to read payroll.

hr.employees.read read

Read the employee list and individual employee records.

hr.employees.write write

Create and update employee records.

hr.attendance.read read

Read attendance records and the monthly summary.

hr.attendance.write write

Write clock events and work records.

hr.leave.read read

Read leave balances and leave requests.

hr.schedules.read read

Read schedules and available staff.

hr.schedules.write write

Write schedules in bulk.

hr.webhooks.manage write

Manage webhook subscriptions and read delivery logs.

Endpoints

What v1 exposes

The endpoints cover what external systems actually reach for: employees, attendance, leave balances and schedules.

GET /api/v1/employees GET /api/v1/employees/{id} POST /api/v1/employees PATCH /api/v1/employees/{id} GET /api/v1/attendance GET /api/v1/attendance/summary POST /api/v1/attendance/clock-events POST /api/v1/attendance/work-records GET /api/v1/leave/balances GET /api/v1/leave/requests GET /api/v1/schedules GET /api/v1/schedules/available-staff POST /api/v1/schedules/bulk GET /api/v1/webhooks POST /api/v1/webhooks GET /api/v1/webhooks/{id}/deliveries DELETE /api/v1/webhooks/{id}
Webhooks

Be told, instead of polling

Register an endpoint and subscribe to events. When a hire, a termination, a leave approval or a payroll lock happens, Console POSTs the payload to you.

  • Each subscription has its own signing secret, stored encrypted rather than in the clear
  • Deliveries are logged: what this endpoint was told, and when
  • Rotating the secret is a separate act, so renaming a label cannot break the receiver
Events you can subscribe to
6 events
employee.created A new employee record is created
employee.terminated An employee is terminated
leave.approved A leave request is approved
leave.cancelled A leave request is cancelled
payroll.finalized A payroll period is finalized
attendance.anomaly An attendance anomaly is flagged
Issuing a token is its own right

Minting a credential that reads employee data is a strictly larger act than reading that data on screen. So hr.api.manage is its own permission slug, not folded into general settings access.

Secrets are encrypted

Webhook signing secrets are encrypted with the application key. That means APP_KEY, and any backup of it, must be treated as secret-bearing.

Deactivate, do not delete

Revoking a token and unregistering a webhook both deactivate rather than delete. The access ends; the record that this endpoint once had access outlives it.

Next step

Wondering whether it fits how you already work?

Tell us how you run payroll today, which time clock you use and how many departments you have. We will tell you straight whether it fits.

Open the demo Get in touch