Integrations › Developer API
timeware® HRMS · Build your own
One API.
Every part of your workforce.
Connect your own systems to timeware® HRMS. The Developer API gives secure, versioned access to your people and organisation structure, sites and devices, shifts and rosters, timesheets, leave, pay elements and clocking data, so payroll, access control and reporting tools stay in step.
REST · JSONVersioned /api/v1OpenAPI referenceSigned webhooksChange feedIncluded in every subscription
Getting started
Three steps to your first page of data.
✓
Your timeware® administrator creates an API key in the application, chooses its scopes, and it is shown once.
✓
Send
X-Api-Key and X-Tenant-Id on every request.✓
Call
GET /api/v1/ping, then read your first page of employees. JSON, camelCase, ISO 8601 dates, GUID identifiers.✓
Keys carry read and write scopes per resource, can be given an expiry, and can be revoked at any time.
Resources
Everything the platform knows, one resource at a time.
Read and, where it makes sense, write. Timesheets, entitlements, rosters and roll call are read-only by design: the calculation engine stays the single source of truth.
Employees
READ · WRITE
People, employment, managers, emergency contacts, addresses and lookups. Partial updates, generated employee numbers, leavers retained.
Organisation
READ · WRITE
Organisations, divisions, departments, groups, four custom group slots, job profiles and employment statuses. Retire rather than delete anything in use.
Sites & devices
READ · WRITE
Sites with areas and time zones, attendance devices and device groups with polling and roll-call configuration.
Shifts & rosters
READ
Shifts, work patterns, rosters and a resolved per-employee schedule that picks timesheet, roster, then work-pattern shifts.
Timesheets & cost
READ
Calculated periods, shifts and pay-element outputs. Whole-workforce cost exports at 1,000 rows a page for payroll.
Leave
READ · WRITE
Entries with every day preserved, entitlements with award, carry-over and usage. Create and update bookings with preview and versioned If-Match.
Pay elements & policies
READ · WRITE
Standard, calculated and shortfall elements with logical ids for payroll; pay policies with organisation links and rate cards.
Clockings & roll call
READ · WRITE
Push raw clockings from your own devices; read live presence and roll-call summaries; fire an alarm.
Webhooks
Hear about changes the moment they happen.
Key functions
✓
Subscribe an HTTPS endpoint to any event: employees, employment, departments, sites, shifts, work patterns, pay elements, leave categories, raw clockings, timesheets, rosters, leave entries, entitlements and roll call.
✓
Every delivery is signed with HMAC-SHA256 over a timestamp and the raw body, so your receiver can prove it came from timeware®.
✓
At-least-once delivery with an Idempotency-Key per event. Failures retry after 5 seconds, then 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours.
✓
Delivery history per endpoint, a test Ping, and one-click signing-secret rotation.
✓
Endpoints can be created by your developers through the API or by your administrator in the timeware® application.
Change feed
Or pull the changes when it suits you.
✓
A single ordered feed of every supported event, whether or not a webhook is listening. Poll it, persist the sequence, replay from where you left off.
✓
Employee and reference lists also take
modifiedSince, and leavers stay visible with includeDeleted=true.✓
Bulk exports for payroll and cost: 1,000 pay rows a page across the whole workforce, by pay period or date range, with cursor paging that never loses a row.
✓
Rebuild in one pass: capture the feed head, read the resources, replay from the captured position.
Built for production
The details integrators usually have to fight for.
Idempotency-Key
Safe retries
Send a key with any create; a retry within 24 hours returns the original response, even after a dropped connection.
nextCursor
Keyset paging
Cursor paging that survives inserts, plus classic page numbers where a UI needs them.
application/problem+json
Errors you can branch on
RFC 9457 problem responses with a stable code, field-level validation errors and a requestId for support.
If-Match
Optimistic concurrency
Leave writes carry a version; a stale update is refused rather than silently overwriting.
{resource}.read / .write
Scoped keys
Grant only what an integration needs. Finalising, cancelling and deleting leave need explicit extra scopes.
Sunset · Link
Predictable versioning
Additive changes within a version; six months of notice before any version retires.
Proven in production: the BioStar 2 and timeware® Professional migration agents are built on this same API.
Questions
Developer API, answered.
Is the API included in the subscription?
Yes. Developer API access, webhooks and the change feed are part of timeware® HRMS. Your administrator creates keys in the application; there is no separate API tier.
What are the rate limits?
Each key may make 1,000 requests a minute on a sliding window, reported on every response with standard X-RateLimit headers. Your administrator can raise a key to 10,000 a minute when an integration needs it.
Can we write data as well as read it?
Yes, where it is safe to. Employees, organisation structure, sites, pay elements, pay policies, raw clockings and individual leave bookings accept writes with the matching scope. Timesheets, entitlements, rosters and roll call are read-only so the calculation engine remains the source of truth.
How do you handle breaking changes?
Within a version changes are additive only. A breaking change ships as a new version, and a retiring version announces it with Sunset and Link headers for at least six months before it stops answering.
Where is the reference documentation?
An interactive OpenAPI reference with worked examples and an error catalogue ships with the API host. Ask your account manager for the link alongside your first key.
Is it secure?
Keys are stored hashed (SHA-256), scoped per resource, rate limited per key and revocable instantly. Webhook deliveries are HMAC-SHA256 signed. The API runs on the same UK-only Azure platform described in our IT security briefing.
