rpa-api

Insurance Broker API — API Reference

API Reference

Complete documentation for the rpa-api Insurance Broker Automation API.

Getting Started

This API automates UAE motor insurance quoting across multiple carrier portals. Submit a customer intake with vehicle details and documents, then poll for quote results. When the broker approves a quote, trigger a payment link send to the customer.

Authentication

All endpoints except /health require an API key. Pass it in the x-api-key header.

x-api-key: YOUR_API_KEY

Rate Limits

Scope	Limit	Applies to
Quote submission	10 / min	POST /api/quotes
Sell / payment link	5 / min	POST /api/quotes/:jobId/sell
Global	100 / min	All endpoints combined

Endpoints

GET/health

Returns the health status of the API, including connectivity to Postgres and Temporal. Use this to verify the system is operational before sending requests.

Response Example

200 OK

{
  "status": "ok",
  "postgres": "up",
  "temporal": "up",
  "timestamp": "2026-05-26T12:00:00.000Z"
}

Status Codes

200All systems operational

503One or more dependencies are down

Example

curl

curl https://api.rpai.vionark.com/health

POST/api/quotesAuth required

Submit a motor insurance quote request. Accepts multipart/form-data with a JSON intake object and document files (mulkiya, EID, licence). Returns a jobId you can poll for results.

Request Body

Field	Type	Required	Description
customer.fullName	string	yes	Full name as on Emirates ID
customer.emiratesId	string	yes	Emirates ID (format: 784-YYYY-NNNNNNN-C)
customer.emiratesIdExpiry	string	yes	EID expiry date (YYYY-MM-DD)
customer.nationality	string	yes	ISO 3166-1 alpha-2 country code (e.g. "IN", "AE")
customer.gender	string	yes	"Male" or "Female"
customer.mobileNumber	string	yes	UAE mobile (e.g. +971501234567)
customer.email	string	yes	Customer email for payment link
motor.vehicle.chassisNumber	string	yes	17-character VIN / chassis number
motor.vehicle.plateCode	string	yes	Plate code (e.g. "1", "2")
motor.vehicle.plateNumber	string	yes	Plate number
motor.vehicle.registrationEmirate	string	yes	Emirate of registration
motor.vehicle.numOfPassengers	number	no	Passenger count from Mulkiya (falls back to VIN decoder)
motor.vehicle.numOfDoors	number	no	Door count (falls back to VIN decoder)
motor.licence.number	string	yes	Driving licence number
motor.previousPolicyExpiry	string	yes	Previous policy expiry (YYYY-MM-DD)
coverage.schemes	string[]	yes	Scheme codes: "65S" (Comprehensive) and/or "66S" (TPL)
targetInsurers	string[]	yes	Insurer IDs to quote (e.g. ["dni"])

Response Example

200 OK

{
  "jobId": "job_abc123def456",
  "status": "queued",
  "deduped": false
}

Status Codes

200Quote request accepted and queued

400Validation failed — missing or invalid fields

401Missing or invalid API key

429Rate limit exceeded (max 10/min)

Example

curl

curl -X POST https://api.rpai.vionark.com/api/quotes \
  -H "x-api-key: YOUR_API_KEY" \
  -F 'intake={"customer":{"fullName":"John Doe","emiratesId":"784-1990-1234567-1","nationality":"IN","gender":"Male","mobileNumber":"+971501234567","email":"john@example.com","emiratesIdExpiry":"2027-12-31"},"motor":{"vehicle":{"chassisNumber":"SJNFAAE11U1234567","plateCode":"1","plateNumber":"12345","registrationEmirate":"Abu Dhabi","color":"WHITE","engineNumber":"ABC12345","firstRegistrationDate":"2020-01-15"},"licence":{"number":"1234567","issueEmirate":"Abu Dhabi","tcNumber":"12345678","expiryDate":"2027-06-30"},"previousPolicyExpiry":"2026-06-01","transactionType":"New"},"coverage":{"schemes":["65S"]},"targetInsurers":["dni"]}' \
  -F 'mulkiya=@/path/to/mulkiya.pdf'

GET/api/quotes/:jobIdAuth required

Poll the status and results of a quote job. Returns the job status plus an array of quote run results (one per insurer/scheme combination). Poll every 2 seconds until status is "completed" or "failed".

Response Example

200 OK

{
  "jobId": "job_abc123def456",
  "status": "completed",
  "results": [
    {
      "id": "run_xyz789",
      "insurer": "dni",
      "schemeCode": "65S",
      "status": "success",
      "premium": 1785,
      "vat": 89.25,
      "total": 1874.25,
      "quotationRef": "MT-2026-4262234"
    },
    {
      "id": "run_xyz790",
      "insurer": "dni",
      "schemeCode": "66S",
      "status": "success",
      "premium": 728,
      "vat": 36.4,
      "total": 764.4,
      "quotationRef": "MT-2026-4262877"
    }
  ]
}

Status Codes

200Job found — check status field

404Job not found

401Missing or invalid API key

Example

curl

curl https://api.rpai.vionark.com/api/quotes/job_abc123def456 \
  -H "x-api-key: YOUR_API_KEY"

POST/api/quotes/:jobId/sellAuth required

Trigger sending the payment link to the customer for an accepted quote. Requires explicit broker consent (checkbox + timestamp). The insurer sends the payment email directly to the customer.

Request Body

Field	Type	Required	Description
quoteRunId	string	yes	ID of the specific quote run to sell
customerEmail	string	yes	Customer email to send payment link
brokerConsentGiven	boolean	yes	Must be true — broker confirms they reviewed the quote
brokerConsentAt	string	yes	ISO timestamp of when broker gave consent

Response Example

200 OK

{
  "saleAttemptId": "sale_abc123",
  "status": "pending",
  "quotationRef": "MT-2026-4262234"
}

Status Codes

200Sale attempt started

400Missing consent or invalid fields

401Missing or invalid API key

404Job or quote run not found

429Rate limit exceeded (max 5/min)

Example

curl

curl -X POST https://api.rpai.vionark.com/api/quotes/job_abc123def456/sell \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quoteRunId":"run_xyz789","customerEmail":"john@example.com","brokerConsentGiven":true,"brokerConsentAt":"2026-05-26T12:00:00Z"}'

GET/api/quotes/:jobId/saleAuth required

Poll the status of a sale attempt (payment link send). Returns the latest sale attempt for the job. Status progresses: pending -> payment-link-sent -> failed.

Response Example

200 OK

{
  "saleAttempt": {
    "id": "sale_abc123",
    "status": "payment-link-sent",
    "quotationRef": "MT-2026-4262234",
    "sentAt": "2026-05-26T12:00:15.000Z"
  }
}

Status Codes

200Sale attempt found (or null if none started)

401Missing or invalid API key

404Job not found

Example

curl

curl https://api.rpai.vionark.com/api/quotes/job_abc123def456/sale \
  -H "x-api-key: YOUR_API_KEY"

Quote Result Statuses

GET /api/quotes/:jobId returns { job, results[] } — one results entry per insurer/scheme. The poll itself returns HTTP 200; the quote outcome lives in each entry’s status. Keep polling until every entry is a settled state (not queued/running).

status	What it means
success	Quote priced. The quote object carries premium, vatAmount, totalAmount and insurerQuoteRef. Sellable via the /sell endpoint.
duplicate	This chassis was already quoted at the carrier. quote.existingQuotations lists the existing references — no new quote is created.
referral	The carrier’s underwriter must price this manually. A reference may be issued but there is no automatic price — not auto-sellable.
rejected	The carrier declined for a business reason. See error.code / error.message. Re-submitting the same data will not change the outcome.
failed	The quote could not be completed. See error.code — many causes are transient and safe to retry.
queued / running	Still in progress. Keep polling until every result is one of the settled states above.

Quote Error Codes

When a result is rejected or failed, it carries an error object with code, message and stepFailed. The code is a stable string you can branch on; message is human-readable and safe to show an end user.

error.code	Retry?	Meaning
INSURER_INTERNAL_ERROR	Yes — soon	The carrier’s own system errored (e.g. its vehicle-data feed was down). Not the customer’s data. Retry in a few minutes.
INSURER_UNAVAILABLE	Yes — soon	The carrier’s site was too slow or unreachable. Usually temporary — retry shortly.
NON_GCC	No	Vehicle is not GCC-spec; the carrier will not write comprehensive cover for it.
INSERT_QUOTATION_REJECTED	No	The carrier declined at quote creation. The reason is in the message.
QUOTE_CONDITION_FAILED	No	A carrier eligibility condition failed. The failing condition is in the message.
QUOTE_BLOCKED	No	The carrier blocked this quote.
DNI_DUPLICATE_NO_REF	No	Chassis already quoted, but the carrier returned no reference. Check the carrier portal.
VALIDATION_FAILED	After fix	Required data was missing or invalid (e.g. passenger or door count). Correct the intake and resubmit.
FILE_CORRUPT	After fix	An uploaded document could not be read. Re-upload a clean file.
PORTAL_LOGIN_FAILED	Yes	Could not sign in to the carrier portal.
CAPTCHA_UNSOLVABLE	Yes	Could not solve the carrier’s login captcha.
PORTAL_RATE_LIMITED	Back off	The carrier throttled access. Wait, then retry.
PORTAL_MAINTENANCE	Later	The carrier portal is in scheduled maintenance.
FAST_PATH_FAILED	Maybe	An unexpected error during quoting. Details are in the message.
INTERNAL	Yes	Unexpected error on our side. Retry; contact support if it persists.

HTTP / Transport Errors

These are returned as the HTTP status of the request itself (request rejected before any quote runs) — distinct from the per-quote outcomes above.

Code	HTTP	Description
VALIDATION_FAILED	400	Request body failed schema validation. Check the errors array in the response.
UNAUTHORIZED	401	Missing or invalid x-api-key header.
RATE_LIMITED	429	Too many requests. Wait and retry after the window resets.
TEMPORAL_UNAVAILABLE	503	Workflow engine is down. Quotes cannot be processed.
INTERNAL	500	Unexpected server error. Check logs or contact support.