ahlan hamad

API reference

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:

ReleaseContents
v1.0Company, employees, payroll runs (read)
v1.1Attendance ingest + read-back
v1.2Webhook endpoints + events
v1.3Leave requests (read) + leave.* events
v1.4Departments, leave balances, payslips, compliance deadlines (read); employee drafts (write)

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

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.

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.

Company

The company this API key belongs to

GET/v1/companylive · v1.0any valid key

Available to every valid key; no scope required.

Responses

StatusDescriptionBody
200

The company.

Company
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
429

Too many requests for this key.

Problem

Employees

List employees

GET/v1/employeeslive · v1.0scope: employees:read

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

NameInTypeDescription
statusquerystring

active — currently employed (every status except left). left — employment has ended. Omit for both.

One of: active, left
entity_idquerystring

Only employees of this legal entity (see Company.entities).

emailquerystring

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_codequerystring

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
limitqueryinteger

Page size.

Range: 1–200Default: 50
cursorquerystring

Opaque next_cursor from the previous page. Omit for the first page.

Responses

StatusDescriptionBody
200

A page of employees.

Page + object
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
429

Too many requests for this key.

Problem

Add an employee as a draft

POST/v1/employeeslive · v1.4scope: employees:write

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.

Request body

EmployeeDraftInput

Responses

StatusDescriptionBody
201

The draft.

EmployeeDraft
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
409

A pending draft or a person in this company already has this email or phone.

Problem
422

The body is well-formed JSON but fails validation.

Problem
429

Too many requests for this key.

Problem

Get one employee

GET/v1/employees/{employee_id}live · v1.0scope: employees:read

Parameters

NameInTypeDescription
employee_idrequiredpathstring

Responses

StatusDescriptionBody
200

The employee.

Employee
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem
429

Too many requests for this key.

Problem

Update an employee's job title or department

PATCH/v1/employees/{employee_id}live · v1.4scope: employees:write

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.

Parameters

NameInTypeDescription
employee_idrequiredpathstring

Request body

EmployeeJobUpdate

Responses

StatusDescriptionBody
200

The employee after the change.

Employee
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem
422

The body is well-formed JSON but fails validation.

Problem
429

Too many requests for this key.

Problem

Payroll

List closed payroll runs

GET/v1/payroll-runslive · v1.0scope: payroll:read

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.

Parameters

NameInTypeDescription
fromqueryMonth

First payroll month to include (inclusive).

toqueryMonth

Last payroll month to include (inclusive).

statusquerystringOne of: finalized, paid
limitqueryinteger

Page size.

Range: 1–200Default: 50
cursorquerystring

Opaque next_cursor from the previous page. Omit for the first page.

Responses

StatusDescriptionBody
200

A page of payroll runs (summary form).

Page + object
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
429

Too many requests for this key.

Problem

Get a closed payroll run with its components and journal

GET/v1/payroll-runs/{payroll_run_id}live · v1.0scope: payroll:read

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.

Parameters

NameInTypeDescription
payroll_run_idrequiredpathstring

Responses

StatusDescriptionBody
200

The payroll run.

PayrollRun
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem
429

Too many requests for this key.

Problem

List payslips

GET/v1/payslipslive · v1.4scope: payslips:read

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

NameInTypeDescription
payroll_run_idquerystring
employee_idquerystring
limitqueryinteger

Page size (this endpoint does per-row work, so the maximum is 50).

Range: 1–50Default: 50
cursorquerystring

Opaque next_cursor from the previous page. Omit for the first page.

Responses

StatusDescriptionBody
200

A page of payslips.

Page + object
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem
429

Too many requests for this key.

Problem

Attendance

Push clock events (clock in/out, breaks)

POST/v1/attendance/eventslive · v1.1scope: attendance:write

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).

Request body

FieldTypeDescription
eventsrequiredarray of AttendanceEventInputUp to 500 items

Example:

{
  "events": [
    {
      "external_id": "qompos-sess-8812-in",
      "employee_ref": {
        "type": "external_id",
        "value": "cashier-0042"
      },
      "type": "clock_in",
      "at": "2026-09-29T08:02:11+04:00",
      "branch_ref": "dubai-marina-01",
      "source": "qompos"
    },
    {
      "external_id": "qompos-sess-8812-out",
      "employee_ref": {
        "type": "external_id",
        "value": "cashier-0042"
      },
      "type": "clock_out",
      "at": "2026-09-29T16:31:40+04:00",
      "branch_ref": "dubai-marina-01",
      "source": "qompos"
    }
  ]
}

Responses

StatusDescriptionBody
207

Per-event results, in request order.

object
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
409

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.

Problem
413

More than 500 events, or body larger than 1 MB.

Problem
422

The body is well-formed JSON but fails validation.

Problem
429

Too many requests for this key.

Problem

Read back daily attendance

GET/v1/attendancelive · v1.1scope: attendance:read

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

NameInTypeDescription
fromrequiredquerystring (date)
torequiredquerystring (date)

Inclusive. At most 62 days after from.

employee_idquerystring

Only this employee's days. An ID that is not an employee of this company returns an empty page.

limitqueryinteger

Page size.

Range: 1–200Default: 50
cursorquerystring

Opaque next_cursor from the previous page. Omit for the first page.

Responses

StatusDescriptionBody
200

A page of attendance days.

Page + object
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
429

Too many requests for this key.

Problem

Leave

List leave requests

GET/v1/leave-requestslive · v1.3scope: leave:read

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

NameInTypeDescription
statusquerystringOne of: pending, approved, rejected, cancelled
employee_idquerystring

Only this employee's requests. An ID that is not an employee of this company returns an empty page.

updated_sincequerystring (date-time)

Only requests whose updated_at is at or after this instant (RFC 3339 with an offset).

limitqueryinteger

Page size.

Range: 1–200Default: 50
cursorquerystring

Opaque next_cursor from the previous page. Omit for the first page.

Responses

StatusDescriptionBody
200

A page of leave requests.

Page + object
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
429

Too many requests for this key.

Problem

List annual leave balances

GET/v1/leave-balanceslive · v1.4scope: leave_balances:read

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

NameInTypeDescription
employee_idquerystring

Only this employee. An ID that is not a current employee of this company returns an empty page.

limitqueryinteger

Page size (this endpoint does per-row work, so the maximum is 50).

Range: 1–50Default: 50
cursorquerystring

Opaque next_cursor from the previous page. Omit for the first page.

Responses

StatusDescriptionBody
200

A page of balances.

Page + object
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem
429

Too many requests for this key.

Problem

Departments

List departments

GET/v1/departmentslive · v1.4scope: departments:read

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.

Responses

StatusDescriptionBody
200

Every department.

Page + object
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem
429

Too many requests for this key.

Problem

Compliance

List upcoming compliance deadlines

GET/v1/compliance-deadlineslive · v1.4scope: compliance:read

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.

Parameters

NameInTypeDescription
daysqueryinteger

Window in days.

Range: 1–60Default: 60

Responses

StatusDescriptionBody
200

The deadlines in the window.

Page + object
400

Malformed request (bad query parameter, invalid JSON, unknown cursor).

Problem
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem
429

Too many requests for this key.

Problem

Webhooks

List webhook endpoints registered by the caller

GET/v1/webhookslive · v1.2scope: webhooks:manage

Responses

StatusDescriptionBody
200

Endpoints owned by the caller: the calling API key, or — for an OAuth access token — the app's connection to this company.

object
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem

Register a webhook endpoint

POST/v1/webhookslive · v1.2scope: webhooks:manage

The response includes the endpoint's signing secret once. Store it; it cannot be retrieved again (rotate by deleting and re-creating). The URL must be https:// on a public host.

Request body

WebhookEndpointInput

Responses

StatusDescriptionBody
201

Created.

WebhookEndpoint + object
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
422

The body is well-formed JSON but fails validation.

Problem

Get a webhook endpoint

GET/v1/webhooks/{webhook_id}live · v1.2scope: webhooks:manage

Parameters

NameInTypeDescription
webhook_idrequiredpathstring

Responses

StatusDescriptionBody
200

The endpoint.

WebhookEndpoint
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem

Change URL, events, or re-enable an endpoint

PATCH/v1/webhooks/{webhook_id}live · v1.2scope: webhooks:manage

Parameters

NameInTypeDescription
webhook_idrequiredpathstring

Request body

FieldTypeDescription
urlstring (uri)
eventsarray of WebhookEventType
activeboolean

Responses

StatusDescriptionBody
200

Updated.

WebhookEndpoint
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem
422

The body is well-formed JSON but fails validation.

Problem

Delete a webhook endpoint

DELETE/v1/webhooks/{webhook_id}live · v1.2scope: webhooks:manage

Parameters

NameInTypeDescription
webhook_idrequiredpathstring

Responses

StatusDescriptionBody
204

Deleted. Pending deliveries are cancelled.

—
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem

Send a `ping` event to the endpoint now

POST/v1/webhooks/{webhook_id}/testlive · v1.2scope: webhooks:manage

Parameters

NameInTypeDescription
webhook_idrequiredpathstring

Responses

StatusDescriptionBody
202

Queued for immediate delivery.

—
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem
409

The endpoint is disabled. Re-enable it with PATCH first.

Problem

Recent delivery attempts for an endpoint (self-debugging)

GET/v1/webhooks/{webhook_id}/deliverieslive · v1.2scope: webhooks:manage

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

NameInTypeDescription
webhook_idrequiredpathstring
statusquerystringOne of: succeeded, failed, pending

Responses

StatusDescriptionBody
200

Up to 100 deliveries.

object
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem

Send one past event again now

POST/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliverlive · v1.2scope: webhooks:manage

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

NameInTypeDescription
webhook_idrequiredpathstring
delivery_idrequiredpathstring

Responses

StatusDescriptionBody
202

Queued. The new attempt appears in the deliveries log.

WebhookDelivery
401

Missing, malformed, revoked or wrong-environment API key.

Problem
403

The key is valid but lacks the required scope (insufficient_scope), or the Partner API is not enabled for this company (api_not_enabled).

Problem
404

No such resource in this company (or not visible to partners, e.g. a draft payroll run).

Problem
409

The endpoint is disabled.

Problem

Webhook events

Every delivery is a WebhookEventenvelope whose data depends on the event type. Verify theX-AH-Signature header on every delivery — see thewebhooks guide.

EventWhenRelease
employee.createdAn employee was addedv1.2
employee.updatedA 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.leftAn employee's employment endedv1.2
payroll_run.finalizedA payroll run was closed and its journal postedv1.2
payroll_run.paidA payroll run was marked paid and its payment journal postedv1.2
payroll_run.correctedA 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.deletedA finalized payroll run was deleted and its journal reversedv1.2
attendance.rejectedA 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.requestedA 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.approvedA 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.rejectedA leave request was rejected

The rejection reason is never sent.

v1.3
leave.cancelledA leave request was cancelled or withdrawn

By the employee, by HR, or automatically when employment ends before the leave starts.

v1.3
leave.updatedA 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
pingTest event sent by the "send test event" actionv1.2

Schemas

Problem

RFC 9457 (formerly 7807) problem details.

FieldTypeDescription
typerequiredstring (uri)
titlerequiredstring
statusrequiredinteger
detailstring
coderequiredstring

Stable machine-readable error code. Branch on this, not on title.

One of: invalid_request, unauthenticated, insufficient_scope, api_not_enabled, not_found, conflict, payload_too_large, validation_failed, read_only, attestation_required, confirmation_required, rate_limited, internal_error
request_idrequiredstring
errorsarray of object

Field-level problems (for validation_failed).

Page

FieldTypeDescription
next_cursorrequiredstring | null

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.

stringPattern: ^-?[0-9]+(\.[0-9]{1,3})?$

CountryCode

stringOne of: KW, SA, AE, QA, BH, OM

CurrencyCode

ISO 4217.

string

LocalizedText

FieldTypeDescription
enrequiredstring
arstring | null

Company

FieldTypeDescription
idrequiredstring
namerequiredLocalizedText
countryrequiredCountryCode | null

The company's home country. null if none is on file.

currencyrequiredCurrencyCode | null

The company's currency, or null if not configured.

timezonerequiredstring | null

IANA timezone, e.g. Asia/Kuwait. null if not configured.

sandboxrequiredboolean

True for sandbox companies (fake data, ah_test_ keys).

entitiesrequiredarray of Entity

Legal establishments. A company operating in several GCC countries has one per country; each has its own currency and payroll runs.

Employee

Partner-safe employee record. Salary, bank, ID-document, date-of-birth, insurance-number and exit-reason data are never included.

FieldTypeDescription
idrequiredstring
employee_coderequiredstring | null

The company's own staff number, if it uses one.

namerequiredLocalizedText
job_titlerequiredLocalizedText
departmentrequiredstring
statusrequiredstring

notice_period — resignation or termination recorded, last day not yet reached. left — employment has ended (the reason is not exposed).

One of: active, probation, on_leave, suspended, notice_period, left
employment_typerequiredstringOne of: full_time, part_time, contract
countryrequiredCountryCode | null

The employee's work country, falling back to the company's. null only for a record with neither on file.

entity_idstring | null
work_locationnull | object

The branch / site the employee is assigned to, if any.

manager_idstring | null
emailstring (email) | null

Contact email on file (usually the work address).

phonestring | null

Contact phone on file, E.164 where available.

hire_daterequiredstring (date)
termination_datestring (date) | null
external_idsmap 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.

PayrollRunSummary

FieldTypeDescription
idrequiredstring
monthrequiredMonth
period_startrequiredstring (date)
period_endrequiredstring (date)
pay_datestring (date) | null
statusrequiredstringOne of: finalized, paid
countryrequiredCountryCode
entity_idstring | null
currencyrequiredCurrencyCode
employee_countrequiredinteger
totalsrequiredobject | null

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_withheldrequiredstring | 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_atstring (date-time) | null

Set if a correction changed this run after it was closed.

PayrollRun

Includes every field of PayrollRunSummary.

FieldTypeDescription
componentsrequiredarray of PayrollComponent

Run totals broken down by pay component. Components with a zero total are omitted. Empty when totals_withheld is set.

journalrequiredarray of JournalEntry

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

FieldTypeDescription
typerequiredstring

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.

One of: basic_salary, housing_allowance, transport_allowance, social_allowance, other_allowances, overtime, additions, absence_deductions, leave_deductions, loan_deductions, other_deductions, employee_social_insurance, employer_social_insurance, employer_dews, income_tax, eosb_accrual, wps_bank_fees, net_pay
totalrequiredMoney
employee_countrequiredinteger

Number of employees with a non-zero amount for this component.

JournalEntry

FieldTypeDescription
idrequiredstring
legrequiredstringOne of: accrual, payment
referencerequiredstring
daterequiredstring (date)
currencyrequiredCurrencyCode
statusrequiredstringOne of: posted, reversed
descriptionLocalizedText
linesrequiredarray of JournalLine

JournalLine

FieldTypeDescription
account_coderequiredstring

Account code in the company's Ahlan Hamad chart of accounts (e.g. 5100).

account_namerequiredLocalizedText
account_typestringOne of: asset, liability, equity, revenue, expense
componentstring | null

The PayrollComponent.type this line comes from, when it maps to one.

debitrequiredMoney
creditrequiredMoney
memostring | null

EmployeeRef

FieldTypeDescription
typerequiredstring
  • 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
valuerequiredstringMax 256 characters

AttendanceEventInput

FieldTypeDescription
external_idrequiredstring

Your unique ID for this event. Makes the call idempotent.

Max 128 characters
employee_refrequiredEmployeeRef
typerequiredstringOne of: clock_in, clock_out, break_start, break_end
atrequiredstring (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_refstring

Your identifier for the location.

Max 128 characters
sourcerequiredstring

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}$
metaobject

Free-form, stored for support (max 2 KB). Never interpreted.

AttendanceEventResult

FieldTypeDescription
external_idrequiredstring
event_idstring
statusrequiredstring
  • 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
reasonstring

Present when status is rejected.

One of: invalid_timestamp, timestamp_out_of_range, invalid_type, employee_left, period_locked
detailstring

AttendanceDay

FieldTypeDescription
employee_idrequiredstring
daterequiredstring (date)
statusrequiredstringOne of: present, late, half_day, absent, on_leave, holiday
first_instring (date-time) | null
last_outstring (date-time) | null
worked_minutesrequiredinteger

Time in closed shifts minus breaks. 0 while the day's only shift is still open.

break_minutesrequiredinteger
sourcesrequiredarray 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.

FieldTypeDescription
idrequiredstring
employee_idrequiredstring
employee_coderequiredstring | null
leave_typerequiredstring

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_maskedrequiredboolean

True when leave_type is personal because the real type is withheld.

start_daterequiredstring (date) | null
end_daterequiredstring (date) | null
daysrequirednumber

Days the request counts, as the leave engine counted them.

statusrequiredstringOne of: pending, approved, rejected, cancelled
awaitingrequiredstring | null

Pending only — whose decision it waits on (a role, never a person).

One of: manager, hr, approver
decided_by_rolerequiredstring | 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_atrequiredstring (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_atrequiredstring (date-time) | null

Cancelled only — when it was cancelled. null for every other status. Added 12 October 2026 (additive).

cancelled_by_rolerequiredstring | 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_atrequiredstring (date-time)
updated_atrequiredstring (date-time)

Last change to anything in this object.

EmployeeDraftInput

FieldTypeDescription
name_enrequiredstringMax 120 characters
name_arstringMax 120 characters
emailstring (email)Max 254 characters
phonestring

International format, e.g. +96550000000.

Max 32 characters
departmentstring

A department id from GET /v1/departments, or its name.

Max 80 characters
job_titlestringMax 120 characters
send_invitebooleanDefault: false

EmployeeDraft

FieldTypeDescription
idrequiredstring

The invite's id (not an employee id).

statusrequiredstring

draft = not sent yet; invited = sent.

One of: draft, invited
namerequiredLocalizedText
emailrequiredstring | null
phonerequiredstring | null
departmentrequiredstring | null
job_titlerequiredstring | null
expires_atrequiredstring (date-time)

EmployeeJobUpdate

FieldTypeDescription
job_title_enstringMax 120 characters
job_title_arstringMax 120 characters
departmentstring

A department id from GET /v1/departments, or its name.

Max 80 characters

Department

FieldTypeDescription
idrequiredstring

The value employees carry in department.

namerequiredLocalizedText
configuredrequiredboolean
headcountrequiredintegerRange: 0–…

LeaveBalance

FieldTypeDescription
employee_idrequiredstring
leave_typerequiredstringOne of: annual
yearrequiredinteger
entitled_daysrequirednumber

This year's entitlement plus carried-over days.

used_daysrequirednumber
remaining_daysrequirednumber
as_ofrequiredstring (date)

Payslip

FieldTypeDescription
idrequiredstring
payroll_run_idrequiredstring
employee_idrequiredstring
monthrequiredMonth
currencyrequiredCurrencyCode
earningsrequiredobject
gross_payrequiredMoney

Sum of earnings.

total_deductionsrequiredMoney
net_payrequiredMoney

ComplianceDeadline

FieldTypeDescription
idrequiredstring

Stable for the same obligation across calls.

kindrequiredstringOne of: payroll_cutoff, payday, wps_wages_due, wps_file_window
countryrequiredCountryCode
daterequiredstring (date)
last_dayrequiredstring (date)

Last on-time day (WPS; equals date for payroll milestones).

days_untilrequiredinteger

Days until date (negative once past).

statusrequiredstringOne of: upcoming, due_soon, due_today, in_window, overdue
entity_namerequiredstring | null
payroll_run_idrequiredstring | null
monthrequiredMonth

WebhookEventType

stringOne of: employee.created, employee.updated, employee.left, payroll_run.finalized, payroll_run.paid, payroll_run.corrected, payroll_run.deleted, attendance.rejected, leave.requested, leave.approved, leave.rejected, leave.cancelled, leave.updated

WebhookEndpointInput

FieldTypeDescription
urlrequiredstring (uri)

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.

eventsrequiredarray of WebhookEventType
descriptionstringMax 200 characters

WebhookEndpoint

FieldTypeDescription
idrequiredstring
urlrequiredstring (uri)
eventsrequiredarray of WebhookEventType
descriptionstring | null
activerequiredboolean

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_reasonstring | nullOne of: delivery_failures, key_revoked, connection_revoked, scope_removed, manual
created_atrequiredstring (date-time)
last_deliverynull | object

WebhookDelivery

FieldTypeDescription
idrequiredstring
event_idrequiredstring
event_typerequiredstring
attemptrequiredinteger

1 for the first try; increments on each retry or redelivery.

statusrequiredstringOne of: succeeded, failed, pending
response_status_codeinteger | null

Your server's HTTP status, or null if the connection failed or timed out.

response_body_excerptstring | null

First 1 KB of your response body.

errorstring | 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_msinteger | null
created_atrequiredstring (date-time)
next_attempt_atstring (date-time) | null

When we will retry, if we will.

requestobject

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).

FieldTypeDescription
idrequiredstring

Unique event ID.

typerequiredstring
created_atrequiredstring (date-time)
company_idrequiredstring
livemoderequiredboolean

False for sandbox companies.

datarequiredobject