API reference

Five-minute start

The only call that works today with no key and no setup is the health check. Start with it to confirm your instance is running and the network reaches it.

# replace the domain with your own server
curl https://bot.example.sa/health

# response
{ "ok": true }

Then request a key from the setup team, and store it in an environment variable. Do not put it in front-end code — the key grants full access to your customers’ records.

export NAATEQ_URL=https://bot.example.sa
export NAATEQ_KEY=nq_live_…

curl "$NAATEQ_URL/api/v1/conversations?limit=1" \
  -H "Authorization: Bearer $NAATEQ_KEY"

The base URL is your own domain

Naateq runs On your server, not on a shared cloud. So there is no single URL for all customers — yours is the domain your system was installed on:

https://<your-domain>/api/v1

And this is not a technical detail: it is the same reason your customers’ conversations never pass through a third party, and the same thing you read on the security page. You own the server, the key, and the access log.

The corresponding burden: availability is your responsibility. We do not promise uptime for a server we do not operate, and what we do commit to is written on the support page.

One key in the header

Every request carries your key in Authorization. The key is shown once at creation and never retrieved again — if it is lost, create another and revoke the old one.

# missing or revoked key
HTTP/1.1 401 Unauthorized

{
  "error": {
    "type": "authentication_error",
    "code": "key_revoked", "message": "The key has been revoked. Create a new one from the dashboard.", "request_id": "req_01J8…" } }

Conversations and messages

Every conversation is isolated by customer number. And the isolation is not a setting you choose — it is built into the system: no call ever sees another customer’s record.

POST /api/v1/messages
Authorization: Bearer $NAATEQ_KEY
Idempotency-Key: a3f1c9de-…

{
  "to": "966501234567", "text": "Your quote is ready — shall we send it?" }

Customers

The customer record is the same one the system writes in crm.json — The fields below are copied from the code, not composed for display. Which is why what you read from the API is what the bot sees at the moment of replying, not a copy lagging behind it.

{ "number": "966501234567", "name": "Mohammed Al-Harbi", "stage": "quoted", "project": "12-metre majlis — custom", "quote": { "amount": 4200, "project": "12-metre majlis — custom", "status": "sent", "date": "2026-08-04" }, "contract": null, "milestones": [], "tickets": [], "payment_links": [], "next_payment_due": null, "created_at": "2026-08-0

Documents

Quotes and contracts. And the document number is not random — it is built by docNumber() from your business prefix, the type letter, the date, and a three-digit sequence:

HT-Q-260804-058
│ │ │ └── daily sequence │ │ └────────── YYMMDD │ └─────────────── Q quote · C contract └──────────────────── your business prefix

⚠ The prefix changes when the business pack changes. Do not hard-code it in your integration — match the pattern, not the text. (Hand-writing it in two places silently broke our own contract-approval command once.)

Payments

And the payment plan is computed, not written. The final instalment is computed by subtraction rather than by multiplication, so the instalments sum to the total exactly whatever rounding does — because a riyal lost in a contract is a defect discovered at collection time:

[ { "id": "moyasar", "label_ar": "<Arabic label>", "configured": true, "mode": "live",
    "min_amount_minor": 100,
    "fields": ["secret_key"] },
  { "id": "paylink", "label_ar": "Paylink",
    "configured": false, "mode": null,
    "min_amount_minor": 500, "fields": ["api_id", "secret_key"] }, { "id": "tap", "label_ar": "<Arabic label>", "configured": false, "mode": null, "min_amount_minor": 100, "fields": ["secret_key"] } ]

{
  "provider": "moyasar",
  "url": "https://…",
  "ref": "inv_01J8…",
  "status": "pending",
  "amount_minor": 210000,
  "currency": "SAR"
}

Webhooks

You register a single URL, and the subscribed events arrive there as JSON with a signature X-Naateq-Signature.

All the events Spec — none of them has an emitter in the code today.

POST /your-endpoint
X-Naateq-Signature: t=1785838800,v1=5f2b…
X-Naateq-Delivery: whd_01J8…

{
  "event": "quote.issued",
  "created_at": "2026-08-04T09:31:02.771Z",
  "data": {
    "doc_number": "HT-Q-260804-058", "customer": { "number": "966501234567", "name": "Mohammed Al-Harbi" }, "total": 4200, "currency": "SAR", "payment_plan": "50% on signing • 30% on initial delivery • 20% on final delivery" } }

We say “ordering is not guaranteed” and “duplication is possible” because both are the truth of every retry system. Anyone promising you guaranteed ordering over an unreliable network is promising you what the first outage will break.

Never trust an unsigned request

Compute HMAC-SHA256 over t + "." + the raw body with the webhook secret, and compare it againstv1 using a constant-time comparison. And reject any request older than five minutes so an old request cannot be replayed against you.

import crypto from "node:crypto";

export function verify(raw, header, secret) {
  const [t, v1] = header.split(",").map(p => p.split("=")[1]);
  // time window: prevents replaying an old request
  if (Math.abs(Date.now() / 1000 - +t) > 300) return false;

  const expect = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${raw}`)
    .digest("hex");

  // constant-time comparison: == leaks the difference through execution time
  const a = Buffer.from(expect), b = Buffer.from(v1);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

⚠ timingSafeEqual throws if the two lengths differ — which is why a length check precedes it. And this is exactly the case that takes down many integrations in production.

And compute the signature over the raw body before any JSON parsing — reordering the keys breaks the signature.

Idempotency — never pay twice

Every POST accepts Idempotency-Key. If the connection drops and the response never reaches you, repeat the same request with the same key: you get the same result not a second payment link and not a duplicated message.

Pagination by cursor, not by number

no page=2: a new record between two requests shifts the numbering, so you miss items or see them twice. A cursor pins the position.

{
  "data": [ … ],
  "has_more": true,
  "next_cursor": "cur_01J8…"
}

And for periodic syncing use updated_after with the last updated_at you received — it transfers only what changed rather than the whole record set.

One shape for every error

Every error carries type for classification,code for programmatic handling,message for display, andrequest_id for support. Handle code no message — the text may improve; the code does not change.

⚠ Gateway credential text is never echoed in any error message — neither in full nor truncated. And this is a rule in the payment layer, not merely a habit: an error message is the most common place a key leaks from.

Limits and data policy

An honest note: as long as the system is on your server, the request limit protects your own resources. Raising it is a setting in your instance, not something you buy from us.

Versioning and deprecation

The version is in the path: /api/v1/. And within one version we add and never remove.

And if we deprecate anything: notice 180 days in advance, a Sunset header on every response from the deprecated endpoint, and it stays working for the whole period.

Changelog

Every change to this reference is logged here with its date — including correcting what was written wrongly.