The first table is generated from openapi.yaml on every site build, so it always matches the contract. The dated log below it is written by hand. See also the versioning and deprecation policy.
New scope leave:read. GET /v1/leave-requests lists the company's leave requests (filter by status, employee_id or updated_since), and five new webhook events report each change: leave.requested, leave.approved, leave.rejected, leave.cancelled and leave.updated. Subscribing to them needs leave:read as well as webhooks:manage, and an endpoint whose key or connection loses leave:read stops receiving them. A request carries dates, day count, status and the deciding role only — never reasons, attachments, balances or names — and sick, maternity, paternity, bereavement, Hajj, iddah and marriage leave are shown as leave_type: "personal". Existing keys and connections do not get the scope: create a new key, or ask the company to reconnect your app.
Look up an employee by email or staff number
Addedv1.0
GET /v1/employees accepts two new optional parameters, email and employee_code, for an exact-match lookup. The email match ignores case; the staff number match does not. The answer is one page with next_cursor: null and only ever holds this company's employees. Use one of the two at a time, and not with cursor. Listing without them is unchanged.
No money totals for payroll runs under 3 employees
Changedv1.0
Effective 2026-10-08. A payroll run with fewer than 3 employees now returns totals: null and the new field totals_withheld: "below_min_headcount", because its totals would be one person's pay. Period, status, currency, dates and employee_count are unchanged. The same rule applies to GET /v1/payroll-runs, GET /v1/payroll-runs/{id} (where components and journal are then empty) and the payroll_run.finalized, payroll_run.paid and payroll_run.corrected webhooks. Runs of 3 or more employees are unchanged. Treat totals as nullable and check totals_withheld.
Partner API terms published (version 2026-10-v1)
Changed
The Partner API & Developer Terms are published at /developers/terms/, with the Data Processing Agreement and its Partner Data Processing Terms at /legal/dpa/ and the sub-processor list at /legal/subprocessors/. Live access now needs acceptance of version 2026-10-v1: a customer user accepts it when creating an ah_live_ key, and an org owner or admin accepts it for each app before it connects to a live company. Each company's access still follows the rollout. Deprecation notice is 12 months for a version and 6 months for an endpoint or field.
OAuth tokens can push attendance and manage webhooks
Changed
An OAuth app can now be granted attendance:write and webhooks:manage. With an access token, POST /v1/attendance/events and every /v1/webhooks endpoint work as they do with an API key. Events and endpoints a token creates belong to the app's connection to the company: another app or key gets 404 for them, and when the company revokes the connection (or the app is suspended or deleted) those endpoints are disabled with disabled_reason: "connection_revoked"; reconnecting the app without webhooks:manage disables them with disabled_reason: "scope_removed".
Guides, changelog and a Postman collection
Docs
New guides in English and Arabic: sandbox and testing, API key or OAuth app, webhooks (with signature samples in Node, Python and PHP), versioning and deprecation, and a preview of the planned OAuth flow. A Postman collection generated from openapi.yaml is at /developers/postman.json. The reference now marks which endpoints are live.
API keys, self-serve sandbox and GET /v1/company
Addedv1.0
Scoped API keys under Integrations → API keys: ah_test_ keys for sandbox companies now, ah_live_ keys once the API terms are published. Anyone signed in can create a sandbox company with generated data. GET /v1/company is the first live endpoint; every response carries X-Request-Id and rate-limit headers, and errors use application/problem+json. The developer docs site opened at /developers.
Draft v1 contract published
Docs
The v1 contract (openapi.yaml, draft 1) and the quickstart were published ahead of the implementation so partners can build in parallel: v1.0 reads, v1.1 attendance, v1.2 webhooks.