Sandbox & testing

You build and test against a sandbox company of your own that holds only generated data. You create it yourself with one button; nobody at Ahlan Hamad has to do anything.

Create a sandbox

1. Sign in to Ahlan Hamad, or create a free account.
2. Open Integrations → API keys and press Create sandbox company.
3. Pick the country: Kuwait, Saudi Arabia, UAE, Qatar, Bahrain or Oman. Currency, timezone, weekend and social-insurance rules follow the country you pick.
4. You become the sandbox's CEO by membership only — your current company does not change. Use Switch to sandbox when you want to work in it.
5. In the sandbox, create an API key and choose its scopes. It starts with ah_test_ and is shown once — copy it straight away.

curl https://actions.ahlanhamad.com/v1/company \
  -H "Authorization: Bearer ah_test_…"

Each user can have one sandbox company. Resetting or deleting a sandbox is not available yet.

What the sandbox contains

• A company named Sandbox Trading Co. (شركة التجربة للتجارة) with one legal entity in the country you picked, and "sandbox": true on GET /v1/company.
• Ten generated employees with obviously fictional names, staff numbers SBX-001 to SBX-010: three nationals and seven expatriates; eight full-time, one part-time and one on contract.
• One finalized payroll run for last month, priced with the product's own payroll and social-insurance engine and with its journal posted — what you read is what a real company's run looks like.
• Generated bank and ID details exist only for the in-app screens. The API never returns those fields, in a sandbox or in production.

How test keys behave

• ah_test_ keys work only with sandbox companies, and ah_live_ keys only with real ones. The wrong kind returns 401 unauthenticated.
• Same endpoints, same scopes, same rate limit (600 requests per minute per key by default).
• Webhook events from a sandbox carry "livemode": false.
• A sandbox is not treated as a customer: no subscription, no invoices, no marketing email or reminders.
• Don't put real people's data into a sandbox. It is a test space and everything in it should stay fictional.

What you can call today

Generated from openapi.yaml: the operations that are live now, and the ones published in the contract that have not shipped yet.

Follow the changelog for what ships next. To try every endpoint quickly, import the Postman collection and set its apiKey variable to your ah_test_ key.