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.

`blockedCarriers` — carriers this request will not reach. When a carrier is skipped at preflight (it requires a field you did not send, or its catalogue cannot serve one of your values), the response carries a top-level blockedCarriers array naming the carrier, the product, the exact field, and whether sending that field would fix it (fixable). The other carriers quote normally, and each skipped carrier also appears in results as its own rejected run. The key is absent when nothing was blocked.

A carrier can also be skipped because WE paused it. When an insurer’s portal account is temporarily unavailable to us, we take it offline rather than send you failures. That appears in blockedCarriers as code "CARRIER_PAUSED" with field: null, fixable: false and retryable: true. Unlike CARRIER_UNSUPPORTED_VALUE this is TEMPORARY and has nothing to do with your data: there is nothing to fix, and the insurer returns on its own with no change to your integration. If EVERY insurer you requested is unavailable and at least one of them is paused, the request itself returns 503 `NO_CARRIER_AVAILABLE` with a Retry-After header rather than creating a job.

Check it. A carrier can be blocked on every single request without any of them failing: if fixable is true, add the named field and that carrier quotes next time.

Poll the status and results of a quote job. The response is { job, results } — plus blockedCarriers when a carrier was skipped at preflight (see below). 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 (DNI 65S and 60A-S1, QIC 65S, Insurance House IH-COMP), all three carriers also return quote.valuation = { low, medium, high, chosenSumInsured, currency } — the car-value range the carrier fetched plus the sum insured we used (chosenSumInsured). Display-only; valuation is absent for TPL (66S / IH-TPL).

results[].schemeCode echoes the product this row was quoted for, so a job requesting several products is matched back by that field — it is the same code you sent in coverage.schemes (for Insurance House it is the carrier's own IH-COMP / IH-TPL).

`chosenSumInsured` is the carrier's own recommended value. All three carriers now insure on the carrier's recommended (medium) figure — the value its own form pre-fills for a human broker — so an API quote matches a manual one. Insurance House already worked this way and QIC's recommended value equals its midpoint, so neither changes; DNI used the Low/High midpoint until 2026-08-09, which under-insured and under-priced Comprehensive quotes by roughly 5%. Expect DNI 65S premiums to sit slightly higher than before, for the correct sum insured. DNI falls back to the midpoint only when it returns no usable medium.

All carriers return money split as quote.premium (net of VAT), quote.vatAmount, and quote.totalAmount (the VAT-inclusive total the customer pays) — always use quote.totalAmount as the amount payable. On Insurance House the VAT is the carrier's own figure when its quote page provides it, otherwise the UAE-standard 5%.

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.

Can this quote be sold — `quote.sellable`, `quote.notSellableReason` and `quote.notSellableCode`. A priced quote is normally sellable and leaves quote.sellable unset. When a quote cannot be sold as-is, the result still carries the real price but sets quote.sellable: false — and, since 2026-08-17, ALWAYS carries both a plain-language quote.notSellableReason you can show the broker as-is and a machine-readable quote.notSellableCode you can branch on. (Quotes produced before that date may carry neither; treat a missing code as "unknown reason".)

The codes, and what each one means for you:

- IH_COMPARISON_ONLY — Insurance House prices BOTH products from one submission but completes the application for only one of them, so when you request both schemes the other comes back as a comparison price. To sell THIS product, request it alone in coverage.schemes. - IH_APPLICATION_INCOMPLETE — Insurance House’s website hung after pricing. The quote is real and saved on their side under the reference we return, but the application never finished, so no payment link can be sent. Do NOT auto-re-quote this vehicle — surface it to a human broker, who completes the saved quotation in the Insurance House portal. Re-running almost always hangs again or trips Insurance House’s duplicate check, and every attempt uses up a submission for that chassis. - IH_POLICY_ALREADY_ISSUED — the recovered Insurance House quotation is already an issued policy. Nothing to sell. - QIC_PREVIOUS_INSURANCE_INVALID — the QIC quote declared the vehicle as NOT previously insured (the previous policy’s expiry does not run up to the policy start date). QIC refuses to pay-link such a quote for its whole life; only a NEW quote with different dates can change it. Since 2026-08-17 you should meet this earlier and cheaper: those dates are visible in your request, so QIC is skipped at preflight and reported in blockedCarriers instead of being quoted. Expect this code on quotes created before that date. - QIC_SCHEME_NOT_COMMITTED — QIC priced the plan but did not confirm it on their side, so it is an uncommitted draft. Re-quote before selling.

Neither field is a quote.warnings entry — they describe sellability only and never mean the price is unreliable. A POST /sell on a non-sellable quote is rejected immediately with 409 carrying the same explanation: QIC_PREVIOUS_INSURANCE_INVALID for the QIC previous-insurance case, QUOTE_NOT_SELLABLE otherwise.

`blockedCarriers` — carriers that never ran. A carrier is skipped at preflight when it requires a field you did not send (CARRIER_REQUIREMENT_MISSING) or it cannot serve one of your values (CARRIER_UNSUPPORTED_VALUE — usually a catalogue gap, but at QIC also a gap in cover: dates showing 2+ uninsured days produce a quote QIC will never pay-link, so we do not build it). The other carriers quote normally, each skipped carrier appears in results as its own rejected run, and the response also carries a top-level blockedCarriers array summarising them: { insurerId, schemeCode, code, field, message, fixable }. field is the exact path to add (e.g. customer.emiratesIdExpiry) and fixable: true means sending it will let that carrier quote next time. The key is absent when nothing was blocked.

A carrier can also be skipped because WE paused it. When an insurer’s portal account is temporarily unavailable to us, we take it offline rather than send you failures. That appears in blockedCarriers as code "CARRIER_PAUSED" with field: null, fixable: false and retryable: true. Unlike CARRIER_UNSUPPORTED_VALUE this is TEMPORARY and has nothing to do with your data: there is nothing to fix, and the insurer returns on its own with no change to your integration. If EVERY insurer you requested is unavailable and at least one of them is paused, the request itself returns 503 `NO_CARRIER_AVAILABLE` with a Retry-After header rather than creating a job.

Please check it on every job. A carrier can be blocked on 100% of your requests without a single one "failing" — this is the field that tells you.

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, and the result then carries quote.notSellableCode — usually "IH_APPLICATION_INCOMPLETE", or "IH_POLICY_ALREADY_ISSUED" when the recovered quotation had already become a policy (a POST /sell on either returns 409 QUOTE_NOT_SELLABLE). Do NOT auto-re-quote that vehicle — hand it to a human broker to finish in the Insurance House portal; re-running almost always hangs again or trips the carrier's duplicate check, and each attempt uses up a submission for that chassis. 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/00001), 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/00001 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 15 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.