Qweli API Reference

REST API for evidence capture, fraud detection, and claims intelligence. All endpoints return JSON. Built for East African insurers, TPAs, and claims teams.

https://api.qweli.maveriqinsure.com

Overview

The Qweli API is organized around REST. It uses standard HTTP verbs, returns JSON, and uses API keys for authentication.

Content-Type: All request bodies must be application/json. All responses are application/json.

Idempotency: POST requests that create resources accept an Idempotency-Key header. Submitting the same key twice returns the original response without creating a duplicate.

Authentication

All API requests require an API key passed in the x-api-key header.

curl

Node.js

Python

curl https://api.qweli.maveriqinsure.com/v1/usage \
  -H "x-api-key: YOUR_API_KEY"

const res = await fetch('https://api.qweli.maveriqinsure.com/v1/usage', {
  headers: { 'x-api-key': process.env.QWELI_API_KEY }
});

import requests

res = requests.get(
    'https://api.qweli.maveriqinsure.com/v1/usage',
    headers={'x-api-key': os.environ['QWELI_API_KEY']}
)

Keep your API key secret. Never expose it in client-side code or public repositories. Rotate it from the Settings page if compromised.

Sandbox credentials

Use these credentials to test the API. Sandbox data is real — it runs against the live pilot environment.

Tenant 1 — Motor

qweli-demo-savannah-motor-2026

Savannah Motor Assurance Ltd

Tenant 2 — Health TPA

qweli-demo-apollo-health-2026

Apollo Health TPA

Cross-insurer testing: Submit the same evidence hash from both tenants to trigger a duplicate flag — demonstrating Qweli Match across insurer boundaries.

Errors

Qweli uses standard HTTP status codes. Error responses include a machine-readable error field.

Code	Meaning
200	Success
201	Resource created
400	Bad request — check your request body
401	Unauthorized — invalid or missing API key
404	Not found — resource doesn't exist or belongs to another tenant
409	Conflict — object not yet in storage, retry confirm
500	Server error — contact support

Evidence capture

The core Qweli flow: register evidence metadata → upload file to object storage → confirm. The two-step upload ensures the cryptographic hash is committed before the file bytes arrive.

POST /v1/captures Register evidence, get presigned upload URL 🔑 API key ▼

Registers evidence metadata and returns a presigned S3 URL for uploading the file directly to object storage. The SHA-256 hash is committed at this point — any file uploaded to the URL is verified against it.

Headers

Name	Type	Required	Description
x-api-key	string	required	Your tenant API key
Idempotency-Key	string	optional	Unique key to prevent duplicate submissions

Body

Field	Type	Required	Description
incidentType	enum	required	MOTOR_ACCIDENT · MOTOR_THEFT · PROPERTY_DAMAGE · MEDICAL_ADMISSION · OTHER
latitude	number	required	GPS latitude at capture time
longitude	number	required	GPS longitude at capture time
mediaHash	string	required	SHA-256 hex digest of the media file (64 chars)
mimeType	string	required	image/jpeg · image/png · video/mp4
captureTimestamp	ISO 8601	required	When the evidence was captured on-device
capturedLatitude	number	required	GPS lat at the moment of capture (may differ from incident)
capturedLongitude	number	required	GPS lng at the moment of capture
fileSizeBytes	integer	required	File size in bytes
policyNumber	string	optional	Policy number to link this evidence to
description	string	optional	Free-text incident description

201Evidence registered

{
  "incidentId": "04213caf-17f0-4318-a103-4b8b9b5c5cc4",
  "evidenceId": "f3b6caf7-e961-4ffb-a47a-8a8571429dd5",
  "uploadUrl": "https://api.qweli.maveriqinsure.com/storage/...",
  "uploadStatus": "QUEUED_OFFLINE"
}

🧪 Try it

x-api-key

Request body (JSON)

POST /v1/captures/:id/confirm Confirm file upload completed 🔑 API key ▼

Called after the file PUT to the presigned URL succeeds. Verifies the object exists in storage, marks the evidence as UPLOADED, triggers the match pipeline, and computes the perceptual hash asynchronously.

🧪 Try it

x-api-key

Evidence ID

GET /v1/evidence List uploaded evidence 🔑 API key ▼

Query parameters

Param	Type	Default	Description
limit	integer	50	Max results (1–100)
offset	integer	0	Pagination offset

🧪 Try it

x-api-key

Claims

Claims are automatically created when evidence is captured against a valid policy. Claims are auto-triaged by risk score.

GET /v1/claims List claims with triage status 🔑 API key ▼

🧪 Try it

x-api-key

GET /v1/claims/triage/summary Triage summary — approved, flagged, under review counts 🔑 API key ▼

🧪 Try it

x-api-key

Qweli Match

Cross-insurer duplicate and near-duplicate detection. Hash-only — raw evidence never leaves your systems. Only cryptographic fingerprints are shared.

POST /v1/match/check Check evidence against cross-insurer hash index 🔑 API key ▼

Field	Type	Required	Description
mediaHash	string	required	SHA-256 hex digest to check
perceptualHash	string	optional	16-char pHash hex for near-duplicate check

🧪 Try it — use same hash from both tenants to trigger cross-insurer flag

x-api-key

Request body

GET /v1/match/stats Match network statistics 🔑 API key ▼

🧪 Try it

x-api-key

Analytics

Cross-incident fraud pattern detection. Runs across your entire claims history to surface patterns a single-claim view misses.

GET /v1/analytics/fraud Full fraud analytics summary 🔑 API key ▼

🧪 Try it

x-api-key

GET /v1/analytics/patterns Cross-incident fraud patterns only 🔑 API key ▼

🧪 Try it

x-api-key

Qweli Health

Pre-authorisation evidence for medical TPAs. Built on the same capture infrastructure as motor — same API, different business logic.

POST /v1/health/preauth Submit a pre-authorisation request 🔑 API key ▼

Field	Type	Required	Description
evidenceId	UUID	required	Evidence record to link this pre-auth to
memberRef	string	required	Opaque ref to member in your system
providerRef	string	required	Hospital/clinic reference
admissionType	enum	optional	INPATIENT · OUTPATIENT · DAY_CASE · EMERGENCY (default: INPATIENT)
diagnosisCode	string	optional	ICD-10 code
preauthAmount	number	optional	Requested amount in KES

Velocity flagging: Members with ≥ 2 admissions in 30 days are automatically placed UNDER_REVIEW. The memberVelocityFlag field in the response signals this.

GET /v1/health/members/:memberRef/history Member admission history and velocity check 🔑 API key ▼

🧪 Try it

x-api-key

Member ref

Authentication endpoints

Dashboard login. Returns a session token for use with x-session-token header.

POST /v1/auth/login Exchange credentials for session token 🔑 API key ▼

🧪 Try it

x-api-key

Request body

GET /v1/auth/session Validate session token x-session-token ▼

Pass the x-session-token header with the token returned from /v1/auth/login. Returns the session payload or 401 if expired.

Webhooks

Receive real-time events when claims are triaged, evidence is flagged, or pre-auth decisions are made.

HMAC signing: Every delivery is signed with HMAC-SHA256 using your webhook secret. Verify the X-Qweli-Signature header before processing.

Subscribe

Verify signature

Event payload

curl -X POST https://api.qweli.maveriqinsure.com/v1/webhooks/subscribe \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-system.com/webhook",
    "events": ["claim.triaged", "evidence.flagged"],
    "secret": "your-hmac-secret"
  }'

// Node.js — verify Qweli webhook signature
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

{
  "event": "evidence.flagged",
  "timestamp": "2026-06-22T10:00:00Z",
  "data": {
    "tenantId": "0d8f2375-...",
    "evidenceId": "f3b6caf7-...",
    "flagType": "DUPLICATE_EVIDENCE",
    "crossTenant": true,
    "confidenceScore": 0.94
  }
}

Available events:

capture.uploaded evidence.flagged claim.triaged health.preauth.submitted health.preauth.decided