ahlan hamad

Version 2026-10-v1 · published 7 October 2026. The Partner Data Processing Terms are Schedule 1 of the Data Processing Agreement; the sub-processor list is published separately. ملخص عربي

Partner API & Developer Terms

Version: 2026-10-v1 · Published: 7 October 2026 · Contracting entity: AHLAN HAMAD - FZCO

These terms apply to everyone who builds on the Ahlan Hamad Partner API. The Partner Data Processing Terms in Schedule 1 of the Ahlan Hamad Data Processing Agreement (https://ahlanhamad.com/legal/dpa/) form part of them. An Arabic summary is published at https://ahlanhamad.com/developers/ar/terms/ (see clause 23.2).

Part A — The agreement

1. Who these terms are between

1.1. These Partner API & Developer Terms (the Terms) are an agreement between AHLAN HAMAD - FZCO, a free zone company licensed by the Dubai Integrated Economic Zones Authority under licence no. 89875, Dubai Silicon Oasis, Dubai, United Arab Emirates (Ahlan Hamad, we, us) and the person or organisation that creates a developer organisation, a partner app or an API key, or that uses the API (you). AHLAN HAMAD - FZCO is the contracting entity for partners and Customers in all six GCC states: Kuwait, Saudi Arabia, the United Arab Emirates, Qatar, Bahrain and Oman.

1.2. If you accept these Terms for an organisation, you confirm you have authority to bind it, and “you” means that organisation.

1.3. You accept these Terms by ticking the acceptance box shown when (a) a live API key is created for you, or (b) an owner or admin of your Developer Organisation accepts the Partner API terms for a partner app in the developer console. The version accepted, the time and the user who accepted are recorded. Using the sandbox is also subject to these Terms (see clause 5.6).

1.4. These Terms sit alongside, and do not replace: (a) the Partner Data Processing Terms in Schedule 1 of the Ahlan Hamad Data Processing Agreement (the Partner DPA Terms), which form part of these Terms; (b) any agreement between you and the Customer; and (c) the Ahlan Hamad referral or reseller partner terms, which govern commissions only and apply only if you separately accept them. Nothing in these Terms entitles you to a referral commission, and nothing in the referral or reseller terms grants API access.

1.5. Order of precedence if documents conflict: (1) the Partner DPA Terms, for anything about personal data; (2) these Terms; (3) the API documentation at ahlanhamad.com/developers.

2. Definitions

In these Terms:

3. Developer accounts and organisations

3.1. Any signed-in Ahlan Hamad user may create a Developer Organisation. You must give accurate details (legal name, website, contact email) and keep them current.

3.2. Each Developer Organisation has members with one of three roles: owner (everything, including managing owners), admin (apps, secrets, sandboxes and non-owner members) and developer (read the organisation’s apps and use its sandboxes). You are responsible for who you add, for their roles and for removing people who no longer need access. You are responsible for everything done under your Developer Organisation and API Credentials.

3.3. You must not create a Developer Organisation if you are a person or entity subject to sanctions that would prohibit us from dealing with you.

4. How access works: sandbox, API keys and OAuth Apps

4.1. Sandbox. You may create a sandbox company (currently one per user) holding generated, fictitious data, and a test key (ah_test_…) for it. Test keys work only against sandbox companies; live keys work only against Live companies. You must not load real personal data into a sandbox. We may reset, limit or delete sandbox companies at any time, with or without notice, and we may delete any sandbox company that has had no activity for 90 days.

4.2. Live API keys (private, single-company integrations). A Customer user who holds the integrations.manage permission (by default, the Customer’s CEO and HR admin roles) may create a live key for their company and give it to you. A live key is issued only after that user accepts the version of these Terms then in force. A live key reaches one Customer company, with the Scopes chosen when it was created; Scopes are fixed at creation and the key must be replaced to change them.

4.3. OAuth Apps (multi-customer integrations). If you will connect to more than a small number of Customers, you must register an App and use OAuth 2.0 (authorization code with PKCE S256, confidential clients only). An App in development status can connect only to sandbox companies owned by your Developer Organisation. To connect to Live companies, the App must be published after review (clause 13) or individually allow-listed by us for a pilot, and an owner or admin of your Developer Organisation must accept the current version of these Terms for that App.

4.4. Customer controls. A Customer may, at any time and without notice to you: revoke a live key; revoke a Connection from Integrations → Connected apps; or disable your webhook endpoints. Revocation takes effect immediately. You must not try to keep accessing a Customer after revocation, for example by asking a different Customer user for a new key without the Customer’s knowledge.

4.5. Pilot partners. Partners that integrate during a pilot using live API keys (for example a point-of-sale partner pushing attendance) must move to an OAuth App when we ask, on at least 90 days’ notice.

5. Customer authorisation — the partner’s own relationship with the Customer

5.1. The Customer decides. You may access a Customer’s data only where that Customer has authorised your access through a live key or an approved Connection, and only for the integration the Customer authorised (the Authorised Purpose).

5.2. You need your own contract with the Customer. Before you receive any Customer Data under a Live Connection, you must have a written agreement with the Customer that: (a) describes the service you provide using the Customer Data; (b) if you act as the Customer’s processor, contains the processor terms the applicable law requires (the Partner DPA Terms set out the minimum); and (c) does not conflict with these Terms. We are not a party to that agreement and are not responsible for your service.

5.3. Notice to individuals. The Customer is responsible for informing its employees and other individuals about its use of integrated services. You must provide the Customer with the information it needs to do so (at least: who you are, what data you receive, what you do with it, where it is stored and for how long). Your App listing must link to a privacy notice that is accurate for your App.

5.4. Accuracy of what you send us. Data you send to the API (for example clock-in and clock-out events through attendance:write) is used by the Customer’s Ahlan Hamad account and can affect pay, including absence deductions, late penalties and overtime. You must send only events that genuinely occurred, from the Customer’s own systems, for the Customer’s own employees, with correct timestamps and identifiers, and correct mistakes promptly. You must not fabricate, alter or back-date events. We store and apply events as received; we are not responsible for the accuracy of data you send.

5.5. No onward use against individuals. You must not use Customer Data to make decisions about an individual (for example hiring, firing, discipline, credit, insurance or tenancy decisions) except where the Customer has instructed you to support a decision that the Customer itself makes, and then only as permitted by law.

5.6. Sandbox data. Sandbox data is generated by us and is not Personal Data. You may use it only to develop and test your integration with Ahlan Hamad.

6. Scopes and least privilege

6.1. The current Scopes are:

Scope What it allows (v1)
(none) GET /v1/company — the company profile (name, country, currency, legal entities)
employees:read Employee directory fields: internal ID, employee code, name (EN/AR), job title (EN/AR), department, simplified status, employment type, country, legal entity, work location, manager ID, work email, phone, hire date, termination date; and employee.* webhook events
payroll:read Closed (finalised or paid) payroll runs as run-level totals and journal lines by component, with employee count — never amounts per employee; and payroll_run.* events
attendance:read Daily attendance per employee (date, status, first in, last out, worked and break minutes, sources)
attendance:write Push clock events (clock in/out, break start/end) for employees; includes attendance:read. API keys only for now
webhooks:manage Register and manage webhook endpoints. API keys only for now

6.2. What the API never returns in v1. By design, the API does not return per-employee salaries or allowances, bank details (IBAN), civil ID, national ID, iqama or passport numbers, dates of birth, social-insurance numbers, exit reasons, or documents. Any future access to more sensitive data will require a new Scope, an updated version of these Terms and of the Partner DPA Terms, and the Customer’s specific approval.

6.3. Least privilege. You must request only the Scopes you need for the Authorised Purpose, describe each Scope’s use in your App listing, and not ask Customers for broader access than your integration uses. We may refuse or reduce Scopes we consider unnecessary.

6.4. Small-headcount payroll totals. Run-level payroll totals for a company or legal entity with very few employees can reveal an individual’s pay. You must treat all payroll data received under payroll:read as confidential Customer Data and Personal Data, and must not attempt to derive any individual’s pay from it except as the Customer instructs for its own accounting.

7. Data use limits

7.1. You may use Customer Data only to provide the Authorised Purpose to that Customer, and as the Customer instructs in writing.

7.2. You must not, and must not allow anyone else to:

7.3. Retention. You must keep Customer Data only as long as the Authorised Purpose needs it, and delete it as set out in clause 18.

8. Acceptable use of the API

8.1. You must not:

9. Security requirements

You must implement and maintain at least the following, and any further measures the Partner DPA Terms require:

9.1. Credentials. Store API Credentials only on servers you control, in a secrets manager or encrypted at rest; never in client-side code, mobile apps, browser storage, logs, tickets or source repositories. Limit access to the people and systems that need it. Rotate a credential immediately if it may have been exposed. Use separate credentials for sandbox and Live.

9.2. Transport. Call the API only over HTTPS (TLS 1.2 or later). Webhook endpoints you register must use https:// and must not resolve to private or internal addresses (the API enforces this).

9.3. Webhook verification. Verify the X-AH-Signature header on every webhook delivery (HMAC-SHA256 over "<timestamp>.<raw body>" with your whsec_ secret), reject stale timestamps as described in the documentation, and process deliveries idempotently.

9.4. OAuth. Use PKCE (S256) and an exact registered redirect URI; keep client secrets confidential; handle refresh-token rotation (a reused refresh token revokes the whole token family).

9.5. Your systems. Protect Customer Data with appropriate technical and organisational measures, including encryption in transit and at rest, access control on a need-to-know basis, multi-factor authentication for administrative access, logging of access to Customer Data, timely patching, and staff confidentiality obligations.

9.6. Vulnerabilities. Report any vulnerability you find in the API to support@ahlanhamad.com and do not disclose it publicly until we have had a reasonable opportunity to fix it.

9.7. Security Incidents. You must notify us at privacy@ahlanhamad.com (copying support@ahlanhamad.com) and each affected Customer without undue delay and in any event within 24 hours of becoming aware of a Security Incident, and give us the information in paragraph P5 of the Partner DPA Terms. You must contain the incident, preserve evidence, cooperate with our and the Customer’s investigation, and not notify regulators or individuals about Customer Data on the Customer’s behalf without the Customer’s instructions unless the law requires you to.

9.8. Security questionnaire. When we ask — before publication of your App and at most once a year while it is published — you must answer our security questionnaire truthfully and completely.

10. Rate limits and fair use

10.1. Each API key, and each OAuth Connection, has a request budget — currently 600 requests per minute — and requests over it receive HTTP 429. Attendance pushes are limited to 500 events per request, and events older than 35 days or more than 5 minutes in the future are rejected. We may change limits, or set different limits for particular keys, Apps or Connections, to protect the service.

10.2. A company may hold at most 25 active API keys and 20 webhook endpoints. Webhook deliveries are retried on a fixed schedule (about 40 hours in total); endpoints that keep failing are disabled after 7 days and the owner is told.

11. Logging and monitoring

11.1. We log every API request: the credential or App and Connection used, the company, a request ID, the method, route, HTTP status, duration and time. These logs are kept for 30 days and are visible to the Customer and to you for your own credentials. Webhook delivery records (including the payload sent and an excerpt of your endpoint’s response) are kept for 30 days.

11.2. We monitor use of the API to operate, secure and improve it, to enforce these Terms and to comply with law. We may share with a Customer the logs that relate to that Customer.

12. Suspension and revocation

12.1. We may suspend or revoke any API Credentials, App, Connection or webhook endpoint, immediately and without notice where reasonably necessary: (a) to protect the security or integrity of the API, Customers or Customer Data; (b) if we reasonably believe you have breached these Terms or the Partner DPA Terms; (c) if required by law, a court or a competent authority; (d) if your traffic endangers the service; or (e) if a Customer tells us your access is not authorised.

12.2. Suspending an App stops all its tokens at once, revokes its Connections and notifies the Customer user who approved each Connection by email.

12.3. Where practical and lawful, we will tell you why and give you a chance to fix the problem before or promptly after we act. Suspension does not stop your obligations about Customer Data you already hold.

13. Marketplace listing and app review

13.1. To publish an App you must submit it for review with a complete listing: name, tagline and description in both English and Arabic, logo, website, privacy-policy URL, support email and at least one redirect URI. Listing content must be accurate and not misleading, and must say what data your App uses and why.

13.2. We may approve, reject (with a reason), suspend or reinstate any App at our discretion. Our review is for our own purposes; approval is not a certification, endorsement or warranty of your App, its security or its legal compliance, and you must not describe it as one.

13.3. Published Apps may be listed in the in-app Integrations directory. We do not guarantee placement, ranking or any number of Customers.

13.4. You must keep your listing, privacy notice and support contact current, respond to Customer support requests within 2 working days, and tell us before you materially change what data your App uses.

14. Branding and trademarks

14.1. Subject to these Terms, we grant you a limited, non-exclusive, non-transferable, revocable licence to use the name “Ahlan Hamad” and our logo only to state truthfully that your App integrates with Ahlan Hamad, in line with any brand guidelines we provide. You must not alter the logo (including its colours or ring order), imply partnership, endorsement or certification beyond what is true, or use our marks in a domain, app or company name.

14.2. You grant us a non-exclusive, worldwide, royalty-free licence during the term to use your name, logo and listing content to list, describe and promote your App’s integration with Ahlan Hamad.

15. Fees

15.1. Access to the API is currently free of charge for partners. We may introduce fees, usage tiers or require Customers to hold a particular subscription plan to use integrations, with at least 90 days’ notice. No fees will apply retroactively.

15.2. You are responsible for your own costs and taxes. These Terms do not create any revenue share or commission.

16. Changes to the API and to these Terms

16.1. Versioning. After a v1 release ships, v1 changes only additively (new fields, new optional parameters, new enum values, new event types). You must ignore unknown fields and tolerate unknown enum values.

16.2. Deprecation. We will give at least 12 months’ notice before retiring a whole API version, and at least 6 months’ notice before retiring an endpoint or field, by a changelog entry, Deprecation/Sunset response headers and email to your Developer Organisation’s owners. We may make shorter-notice changes where needed for security, legal compliance or to prevent harm.

16.3. Changes to these Terms. We may update these Terms. We will give at least 30 days’ notice of material changes by email to your Developer Organisation’s owners and on /developers. Changes needed for legal or security reasons may take effect sooner. Every new version has a new version string. When it takes effect: (a) new live keys are issued only to a Customer user who accepts the new version; (b) live keys already issued keep working; and (c) your App’s Live Connections are paused until an owner or admin of your Developer Organisation accepts the new version for that App in the developer console, and resume once they do.

17. Confidentiality

17.1. Each party will keep the other’s non-public information confidential, use it only for these Terms and protect it with at least reasonable care. Our confidential information includes non-public documentation, sandbox credentials and security information. Customer Data is subject to the stricter rules in clause 7 and the Partner DPA Terms.

17.2. This clause does not apply to information that is public through no fault of the receiving party, already known to it, independently developed or lawfully received from a third party, and allows disclosure required by law (with prompt notice where lawful).

18. Term, termination and data deletion

18.1. These Terms apply from your acceptance until terminated. You may stop using the API and close your Developer Organisation at any time. We may terminate these Terms or any App for convenience on 30 days’ notice, or immediately under clause 12.

18.2. When a Connection ends (revoked by the Customer, by you, by us or because the Customer’s subscription ends), you must stop accessing that Customer and, within 30 days, delete or return (at the Customer’s choice) all Customer Data of that Customer, including copies, unless the law requires you to keep it or the Customer has its own contract with you allowing you to keep it for its service. You must confirm deletion in writing on request.

18.3. When these Terms end, all Connections end, all API Credentials are revoked, clause 18.2 applies to every Customer, and clauses 7, 9.7, 11, 17, 18, 19, 20, 21, 22 and 23 survive.

19. Intellectual property

19.1. We and our licensors own the API, documentation, service and our marks. You own your App. Except for the licences expressly granted, no rights are transferred.

19.2. Customer Data belongs to the Customer (or the individuals concerned). Nothing in these Terms gives you or us ownership of it.

19.3. If you give us feedback, we may use it without obligation to you.

20. Disclaimers

20.1. The API is provided “as is” and “as available”. We give no uptime or support-response commitment.

20.2. To the extent the law allows, we disclaim all warranties, express or implied, including merchantability, fitness for a particular purpose, accuracy and non-infringement. Calculations and data returned by the API (including payroll totals and attendance) come from the Customer’s account and are not verified by us for your purposes.

21. Limitation of liability

21.1. To the extent the law allows, neither party is liable for indirect, consequential, special or punitive loss, or for loss of profit, revenue, goodwill or data, arising out of these Terms.

21.2. To the extent the law allows, our total liability arising out of these Terms in any 12-month period is limited to the greater of USD 100 and the fees you paid us in that period.

21.3. The limits in 21.1 and 21.2 do not apply to: your breach of clauses 7, 8 or 9 or the Partner DPA Terms; your indemnity under clause 22; either party’s fraud or wilful misconduct; or any liability that cannot be limited by law.

22. Indemnity

22.1. You will defend and indemnify us, our affiliates and our personnel against any third-party claim, regulatory fine or penalty (to the extent the law allows it to be indemnified), loss and reasonable costs arising from: (a) your breach of these Terms or the Partner DPA Terms; (b) your App or service, including its processing of Customer Data; (c) data you send to the API; or (d) a dispute between you and a Customer or an individual.

22.2. We will notify you promptly of a claim, let you control the defence (we may join with our own counsel at our cost), and not settle in a way that admits fault on your behalf without your consent.

23. General

23.1. Governing law and disputes. These Terms, and any non-contractual obligation arising out of or in connection with them, are governed by the laws of the Emirate of Dubai and the federal laws of the United Arab Emirates as applied in Dubai. Any dispute arising out of or in connection with these Terms, including any question about their existence, validity or termination, is finally resolved by arbitration administered by the Dubai International Arbitration Centre (DIAC) under the DIAC Arbitration Rules in force when the arbitration starts. The seat of arbitration is Dubai, United Arab Emirates, and the language of the arbitration is English. Either party may seek urgent interim relief from any competent court.

23.2. Language. These Terms are made in English. The Arabic summary published at /developers/ar/terms/ is for convenience only and does not change these Terms. Where the law of a GCC state requires an Arabic version for proceedings before its courts or authorities, the Arabic version prevails for those proceedings; otherwise the English version prevails.

23.3. Notices. We send notices to the email of your Developer Organisation’s owners and, for API matters, may also publish them on /developers/changelog. You send notices to support@ahlanhamad.com, with a copy to AHLAN HAMAD - FZCO, Dubai Silicon Oasis, Dubai, United Arab Emirates.

23.4. Assignment. You may not assign these Terms without our written consent. We may assign them to an affiliate or a successor to our business, on notice.

23.5. Relationship. The parties are independent contractors. These Terms create no partnership, agency, employment or exclusivity.

23.6. Export and sanctions. You will comply with applicable export-control and sanctions laws.

23.7. Entire agreement; severability; waiver. These Terms (with the Partner DPA Terms and the documents they refer to) are the entire agreement on their subject. If a provision is invalid, the rest continues. A failure to enforce is not a waiver.

23.8. Third parties. Customers may enforce clauses 5, 7, 9.7, 18.2 and the Partner DPA Terms directly against you. To the extent the governing law does not allow a Customer to enforce them directly, you give each Customer you connect to the same undertakings directly.

23.9. Contact. support@ahlanhamad.com · privacy@ahlanhamad.com for data-protection and security matters · ahlanhamad.com/developers.

Part B — Acceptance wording used in the product

These are the statements shown in the product in English; Arabic-language users see them in Arabic. Words in italics are filled in by the product. Each acceptance records the version, the time and the accepting user.

Live API key dialog (shown to the Customer user creating the key):

☐ I accept the Ahlan Hamad Partner API Terms (version 2026-10-v1) on behalf of company name. I confirm the partner who will receive this key has an agreement with us for the integration, and I understand the key gives them access to the data shown above until I revoke it.

Developer console — “Go live” for an App (shown to an org owner or admin):

☐ I have authority to bind Developer Organisation name and accept the Ahlan Hamad Partner API & Developer Terms and the Partner Data Processing Terms (version 2026-10-v1).

OAuth consent screen (Customer side), under the scope list:

App name is provided by Developer Organisation name, not by Ahlan Hamad. Its use of your data is governed by your agreement with Developer Organisation name and its privacy policy. Ahlan Hamad requires partners to follow the Partner API Terms.

Each screen links to these Terms and to the Data Processing Agreement.