ahlan hamad

Ahlan Hamad Partner API

Connect your product to the HR and payroll data of the GCC companies that use Ahlan Hamad — with their permission, one company at a time. Accounting systems read finalized payroll as balanced journals; POS and time-clock systems send shifts that flow into payroll; everyone can follow changes through signed webhooks.

Pilot. The API is opening to partners in stages and the contract is still a draft (1.0.0-draft.1). After each release ships, v1 only grows — new fields, parameters, enum values and events — and never removes anything.
QuickstartSandbox, first request, attendance, webhook signatures.API referenceEvery endpoint, event and field.OpenAPI specDownload openapi.yaml for Postman, Swagger or codegen.ErrorsEvery error code and what to do about it.

What ships when

ReleaseWhat you can do
v1.0Read company, employees and closed payroll runs (totals and journals)
v1.1Push clock events from POS and time-clock systems; read attendance back
v1.2Webhooks: signed events, delivery log and redelivery

Each endpoint in the reference is tagged with the release it ships in. The contract is also available as JSON.

Start building

  1. Sign in to Ahlan Hamad, or create a free account.
  2. Open Integrations → API keys and chooseCreate sandbox company. You pick the country; the sandbox comes with generated employees and a finalized payroll run.
  3. Switch to the sandbox, create an API key (it starts with ah_test_) and copy it — it is shown once.
  4. Call the API:
    curl https://actions.ahlanhamad.com/v1/company \
  -H "Authorization: Bearer ah_test_…"

To go live with a customer, the customer creates an ah_live_key for you in their own account and chooses what it can access. Your code does not change — only the key.

What data you get — and what you never get

Available: company details and legal entities; employees' names (English and Arabic), staff numbers, job titles, departments, branches, status and dates; closed payroll runs as totals, per-component breakdowns and the double-entry journal; attendance.

Never returned: individual salaries or allowances, bank details, civil ID or passport numbers, dates of birth, social insurance numbers, documents, or reasons for leaving.

Base URL

Support

Email support@ahlanhamad.comand include the X-Request-Id of the call you are asking about. Use of the API is subject to the API terms.