Returns the health status of the API and its core dependencies. Use this to verify the system is operational before sending requests.

status has three values: "ok" (database + workflow engine both up), "degraded" (database up but the workflow engine is down — the API still answers and reads work, but new quotes may not start; returned with HTTP 200), and "down" (database down; returned with HTTP 503). If you gate on health, treat both "ok" and "degraded" as reachable — do NOT treat "degraded" as a failure.

Submit a motor insurance quote request. Accepts multipart/form-data with a JSON intake object and document files. Use combined field names (mulkiya, emirates-id, license) for single-file uploads, or split variants (mulkiya-front, mulkiya-back, emirates-id-front, etc.) if you have separate scans. Other accepted kinds: passport-bio, no-claim-certificate. Returns a jobId you poll for results.

A new or retried submission returns 202 with { jobId, status: "running" }. A duplicate of an in-flight or completed request (same customer + chassis + plate + coverage) returns 200 with { jobId, status, deduped: true } and reuses the existing job — no second quote is run. Either way, poll GET /api/quotes/:jobId with the returned jobId.

Poll the status and results of a quote job. The response is { job, results }. Branch on the OVERALL job.status ("queued" / "running" / "completed" / "failed") — poll every 2 seconds until it is "completed" or "failed" — then read each per-insurer/scheme outcome in results[].status.

Each result is a nested object: { jobId, quoteRunId, insurerId, schemeCode, status, quote?, error?, timings }. The quote object is present on settled outcomes that produced data; money is returned as { amount, currency } objects (e.g. quote.totalAmount.amount), NOT bare numbers. On rejected / failed there is usually no quote, only error ({ code, message, stepFailed }).

A success or referral result may also carry an optional quote.makeMismatch = { enteredMake, decodedMake } when the vehicle make you submitted clearly disagrees with the make the carrier decoded from the chassis number (e.g. you sent "BMW" but the chassis decodes as "Toyota"). It is informational only — the quote is still priced for the decoded vehicle — but you should confirm the chassis number is correct before selling.

On DNI, a settled result also echoes quote.placeOfRegistration (the emirate we sent the carrier); Insurance House and QIC do not return this field. For Comprehensive (65S), DNI and QIC also return quote.valuation = { low, medium, high, chosenSumInsured, currency } — the car-value range the carrier fetched plus the midpoint we insured on. Both are display-only; valuation is absent for TPL (66S).

Vehicle identity on DNI Third-Party (66S). DNI validates the vehicle model + body type + engine against its own per-model catalogue for TPL — a value it does not recognise causes a "refer to underwriter" outcome. To match what a human broker picks from DNI's own dropdowns, we resolve what you send against DNI's catalogue: the model may be matched to DNI's catalogue spelling (e.g. "SONATA HYBRID" from the registration card → DNI's "SONATA"; "NISSAN ALTIMA" → "ALTIMA"), the body type is taken from DNI's per-model options (so an SUV is no longer assumed to be a sedan when bodyType is omitted), and the engine is read from the carrier's chassis decoder — when the exact engine is not on DNI's allowed list, the NEAREST allowed engine (within 0.4 L) may be declared instead. Every substitution adds a plain-language note to quote.warnings naming both values. When no honest match exists we declare your values as-is and the carrier may return referral — we never misdeclare a vehicle to force a price. No integration change is needed — just surface quote.warnings to your users.

Recovered ("reclaimed") quotes — Insurance House. If the carrier's website hangs AFTER a quote has priced, we automatically recover the quote from the carrier's saved-quote list instead of failing the run. Such a success result carries quote.reclaimed: true plus a plain-language note in quote.warnings. Check quote.sellable: true means the application also completed on the carrier's side — sell it as normal; false means the price is real but the application did not finish — re-run the quote for this vehicle to complete it (a POST /sell on it returns 409 QUOTE_NOT_SELLABLE). Only when the recovery is impossible (the carrier is truly down) does the run stay failed with error.code: "INSURER_UNAVAILABLE".

Trigger sending the payment link for an accepted quote. Requires explicit broker consent (checkbox + timestamp). The carrier sends the payment email to the broker’s central inbox (eSanad mediates payment) — not to the customer directly. Works for DNI, Insurance House, and QIC.

202 means accepted, not sent. The response body carries the freshly-claimed sale attempt with status: "pending" — the payment-link send has only been *queued*, and it can still fail. Poll GET /api/quotes/:jobId/sale until the status becomes payment-link-sent (link sent) or failed (see the Sale Error Codes reference for why).

Auto-polling after sell: once the link is ACTUALLY sent (status reaches payment-link-sent), a background workflow starts polling the carrier every 10 minutes for up to 24 hours, watching for the issued policy. You do not need to do anything — once coreStatus === "Approved" appears on GET /policy, the policy is issued and synced to RTA. You can short-circuit the wait by calling POST /refresh-policy manually — for DNI, pass the CRS policy number the customer forwards; for Insurance House and QIC, pass nothing (the policy is auto-derived from the saved quote reference).

All three carriers auto-poll (DNI, Insurance House, QIC). QIC discovers the issued policy by the saved quote number (no policy number to paste) and caches the Policy Schedule + Receipt PDFs to S3.

If issuance takes longer than 24 hours — the carrier can issue the policy hours-to-days after payment — the auto-poll stops, the sale stays at payment-link-sent, and no automatic notification is sent. Retrieve a late-issued policy at ANY time (no time limit) by calling POST /refresh-policy with the CRS number.

Poll the status of a sale attempt (payment link send).

Query param `?quoteRunId=<uuid>` (optional but recommended). Pass the run you sold to get THAT run's attempt. This is REQUIRED to correctly track a multi-product job where you sold more than one run (e.g. a 65S Comprehensive and a 66S TPL sold separately) — each run has its own sale attempt, and without the param the response is just the most recent attempt for the WHOLE job (so one run's poll could read the other run's status). For a single sale it can be omitted. A malformed quoteRunId returns 400 BAD_QUOTE_RUN_ID.

Returns { saleAttempt } (the matching attempt, or the newest for the job when no param is given), or { saleAttempt: null } if no sell has been triggered yet. The saleAttempt always carries id, jobId, quoteRunId, insurerId, quotationRef, customerEmail, status, brokerConsentAt, initiatedAt; completedAt appears once the link is sent; on failure an error: { step, code, message } object is included — see the Sale Error Codes reference for the stable code values (e.g. IH_COMPLIANCE_HOLD is a permanent customer-specific hold; INTERNAL is retryable). No `paymentUrl` is returned — the carrier emails the payment link straight to the broker’s central inbox (eSanad mediates payment), so the API never hands back a URL. (Note: the field is completedAt, not sentAt.)

Status progression: pending → payment-link-sent → policy-issued | failed. The terminal policy-issued state is set by the auto-polling workflow once the carrier confirms the policy has been issued; you can also watch GET /policy directly for the richer policy data.

Trigger a one-shot retrieval of an issued policy from the carrier. Carrier-agnostic: the same endpoint serves every carrier; only HOW the policy is identified differs. DNI - the broker PASTES crsPolNo (the UAE regulator policy ID, format 02/601/65S/2026/11784), from the customer confirmation email or DNI dashboard. Insurance House - auto-derives the policy from its saved quote ref, so OMIT crsPolNo (it is ignored for IH); IH policy numbers are shaped DP/01/1001/26/15582 and appear in the response only once IIRIS issues the policy (before that the status reads Pending Approval); IH caches the Policy Schedule + Tax Invoice PDFs to S3 (returned as schedulePdfSignedUrl + invoicePdfSignedUrl). QIC - also auto-derives from the saved quote number, so OMIT crsPolNo; QIC policy numbers are shaped 2620000001 and appear only once QIC issues the policy (before that the status reads Pending Approval); QIC caches the Policy Schedule + Receipt PDFs to S3 (returned as schedulePdfSignedUrl + invoicePdfSignedUrl). Read-only: never binds, never emails. The retrieval takes ~20–30s; poll GET /policy for the result.

This endpoint is OPTIONAL when a sell has been triggered: the auto-polling workflow (started by POST /sell) already polls the carrier every 10 minutes for up to 24 hours and will discover the policy for you (the CRS for DNI; the issued policy for IH). Use this endpoint to short-circuit the wait when you already have the CRS in hand. It is ALSO the fallback after that window: the auto-poll gives up at 24 hours, so for a policy the carrier issues later (often days after payment) call this endpoint with the CRS number — it has no time limit.

Poll the latest retrieved policy for a job. Returns { policy: null } until the first successful retrieval, then the full policy record. For multi-policy jobs (e.g. 65S Comprehensive + 66S TPL sold to the same customer), an additional policies array is returned ordered DESC by retrievedAt — render one panel per row; the convenience policy field is policies[0] for backward compatibility.

Signed PDF URLs (schedulePdfSignedUrl, jacketPdfSignedUrl, invoicePdfSignedUrl) are valid for 5 minutes and point to our S3 cache; refresh the row to regenerate them. Carrier-hosted URLs (schedulePdfUrl, dnLink, cnLink, receiptLink) are absolute and may require a carrier login.

`customerSnapshot.email` and `customerSnapshot.mobile` reflect the fixed broker contact (cs@esanad.com / 0522486502), NOT the customer’s real email/phone — the carrier-facing contact is centralised (the customer’s real contact stays in our DB only). fullName and gender ARE the real customer’s.