Endpoints

* Any one of the three is enough to connect; all three is best.

Authentication

We send the key in both headers — read whichever you prefer:

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY

• HTTPS on a public host is required. Redirects (301/302) are not followed — give us the final URL.
• The base URL is what /products, /customers and /orders are appended to, e.g. https://api.example.com/v1.
• Use a dedicated read-only key that can be revoked at any time. Each key belongs to one account (company or branch) and returns only its data.

Pagination & response shape

Every endpoint accepts page (1-based) and per_page (we request 200; you may return fewer, e.g. 100, and say so in meta). JSON response:

{ "data": [ ... ], "meta": { "page": 1, "per_page": 200, "total": 1240, "last_page": 7 } }

We also accept "has_more": true|false instead of last_page, or a bare array (we stop at a shorter page). A missing endpoint should return 404. Our default pace is 60 requests per minute, and we honor 429 with Retry-After.

Products

{
  "data": [
    {
      "id": "1001",
      "code": "P-1001",
      "name": "Cordless Drill 18V",
      "brand": "Example Tools",
      "price": 349.00,
      "sale_price": 299.00,
      "currency": "SAR",
      "sku": "DRL-18V",
      "images": ["https://example.com/img/drill-1.jpg", "https://example.com/img/drill-2.jpg"],
      "url": "https://example.com/products/cordless-drill-18v",
      "category": "Power Tools",
      "categories": ["Power Tools", "Drills"],
      "description": "18V cordless drill with 2 batteries and a charger. Keyless chuck 13 mm.",
      "attributes": [{"name": "Voltage", "value": "18V"}, {"name": "Chuck", "value": "13 mm"}, {"name": "Weight", "value": "1.6 kg"}],
      "unit": "piece",
      "stock": 25,
      "in_stock": true,
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 200, "total": 1240, "last_page": 7 }
}

Customers

updated_since is optional: return customers whose details or orders changed since then (used by the daily sync; manual syncs request everything). If you don't support it, return everything.

{
  "data": [
    {
      "id": "C-5521",
      "name": "Sara Ahmed",
      "phone": "+966500000000",
      "email": "sara@example.com",
      "city": "Riyadh",
      "country": "SA",
      "orders_count": 4,
      "total_spent": 1890.50,
      "currency": "SAR",
      "last_order_at": "2026-09-28T17:05:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 200, "total": 8312, "last_page": 42 }
}

Orders optional

When published, we build each customer's purchase history from it (order count · spend · last order) and read it in full on every customer sync. An order without customer_id (a walk-in POS sale) is matched by the phone or email in customer; an order with neither only counts toward orders scanned.

{
  "data": [
    {
      "id": "INV-90017",
      "customer_id": "C-5521",
      "status": "paid",
      "total": 472.50,
      "currency": "SAR",
      "created_at": "2026-09-28T17:05:00Z"
    },
    {
      "id": "INV-90018",
      "customer_id": null,
      "customer": { "name": "Walk-in customer", "phone": "+966511111111", "email": null },
      "status": "paid",
      "total": 89.00,
      "currency": "SAR",
      "created_at": "2026-09-28T18:40:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 200, "has_more": false }
}

Version 2 — data for AI agents optional additions

Extra product fields /products

Items without an image don't enter the Brand Library (it is for design), but they do enter the agents' catalog.

Detailed orders /orders

On top of v1 fields add: number · payment_status (unpaid · partial · paid · refunded) · subtotal · tax · discount · updated_at · items[] (product_id · sku · name · quantity · price · total). Status: pending · processing · completed · cancelled · refunded (paid accepted).

{
  "id": "SO-5531",
  "number": "SO-5531",
  "customer_id": "C-77",
  "customer": { "name": "Sara Ahmed", "phone": "+966500000001", "email": "sara@example.com" },
  "status": "processing",
  "payment_status": "unpaid",
  "currency": "SAR",
  "subtotal": 600.00, "tax": 90.00, "discount": 0, "total": 690.00,
  "created_at": "2026-10-03T12:10:00+03:00",
  "updated_at": "2026-10-03T12:15:00+03:00",
  "items": [
    { "product_id": "1001", "sku": "DRL-18V", "name": "Cordless Drill 18V", "quantity": 2, "price": 300.00, "total": 600.00 }
  ]
}

Suppliers GET /suppliers optional

{
  "data": [
    {
      "id": "S-12",
      "name": "Example Trading Co.",
      "contact_name": "Khalid",
      "phone": "+966512345678",
      "email": "sales@example.com",
      "city": "Jeddah",
      "country": "SA",
      "tax_number": "300000000000003",
      "currency": "SAR",
      "updated_at": "2026-10-02T08:00:00Z",
      "products": [
        { "product_id": "1001", "sku": "DRL-18V", "name": "Cordless Drill 18V", "price": 210.00, "currency": "SAR", "min_qty": 10, "lead_time_days": 5 }
      ]
    }
  ],
  "meta": { "page": 1, "per_page": 200, "has_more": false }
}

Invoices GET /invoices optional

Status: draft · issued · partial · paid · overdue · void. We also mark an invoice overdue ourselves once due_at passes with an amount still due.

{
  "data": [
    {
      "id": "INV-2026-0091",
      "number": "INV-2026-0091",
      "order_id": "SO-5531",
      "customer_id": "C-77",
      "status": "partial",
      "currency": "SAR",
      "total": 690.00, "amount_paid": 200.00, "amount_due": 490.00,
      "issued_at": "2026-10-03", "due_at": "2026-10-17",
      "updated_at": "2026-10-05T09:00:00Z",
      "items": [ { "product_id": "1001", "name": "Cordless Drill 18V", "quantity": 2, "price": 300.00 } ]
    }
  ],
  "meta": { "page": 1, "per_page": 200, "last_page": 1 }
}

Payments GET /payments optional

Each payment links to its invoice (invoice_id) so we update paid and due amounts. Status: completed · pending · failed · refunded.

{
  "data": [
    {
      "id": "PAY-881",
      "invoice_id": "INV-2026-0091",
      "order_id": "SO-5531",
      "customer_id": "C-77",
      "amount": 200.00,
      "currency": "SAR",
      "method": "mada",
      "status": "completed",
      "paid_at": "2026-10-04T16:20:00+03:00"
    }
  ],
  "meta": { "page": 1, "per_page": 200, "has_more": false }
}

Version 3 — full system data for internal agents optional additions

Data classification: public and internal

public may be read by the customer-facing agent, limited to the customer it is talking to (catalog without cost · that customer's orders, invoices, quotes and returns). internal is for internal agents and the owner only: purchases, purchase prices, costs, margins, reps, finance, the audit log and all sales. Alaamah One enforces this itself: a customer-facing agent can never read an internal resource, even if someone enables it, and cost fields never reach it. Send complete data; we do the withholding.

Common shape

• Every endpoint: GET {base}/{path}?page=1&per_page=200&updated_since=… with the same { "data": [...], "meta": {...} } envelope and pagination.
• Optional filters we may send: from · to (document date) · branch_id · warehouse_id · customer_id · supplier_id · user_id · status. Ignore what you don't support.
• A document (quote · purchase order · supplier invoice · goods receipt · return · transfer · adjustment · expense · supplier payment): id required · number · status · customer_id or supplier_id (plus customer/supplier with a name) · user_id or salesperson_id · branch_id · warehouse_id · currency · subtotal · discount · tax · total · amount_paid · amount_due · date · due_at · approved_at · approved_by · updated_at · items[].
• A line: product_id · sku · name · quantity · unit · price · discount (amount) · tax (amount) · total · cost (internal). We keep up to 200 lines per document, stored compactly.
• Documents, movements and the audit log are kept for 24 months by default; older rows are deleted.

{
  "data": [
    {
      "id": "PO-1042",
      "number": "PO-1042",
      "status": "approved",
      "supplier_id": "S-12",
      "supplier": { "name": "Example Trading Co." },
      "user_id": "U-7",
      "branch_id": "BR-1",
      "warehouse_id": "WH-1",
      "currency": "SAR",
      "subtotal": 4200.00, "discount": 200.00, "tax": 600.00, "total": 4600.00,
      "amount_paid": 0, "amount_due": 4600.00,
      "date": "2026-10-03T10:00:00+03:00",
      "due_at": "2026-11-02",
      "approved_at": "2026-10-03T12:30:00+03:00", "approved_by": "U-2",
      "updated_at": "2026-10-03T12:30:00+03:00",
      "items": [
        { "product_id": "1001", "sku": "DRL-18V", "name": "Cordless Drill 18V", "quantity": 20, "unit": "piece",
          "price": 210.00, "discount": 10.00, "tax": 30.00, "total": 4200.00, "cost": 210.00 }
      ]
    }
  ],
  "meta": { "page": 1, "per_page": 200, "has_more": false }
}

Endpoints

In v2, /orders and /invoices also accept salesperson_id (or rep_id) and branch_id, and their lines discount and tax. Customer payments and receipts stay on /payments.

Specific fields

{ "data": [ { "customer_id": "C-77", "name": "Sara Ahmed", "currency": "SAR", "as_of": "2026-10-07",
    "current": 1200.00, "d1_30": 490.00, "d31_60": 0, "d61_90": 0, "d90_plus": 300.00, "total": 1990.00,
    "rep_id": "U-7", "open_invoices": 3, "oldest_invoice_at": "2026-06-20" } ],
  "meta": { "page": 1, "per_page": 200, "last_page": 1 } }

{ "data": [ { "id": "MV-88120", "product_id": "1001", "sku": "DRL-18V", "warehouse_id": "WH-1", "type": "sale",
    "quantity": -2, "unit_cost": 210.00, "document_type": "invoice", "document_id": "INV-2026-0091", "user_id": "U-7",
    "date": "2026-10-03T12:12:00+03:00" } ],
  "meta": { "page": 1, "per_page": 200, "has_more": true } }

Audit log /audit-log

Every create, approve, edit or delete of a document: action (create · approve · edit · delete · cancel · post) · document_type · document_id · document_number · user_id · user_name · summary · at. We also accept event · subject_type · subject_id · description · created_at. Non-document events (vehicle tracking, sessions) are not stored — a subject_type filter helps.

{ "data": [ { "id": "AU-55012", "action": "approve", "document_type": "purchase_order", "document_id": "PO-1042",
    "document_number": "PO-1042", "user_id": "U-2", "user_name": "Finance Manager", "summary": "Approved 4,600.00 SAR",
    "at": "2026-10-03T12:30:00+03:00" } ],
  "meta": { "page": 1, "per_page": 200, "has_more": false } }

Built-in connector support

Based on each system's documented public API. “Custom system (API)” and Alaamah ERP support whatever they publish with this spec. After the first sync, the card under Systems shows what actually arrived.

Webhooks from your system to Alaamah One optional

Instead of waiting for the daily sync, push events as they happen. The account owner enables them in Connected accounts → Systems → Webhooks and gets a URL and a secret unique to that connection (the secret is shown once and can be rotated).

POST https://one.alaamah.com/webhook/systems/{hook_key}
Content-Type: application/json
X-Alaamah-Signature: t=1791012345,v1=5f2b…(hex)

{
  "id": "evt_01J9ZK3M7Q",
  "type": "payment.received",
  "created_at": "2026-10-04T16:20:05+03:00",
  "data": { "id": "PAY-881", "invoice_id": "INV-2026-0091", "customer_id": "C-77", "amount": 200.00, "currency": "SAR", "paid_at": "2026-10-04T16:20:00+03:00" }
}

Purchase tracking (optional)

On order.created and payment.received you may add data.customer.email and a data.tracking object. We use them to send the purchase server-side to the pixels the merchant enabled in One (Meta · Snapchat · TikTok · Google Analytics 4 · Microsoft Advertising). Send the same event_id your browser pixel uses so the platforms merge the two instead of counting twice.

Signature

Header X-Alaamah-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, t + "." + raw body). We reject requests whose timestamp differs from our clock by more than 5 minutes, or with a wrong signature (401). id is unique per event: a re-sent event returns 200 with "duplicate": true and is never applied twice — retry safely on network errors.

# PHP
$t   = time();
$sig = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
$header = "t={$t},v1={$sig}";

# Node.js
const t = Math.floor(Date.now() / 1000);
const sig = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
headers['X-Alaamah-Signature'] = `t=${t},v1=${sig}`;

# Python
t = int(time.time())
sig = hmac.new(secret.encode(), f"{t}.{raw_body}".encode(), hashlib.sha256).hexdigest()

Version 3 events

Same signature and rules as Webhooks: quote.created · quote.approved · po.created · po.approved · goods.received · return.created (data.type: sale · purchase) · payment.made (a supplier payment) · stock.adjusted. data is shaped like the matching endpoint. Internal events: stored, never sent to a customer.

{ "id": "evt_01JA2B3C4D", "type": "po.approved", "created_at": "2026-10-03T12:30:05+03:00",
  "data": { "id": "PO-1042", "number": "PO-1042", "supplier_id": "S-12", "status": "approved", "total": 4600.00, "currency": "SAR",
            "approved_at": "2026-10-03T12:30:00+03:00", "approved_by": "U-2" } }

Connect from Odoo · Daftra · Qoyod · Zoho · SAP · Oracle

MCP server

Alaamah One is a remote Model Context Protocol server. Any MCP client can read the brand identity, list works and products, and create images, flyers and videos on the user's plan.

Connect a client

Add https://one.alaamah.com/mcp as a custom connector (remote MCP server) in your client. The client discovers the authorization server, registers itself and opens the Alaamah One sign-in page, where the user approves access.

{
  "mcpServers": {
    "alaamah-one": { "url": "https://one.alaamah.com/mcp" }
  }
}

OAuth 2.1

• PKCE with S256 is required.
• Send the access token as Authorization: Bearer … on every /mcp request.
• The user can revoke any client at any time from Connected apps in Alaamah One.

Brand selection

An account can own several brands. Studio tools act on the current brand; send X-Alaamah-Brand: <brand id> to choose another. The server accepts it only if the brand belongs to the token owner, otherwise it answers 403.

Preview and confirm

Tools that spend credits never run on the first call. They return a preview with the cost estimate and a plan_token. Ask the user, then call the same tool with the same inputs plus "confirm": true and that plan_token. confirm without a matching token is rejected, and previews expire after 15 minutes.

// 1) preview
{"name": "generate_image", "arguments": {"prompt": "A product shot on a white table"}}
// → a preview with the cost estimate and a plan_token

// 2) run after the user approves
{"name": "generate_image", "arguments": {"prompt": "A product shot on a white table", "confirm": true, "plan_token": "<from the preview>"}}

Tools

53 tools. The list a client sees depends on the user's plan and team permissions.

Error codes & how we handle them

Quick test

curl -H "Authorization: Bearer YOUR_API_KEY" -H "X-API-Key: YOUR_API_KEY" \
  "https://api.example.com/v1/products?page=1&per_page=200"

curl -H "Authorization: Bearer YOUR_API_KEY" -H "X-API-Key: YOUR_API_KEY" \
  "https://api.example.com/v1/customers?page=1&per_page=200&updated_since=2026-10-01T00:00:00Z"

curl -H "Authorization: Bearer YOUR_API_KEY" -H "X-API-Key: YOUR_API_KEY" \
  "https://api.example.com/v1/orders?page=1&per_page=200"

# expected without a key: 401
curl -i "https://api.example.com/v1/products?page=1&per_page=1"

The connection card in Alaamah One also has a “Test connection” button that shows each endpoint's status before connecting.

Pre-launch checklist

• HTTPS URL on a public host, with no redirect.
• Read-only key, read from Authorization: Bearer or X-API-Key; no key returns 401.
• Each key returns only its own account's data (company or branch) — never another company's.
• page and per_page work, and meta.last_page or has_more are correct.
• id values are stable across syncs.
• Every item has at least one https image.
• Phones in international format +966… where possible.
• Dates in ISO 8601 with a timezone (Z or +03:00).
• Unpublished endpoints return 404.

Privacy

Your customer data stays in your brand’s account only, and the key is stored encrypted and never shown again. Disconnecting deletes the key and keeps what was imported (you can delete it). Tags and marketing consent set in Alaamah One are never overwritten by a sync.