{ "openapi": "3.1.0", "info": { "title": "Wathiqaty Insurer API", "version": "1.0.0", "description": "System-to-system API for insurance companies selling through Wathiqaty. Guides: https://developers.wathiqaty.com" }, "servers": [ { "url": "https://sandbox-api.wathiqaty.com/api/v1", "description": "Sandbox" }, { "url": "https://api.wathiqaty.com/api/v1", "description": "Production" } ], "tags": [ { "name": "Authentication", "description": "Exchange your API client's credentials for a 15-minute bearer token (OAuth 2.0 client credentials, RFC 6749 §4.4). Cache it and renew it shortly before it expires." }, { "name": "Company", "description": "Your company as Wathiqaty sees it. A cheap call to check a new token works." }, { "name": "Packages", "description": "Packages (your products) are authored by your staff in the Wathiqaty portal, because benefits, wordings and documents need a human. Through the API your core system keeps the pricing and the on-sale state in sync. Price changes apply to quotes from the next request. Policies already sold keep the price they were sold at." }, { "name": "Policies", "description": "Wathiqaty issues a policy the moment the customer's payment is captured, and sends `policy.issued`. Book it in your core system, then store your policy number on it. Everything sold (cover, price, taxes, cancellation scale) is frozen on the policy and never changes afterwards." }, { "name": "Cancellations", "description": "A customer's cancellation request waits for your decision (`cancellation.requested`). The refund is quoted when the request is made, from the scale in force that day, and frozen on the request." }, { "name": "Claims", "description": "The full claim workflow: `submitted` → `under_review` ⇄ `documents_requested` → `approved` → `settled` → `closed`, or `rejected` → `closed`. The customer can withdraw before a decision. Your staff can work the same claims in the Wathiqaty portal at the same time; both see the same state." }, { "name": "Finance & settlements", "description": "Every captured payment freezes its breakdown: gross (tax-inclusive) = net + taxes, and Wathiqaty's commission is a share of the net. Commission accrues on the ledger at capture and is reversed in proportion on refunds. Wathiqaty requests settlement of the balance periodically; you pay and upload the proof." }, { "name": "Bordereaux", "description": "CSV files for reconciliation, or for companies that integrate by file first. UTF-8 with a BOM so Excel keeps Arabic names intact. A nightly SFTP drop of the same files is available on request." }, { "name": "Webhook endpoints", "description": "Where Wathiqaty sends events (see the Webhooks guide for payloads and signatures). Up to 5 endpoints per environment." }, { "name": "Sandbox simulator", "description": "Sandbox-only routes that play the customer, so you can drive every flow from your side without the Wathiqaty app. They fire the same webhooks as real activity. They return 404 in production." } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "clientBasic": { "type": "http", "scheme": "basic", "description": "client_id:client_secret, token route only." } } }, "paths": { "/auth/partner/token": { "post": { "operationId": "create-token", "tags": [ "Authentication" ], "summary": "Get an access token", "description": "Send the client id and secret with HTTP Basic auth. There is no refresh token: ask again with the same credentials. This route is limited to 10 calls a minute per client.", "security": [ { "clientBasic": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": false, "properties": { "grant_type": { "description": "Always `client_credentials`.", "enum": [ "client_credentials" ], "type": "string" }, "scope": { "description": "Space-separated subset of the client's scopes. Omit it to get them all.", "type": "string" } }, "required": [ "grant_type" ] }, "example": { "grant_type": "client_credentials", "scope": "policies:read claims:read claims:write" } } } }, "responses": { "200": { "description": "A token.", "content": { "application/json": { "example": { "status": "success", "data": { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…", "tokenType": "Bearer", "expiresIn": 900, "scope": "policies:read claims:read claims:write" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/auth/partner/token", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`invalid_scope`: A requested scope isn't granted to this client.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "401": { "description": "`invalid_client`: Unknown client, wrong secret, or the client is revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "403": { "description": "`ip_not_allowed`: The client has an IP allow-list and this IP isn't on it.\n`tenant_not_active`: Your company is suspended on Wathiqaty.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "429": { "description": "`rate_limited`: More than 10 token requests a minute. Cache tokens.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/company": { "get": { "operationId": "get-company", "tags": [ "Company" ], "summary": "Get your company", "description": "", "security": [ { "bearer": [] } ], "parameters": [], "responses": { "200": { "description": "Your company profile.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "a3c1e0f2-5b7d-4e19-8c2a-0f6d9b1e4a77", "name": { "en": "Demo Insurance", "ar": "ديمو للتأمين" }, "status": "active", "insuranceTypes": [ "individual_medical", "new_cars" ], "numbering": { "policyCardPrefix": "MC" }, "supportSettings": { "phone": "19000", "email": "care@insurer.example" } }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/company", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/packages": { "get": { "operationId": "list-packages", "tags": [ "Packages" ], "summary": "List packages", "description": "Scope: `packages:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "insuranceType", "in": "query", "required": false, "description": "Line of business.", "schema": { "description": "Line of business.", "enum": [ "individual_medical", "new_cars" ], "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Only `active` packages are sold.", "schema": { "description": "Only `active` packages are sold.", "enum": [ "draft", "active", "inactive" ], "type": "string" } }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only rows changed at or after this instant. Pass the `updatedAt` of the last row you processed (change feed).", "schema": { "description": "Only rows changed at or after this instant. Pass the `updatedAt` of the last row you processed (change feed).", "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Default 1.", "schema": { "description": "Page number, from 1. Default 1.", "type": "integer" } }, { "name": "size", "in": "query", "required": false, "description": "Items per page, 1–100. Default 20.", "schema": { "description": "Items per page, 1–100. Default 20.", "type": "integer" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "schema": { "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "A page of packages.", "content": { "application/json": { "example": { "status": "success", "data": { "items": [ { "id": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "insuranceType": "individual_medical", "status": "active", "name": { "en": "Gold Care", "ar": "جولد كير" }, "externalReference": "PRD-GOLD-2026", "sumInsured": "250000.00", "readiness": { "sellable": true, "missing": [] }, "version": 7, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-11-02T10:20:00.000Z" } ], "meta": { "page": 1, "size": 20, "totalItems": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false } }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/packages", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/packages/{id}": { "get": { "operationId": "get-package", "tags": [ "Packages" ], "summary": "Get a package", "description": "`readiness.missing` lists what blocks activation. The `ETag` header (and `version`) is what to send as `If-Match` on writes.\n\nScope: `packages:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The package's Wathiqaty id.", "schema": { "description": "The package's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The package.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "insuranceType": "individual_medical", "status": "active", "name": { "en": "Gold Care", "ar": "جولد كير" }, "externalReference": "PRD-GOLD-2026", "sumInsured": "250000.00", "readiness": { "sellable": true, "missing": [] }, "version": 7, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-11-02T10:20:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/packages/5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Package doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/packages/{id}/rating-rules": { "get": { "operationId": "get-rating-rules", "tags": [ "Packages" ], "summary": "Get pricing rules", "description": "Each rule matches a customer profile (`criteria`) and sets a tax-inclusive `price`; `loadings` add a percentage for specific answers.\n\nScope: `packages:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The package's Wathiqaty id.", "schema": { "description": "The package's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The package's rules.", "content": { "application/json": { "example": { "status": "success", "data": { "version": 7, "rules": [ { "id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "price": "9500.00", "criteria": [ { "factor": "age", "min": 18, "max": 35 }, { "factor": "gender", "values": [ "male", "female" ] } ], "loadings": [ { "factor": "pre_existing_condition", "value": "diabetes", "percent": "15.00" } ] }, { "id": "9b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "price": "12800.00", "criteria": [ { "factor": "age", "min": 36, "max": 50 } ], "loadings": [] } ] }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Package doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } }, "put": { "operationId": "replace-rating-rules", "tags": [ "Packages" ], "summary": "Replace pricing rules", "description": "Replaces **all** rules of the package in one transaction. Rules not in the body are removed. Counts as 10 requests against your rate limit.\n\nScope: `packages:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The package's Wathiqaty id.", "schema": { "description": "The package's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "The ETag you read, e.g. W/\"7\".", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "rules": { "description": "1–500 rules: `{ price (decimal string), criteria[{ factor, min?, max?, values? }], loadings[{ factor, value, percent }] }`.", "type": "array", "items": { "type": "object" } } }, "required": [ "rules" ] }, "example": { "rules": [ { "price": "9500.00", "criteria": [ { "factor": "age", "min": 18, "max": 35 }, { "factor": "gender", "values": [ "male", "female" ] } ], "loadings": [ { "factor": "pre_existing_condition", "value": "diabetes", "percent": "15.00" } ] }, { "price": "12800.00", "criteria": [ { "factor": "age", "min": 36, "max": 50 } ], "loadings": [] } ] } } } }, "responses": { "200": { "description": "The new rules and the package's new version.", "content": { "application/json": { "example": { "status": "success", "data": { "version": 8, "rules": [ { "id": "8a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "price": "9500.00", "criteria": [ { "factor": "age", "min": 18, "max": 35 }, { "factor": "gender", "values": [ "male", "female" ] } ], "loadings": [ { "factor": "pre_existing_condition", "value": "diabetes", "percent": "15.00" } ] }, { "id": "9b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e", "price": "12800.00", "criteria": [ { "factor": "age", "min": 36, "max": 50 } ], "loadings": [] } ] }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "PUT", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Package doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "412": { "description": "`version_conflict`: Changed since you read it (`If-Match` doesn't match). Reload and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "422": { "description": "`validation_error`: A rule is invalid (`details.fields`, e.g. `rules.3.price`).\n`unknown_rating_factor`: A factor or value isn't one your company has selected.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/packages/{id}/activate": { "post": { "operationId": "activate-package", "tags": [ "Packages" ], "summary": "Put a package on sale", "description": "`draft` or `inactive` → `active`, only when the package is complete.\n\nScope: `packages:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The package's Wathiqaty id.", "schema": { "description": "The package's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The package, now `active`.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "insuranceType": "individual_medical", "status": "active", "name": { "en": "Gold Care", "ar": "جولد كير" }, "externalReference": "PRD-GOLD-2026", "sumInsured": "250000.00", "readiness": { "sellable": true, "missing": [] }, "version": 7, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-11-02T10:20:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Package doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "409": { "description": "`package_duplicate`: Another active package has the same policy and name.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "422": { "description": "`package_incomplete`: Something is missing (`details.missing`, e.g. `rating_rules`, `terms_and_conditions`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/packages/{id}/deactivate": { "post": { "operationId": "deactivate-package", "tags": [ "Packages" ], "summary": "Take a package off sale", "description": "→ `inactive`. Sold policies are not affected.\n\nScope: `packages:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The package's Wathiqaty id.", "schema": { "description": "The package's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The package, now `inactive`.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "insuranceType": "individual_medical", "status": "inactive", "name": { "en": "Gold Care", "ar": "جولد كير" }, "externalReference": "PRD-GOLD-2026", "sumInsured": "250000.00", "readiness": { "sellable": true, "missing": [] }, "version": 7, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-11-02T10:20:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Package doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/packages/{id}/external-reference": { "put": { "operationId": "set-package-reference", "tags": [ "Packages" ], "summary": "Set your product code", "description": "Echoed on every policy sold from the package as `packageExternalReference`.\n\nScope: `packages:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The package's Wathiqaty id.", "schema": { "description": "The package's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "externalReference": { "description": "Your own reference, 1–100 characters, unique within your company.", "type": "string" } }, "required": [ "externalReference" ] }, "example": { "externalReference": "PRD-GOLD-2026" } } } }, "responses": { "200": { "description": "The package.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "insuranceType": "individual_medical", "status": "active", "name": { "en": "Gold Care", "ar": "جولد كير" }, "externalReference": "PRD-GOLD-2026", "sumInsured": "250000.00", "readiness": { "sellable": true, "missing": [] }, "version": 7, "createdAt": "2026-09-01T08:00:00.000Z", "updatedAt": "2026-11-02T10:20:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "PUT", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Package doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "409": { "description": "`conflict`: Another package of yours already has this reference.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/policies": { "get": { "operationId": "list-policies", "tags": [ "Policies" ], "summary": "List policies", "description": "Also the change feed: `sortBy=updatedAt&sortOrder=asc&updatedSince=`. Use `hasExternalReference=false` to find policies you haven't booked yet.\n\nScope: `policies:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Policy status.", "schema": { "description": "Policy status.", "enum": [ "active", "expired", "cancelled" ], "type": "string" } }, { "name": "insuranceType", "in": "query", "required": false, "description": "Line of business.", "schema": { "description": "Line of business.", "enum": [ "individual_medical", "new_cars" ], "type": "string" } }, { "name": "packageId", "in": "query", "required": false, "description": "Sold from this package.", "schema": { "description": "Sold from this package.", "type": "string", "format": "uuid" } }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only rows changed at or after this instant. Pass the `updatedAt` of the last row you processed (change feed).", "schema": { "description": "Only rows changed at or after this instant. Pass the `updatedAt` of the last row you processed (change feed).", "type": "string", "format": "date-time" } }, { "name": "issuedFrom", "in": "query", "required": false, "description": "Issued on or after (Cairo date).", "schema": { "description": "Issued on or after (Cairo date).", "type": "string", "format": "date" } }, { "name": "issuedTo", "in": "query", "required": false, "description": "Issued on or before (Cairo date).", "schema": { "description": "Issued on or before (Cairo date).", "type": "string", "format": "date" } }, { "name": "externalReference", "in": "query", "required": false, "description": "Exact match on your number.", "schema": { "description": "Exact match on your number.", "type": "string" } }, { "name": "hasExternalReference", "in": "query", "required": false, "description": "`false`: policies you haven't booked yet.", "schema": { "description": "`false`: policies you haven't booked yet.", "type": "boolean" } }, { "name": "sortBy", "in": "query", "required": false, "description": "Default `createdAt`.", "schema": { "description": "Default `createdAt`.", "enum": [ "createdAt", "updatedAt", "coverageEndsAt" ], "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Default 1.", "schema": { "description": "Page number, from 1. Default 1.", "type": "integer" } }, { "name": "size", "in": "query", "required": false, "description": "Items per page, 1–100. Default 20.", "schema": { "description": "Items per page, 1–100. Default 20.", "type": "integer" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "schema": { "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "A page of policies.", "content": { "application/json": { "example": { "status": "success", "data": { "items": [ { "id": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "number": "POL-00000042", "externalReference": "MI/2026/MED/004213", "packageId": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "packageExternalReference": "PRD-GOLD-2026", "packageName": { "en": "Gold Care", "ar": "جولد كير" }, "insuranceType": "individual_medical", "status": "active", "coverageStartsAt": "2026-11-05T09:15:00.000Z", "coverageEndsAt": "2027-11-05T09:15:00.000Z", "cancelledAt": null, "sumInsured": "250000.00", "premium": { "net": "8333.33", "taxes": [ { "name": "VAT", "rate": "14.00", "amount": "1166.67" } ], "total": "9500.00", "currency": "EGP" }, "commission": { "rate": "10.00", "amount": "833.33" }, "customer": { "name": "Mona Adel", "email": "mona@example.com", "phone": "01012345678", "nationalId": "29001011234567", "birthDate": "1990-01-01", "gender": "female" }, "kyc": { "provider": "lumin", "verifiedId": "lm_7c1d9e2f", "verifiedAt": "2026-11-05T09:02:11.000Z" }, "vehicle": null, "cardNumber": "MC-2026-42", "cancellationScale": { "effectiveFrom": "2026-10-01", "tiers": [ { "fromDay": 0, "toDay": 14, "refundPercent": "90.00", "basis": "flat" }, { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" } ] }, "createdAt": "2026-11-05T09:15:05.000Z", "updatedAt": "2026-11-05T09:16:40.000Z" } ], "meta": { "page": 1, "size": 20, "totalItems": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false } }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/policies", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/policies/{id}": { "get": { "operationId": "get-policy", "tags": [ "Policies" ], "summary": "Get a policy", "description": "Includes the policyholder (`customer`, with the national id verified by eKYC), the eKYC evidence (`kyc`), the vehicle for car policies, and the frozen premium breakdown. Every read is written to the audit log.\n\nScope: `policies:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The policy's Wathiqaty id.", "schema": { "description": "The policy's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The policy.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "number": "POL-00000042", "externalReference": "MI/2026/MED/004213", "packageId": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "packageExternalReference": "PRD-GOLD-2026", "packageName": { "en": "Gold Care", "ar": "جولد كير" }, "insuranceType": "individual_medical", "status": "active", "coverageStartsAt": "2026-11-05T09:15:00.000Z", "coverageEndsAt": "2027-11-05T09:15:00.000Z", "cancelledAt": null, "sumInsured": "250000.00", "premium": { "net": "8333.33", "taxes": [ { "name": "VAT", "rate": "14.00", "amount": "1166.67" } ], "total": "9500.00", "currency": "EGP" }, "commission": { "rate": "10.00", "amount": "833.33" }, "customer": { "name": "Mona Adel", "email": "mona@example.com", "phone": "01012345678", "nationalId": "29001011234567", "birthDate": "1990-01-01", "gender": "female" }, "kyc": { "provider": "lumin", "verifiedId": "lm_7c1d9e2f", "verifiedAt": "2026-11-05T09:02:11.000Z" }, "vehicle": null, "cardNumber": "MC-2026-42", "cancellationScale": { "effectiveFrom": "2026-10-01", "tiers": [ { "fromDay": 0, "toDay": 14, "refundPercent": "90.00", "basis": "flat" }, { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" } ] }, "createdAt": "2026-11-05T09:15:05.000Z", "updatedAt": "2026-11-05T09:16:40.000Z" }, "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" } } } } }, "404": { "description": "`not_found`: Policy doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/policies/{id}/documents": { "get": { "operationId": "list-policy-documents", "tags": [ "Policies" ], "summary": "List policy documents", "description": "Generated PDFs (`policy_schedule`, `insurance_card`, `signed_contract`). Download from `url`; files are never streamed through the API.\n\nScope: `policies:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The policy's Wathiqaty id.", "schema": { "description": "The policy's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The documents.", "content": { "application/json": { "example": { "status": "success", "data": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "documentType": "policy_schedule", "fileName": "POL-00000042.pdf", "contentType": "application/pdf", "url": "https://files.wathiqaty.com/policies/POL-00000042.pdf", "createdAt": "2026-11-05T09:15:40.000Z" } ], "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Policy doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/policies/{id}/external-reference": { "put": { "operationId": "set-policy-reference", "tags": [ "Policies" ], "summary": "Set your policy number", "description": "Store your core system's policy number. Send `If-Match` to change one that is already set. Fires `policy.updated`.\n\nScope: `policies:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The policy's Wathiqaty id.", "schema": { "description": "The policy's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "The ETag you read, e.g. W/\"7\".", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "externalReference": { "description": "Your own reference, 1–100 characters, unique within your company.", "type": "string" }, "showToCustomer": { "description": "Show it in the customer's app next to the Wathiqaty number. Default `true`.", "type": "boolean" } }, "required": [ "externalReference" ] }, "example": { "externalReference": "MI/2026/MED/004213", "showToCustomer": true } } } }, "responses": { "200": { "description": "The policy.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "number": "POL-00000042", "externalReference": "MI/2026/MED/004213", "packageId": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "packageExternalReference": "PRD-GOLD-2026", "packageName": { "en": "Gold Care", "ar": "جولد كير" }, "insuranceType": "individual_medical", "status": "active", "coverageStartsAt": "2026-11-05T09:15:00.000Z", "coverageEndsAt": "2027-11-05T09:15:00.000Z", "cancelledAt": null, "sumInsured": "250000.00", "premium": { "net": "8333.33", "taxes": [ { "name": "VAT", "rate": "14.00", "amount": "1166.67" } ], "total": "9500.00", "currency": "EGP" }, "commission": { "rate": "10.00", "amount": "833.33" }, "customer": { "name": "Mona Adel", "email": "mona@example.com", "phone": "01012345678", "nationalId": "29001011234567", "birthDate": "1990-01-01", "gender": "female" }, "kyc": { "provider": "lumin", "verifiedId": "lm_7c1d9e2f", "verifiedAt": "2026-11-05T09:02:11.000Z" }, "vehicle": null, "cardNumber": "MC-2026-42", "cancellationScale": { "effectiveFrom": "2026-10-01", "tiers": [ { "fromDay": 0, "toDay": 14, "refundPercent": "90.00", "basis": "flat" }, { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" } ] }, "createdAt": "2026-11-05T09:15:05.000Z", "updatedAt": "2026-11-05T09:16:40.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "PUT", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Policy doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "409": { "description": "`conflict`: Another policy of yours already has this reference.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "412": { "description": "`version_conflict`: Changed since you read it (`If-Match` doesn't match). Reload and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/policies/{id}/cancel": { "post": { "operationId": "cancel-policy", "tags": [ "Policies" ], "summary": "Cancel a policy", "description": "Insurer-initiated cancellation. The refund comes from your cancellation scale in force today; taxes are never refunded. Creates a cancellation (`refund_pending`, or `completed` when nothing is due).\n\nScope: `policies:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The policy's Wathiqaty id.", "schema": { "description": "The policy's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "description": "3–2000 characters, shown to the customer.", "type": "string" }, "effectiveDate": { "description": "Default today. Not in the past, not after the cover ends.", "type": "string", "format": "date" } }, "required": [ "reason" ] }, "example": { "reason": "Non-disclosure of a pre-existing condition" } } } }, "responses": { "201": { "description": "The cancellation.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e", "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "status": "refund_pending", "initiatedBy": "insurer", "reason": "Moved to my employer's group cover", "requestedAt": "2026-11-20T11:00:00.000Z", "refundQuote": { "daysElapsed": 15, "tier": { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" }, "refundAmount": "6202.74", "taxesRetained": "1166.67", "commissionReversal": "620.27" }, "decidedAt": null, "completedAt": null, "updatedAt": "2026-11-20T11:00:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Policy doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "409": { "description": "`cancellation_already_open`: A cancellation is already open on this policy.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "422": { "description": "`policy_not_active`: The policy is expired or cancelled.\n`claim_approved`: An approved claim on the policy blocks a refunding cancellation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/cancellations": { "get": { "operationId": "list-cancellations", "tags": [ "Cancellations" ], "summary": "List cancellations", "description": "Scope: `cancellations:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Cancellation status.", "schema": { "description": "Cancellation status.", "enum": [ "requested", "refund_pending", "completed", "rejected", "withdrawn" ], "type": "string" } }, { "name": "policyId", "in": "query", "required": false, "description": "On this policy.", "schema": { "description": "On this policy.", "type": "string", "format": "uuid" } }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only rows changed at or after this instant. Pass the `updatedAt` of the last row you processed (change feed).", "schema": { "description": "Only rows changed at or after this instant. Pass the `updatedAt` of the last row you processed (change feed).", "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Default 1.", "schema": { "description": "Page number, from 1. Default 1.", "type": "integer" } }, { "name": "size", "in": "query", "required": false, "description": "Items per page, 1–100. Default 20.", "schema": { "description": "Items per page, 1–100. Default 20.", "type": "integer" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "schema": { "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "A page of cancellations.", "content": { "application/json": { "example": { "status": "success", "data": { "items": [ { "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e", "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "status": "requested", "initiatedBy": "customer", "reason": "Moved to my employer's group cover", "requestedAt": "2026-11-20T11:00:00.000Z", "refundQuote": { "daysElapsed": 15, "tier": { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" }, "refundAmount": "6202.74", "taxesRetained": "1166.67", "commissionReversal": "620.27" }, "decidedAt": null, "completedAt": null, "updatedAt": "2026-11-20T11:00:00.000Z" } ], "meta": { "page": 1, "size": 20, "totalItems": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false } }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/cancellations/{id}": { "get": { "operationId": "get-cancellation", "tags": [ "Cancellations" ], "summary": "Get a cancellation", "description": "Scope: `cancellations:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The cancellation's Wathiqaty id.", "schema": { "description": "The cancellation's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The cancellation with its frozen refund quote.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e", "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "status": "requested", "initiatedBy": "customer", "reason": "Moved to my employer's group cover", "requestedAt": "2026-11-20T11:00:00.000Z", "refundQuote": { "daysElapsed": 15, "tier": { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" }, "refundAmount": "6202.74", "taxesRetained": "1166.67", "commissionReversal": "620.27" }, "decidedAt": null, "completedAt": null, "updatedAt": "2026-11-20T11:00:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Cancellation doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/cancellations/{id}/approve": { "post": { "operationId": "approve-cancellation", "tags": [ "Cancellations" ], "summary": "Approve a cancellation", "description": "`requested` → `refund_pending` (the refund is then sent through the gateway or recorded manually) or `completed` when nothing is refunded. The policy is cancelled when the cancellation completes.\n\nScope: `cancellations:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The cancellation's Wathiqaty id.", "schema": { "description": "The cancellation's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The cancellation.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e", "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "status": "refund_pending", "initiatedBy": "customer", "reason": "Moved to my employer's group cover", "requestedAt": "2026-11-20T11:00:00.000Z", "refundQuote": { "daysElapsed": 15, "tier": { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" }, "refundAmount": "6202.74", "taxesRetained": "1166.67", "commissionReversal": "620.27" }, "decidedAt": null, "completedAt": null, "updatedAt": "2026-11-20T11:00:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Cancellation doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/cancellations/{id}/reject": { "post": { "operationId": "reject-cancellation", "tags": [ "Cancellations" ], "summary": "Reject a cancellation", "description": "Scope: `cancellations:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The cancellation's Wathiqaty id.", "schema": { "description": "The cancellation's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "description": "3–2000 characters, shown to the customer.", "type": "string" } }, "required": [ "reason" ] }, "example": { "reason": "The policy is past the cancellation window in the wording." } } } }, "responses": { "200": { "description": "The cancellation.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e", "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "status": "rejected", "initiatedBy": "customer", "reason": "Moved to my employer's group cover", "requestedAt": "2026-11-20T11:00:00.000Z", "refundQuote": { "daysElapsed": 15, "tier": { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" }, "refundAmount": "6202.74", "taxesRetained": "1166.67", "commissionReversal": "620.27" }, "decidedAt": null, "completedAt": null, "updatedAt": "2026-11-20T11:00:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Cancellation doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/cancellations/{id}/manual-refund": { "post": { "operationId": "record-manual-refund", "tags": [ "Cancellations" ], "summary": "Record a manual refund", "description": "You refunded the customer outside the payment gateway: `refund_pending` → `completed`.\n\nScope: `cancellations:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The cancellation's Wathiqaty id.", "schema": { "description": "The cancellation's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reference": { "description": "Your transfer reference, 1–255 characters.", "type": "string" }, "paidAt": { "description": "When the refund was paid.", "type": "string", "format": "date-time" } }, "required": [ "reference", "paidAt" ] }, "example": { "reference": "TRX-88213", "paidAt": "2026-11-22T10:00:00Z" } } } }, "responses": { "200": { "description": "The cancellation, now `completed`.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e", "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "status": "completed", "initiatedBy": "customer", "reason": "Moved to my employer's group cover", "requestedAt": "2026-11-20T11:00:00.000Z", "refundQuote": { "daysElapsed": 15, "tier": { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" }, "refundAmount": "6202.74", "taxesRetained": "1166.67", "commissionReversal": "620.27" }, "decidedAt": null, "completedAt": null, "updatedAt": "2026-11-20T11:00:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Cancellation doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims": { "get": { "operationId": "list-claims", "tags": [ "Claims" ], "summary": "List claims", "description": "Drafts are never visible to you.\n\nScope: `claims:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Claim status.", "schema": { "description": "Claim status.", "enum": [ "submitted", "under_review", "documents_requested", "approved", "rejected", "settled", "closed", "withdrawn" ], "type": "string" } }, { "name": "policyId", "in": "query", "required": false, "description": "On this policy.", "schema": { "description": "On this policy.", "type": "string", "format": "uuid" } }, { "name": "categoryId", "in": "query", "required": false, "description": "Claim category.", "schema": { "description": "Claim category.", "type": "string", "format": "uuid" } }, { "name": "insuranceType", "in": "query", "required": false, "description": "Line of business.", "schema": { "description": "Line of business.", "enum": [ "individual_medical", "new_cars" ], "type": "string" } }, { "name": "updatedSince", "in": "query", "required": false, "description": "Only rows changed at or after this instant. Pass the `updatedAt` of the last row you processed (change feed).", "schema": { "description": "Only rows changed at or after this instant. Pass the `updatedAt` of the last row you processed (change feed).", "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Default 1.", "schema": { "description": "Page number, from 1. Default 1.", "type": "integer" } }, { "name": "size", "in": "query", "required": false, "description": "Items per page, 1–100. Default 20.", "schema": { "description": "Items per page, 1–100. Default 20.", "type": "integer" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "schema": { "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "A page of claims.", "content": { "application/json": { "example": { "status": "success", "data": { "items": [ { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "submitted", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" } ], "meta": { "page": 1, "size": 20, "totalItems": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false } }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/claims/{id}": { "get": { "operationId": "get-claim", "tags": [ "Claims" ], "summary": "Get a claim", "description": "With items, documents (download from `url`), open document requests and `policyCoverage` (what is left of the sum insured).\n\nScope: `claims:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The claim.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "submitted", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims/{id}/external-reference": { "put": { "operationId": "set-claim-reference", "tags": [ "Claims" ], "summary": "Set your claim number", "description": "Scope: `claims:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": false, "description": "The ETag you read, e.g. W/\"7\".", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "externalReference": { "description": "Your own reference, 1–100 characters, unique within your company.", "type": "string" } }, "required": [ "externalReference" ] }, "example": { "externalReference": "CL/2026/000981" } } } }, "responses": { "200": { "description": "The claim.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": "CL/2026/000981", "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "submitted", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "PUT", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "412": { "description": "`version_conflict`: Changed since you read it (`If-Match` doesn't match). Reload and retry.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims/{id}/start-review": { "post": { "operationId": "start-claim-review", "tags": [ "Claims" ], "summary": "Start reviewing", "description": "`submitted` → `under_review`.\n\nScope: `claims:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The claim.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "under_review", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims/{id}/document-requests": { "post": { "operationId": "request-claim-documents", "tags": [ "Claims" ], "summary": "Request documents", "description": "→ `documents_requested` (or adds to the open round). The customer is notified and resubmits (`claim.resubmitted`).\n\nScope: `claims:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "requests": { "description": "1–20 of `{ requirementKey | name (1–255), note?, dueDate? }`.", "type": "array", "items": { "type": "object" } } }, "required": [ "requests" ] }, "example": { "requests": [ { "name": "Itemised hospital invoice", "note": "Stamped by the hospital", "dueDate": "2026-12-15" } ] } } } }, "responses": { "200": { "description": "The claim.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "documents_requested", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims/{id}/documents/{documentId}/review": { "post": { "operationId": "review-claim-document", "tags": [ "Claims" ], "summary": "Accept or reject a document", "description": "Rejecting reopens a request for it and moves `under_review` → `documents_requested`.\n\nScope: `claims:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "documentId", "in": "path", "required": true, "description": "The document's id.", "schema": { "description": "The document's id.", "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "decision": { "description": "Your decision.", "enum": [ "accepted", "rejected" ], "type": "string" }, "reason": { "description": "3–2000 characters. Required to reject.", "type": "string" } }, "required": [ "decision" ] }, "example": { "decision": "rejected", "reason": "The report is not signed." } } } }, "responses": { "200": { "description": "The claim.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "submitted", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Claim or document doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims/{id}/approval-preview": { "get": { "operationId": "preview-claim-approval", "tags": [ "Claims" ], "summary": "Preview an approval", "description": "What the customer would be paid after the deductible, and what would remain of the cover. Changes nothing.\n\nScope: `claims:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "approvedAmount", "in": "query", "required": true, "description": "Amount you intend to approve, > 0.", "schema": { "description": "Amount you intend to approve, > 0.", "type": "string", "pattern": "^-?\\d{1,10}(\\.\\d{1,2})?$" } } ], "responses": { "200": { "description": "The preview.", "content": { "application/json": { "example": { "status": "success", "data": { "deductibleApplied": "0.00", "payableAmount": "4200.00", "remainingAfter": "245800.00" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims/{id}/approve": { "post": { "operationId": "approve-claim", "tags": [ "Claims" ], "summary": "Approve a claim", "description": "`under_review` → `approved`. Itemised claims list **every** item once (an item below its claimed amount needs a `reason`); other claims send `approvedAmount`. Every document must be reviewed first, and the total can't exceed what is left of the sum insured.\n\nScope: `claims:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "items": { "description": "Itemised claims: `{ lineId, approvedAmount, reason? }` for every item.", "type": "array", "items": { "type": "object" } }, "approvedAmount": { "description": "Other claims: > 0 and ≤ the claimed amount.", "type": "string", "pattern": "^-?\\d{1,10}(\\.\\d{1,2})?$" } }, "required": [] }, "example": { "items": [ { "lineId": "l1", "approvedAmount": "700.00" }, { "lineId": "l2", "approvedAmount": "3000.00", "reason": "Network price for MRI is 3000" } ] } } } }, "responses": { "200": { "description": "The claim, now `approved`.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "approved", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": "3700.00", "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).\n`documents_pending`: A document is still pending (`details.pendingDocumentIds`).\n`claim_not_payable`: Over the remaining cover (`details.remaining`, `details.sumInsured`, `details.consumed`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "422": { "description": "`validation_error`: Wrong form for the claim, or items missing or repeated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims/{id}/reject": { "post": { "operationId": "reject-claim", "tags": [ "Claims" ], "summary": "Reject a claim", "description": "Scope: `claims:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "description": "3–2000 characters, shown to the customer.", "type": "string" } }, "required": [ "reason" ] }, "example": { "reason": "The treatment is excluded under section 4.2 of the wording." } } } }, "responses": { "200": { "description": "The claim, now `rejected`.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "rejected", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims/{id}/settle": { "post": { "operationId": "settle-claim", "tags": [ "Claims" ], "summary": "Mark a claim paid", "description": "`approved` → `settled`, with your payment reference.\n\nScope: `claims:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "settlementReference": { "description": "1–255 characters.", "type": "string" } }, "required": [ "settlementReference" ] }, "example": { "settlementReference": "PAY-2026-55120" } } } }, "responses": { "200": { "description": "The claim, now `settled`.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "settled", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims/{id}/close": { "post": { "operationId": "close-claim", "tags": [ "Claims" ], "summary": "Close a claim", "description": "`settled` or `rejected` → `closed`.\n\nScope: `claims:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The claim, now `closed`.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "closed", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/claims/{id}/messages": { "get": { "operationId": "list-claim-messages", "tags": [ "Claims" ], "summary": "List claim messages", "description": "Scope: `claims:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "required": false, "description": "Messages after this message id.", "schema": { "description": "Messages after this message id.", "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "1–100. Default 50.", "schema": { "description": "1–100. Default 50.", "type": "integer" } } ], "responses": { "200": { "description": "Messages, oldest first.", "content": { "application/json": { "example": { "status": "success", "data": [ { "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "author": "customer", "body": "I uploaded the stamped invoice.", "attachments": [], "createdAt": "2026-12-03T09:00:00.000Z" } ], "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } }, "post": { "operationId": "send-claim-message", "tags": [ "Claims" ], "summary": "Message the customer", "description": "A public reply on the claim. Retries with the same `clientMessageId` don't post twice.\n\nScope: `claims:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim's Wathiqaty id.", "schema": { "description": "The claim's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "body": { "description": "1–5000 characters.", "type": "string" }, "clientMessageId": { "description": "Your id for the message, for safe retries.", "type": "string", "format": "uuid" } }, "required": [ "body" ] }, "example": { "body": "Thank you, we are reviewing the invoice.", "clientMessageId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f" } } } }, "responses": { "201": { "description": "The message.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a", "author": "insurer", "body": "Thank you, we are reviewing the invoice.", "attachments": [], "createdAt": "2026-12-03T09:05:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: The claim is closed or withdrawn.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Claim doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/finance/payments": { "get": { "operationId": "list-payments", "tags": [ "Finance & settlements" ], "summary": "List captured payments", "description": "Scope: `finance:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "paidFrom", "in": "query", "required": false, "description": "Captured on or after (Cairo date).", "schema": { "description": "Captured on or after (Cairo date).", "type": "string", "format": "date" } }, { "name": "paidTo", "in": "query", "required": false, "description": "Captured on or before (Cairo date).", "schema": { "description": "Captured on or before (Cairo date).", "type": "string", "format": "date" } }, { "name": "policyId", "in": "query", "required": false, "description": "For this policy.", "schema": { "description": "For this policy.", "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Default 1.", "schema": { "description": "Page number, from 1. Default 1.", "type": "integer" } }, { "name": "size", "in": "query", "required": false, "description": "Items per page, 1–100. Default 20.", "schema": { "description": "Items per page, 1–100. Default 20.", "type": "integer" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "schema": { "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "A page of payments.", "content": { "application/json": { "example": { "status": "success", "data": { "items": [ { "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "paidAt": "2026-11-05T09:15:00.000Z", "gross": "9500.00", "taxes": [ { "name": "VAT", "rate": "14.00", "amount": "1166.67" } ], "net": "8333.33", "commission": "833.33", "insurerNet": "7500.00", "refunded": "0.00" } ], "meta": { "page": 1, "size": 20, "totalItems": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false } }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/finance/ledger": { "get": { "operationId": "list-ledger", "tags": [ "Finance & settlements" ], "summary": "List commission ledger entries", "description": "Append-only: `accrual` (+), `reversal` (−), `settlement_paid` (−).\n\nScope: `finance:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "On or after.", "schema": { "description": "On or after.", "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "On or before.", "schema": { "description": "On or before.", "type": "string", "format": "date" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Default 1.", "schema": { "description": "Page number, from 1. Default 1.", "type": "integer" } }, { "name": "size", "in": "query", "required": false, "description": "Items per page, 1–100. Default 20.", "schema": { "description": "Items per page, 1–100. Default 20.", "type": "integer" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "schema": { "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "A page of entries.", "content": { "application/json": { "example": { "status": "success", "data": { "items": [ { "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "type": "accrual", "amount": "833.33", "paymentId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "createdAt": "2026-11-05T09:15:01.000Z" }, { "id": "6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c", "type": "reversal", "amount": "-620.27", "paymentId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "createdAt": "2026-11-22T10:00:01.000Z" } ], "meta": { "page": 1, "size": 20, "totalItems": 2, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false } }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/finance/balance": { "get": { "operationId": "get-balance", "tags": [ "Finance & settlements" ], "summary": "Get the commission balance", "description": "Scope: `finance:read`.", "security": [ { "bearer": [] } ], "parameters": [], "responses": { "200": { "description": "What you owe Wathiqaty now.", "content": { "application/json": { "example": { "status": "success", "data": { "commissionDue": "184500.00", "currency": "EGP", "lastSettledAt": "2026-11-03T12:00:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/commission-settlements": { "get": { "operationId": "list-settlements", "tags": [ "Finance & settlements" ], "summary": "List settlements", "description": "Scope: `finance:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Settlement status.", "schema": { "description": "Settlement status.", "enum": [ "requested", "proof_submitted", "confirmed", "rejected", "cancelled" ], "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Default 1.", "schema": { "description": "Page number, from 1. Default 1.", "type": "integer" } }, { "name": "size", "in": "query", "required": false, "description": "Items per page, 1–100. Default 20.", "schema": { "description": "Items per page, 1–100. Default 20.", "type": "integer" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "schema": { "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "A page of settlements.", "content": { "application/json": { "example": { "status": "success", "data": { "items": [ { "id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b", "status": "requested", "periodFrom": "2026-11-01", "periodTo": "2026-11-30", "amount": "184500.00", "platformBankAccount": { "bank": "National Bank of Egypt", "iban": "EG380019000500000000263180002" }, "proof": null, "requestedAt": "2026-12-01T07:00:00.000Z", "updatedAt": "2026-12-01T07:00:00.000Z" } ], "meta": { "page": 1, "size": 20, "totalItems": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false } }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/commission-settlements/{id}": { "get": { "operationId": "get-settlement", "tags": [ "Finance & settlements" ], "summary": "Get a settlement", "description": "Scope: `finance:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The settlement's Wathiqaty id.", "schema": { "description": "The settlement's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The settlement.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b", "status": "requested", "periodFrom": "2026-11-01", "periodTo": "2026-11-30", "amount": "184500.00", "platformBankAccount": { "bank": "National Bank of Egypt", "iban": "EG380019000500000000263180002" }, "proof": null, "requestedAt": "2026-12-01T07:00:00.000Z", "updatedAt": "2026-12-01T07:00:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Settlement doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/commission-settlements/{id}/proof-upload-url": { "post": { "operationId": "create-proof-upload-url", "tags": [ "Finance & settlements" ], "summary": "Get an upload URL for the proof", "description": "Returns a presigned POST. Send the file straight to `url` as `multipart/form-data` with every entry of `fields` first, then `file`. PDF, PNG or JPEG, up to 10 MB, within 15 minutes.\n\nScope: `finance:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The settlement's Wathiqaty id.", "schema": { "description": "The settlement's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "fileName": { "description": "Original file name.", "type": "string" }, "contentType": { "description": "MIME type.", "enum": [ "application/pdf", "image/png", "image/jpeg" ], "type": "string" } }, "required": [ "fileName", "contentType" ] }, "example": { "fileName": "transfer.pdf", "contentType": "application/pdf" } } } }, "responses": { "201": { "description": "Where to upload.", "content": { "application/json": { "example": { "status": "success", "data": { "url": "https://uploads.wathiqaty.com/", "fields": { "key": "settlements/e4f5…/transfer.pdf", "Policy": "eyJ…", "X-Amz-Signature": "…" }, "fileKey": "settlements/e4f5…/transfer.pdf", "expiresAt": "2026-12-02T09:15:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Settlement doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/commission-settlements/{id}/proof": { "post": { "operationId": "submit-settlement-proof", "tags": [ "Finance & settlements" ], "summary": "Submit payment proof", "description": "`requested` (or `rejected`) → `proof_submitted`. Wathiqaty confirms or rejects it (`settlement.confirmed` / `settlement.rejected`).\n\nScope: `finance:write`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The settlement's Wathiqaty id.", "schema": { "description": "The settlement's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "fileKey": { "description": "`fileKey` from the upload URL, after uploading.", "type": "string" }, "transferReference": { "description": "Bank transfer reference.", "type": "string" }, "transferredAt": { "description": "When you paid.", "type": "string", "format": "date-time" } }, "required": [ "fileKey", "transferReference", "transferredAt" ] }, "example": { "fileKey": "settlements/e4f5…/transfer.pdf", "transferReference": "NBE-0098812", "transferredAt": "2026-12-02T08:00:00Z" } } } }, "responses": { "200": { "description": "The settlement.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "e4f5a6b7-c8d9-4e0f-9a1b-2c3d4e5f6a7b", "status": "proof_submitted", "periodFrom": "2026-11-01", "periodTo": "2026-11-30", "amount": "184500.00", "platformBankAccount": { "bank": "National Bank of Egypt", "iban": "EG380019000500000000263180002" }, "proof": null, "requestedAt": "2026-12-01T07:00:00.000Z", "updatedAt": "2026-12-01T07:00:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "400": { "description": "`bad_request`: Not allowed in the current status (`details.from`, `details.to`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "404": { "description": "`not_found`: Settlement doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "422": { "description": "`file_not_uploaded`: Nothing was uploaded under `fileKey`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/bordereaux/premium": { "get": { "operationId": "premium-bordereau", "tags": [ "Bordereaux" ], "summary": "Premium bordereau", "description": "One row per policy issued or cancelled in the range. Columns: `policy_id, policy_number, external_reference, package_external_reference, insurance_type, event, event_at, coverage_starts_at, coverage_ends_at, holder_name, holder_national_id, sum_insured, gross_premium, taxes, net_premium, commission, insurer_net, refund_amount, commission_reversed`. Ranges over 93 days answer `202` with an export id; the file follows in `bordereau.ready`.\n\nScope: `finance:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "First Cairo date, inclusive.", "schema": { "description": "First Cairo date, inclusive.", "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Last Cairo date, inclusive.", "schema": { "description": "Last Cairo date, inclusive.", "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The CSV file.", "content": { "text/csv": { "example": "policy_id,policy_number,external_reference,event,event_at,gross_premium,net_premium,commission,insurer_net\n6f1c2d3e-…,POL-00000042,MI/2026/MED/004213,issued,2026-11-05T09:15:00Z,9500.00,8333.33,833.33,7500.00" } } }, "422": { "description": "`validation_error`: `to` before `from`, or a bad date.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/bordereaux/claims": { "get": { "operationId": "claims-bordereau", "tags": [ "Bordereaux" ], "summary": "Claims bordereau", "description": "One row per claim that changed status in the range: `claim_id, claim_number, external_reference, policy_number, status, status_at, claimed_amount, approved_amount, payable_amount, settlement_reference`.\n\nScope: `finance:read`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "First Cairo date, inclusive.", "schema": { "description": "First Cairo date, inclusive.", "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "description": "Last Cairo date, inclusive.", "schema": { "description": "Last Cairo date, inclusive.", "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The CSV file.", "content": { "text/csv": { "example": "claim_id,claim_number,policy_number,status,status_at,claimed_amount,approved_amount\nc9e8d7f6-…,CLM-00000107,POL-00000042,approved,2026-12-04T13:00:00Z,4200.00,3700.00" } } }, "422": { "description": "`validation_error`: `to` before `from`, or a bad date.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/webhook-endpoints": { "get": { "operationId": "list-webhook-endpoints", "tags": [ "Webhook endpoints" ], "summary": "List endpoints", "description": "Scope: `webhooks:manage`.", "security": [ { "bearer": [] } ], "parameters": [], "responses": { "200": { "description": "Your endpoints.", "content": { "application/json": { "example": { "status": "success", "data": [ { "id": "f0e1d2c3-b4a5-4968-8776-655443322110", "url": "https://core.insurer.example/wathiqaty/webhooks", "events": [ "policy.issued", "policy.cancelled", "cancellation.requested" ], "enabled": true, "description": "Core policy system", "createdAt": "2026-11-01T10:00:00.000Z" } ], "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } }, "post": { "operationId": "create-webhook-endpoint", "tags": [ "Webhook endpoints" ], "summary": "Create an endpoint", "description": "The response carries `signingSecret` **once**. Store it in your secret manager.\n\nScope: `webhooks:manage`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "UUID v4, reused on retries of the same action.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "url": { "description": "Public `https://` URL. Private and loopback addresses are refused.", "type": "string" }, "events": { "description": "Event types, or `[\"*\"]` for all, current and future.", "type": "array", "items": { "type": "string" } }, "description": { "description": "Up to 255 characters.", "type": "string" } }, "required": [ "url", "events" ] }, "example": { "url": "https://core.insurer.example/wathiqaty/webhooks", "events": [ "policy.issued", "policy.cancelled", "cancellation.requested" ], "description": "Core policy system" } } } }, "responses": { "201": { "description": "The endpoint and its signing secret.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "f0e1d2c3-b4a5-4968-8776-655443322110", "url": "https://core.insurer.example/wathiqaty/webhooks", "events": [ "policy.issued", "policy.cancelled", "cancellation.requested" ], "enabled": true, "description": "Core policy system", "createdAt": "2026-11-01T10:00:00.000Z", "signingSecret": "whsec_5f3c9a…" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "409": { "description": "`webhook_endpoint_limit`: You already have 5 endpoints in this environment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } }, "422": { "description": "`validation_error`: Not https, a private address, or an unknown event type.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/webhook-endpoints/{id}": { "patch": { "operationId": "update-webhook-endpoint", "tags": [ "Webhook endpoints" ], "summary": "Update an endpoint", "description": "Re-enabling an endpoint that was disabled after failures does not resend old events; redeliver them from the delivery list.\n\nScope: `webhooks:manage`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's Wathiqaty id.", "schema": { "description": "The endpoint's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "url": { "description": "New URL.", "type": "string" }, "events": { "description": "Replaces the list.", "type": "array", "items": { "type": "string" } }, "enabled": { "description": "Pause or resume deliveries.", "type": "boolean" }, "description": { "description": "Up to 255 characters.", "type": "string" } }, "required": [] }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "The endpoint.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "f0e1d2c3-b4a5-4968-8776-655443322110", "url": "https://core.insurer.example/wathiqaty/webhooks", "events": [ "policy.issued", "policy.cancelled", "cancellation.requested" ], "enabled": false, "description": "Core policy system", "createdAt": "2026-11-01T10:00:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "PATCH", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Endpoint doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } }, "delete": { "operationId": "delete-webhook-endpoint", "tags": [ "Webhook endpoints" ], "summary": "Delete an endpoint", "description": "Scope: `webhooks:manage`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's Wathiqaty id.", "schema": { "description": "The endpoint's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted. No body." }, "404": { "description": "`not_found`: Endpoint doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/webhook-endpoints/{id}/rotate-secret": { "post": { "operationId": "rotate-webhook-secret", "tags": [ "Webhook endpoints" ], "summary": "Rotate the signing secret", "description": "For 24 hours every delivery carries two signatures (old and new), so you can deploy the new secret without dropping events.\n\nScope: `webhooks:manage`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's Wathiqaty id.", "schema": { "description": "The endpoint's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The new secret, shown once.", "content": { "application/json": { "example": { "status": "success", "data": { "signingSecret": "whsec_a91e0b…", "previousSecretExpiresAt": "2026-11-06T09:15:02.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Endpoint doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/webhook-endpoints/{id}/test": { "post": { "operationId": "test-webhook-endpoint", "tags": [ "Webhook endpoints" ], "summary": "Send a test event", "description": "Sends a signed `ping` event now and reports what your endpoint answered.\n\nScope: `webhooks:manage`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's Wathiqaty id.", "schema": { "description": "The endpoint's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Your endpoint's answer.", "content": { "application/json": { "example": { "status": "success", "data": { "deliveryId": "0d0a7c9b-8e6f-4a5b-9c3d-2e1f0a9b8c7d", "status": 200, "latencyMs": 182 }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Endpoint doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/webhook-endpoints/{id}/deliveries": { "get": { "operationId": "list-webhook-deliveries", "tags": [ "Webhook endpoints" ], "summary": "List deliveries", "description": "The last 30 days of attempts, newest first.\n\nScope: `webhooks:manage`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The endpoint's Wathiqaty id.", "schema": { "description": "The endpoint's Wathiqaty id.", "type": "string", "format": "uuid" } }, { "name": "eventType", "in": "query", "required": false, "description": "Only this event type.", "schema": { "description": "Only this event type.", "type": "string" } }, { "name": "failed", "in": "query", "required": false, "description": "Only attempts that didn't get a 2xx.", "schema": { "description": "Only attempts that didn't get a 2xx.", "type": "boolean" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1. Default 1.", "schema": { "description": "Page number, from 1. Default 1.", "type": "integer" } }, { "name": "size", "in": "query", "required": false, "description": "Items per page, 1–100. Default 20.", "schema": { "description": "Items per page, 1–100. Default 20.", "type": "integer" } }, { "name": "sortOrder", "in": "query", "required": false, "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "schema": { "description": "Default `desc`. Use `asc` with `sortBy=updatedAt` for a change feed.", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "description": "A page of delivery attempts.", "content": { "application/json": { "example": { "status": "success", "data": { "items": [ { "id": "0d0a7c9b-8e6f-4a5b-9c3d-2e1f0a9b8c7d", "eventId": "evt_7f6c1b0e-3c2d-4c84-9a0e-2f3b1c5d7e90", "eventType": "policy.issued", "attempt": 2, "status": 503, "latencyMs": 10000, "responseSnippet": "Service Unavailable", "nextAttemptAt": "2026-11-05T09:51:00.000Z", "createdAt": "2026-11-05T09:21:00.000Z" } ], "meta": { "page": 1, "size": 20, "totalItems": 1, "totalPages": 1, "hasNextPage": false, "hasPreviousPage": false } }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "GET", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Endpoint doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/webhook-deliveries/{id}/redeliver": { "post": { "operationId": "redeliver-webhook", "tags": [ "Webhook endpoints" ], "summary": "Redeliver an event", "description": "Sends the event again now, with the same event `id` (so your dedupe still works).\n\nScope: `webhooks:manage`.", "security": [ { "bearer": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The delivery's Wathiqaty id.", "schema": { "description": "The delivery's Wathiqaty id.", "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Queued.", "content": { "application/json": { "example": { "status": "success", "data": { "deliveryId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "404": { "description": "`not_found`: Delivery doesn't exist or isn't your company's.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/sandbox/simulate/policy-sale": { "post": { "operationId": "simulate-sale", "tags": [ "Sandbox simulator" ], "summary": "Simulate a sale", "description": "Creates a test customer (eKYC passed), a captured payment and an issued policy. Fires `policy.issued`.\n\nSandbox only.", "security": [ { "bearer": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "packageId": { "description": "An `active` package of yours.", "type": "string", "format": "uuid" }, "customer": { "description": "Override `{ name, birthDate, gender }`; random otherwise.", "type": "object" }, "vehicle": { "description": "Car packages: `{ brand, model, year, value }`; random otherwise.", "type": "object" } }, "required": [ "packageId" ] }, "example": { "packageId": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "customer": { "name": "Test Customer", "birthDate": "1990-01-01", "gender": "female" } } } } }, "responses": { "201": { "description": "The issued policy.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "number": "POL-00000042", "externalReference": "MI/2026/MED/004213", "packageId": "5e2b8c41-9d3a-4f67-b1c0-7a8e2d4f6b13", "packageExternalReference": "PRD-GOLD-2026", "packageName": { "en": "Gold Care", "ar": "جولد كير" }, "insuranceType": "individual_medical", "status": "active", "coverageStartsAt": "2026-11-05T09:15:00.000Z", "coverageEndsAt": "2027-11-05T09:15:00.000Z", "cancelledAt": null, "sumInsured": "250000.00", "premium": { "net": "8333.33", "taxes": [ { "name": "VAT", "rate": "14.00", "amount": "1166.67" } ], "total": "9500.00", "currency": "EGP" }, "commission": { "rate": "10.00", "amount": "833.33" }, "customer": { "name": "Mona Adel", "email": "mona@example.com", "phone": "01012345678", "nationalId": "29001011234567", "birthDate": "1990-01-01", "gender": "female" }, "kyc": { "provider": "lumin", "verifiedId": "lm_7c1d9e2f", "verifiedAt": "2026-11-05T09:02:11.000Z" }, "vehicle": null, "cardNumber": "MC-2026-42", "cancellationScale": { "effectiveFrom": "2026-10-01", "tiers": [ { "fromDay": 0, "toDay": 14, "refundPercent": "90.00", "basis": "flat" }, { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" } ] }, "createdAt": "2026-11-05T09:15:05.000Z", "updatedAt": "2026-11-05T09:16:40.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } }, "422": { "description": "`package_not_active`: The package isn't on sale.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "fail", "error" ] }, "data": { "type": "null" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "metadata": { "type": "object" } } } } } } } } }, "/partner/sandbox/simulate/cancellation-request": { "post": { "operationId": "simulate-cancellation", "tags": [ "Sandbox simulator" ], "summary": "Simulate a cancellation request", "description": "Fires `cancellation.requested`.\n\nSandbox only.", "security": [ { "bearer": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "policyId": { "description": "An active sandbox policy.", "type": "string", "format": "uuid" }, "reason": { "description": "Default \"Sandbox test\".", "type": "string" } }, "required": [ "policyId" ] }, "example": { "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e" } } } }, "responses": { "201": { "description": "The cancellation.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "b7d4e1a9-2c3f-4a58-9e6b-0d1c2b3a4f5e", "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "status": "requested", "initiatedBy": "customer", "reason": "Moved to my employer's group cover", "requestedAt": "2026-11-20T11:00:00.000Z", "refundQuote": { "daysElapsed": 15, "tier": { "fromDay": 15, "toDay": 365, "refundPercent": "80.00", "basis": "pro_rata" }, "refundAmount": "6202.74", "taxesRetained": "1166.67", "commissionReversal": "620.27" }, "decidedAt": null, "completedAt": null, "updatedAt": "2026-11-20T11:00:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/sandbox/simulate/claim": { "post": { "operationId": "simulate-claim", "tags": [ "Sandbox simulator" ], "summary": "Simulate a claim", "description": "A submitted claim with placeholder documents. Fires `claim.submitted`.\n\nSandbox only.", "security": [ { "bearer": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "policyId": { "description": "An active sandbox policy.", "type": "string", "format": "uuid" }, "claimedAmount": { "description": "Amount claimed.", "type": "string", "pattern": "^-?\\d{1,10}(\\.\\d{1,2})?$" }, "categoryId": { "description": "Default: the first category of the line.", "type": "string", "format": "uuid" } }, "required": [ "policyId", "claimedAmount" ] }, "example": { "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "claimedAmount": "4200.00" } } } }, "responses": { "201": { "description": "The claim.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "submitted", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/sandbox/simulate/claim-resubmission": { "post": { "operationId": "simulate-resubmission", "tags": [ "Sandbox simulator" ], "summary": "Simulate a document resubmission", "description": "The customer answers your open document requests. Fires `claim.resubmitted`.\n\nSandbox only.", "security": [ { "bearer": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "claimId": { "description": "A `documents_requested` claim.", "type": "string", "format": "uuid" } }, "required": [ "claimId" ] }, "example": { "claimId": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f" } } } }, "responses": { "200": { "description": "The claim, back `under_review`.", "content": { "application/json": { "example": { "status": "success", "data": { "id": "c9e8d7f6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "number": "CLM-00000107", "externalReference": null, "policyId": "6f1c2d3e-4b5a-4c69-8d7e-1f2a3b4c5d6e", "categoryId": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f", "status": "under_review", "incidentDate": "2026-12-01", "claimedAmount": "4200.00", "approvedAmount": null, "items": [ { "lineId": "l1", "description": "Outpatient consultation", "claimedAmount": "700.00" }, { "lineId": "l2", "description": "MRI scan", "claimedAmount": "3500.00" } ], "documents": [ { "id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a", "requirementKey": "medical_report", "status": "pending", "fileName": "report.pdf", "url": "https://files.wathiqaty.com/claims/report.pdf" } ], "documentRequests": [], "policyCoverage": { "sumInsured": "250000.00", "consumed": "0.00", "remaining": "250000.00" }, "submittedAt": "2026-12-02T08:30:00.000Z", "updatedAt": "2026-12-02T08:30:00.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } }, "/partner/sandbox/clock": { "post": { "operationId": "advance-clock", "tags": [ "Sandbox simulator" ], "summary": "Move the sandbox clock", "description": "Moves your sandbox's clock forward, to test expiry and the cancellation scale's tiers. `{ \"reset\": true }` goes back to real time.\n\nSandbox only.", "security": [ { "bearer": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "advanceDays": { "description": "1–400 days forward.", "type": "integer" }, "reset": { "description": "Back to real time.", "type": "boolean" } }, "required": [] }, "example": { "advanceDays": 30 } } } }, "responses": { "200": { "description": "The sandbox's current time.", "content": { "application/json": { "example": { "status": "success", "data": { "now": "2026-12-05T09:15:02.000Z" }, "error": null, "metadata": { "timestamp": "2026-11-05T09:15:02.481Z", "path": "/api/v1/partner/…", "method": "POST", "requestId": "8d7e2c1a-41f0-4a4e-9a55-6f0b3c2d1e77" } } } } } } } } } }