Version 1.0.0-draft.1 · generated fromopenapi.yaml(JSON,Postman collection). Endpoints markedlive are served today; the rest are contract only until their release ships (changelog). Base URL:https://actions.ahlanhamad.com.
The Ahlan Hamad Partner API lets approved partners (accounting, point-of-sale, banking) integrate with a company's HR and payroll data in Ahlan Hamad.
Status: DRAFT. This contract is published ahead of the implementation so partners can build in parallel. Every operation carries an x-release marker:
Shapes may still change before each release ships; after it ships, v1 only changes additively (new fields, new optional parameters, new enum values, new event types). Clients must ignore unknown fields and tolerate unknown enum values.
Data protection. v1 never returns salaries, allowances per employee, bank details (IBAN), civil ID / passport numbers, dates of birth, social insurance numbers, or documents. Payroll data is available only as run-level totals and journal lines — and only for runs of at least 3 employees. For a smaller run the totals would be one person's pay, so it is returned with totals: null and totals_withheld: "below_min_headcount" (see PayrollRunSummary).
Leave requests (leave:read) carry dates, day count, status and who decided as a role (manager, hr, approver) — never the employee's reason, the rejection reason, attachments or medical certificates, leave balances, or approver names. Leave types that reveal health, religion, family or marital status (sick, maternity, paternity, bereavement, Hajj, iddah, marriage) are returned as leave_type: "personal" (see LeaveRequest).
v1.4. The v1.4 operations are API-key only (an OAuth app cannot request them), and a key can never carry a scope its creator's own role does not grant — checked when the key is created and again on every request. No v1.4 operation runs payroll, finalizes a run, moves money or changes bank details.
Payslips (payslips:read) are the one exception to the data protection rule above: each employee's earnings, deductions and net pay for a finalized run (never IBAN, civil ID or bank code). A key gets the scope only with the company's attestation (controller and lawful basis, employees told, a processor agreement with you, and employee consent for staff in Kuwait, Oman or Jordan), re-checked on every request (403 attestation_required). Payslips are not available on live companies until Partner Terms that allow them are in force; sandbox keys can use them today.
Conventions
JSON over HTTPS, UTF-8. Field names are snake_case.
Timestamps are RFC 3339 with an explicit offset (2026-09-29T08:02:11+04:00). Timestamps we return are UTC (Z).
Calendar dates are YYYY-MM-DD; payroll months are YYYY-MM.
Money is a decimal string in the currency's minor-unit precision ("1250.500" KWD/BHD/OMR, "1250.50" SAR/AED/QAR), always paired with an ISO 4217 currency. Never parse money as a float.
IDs are opaque strings. Do not infer structure from them.
Authentication
Authorization: Bearer <key>. Keys are created in Ahlan Hamad under Integrations → API keys by a company user with the integrations.manage permission (CEO or HR admin by default). A key belongs to exactly one company, carries a fixed set of scopes, and is shown once at creation.
ah_live_… keys work only for live companies.
ah_test_… keys work only for sandbox companies (fake data you can build against safely). Using the wrong kind returns 401.
Sandbox, self-serve. Anyone with an Ahlan Hamad login can press Create sandbox company (on /developers or Integrations → API keys) to get a private sandbox company pre-filled with fake employees and one finalized payroll run, then issue ah_test_ keys for it. No contact with Ahlan Hamad is needed to start building.
Scopes: employees:read, payroll:read, attendance:read, attendance:write, leave:read, webhooks:manage. GET /v1/company needs none. Subscribing to leave.* webhooks needs leave:read as well as webhooks:manage. The same header also accepts an OAuth access token (ahat_…) issued to a partner app a company connected; it carries the scopes the company granted, any of the six above. Attendance events and webhook endpoints a token creates belong to that app's connection to the company.
Returns partner-safe employee records, oldest first. Archived records are never returned. To follow changes, subscribe to the employee.* webhooks (v1.2) instead of polling; there is no updated_since filter in v1.
Parameters
Name
In
Type
Description
status
query
string
active — currently employed (every status except left). left — employment has ended. Omit for both.
One of: active, left
entity_id
query
string
Only employees of this legal entity (see Company.entities).
email
query
string
Exact-match lookup by contact email (case-insensitive). Returns the matching employees of this company in one page with next_cursor: null; an email on file at another company returns nothing. Cannot be combined with employee_code or cursor.
Max 256 characters
employee_code
query
string
Exact-match lookup by the company's own staff number (Employee.employee_code, case-sensitive). One page, next_cursor: null. Cannot be combined with email or cursor.
Max 256 characters
limit
query
integer
Page size.
Range: 1–200Default: 50
cursor
query
string
Opaque next_cursor from the previous page. Omit for the first page.
Adds a person as a draft: a pending employee invite, the same record HR's "Invite employee" creates. The person becomes an Employee (and employee.created fires) only when they accept the invite. Their login role is always employee.
With send_invite: false (the default) nothing is sent: the draft waits in Employees → Invites for HR to review and send. With send_invite: true the invite email (and WhatsApp, when a phone is given) goes out immediately.
Give an email, a phone, or both. A second draft for the same email or phone while one is pending, or for someone already in the company, answers 409 conflict — so retrying a request is safe. Pay, bank and identity fields cannot be set through the API.
Changes job_title_en, job_title_ar and/or department — nothing else. Pay, bank details, identity documents, status, dates and the reporting line are not writable through the API. Each changed field shows in the employee's change history with this API key as the actor, and employee.updated fires. Sending the current values is a no-op. Former and archived employees answer 404.
Returns only runs that are finalized or paid, newest month first. Draft runs are never exposed. A company that pays in several countries has one run per country (and legal entity) per month.
Run totals, a breakdown by pay component (each with the number of employees it applies to), and the double-entry journal Ahlan Hamad posted for the run. No per-employee amounts are returned.
A run with fewer than 3 employees carries no money at all: totals is null, totals_withheld is below_min_headcount, and components and journal are empty arrays.
Per-employee pay for FINALIZED or PAID runs: earnings by component, gross, total deductions and net pay. Pass payroll_run_id (every payslip of that run), employee_id (that employee's payslips, newest first) or both. Draft runs are never returned. Read-only: nothing here runs, finalizes or pays payroll. Never returns IBAN, civil ID or bank code.
Parameters
Name
In
Type
Description
payroll_run_id
query
string
employee_id
query
string
limit
query
integer
Page size (this endpoint does per-row work, so the maximum is 50).
Range: 1–50Default: 50
cursor
query
string
Opaque next_cursor from the previous page. Omit for the first page.
Submit up to 500 events per request. Each event is processed independently and the response lists one result per event, in the same order as the request.
Idempotent on external_id (per company and source): resending an event you already sent returns duplicate and changes nothing, so it is always safe to retry a request that timed out.
Employee matching.employee_ref identifies the person. Events whose employee cannot be matched are stored, not dropped, with result unmatched_employee: the company's HR team links the person once in Ahlan Hamad and every stored event for them is then processed automatically. You do not need to resend.
Branches.branch_ref is your identifier for the location. An unknown branch never rejects an event — it is stored as given and HR can map it later.
Clock events are paired into shifts in the employee's attendance time zone — their work country's, else the company's configured zone; a shift that crosses midnight belongs to the day it started. Break time is subtracted from worked time.
Pairing rules. Events may arrive late or out of order; the day is recomputed from every event you have sent for that person.
A second clock_in while a shift is already open is treated as a repeat and ignored (the shift keeps the earlier start).
A clock_out with no open shift is ignored.
A clock_out more than 16 hours after its clock_in does not pair; the shift stays open with no clock-out.
Breaks count only inside an open shift; a break still open at clock_out ends there.
Days recorded elsewhere. If the employee app or the company's HR team already recorded that employee's day, your events are stored and answered accepted, but that day is not overwritten.
Validation. A request whose body is malformed (an event without external_id, employee_ref or source, a source that breaks the pattern, meta over 2 KB, …) is refused whole with 422 and nothing is stored. Problems with one event's type or at reject only that event (see AttendanceEventResult.reason).
The company has no time zone set, so clock events cannot be placed on a day (code: conflict). Nothing is stored; retry once the company has set its time zone.
One record per employee per day, as Ahlan Hamad holds it after pairing clock events. Includes days recorded by other sources (the employee app, manual HR entries) — check sources.
Parameters
Name
In
Type
Description
fromrequired
query
string (date)
torequired
query
string (date)
Inclusive. At most 62 days after from.
employee_id
query
string
Only this employee's days. An ID that is not an employee of this company returns an empty page.
limit
query
integer
Page size.
Range: 1–200Default: 50
cursor
query
string
Opaque next_cursor from the previous page. Omit for the first page.
The company's leave requests in the LeaveRequest form — dates, day count, status and a privacy-masked type; never reasons, attachments or balances. Requests of archived employees are not returned.
Order. Without updated_since: most recently changed first. With updated_since: oldest change first from that instant, so a poller can keep the newest updated_at it has seen and pass it next time (expect to see that last row again; deduplicate on id + updated_at). With employee_id: that employee's requests, newest first.
updated_at moves only when something in LeaveRequest changes. A filtered page can hold fewer than limit items while next_cursor is set; a cursor is valid only with the same employee_id and updated_since it was issued for.
Parameters
Name
In
Type
Description
status
query
string
One of: pending, approved, rejected, cancelled
employee_id
query
string
Only this employee's requests. An ID that is not an employee of this company returns an empty page.
updated_since
query
string (date-time)
Only requests whose updated_at is at or after this instant (RFC 3339 with an offset).
limit
query
integer
Page size.
Range: 1–200Default: 50
cursor
query
string
Opaque next_cursor from the previous page. Omit for the first page.
Each current employee's ANNUAL leave balance for this calendar year, as of today, from the same engine the app's leave screens use (entitlement with carry-over, days used, days remaining). Other leave types are not included yet. Former and archived employees are not returned.
Parameters
Name
In
Type
Description
employee_id
query
string
Only this employee. An ID that is not a current employee of this company returns an empty page.
limit
query
integer
Page size (this endpoint does per-row work, so the maximum is 50).
Range: 1–50Default: 50
cursor
query
string
Opaque next_cursor from the previous page. Omit for the first page.
The departments configured in Settings → Departments, each with the number of current employees filed under it, followed by any department employees carry that Settings does not list (configured: false). One page, always: next_cursor is null. Match an employee's department against id.
Dated obligations in the next days days, oldest first: payroll cut-off and pay days from the company's payroll schedules, and the WPS clock of each finalized run (the day wages fall due, or Saudi Mudad's file window, with the last on-time day). WPS items stay listed for days days after their last day so an overdue one is visible. Social-insurance contribution dates and document expiries are not included yet. One page, always.
The response includes the endpoint's signing secretonce. Store it; it cannot be retrieved again (rotate by deleting and re-creating). The URL must be https:// on a public host.
The last 100 deliveries to this endpoint, newest first: what we sent, when, what your server answered, and whether we will retry. The same log is visible to the company in Ahlan Hamad under Integrations → API keys. Deliveries older than 30 days are removed.
Parameters
Name
In
Type
Description
webhook_idrequired
path
string
status
query
string
One of: succeeded, failed, pending
Responses
Status
Description
Body
200
Up to 100 deliveries.
object
401
Missing, malformed, revoked or wrong-environment API key.
Re-sends the original event (same event id, same payload, fresh signature and timestamp) as a new delivery attempt. Works for any delivery in the log, including successful ones, and on an endpoint that was auto-disabled — re-enable it first with PATCH. A redelivery is a single attempt: if it fails it is not retried automatically.
Parameters
Name
In
Type
Description
webhook_idrequired
path
string
delivery_idrequired
path
string
Responses
Status
Description
Body
202
Queued. The new attempt appears in the deliveries log.
Every delivery is a WebhookEventenvelope whose data depends on the event type. Verify theX-AH-Signature header on every delivery — see thewebhooks guide.
Event
When
Release
employee.created
An employee was added
v1.2
employee.updated
A partner-visible field of an employee changed
Sent when any field in the Employee schema changes. Delivered at least once and possibly late (a nightly reconciliation catches changes made through bulk tools); always re-read the embedded object rather than diffing.
v1.2
employee.left
An employee's employment ended
v1.2
payroll_run.finalized
A payroll run was closed and its journal posted
v1.2
payroll_run.paid
A payroll run was marked paid and its payment journal posted
v1.2
payroll_run.corrected
A closed payroll run's amounts changed
A correction was applied to a run that was already finalized or paid. Totals and journal lines may have changed — re-fetch the run with GET /v1/payroll-runs/{id}.
v1.2
payroll_run.deleted
A finalized payroll run was deleted and its journal reversed
v1.2
attendance.rejected
A stored clock event could not become attendance
Sent for events that were accepted but later could not be paired into a valid shift (e.g. a clock-out with no clock-in, or a shift over 16 hours), and for events still unmatched to an employee after 72 hours. Not yet emitted: v1.2 accepts subscriptions to this type today, but no attendance.rejected events are sent until the pairing release wires the emitter up.
v1.2
leave.requested
A leave request was submitted
Sent for every new request, whoever filed it (the employee in the app, WhatsApp or Slack, or HR on their behalf). Needs leave:read on the key or connection that owns the endpoint, at subscription AND at delivery time. A request recorded already decided is followed by its decision event.
v1.3
leave.approved
A leave request was finally approved
Final approval only — an earlier step clearing it (the manager) is leave.updated with a new awaiting.
v1.3
leave.rejected
A leave request was rejected
The rejection reason is never sent.
v1.3
leave.cancelled
A leave request was cancelled or withdrawn
By the employee, by HR, or automatically when employment ends before the leave starts.
v1.3
leave.updated
A pending or approved request changed without a decision
The next approver changed (awaiting), or the dates / day count changed (e.g. trimmed to an employee's last working day). Re-read the embedded object rather than diffing.
v1.3
ping
Test event sent by the "send test event" action
v1.2
Schemas
Problem
RFC 9457 (formerly 7807) problem details.
Field
Type
Description
typerequired
string (uri)
titlerequired
string
statusrequired
integer
detail
string
coderequired
string
Stable machine-readable error code. Branch on this, not on title.
Pass as cursor to get the next page. null on the last page. A filtered page can hold fewer than limit items (even none) while next_cursor is still set — keep paging until it is null.
Month
stringPattern: ^[0-9]{4}-(0[1-9]|1[0-2])$
Money
Decimal string in the currency's minor-unit precision.
The employee's work country, falling back to the company's. null only for a record with neither on file.
entity_id
string | null
work_location
null | object
The branch / site the employee is assigned to, if any.
manager_id
string | null
email
string (email) | null
Contact email on file (usually the work address).
phone
string | null
Contact phone on file, E.164 where available.
hire_daterequired
string (date)
termination_date
string (date) | null
external_ids
map of string
Identifiers this person has in partner systems, keyed by partner app (e.g. {"qompos": "cashier-0042"}). Only the calling key's own app is included. Available from v1.1.
Run-level money totals. null when totals_withheld is set: a run with fewer than 3 employees is never totalled for partners, because its "aggregate" would reveal an individual's pay. Run metadata and employee_count are still returned.
totals_withheldrequired
string | null
Why totals is null — null when totals are returned. below_min_headcount: the run has fewer than 3 employees. 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.* webhook bodies. A correction can move a run across the line in either direction. New reasons may be added; treat an unknown value as "withheld".
One of: below_min_headcount
last_corrected_at
string (date-time) | null
Set if a correction changed this run after it was closed.
The journal entries Ahlan Hamad posted for this run: the accrual leg when the run was finalized, and the payment leg once it is marked paid. Each entry balances (sum of debits = sum of credits). Empty when totals_withheld is set.
PayrollComponent
Field
Type
Description
typerequired
string
New types may be added; treat unknown values as "other". eosb_accrual and wps_bank_fees appear once end-of-service accrual and wage-protection fees are included in the payroll journal.
external_id — your own identifier for the person (recommended). HR links it to the employee once; after that it always matches.
employee_id — Ahlan Hamad's Employee.id.
employee_code — the company's staff number.
email, phone — matched against the employee's contact details. Phones are compared as E.164, so +971501234567, 00971501234567 and 050 123 4567 are the same number. Send the full international number; a national one is read in the company's Gulf country.
A reference that does not match exactly one employee is held as unmatched_employee until HR links it — whichever type you used.
One of: external_id, employee_id, employee_code, email, phone
valuerequired
string
Max 256 characters
AttendanceEventInput
Field
Type
Description
external_idrequired
string
Your unique ID for this event. Makes the call idempotent.
One of: clock_in, clock_out, break_start, break_end
atrequired
string (date-time)
When it happened, RFC 3339 with offset (e.g. 2026-09-29T08:02:11+04:00). Free text, a time without an offset and impossible dates (2026-02-30) are rejected per event with invalid_timestamp. Must not be more than 5 minutes in the future or 35 days in the past.
branch_ref
string
Your identifier for the location.
Max 128 characters
sourcerequired
string
Your system's name, fixed per integration (e.g. qompos). A key issued for a named partner app only accepts that app's name here (a Qompos key must send qompos); otherwise the request is refused with 422.
Pattern: ^[a-z0-9_-]{2,32}$
meta
object
Free-form, stored for support (max 2 KB). Never interpreted.
AttendanceEventResult
Field
Type
Description
external_idrequired
string
event_id
string
statusrequired
string
accepted — stored and matched to an employee.
duplicate — already received; nothing changed.
unmatched_employee — stored; will be processed once HR links the person.
rejected — not stored; see reason.
One of: accepted, duplicate, unmatched_employee, rejected
reason
string
Present when status is rejected.
One of: invalid_timestamp, timestamp_out_of_range, invalid_type, employee_left, period_locked
detail
string
AttendanceDay
Field
Type
Description
employee_idrequired
string
daterequired
string (date)
statusrequired
string
One of: present, late, half_day, absent, on_leave, holiday
first_in
string (date-time) | null
last_out
string (date-time) | null
worked_minutesrequired
integer
Time in closed shifts minus breaks. 0 while the day's only shift is still open.
break_minutesrequired
integer
sourcesrequired
array of string
Where the day's record came from: your source for days built from your events, employee_app for the Ahlan Hamad employee app, and manual for anything HR entered.
LeaveRequest
A leave request, minimised. Never included: the employee's reason or note, the rejection reason, attachments / medical certificates, leave balances, approver names or user IDs. Requires leave:read.
Field
Type
Description
idrequired
string
employee_idrequired
string
employee_coderequired
string | null
leave_typerequired
string
The leave type's stable code, except that sick, maternity, paternity, bereavement, Hajj, iddah and marriage leave are all returned as personal (they reveal health, religion, family or marital status). New types may be added; treat unknown values like personal.
One of: annual, unpaid, study, emergency, personal
leave_type_maskedrequired
boolean
True when leave_type is personal because the real type is withheld.
start_daterequired
string (date) | null
end_daterequired
string (date) | null
daysrequired
number
Days the request counts, as the leave engine counted them.
statusrequired
string
One of: pending, approved, rejected, cancelled
awaitingrequired
string | null
Pending only — whose decision it waits on (a role, never a person).
One of: manager, hr, approver
decided_by_rolerequired
string | null
Approved / rejected — the deciding role, when recorded. For a cancelled request that had been approved, the role that APPROVED it (cancelling no longer clears it); null for a request withdrawn while still pending, and for requests cancelled before 12 October 2026.
One of: manager, hr, approver
decided_atrequired
string (date-time) | null
When it was approved or rejected; null while pending. For a cancelled request that had been approved, the time of that approval when recorded. Otherwise (a request withdrawn while pending, or one cancelled before 12 October 2026) it is the time of the cancellation, as before — prefer cancelled_at for that.
cancelled_atrequired
string (date-time) | null
Cancelled only — when it was cancelled. null for every other status. Added 12 October 2026 (additive).
cancelled_by_rolerequired
string | null
Cancelled only — who cancelled it, as a role: employee (withdrew their own pending request), hr, or system (leave released automatically when the employment ended before it started). null for other statuses and for requests cancelled before 12 October 2026. Added 12 October 2026 (additive).
One of: employee, hr, system
created_atrequired
string (date-time)
updated_atrequired
string (date-time)
Last change to anything in this object.
EmployeeDraftInput
Field
Type
Description
name_enrequired
string
Max 120 characters
name_ar
string
Max 120 characters
email
string (email)
Max 254 characters
phone
string
International format, e.g. +96550000000.
Max 32 characters
department
string
A department id from GET /v1/departments, or its name.
https:// only, on a public host. Private, loopback and link-local addresses are refused — as literals, and when the host name resolves to one (checked again before every delivery). A company can register at most 20 endpoints.
False after 7 days of failed deliveries, when the API key that owns it is revoked (key_revoked), or — for an endpoint created with an OAuth access token — when the company revokes the app's connection, or the app is suspended or deleted (connection_revoked), or when the company reconnects the app without webhooks:manage (scope_removed). Re-enable with PATCH once fixed (for connection_revoked / scope_removed, after the company reconnects the app with webhooks:manage).
disabled_reason
string | null
One of: delivery_failures, key_revoked, connection_revoked, scope_removed, manual
created_atrequired
string (date-time)
last_delivery
null | object
WebhookDelivery
Field
Type
Description
idrequired
string
event_idrequired
string
event_typerequired
string
attemptrequired
integer
1 for the first try; increments on each retry or redelivery.
statusrequired
string
One of: succeeded, failed, pending
response_status_code
integer | null
Your server's HTTP status, or null if the connection failed or timed out.
response_body_excerpt
string | null
First 1 KB of your response body.
error
string | null
Our side of a failure (timeout, DNS, TLS, connection refused, a destination that resolves to a private address, a redirect). A delivery cancelled before it was sent (endpoint disabled or deleted, key or connection revoked) has status: failed and an error starting Cancelled:.
duration_ms
integer | null
created_atrequired
string (date-time)
next_attempt_at
string (date-time) | null
When we will retry, if we will.
request
object
Exactly what we sent.
WebhookEvent
Envelope for every webhook delivery.
Verify every delivery. Each request carries X-AH-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256> where the HMAC is computed with the endpoint's secret over <t>.<raw request body>. Reject if the signature does not match or t is more than 5 minutes from your clock.
Delivery. At least once, not necessarily in order. Deduplicate on id. Respond 2xx within 10 seconds; otherwise we retry after 1 min, 5 min, 30 min, 2 h, 12 h and 24 h. Redirects (3xx) are not followed and count as a failure. After 7 days of failures the endpoint is disabled and the company owner is emailed.
Each request also carries X-AH-Event-Id (= id), X-AH-Event-Type and X-AH-Delivery-Id (the WebhookDelivery.id in the log).