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.Postman collectionEvery endpoint, ready to send. Generated from the spec.

Guides

Also in Arabic: الأدلة بالعربية.

Sandbox & testingYour own sandbox company with generated data and ah_test_ keys.API key or OAuth app?One company's integration, or a product many companies connect to.WebhooksSignature verification in Node, Python and PHP; retries and auto-disable.OAuth (preview)The planned authorization-code + PKCE flow.ChangelogWhat is live, what ships next, and what changed.VersioningAdditive within v1; breaking changes only in v2.

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
v1.3Leave requests: dates and status (no reasons or attachments), plus leave webhooks

Each endpoint in the reference is tagged with the release it ships in; the changelog shows which are live. The contract is also available as JSON.

Start building

Request access. The Partner API isn't open to everyone yet: request API access and we'll get back to you — the steps below apply once your access is on.

  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 (runs of 3 or more employees — a smaller run shows no money, since its total would be someone's pay); 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.