Conventions

Rules every endpoint follows. Read them once before you build.

Requests#

• JSON in and out (Content-Type: application/json), UTF-8. The only exceptions are the token route (form-encoded) and bordereaux (CSV out).
• Unknown body fields and query parameters are rejected (400 bad_request), so typos fail loudly instead of being ignored.
• Bodies are limited to 100 KB.

Response envelope#

Every JSON response, success or error, has the same four keys:

{
  "status": "success",
  "data": { "id": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "status": "active" },
  "error": null,
  "metadata": {
    "timestamp": "2026-11-05T09:15:02.481Z",
    "path": "/api/v1/partner/policies/6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e",
    "method": "GET",
    "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77"
  }
}

• status is success (2xx), fail (4xx: fix the request) or error (5xx: our side, retry later).
• Read the HTTP status code and error.code. Never parse error.message: it's English text for developers and can change. See Errors.
• metadata.requestId identifies the call. Log it and quote it to support.

Data formats#

Pagination#

Lists take page (from 1) and size (1–100, default 20) and return:

{
  "items": [ { "id": "…" } ],
  "meta": {
    "page": 2,
    "size": 20,
    "totalItems": 47,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": true
  }
}

Change feed#

Policies, cancellations, claims and packages accept updatedSince. Sorted by updatedAt ascending, a list is a change feed: a reliable way to sync, and the safety net behind webhooks.

# Every few minutes, per resource:
since = load_checkpoint("policies")          # e.g. 2026-11-04T00:00:00.000Z
loop:
  page = GET /partner/policies?updatedSince={since}&sortBy=updatedAt&sortOrder=asc&size=100
  for row in page.items:
      upsert(row) unless already_seen(row.id, row.updatedAt)
  if page.items: since = page.items[-1].updatedAt; save_checkpoint("policies", since)
  if not page.meta.hasNextPage: break

Rows changed in the same millisecond can appear on two pages, so make the upsert idempotent on id + updatedAt.

Idempotency#

A network failure can hide whether a write happened. Send Idempotency-Key: <UUID v4> on writes; if you retry with the same key, the action runs once and every retry gets the first result.

• One key per action (one cancellation, one approval), reused for every retry of it. A new action gets a new key.
• Successful results are kept for 24 hours.
• A failed request (validation or business error) releases the key, so you can fix the input and retry with the same key.

Each endpoint shows whether it requires or supports the header. Required on money-moving actions (cancel a policy, record a refund).

Concurrent edits#

Your staff may edit the same resource in the Wathiqaty portal while your system does through the API. Editable resources return a version in ETag (and a version field). Send it back as If-Match: if someone changed the resource since you read it, you get 412 version_conflict with details.currentVersion instead of silently overwriting their change. Reload, re-apply, resend.

Files#

Files are never streamed through the API. Responses carry a url to download from directly. To upload (settlement proof), ask for a presigned upload URL, send the file straight to storage, then reference its fileKey.

Personal data#

Policies carry the policyholder's personal data, including the national id verified by eKYC. Request policies:read only for systems that need it, store only what your policy administration requires, and handle it under Egypt's Personal Data Protection Law (151/2020) and the integration agreement.