Skip to content
حلول

Developers

Build on the Hlool API

One REST API for the whole ERP — the same API our desktop and mobile apps run on. Bearer tokens, strict per-company scoping, and an MCP server for AI clients.

Browse the API reference Download the OpenAPI JSON

Quickstart

From zero to your first call in three steps.

1. Get a token

Sign in to the web app and create a token under Settings → API tokens — it is shown only once, so store it somewhere safe. Programmatic clients can instead exchange credentials at the token endpoint (accounts with two-factor authentication must include a code).

Open Settings → API tokens

2. Pick a company

Call GET /me with your token to list the companies you belong to, then send the chosen company id as the X-Company header on every call. Records of other companies simply do not exist for the request.

3. Make your first call

List endpoints paginate with ?page and ?per_page (default 25, max 100) and answer in the {data, links, meta} envelope.

# 1) Issue a token (or create one in Settings → API tokens)
curl -X POST https://app.hlooltech.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "••••••••", "device_name": "my-integration"}'

# 2) List your companies
curl https://app.hlooltech.com/api/v1/me \
  -H "Authorization: Bearer <token>"

# 3) First call — list contacts of one company
curl "https://app.hlooltech.com/api/v1/contacts?per_page=25" \
  -H "Authorization: Bearer <token>" \
  -H "X-Company: <company-uuid>"

Authentication

Send the token in the Authorization: Bearer header on every request. A token acts as you: your role inside the company decides what each endpoint allows, and every operation in the reference lists the permission it requires. Tokens expire after 90 days; revoke one at any time from Settings → API tokens, or by calling DELETE /auth/token with it.

Company context (X-Company)

Hlool is multi-company. The X-Company header selects the workspace for the request and is required everywhere except the token endpoint and GET /me. If it names a company you do not belong to, the request is rejected.

Errors, limits & pagination

Failures use exactly the shapes below — never a custom envelope. The API allows 120 requests per minute per token; validation errors (422) list every offending field.

401 Token missing, invalid or expired.
403 Your role in this company lacks the permission, or the record belongs to another company.
404 The record does not exist in the selected company.
422 Validation failed — see the per-field errors map. 
{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

AI clients (MCP)

The same token also unlocks the Hlool MCP server: AI clients such as Claude and ChatGPT can query contacts, invoices, sales orders, stock levels, employees and tasks — and create tasks — always under your permissions and your company scope.

Endpoint: POST https://app.hlooltech.com/mcp

On the roadmap

Outgoing webhooks (subscribing to events such as an invoice being paid) and third-party OAuth apps are not available yet — today, integrations authenticate with personal tokens. The provider callbacks we receive (payments, WhatsApp, email delivery) are internal plumbing, not a developer surface.