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.
1.0.0-draft.1). After each release ships, v1 only grows — new fields, parameters, enum values and events — and never removes anything.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: الأدلة بالعربية.
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
| Release | What you can do |
|---|---|
v1.0 | Read company, employees and closed payroll runs (totals and journals) |
v1.1 | Push clock events from POS and time-clock systems; read attendance back |
v1.2 | Webhooks: signed events, delivery log and redelivery |
v1.3 | Leave 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.
- Sign in to Ahlan Hamad, or create a free account.
- Open Integrations → API keys and chooseCreate sandbox company. You pick the country; the sandbox comes with generated employees and a finalized payroll run.
- Switch to the sandbox, create an API key (it starts with
ah_test_) and copy it — it is shown once. - 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
https://actions.ahlanhamad.com— Production (live and sandbox companies)
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.