{ "openapi": "3.1.0", "info": { "title": "Flexysure Open API", "version": "v1", "summary": "Quote, bind, collect, certify and finance insurance through Flexysure.", "description": "The Flexysure Open API for insurance intermediaries: reference data, motor, medical, travel and standard quotes, policies, M-Pesa payments, premium finance, DMVIC certificates, CRM, claims, ERP exports, SMS, the client area and signed webhooks. Errors are RFC 9457 problem documents. Release 1.0 of 2026-10-14.", "contact": { "name": "Flexysure developer support", "url": "https://flexysure.intrepidprojects.co.ke/developers" }, "x-release": "1.0", "x-release-date": "2026-10-14" }, "servers": [ { "url": "https://flexysure.intrepidprojects.co.ke/api/v1", "description": "This deployment" } ], "tags": [ { "name": "Authentication", "description": "Flexysure issues short-lived bearer tokens to API clients created on Settings → API keys. Request a token with the OAuth2 client-credentials grant, then send it as `Authorization: Bearer ` on every call. Tokens carry scopes; a request outside the token's scopes gets a 403 `insufficient_scope` problem. A token never does more than its key currently allows: removing a scope from the key in Settings applies to tokens already issued. Tokens of a suspended organisation get 401 `tenant_inactive`; a key whose actor user is disabled gets 401 `actor_disabled`. Writes are checked against the acting user's abilities (the agent, the key's actor user, or the key's creator): 403 `actor_forbidden` when that user may not do it. Every response carries `X-Request-Id`; quote it when you contact support." }, { "name": "Reference data", "description": "Look-ups you need before quoting or saving: the organisation's insurers, branches, staff, levies, motor benefits and product lines. All lists are scoped to the organisation that owns the token and returned as `{\"data\": [...]}`. They are small, so none of them paginate." }, { "name": "Motor", "description": "Price, quote and bind motor cover with Insurance Cloud field names. Amounts in requests are whole shillings; responses show whole shillings next to `_minor` cents. The server is authoritative on price: every save re-prices with the current rates and refuses a premium more than KES 1 away with 422 `premium_mismatch` (the body carries the server figures). A save creates or matches the client, stores the quote, raises the policy pending payment (cash and carry) and its debit notes (1–4 instalments), and returns the client-area credentials." }, { "name": "Medical", "description": "Family medical cover with Insurance Cloud field names. Limits and premiums in requests are whole shillings. On save the family is re-priced from the members' dates of birth (ages at the cover start date) and the premium must match the server price within KES 1. A member census (members[] with family_no and category, plus categories[]) may replace the ages: several families price a group (corporate) scheme with one option per insurer that can cover every family." }, { "name": "Travel", "description": "Single-trip travel cover with Insurance Cloud field names, including its spellings (`traveling_from`, `benefitiary_relationship`, `benefitiary_phone_no`) — the correct spellings are accepted too. Cover runs from departure to return." }, { "name": "Standard products", "description": "Packaged covers — personal accident, domestic package, WIBA, fire, golfer's and the like — priced flat, by age band or as a rate on the sum insured. Insurance Cloud field names (`coverName`, `basicPremium`, `sumInsured`)." }, { "name": "Policies and quotes", "description": "Everything after the sale, which Insurance Cloud does not expose: list and read policies, endorse them mid-term, preview and confirm a cancellation with its refund, and raise a renewal quote. Results respect visibility: an agent (by `X-Agent-Code`/`X-Agent-Key`, or a key whose actor is an agent) sees only what they created; a policy outside reach is a 404." }, { "name": "Payments", "description": "Collect premiums with an M-Pesa STK push, follow the prompt to its result, and read receipts and client balances. The STK callback lands on Flexysure's Daraja webhook, which raises the receipt, allocates it to the debit note and activates the policy (and queues the DMVIC certificate) once the first instalment is paid; a premium-finance loan ref collects an instalment for Flexysure Finance instead. Subscribe to the `payment.received` and `policy.activated` webhooks rather than polling where you can. Amounts are sent in whole shillings (`amount`) and returned in shillings plus cents (`amount_minor`)." }, { "name": "Prospects", "description": "The CRM pipeline. Creating a prospect takes Insurance Cloud's field names (`p_name`, `status`, `products[]`, `assign_to[]`) and answers in its shape; listing, reading, updating, logging activity and converting to a client are Flexysure additions in the `{data, meta, links}` shape with cursor pagination. Agents (an actor with own-records visibility, or X-Agent-Code/X-Agent-Key) see prospects they created or are assigned to; staff see all." }, { "name": "Clients", "description": "Policyholders, keyed by client number. Creating a client runs the same duplicate check as the web app (phone, ID number, KRA PIN): a match answers 409 `duplicate_client` with the matching client numbers unless `force` is true. Agents see clients they created or are the salesperson for; staff see all. Insurance Cloud's flat export is GET /erp/clients." }, { "name": "Claims", "description": "Register claims on policies and move them through the lifecycle: registered → documents pending → with underwriter → under assessment → approved or repudiated → settled → closed (or withdrawn). Insurance Cloud only exports claims (GET /erp/claims); everything here is Flexysure. Agents see claims they registered, claims on policies they created and claims of clients they are the salesperson for." }, { "name": "Premium finance", "description": "Spread a premium over monthly instalments with Flexysure Premium Finance: quote, apply, sign the agreement with a one-time code, collect the deposit and follow the loan. Offered through brokerages and agencies only: a SACCO or microfinance token gets 403 `ipf_not_offered`. Credit decisions and paying the underwriter stay with Flexysure Finance staff; there is no API to approve an application or disburse a loan. Instalments are paid to Flexysure Finance's paybill with the loan ref as the account number, or by an M-Pesa prompt: `POST /payment/stk/push` with the loan ref as `account` (purpose `ipf_repayment`). A running loan can be settled early with `POST /ipf/loans/{uuid}/early-settlement`. Rule failures from the finance actions come back as 422 `validation_failed` with the reason under `errors.ipf` (or `errors.otp`, `errors.tenor_months`)." }, { "name": "ERP exports", "description": "Insurance Cloud's ERP endpoints, record for record, for integrators syncing an accounting or ERP system: `{status, [], meta, links}` with `page`/`per_page`. Amounts are whole shillings. Visibility: staff tokens see every record; agents (actor with own-records visibility, or X-Agent-Code/X-Agent-Key) see records they created, records of clients they are the salesperson for, and claims on policies they created. `agents[]` lists the agents attached to a record (its creator and the client's salesperson, when they are agents)." }, { "name": "Client area", "description": "A customer's own account for your app or website, compatible with Insurance Cloud's Client Area: passwordless sign-in by one-time code, details, policies, policy detail with documents and a ledger-backed statement. Sign-in returns `client_no` and `client_key`; send them as `X-Client-No` and `X-Client-Key` with your organisation's bearer token. Money in the Insurance Cloud endpoints is in shillings; the Flexysure-only endpoints (loans, pay, claims) use integer cents (`*_minor`). Policy `status` is 1 for active cover and 0 for any other status. A new sign-in (verify-otp or register) replaces the client's earlier keys; the key returned when your system saves a policy (`portal.client_key`) replaces only earlier policy keys, so it never signs the customer out of their app." }, { "name": "Motor certificates (DMVIC)", "description": "Issue, fetch, check and cancel DMVIC motor insurance certificates. Issuance follows the paid-stage rule: a policy is certified once it is active (first instalment paid in full); on an instalment plan the cover period is split into stages and stage n is issued once instalment n is paid and stage n−1 exists. Every issue runs DMVIC's double-insurance check first. Responses keep Insurance Cloud's `{success, message}` shape; failures are problem documents that also carry `success: false` and `message`. In the demo every call goes to the bundled DMVIC simulator." }, { "name": "SMS", "description": "Send SMS from the organisation's sender ID and read the outbox, in Insurance Cloud's shapes. Each message costs one unit per 160-character segment from the organisation's SMS balance; a message that cannot be sent (bad number, no units, provider rejection) costs nothing. In the demo the provider is simulated and messages are marked sent at once." }, { "name": "Webhooks", "description": "Register HTTPS endpoints and Flexysure will POST a signed JSON event to them when money lands, cover changes, a motor certificate is issued, a claim moves or premium finance is decided. Deliveries are retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed; failed deliveries can be retried by hand. Verify every request with the Flexysure-Signature header: t=,v1=; reject timestamps older than 300 seconds and compare in constant time." } ], "paths": { "/oauth/token": { "post": { "operationId": "post_oauth_token", "tags": [ "Authentication" ], "summary": "Get an access token", "description": "Exchanges a client id and secret for a bearer token (default lifetime 24 hours). Accepts a JSON or form body with `grant_type=client_credentials`, `client_id`, `client_secret` and an optional space-separated `scope`; HTTP Basic client authentication; or, for Insurance Cloud migrations, the body `{\"key\": \"...\", \"passkey\": \"...\"}`. When `scope` is omitted the token carries every scope the client is allowed.\n\nRate limit: 10 requests per minute per IP address.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "description": "Must be `client_credentials` (default).", "examples": [ "client_credentials" ] }, "client_id": { "type": "string", "description": "Public client id from Settings → API keys (fx_live_…).", "examples": [ "fx_live_3fK9aQ2bX8mN1pL4rS6tU0vW" ] }, "client_secret": { "type": "string", "description": "The secret shown once when the key was created or rotated." }, "scope": { "type": "string", "description": "Space-separated subset of the client's scopes.", "examples": [ "read quote bind" ] }, "key": { "type": "string", "description": "Insurance Cloud alias for client_id." }, "passkey": { "type": "string", "description": "Insurance Cloud alias for client_secret." } }, "required": [ "client_id", "client_secret" ] }, "example": { "grant_type": "client_credentials", "client_id": "fx_live_3fK9aQ2bX8mN1pL4rS6tU0vW", "client_secret": "fxs_…", "scope": "read quote bind" } } } }, "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "type": "object" }, "example": { "access_token": "e3mT…48 characters…", "token_type": "Bearer", "expires_in": 86400, "scope": "read quote bind" } } } }, "400": { "description": "`invalid_request`, `invalid_scope` or `unsupported_grant_type`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "`invalid_client`: unknown client id, wrong secret, or revoked client", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "403": { "description": "`tenant_inactive`: the organisation is suspended or still in KYC review", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "429": { "description": "`rate_limited`: more than 10 attempts a minute from one IP", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [], "x-scope": null, "x-rate-limit": "10 requests per minute per IP address", "x-idempotent": false, "x-flexysure-only": false } }, "/me": { "get": { "operationId": "get_me", "tags": [ "Reference data" ], "summary": "Who am I", "description": "The client, organisation, scopes and actor behind the current token. Useful as a connectivity check and to learn which scopes a token actually carries.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "responses": { "200": { "description": "Client, tenant, scopes, actor and token expiry", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "client": { "id": "fx_live_…", "name": "Agency portal", "rate_limit_per_minute": 60 }, "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers", "type": "brokerage", "paybill": "600123" }, "scopes": [ "read", "quote", "bind" ], "actor": { "id": 4, "name": "Kevin Kiprop", "role": "agent", "code": "KK01", "own_records_only": true }, "token": { "expires_at": "2026-10-15T09:00:00+03:00", "expires_in": 86000 }, "request_id": "0f6d…" } } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/insurers": { "get": { "operationId": "get_insurers", "tags": [ "Reference data" ], "summary": "List insurers", "description": "Underwriters the organisation places business with. `insurer_id` values from here are what the quote endpoints accept.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive match on short or legal name.", "examples": [ "savanna" ] }, "description": "Case-insensitive match on short or legal name.", "example": "savanna" } ], "responses": { "200": { "description": "Insurers", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 1, "name": "Savanna General", "legal_name": "Savanna General Insurance Ltd", "dmvic_member_id": 901, "commission_rate_bps": 1000, "status": "active", "monogram": "SG" } ] } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/branches": { "get": { "operationId": "get_branches", "tags": [ "Reference data" ], "summary": "List branches", "description": "Rate limit: 60 requests per minute per token (per-client override). Scope: read.", "responses": { "200": { "description": "Branches", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 1, "code": "NBO", "name": "Nairobi HQ", "city": "Nairobi" } ] } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/risk-managers": { "get": { "operationId": "get_risk_managers", "tags": [ "Reference data" ], "summary": "List risk managers", "description": "Staff who own client relationships: principals and account executives. Use their `id` as `risk_manager_id` when saving a client.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "responses": { "200": { "description": "Users", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 2, "name": "Faith Njeri", "email": "ae.simba@example.test", "phone": "0711000303", "role": "account_exec", "code": null, "branch_id": 1 } ] } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/sales-people": { "get": { "operationId": "get_sales_people", "tags": [ "Reference data" ], "summary": "List sales people", "description": "Agents and account executives with their agent `code` (what `X-Agent-Code` expects) and branch. Use `id` as `sales_person_id` when saving a client.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "responses": { "200": { "description": "Users", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 4, "name": "Kevin Kiprop", "email": "agent.simba@example.test", "phone": "0711000304", "role": "agent", "code": "KK01", "branch_id": 2 } ] } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/policy/taxes": { "get": { "operationId": "get_policy_taxes", "tags": [ "Reference data" ], "summary": "List levies and duties", "description": "The taxes added to every premium (training levy, policyholders compensation fund, stamp duty). Percent-based items carry `rate_bps`; flat items carry `amount` (whole shillings) and `amount_minor` (cents).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "responses": { "200": { "description": "Taxes", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 1, "code": "TL", "name": "Training levy", "basis": "percent", "rate_bps": 20, "rate_percent": 0.2, "amount": null, "amount_minor": null }, { "id": 3, "code": "SD", "name": "Stamp duty", "basis": "flat", "rate_bps": null, "rate_percent": null, "amount": 40, "amount_minor": 4000 } ] } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/motor/benefits": { "get": { "operationId": "get_motor_benefits", "tags": [ "Reference data" ], "summary": "List motor benefits", "description": "Distinct benefit names across the organisation's motor products. `id` is a stable hash of the name, so it survives re-seeding.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "responses": { "200": { "description": "Benefits", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "3a9c1f0e7b2d", "name": "Courtesy car 10 days" }, { "id": "b81e…", "name": "Towing" } ] } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/products": { "get": { "operationId": "get_products", "tags": [ "Reference data" ], "summary": "List product lines and standard products", "description": "The four product lines with their quote endpoints, plus the standard products catalogue (personal accident, domestic package, WIBA…) once the organisation has one.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "responses": { "200": { "description": "Lines and standard products", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "lines": [ { "code": "motor", "name": "Motor", "quote_endpoint": "/api/v1/motor/quote" } ], "standard_products": [ { "id": 1, "code": "PA", "name": "Personal accident", "description": "…", "brochure_url": null, "product_line": "standard" } ] } } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/motor/quote": { "post": { "operationId": "post_motor_quote", "tags": [ "Motor" ], "summary": "Price a vehicle", "description": "Returns one option per insurer that rates the class, cheapest first. Nothing is stored — use save_quote to keep a quote against a client.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: quote.", "parameters": [ { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code (see GET /api/v1/sales-people). With X-Agent-Key the agent becomes the creator and only sees their own records." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key; required with X-Agent-Code." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "class": { "type": "string", "enum": [ "Motor", "Tuktuk", "Motorcycle" ], "description": "Case-insensitive. Tuktuk is rated on the PSV schedule when `coverage` names a PSV/hire use, otherwise as a commercial vehicle." }, "coverage": { "type": "string", "description": "`Private` (default), a commercial class (e.g. \"Commercial - own goods\") or a PSV class (e.g. \"PSV - matatu\", \"Taxi\"). Maps to the rating class private, commercial or psv; motorcycles always rate as motorcycle.", "examples": [ "Private" ] }, "scope": { "type": "string", "enum": [ "Comprehensive", "TPO" ], "description": "Case-insensitive; \"Third party only\" is accepted." }, "cover_period": { "type": "string", "enum": [ "annual", "tor" ], "description": "`annual` (default) runs a year less a day. `tor` (time on risk) ends `days` days after the start date. The premium is the annual premium either way." }, "days": { "type": "integer", "description": "Required for `tor`: 1–364." }, "year": { "type": "integer", "description": "Year of manufacture.", "examples": [ 2018 ] }, "value": { "type": "integer", "description": "Vehicle value in whole shillings. Required for comprehensive cover.", "examples": [ 1000000 ] }, "tonnage": { "type": "number", "description": "Carrying capacity in tonnes (commercial). Echoed on each option and stored on the vehicle." }, "pll": { "type": "integer", "description": "Passenger legal liability: number of passengers. Echoed on each option and stored on the vehicle." }, "insurer_id": { "type": "array", "items": { "type": "integer" }, "description": "Limit to these insurers (a single id is accepted too). Default: every insurer on the panel." }, "start_date": { "type": "string", "description": "Flexysure only. Cover start (Y-m-d); a past date starts today." } }, "required": [ "class", "scope", "year" ] }, "example": { "class": "Motor", "coverage": "Private", "scope": "Comprehensive", "cover_period": "annual", "year": 2018, "value": 1000000, "pll": 4, "insurer_id": [ 1, 2 ] } } } }, "responses": { "200": { "description": "Options", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "2 options found.", "quote": { "class": "Motor", "coverage": "Private", "scope": "Comprehensive", "vehicle_class": "private", "cover_type": "comprehensive", "cover_period": "annual", "days": 365, "start_date": "2026-10-14", "end_date": "2027-10-13", "year": 2018, "tonnage": null, "pll": 4, "value": 1000000, "value_minor": 100000000 }, "options": [ { "insurer_id": 1, "insurer_name": "Savanna General", "monogram": "SG", "motor_product_id": 11, "vehicle_class": "private", "cover_type": "comprehensive", "rate": 3.5, "rate_bps": 350, "value": 1000000, "value_minor": 100000000, "basic_premium": 35000, "basic_premium_minor": 3500000, "taxes": [ { "code": "TL", "name": "Training levy", "amount": 70, "amount_minor": 7000 }, { "code": "PHCF", "name": "Policyholders compensation fund", "amount": 88, "amount_minor": 8800 }, { "code": "SD", "name": "Stamp duty", "amount": 40, "amount_minor": 4000 } ], "taxes_total": 198, "taxes_total_minor": 19800, "total": 35198, "total_minor": 3519800, "commission_rate_bps": 1000, "benefits": [ { "id": "3a9c1f0e7b2d", "name": "Windscreen up to KES 50,000" }, { "id": "b81e2c4d5f60", "name": "Towing" } ], "limits_of_liability": [ { "benefit_id": "3a9c1f0e7b2d", "item": "Windscreen", "limit": 50000 }, { "benefit_id": "b81e2c4d5f60", "item": "Towing", "limit": null } ], "excess": "2.5% of claim, min KES 15,000", "pll": 4, "tonnage": null, "instalments": [ { "parts": 1, "amounts": [ 35198 ], "amounts_minor": [ 3519800 ] }, { "parts": 2, "amounts": [ 17599, 17599 ], "amounts_minor": [ 1759900, 1759900 ] } ], "ipf_offers": [ { "tenor_months": 6, "deposit": 7040, "deposit_minor": 704000, "instalment": 5397, "instalment_minor": 539700, "apr_bps": 4200, "lender_name": "Flexysure Premium Finance" } ], "ipf_reason": null } ] } } } }, "422": { "description": "`validation_failed`, or `no_quote` when no insurer rates the class", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "quote" ] }, { "bearer": [] } ], "x-scope": "quote", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/motor/save_quote": { "post": { "operationId": "post_motor_save_quote", "tags": [ "Motor" ], "summary": "Save a quote for a client", "description": "Creates or matches the client and stores the quote with every insurer's option (valid for 14 days). Each entry in `quotes[]` is checked against the server price.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: quote.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. A unique value per save (a UUID). Retrying with the same key and body returns the first response with `Idempotent-Replayed: true`." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code (see GET /api/v1/sales-people). With X-Agent-Key the agent becomes the creator and only sees their own records." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key; required with X-Agent-Code." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "Wanjiru Kamau" ] }, "phone": { "type": "string", "description": "Kenyan mobile, any format (0712…, +254712…).", "examples": [ "0712345678" ] }, "email": { "type": "string", "examples": [ "wanjiru@example.co.ke" ] }, "idno": { "type": "string", "description": "National ID or passport number (`id_no` also accepted).", "examples": [ "23456789" ] }, "pin": { "type": "string", "description": "KRA PIN (`kra_pin` also accepted)." }, "risk_manager_id": { "type": "integer", "description": "From GET /api/v1/risk-managers." }, "branch_id": { "type": "integer", "description": "From GET /api/v1/branches." }, "sales_person_id": { "type": "integer", "description": "From GET /api/v1/sales-people. `agentcode` (an agent code) is accepted instead." }, "client_no": { "type": "string", "description": "Flexysure only: link this existing client (one you can see) explicitly instead of matching." }, "force": { "type": "boolean", "description": "Flexysure only: add a new client even though `duplicate_client` matches exist." }, "type": { "type": "string", "enum": [ "individual", "corporate" ] } }, "required": [ "name", "phone" ], "description": "The insured. An existing client is reused only when the ID number or KRA PIN matches, the name agrees and the caller may see that client; any other match (phone only, a different name, someone else's client) is 409 `duplicate_client` listing the matches (client_no only for clients you can see). Then send `client_no` to link a client you can see, or `force: true` to add a new one. An existing client's sales person and risk manager are never changed by a save." }, "vehicle": { "type": "object", "properties": { "value": { "type": "integer" }, "year": { "type": "integer" }, "reg_no": { "type": "string" }, "coverage": { "type": "string" }, "scope": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" }, "class": { "type": "string", "description": "Motor (default), Tuktuk or Motorcycle." } }, "required": [ "year", "scope" ] }, "quotes": { "type": "array", "items": {}, "description": "The options you showed the client: insurer_id, rate, basic, taxes, total (whole shillings), benefits[]." } }, "required": [ "client", "vehicle" ] }, "example": { "client": { "name": "Otieno Ouma", "email": "otieno@example.co.ke", "phone": "0722000111", "idno": "30111222", "agentcode": "KK01" }, "vehicle": { "value": 1000000, "year": 2018, "reg_no": "KDB 456B", "coverage": "Private", "scope": "Comprehensive", "make": "Mazda", "model": "Demio" }, "quotes": [ { "insurer_id": 1, "rate": 3.5, "basic": 35000, "taxes": 198, "total": 35198, "benefits": [] } ] } } } }, "responses": { "201": { "description": "Quote saved", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Quote saved.", "id": 88, "uuid": "5b0f…", "quote_no": "Q-000088", "client_no": "C-000124", "valid_until": "2026-10-28", "data": { "uuid": "5b0f…", "product_line": "motor", "status": "presented", "options": [ { "option_id": 301, "insurer_id": 1, "insurer_name": "Savanna General", "rate": 3.5, "total": 35198, "total_minor": 3519800 } ] } } } } }, "422": { "description": "`validation_failed`, `premium_mismatch` or `no_quote`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "quote" ] }, { "bearer": [] } ], "x-scope": "quote", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": false } }, "/motor/save": { "post": { "operationId": "post_motor_save", "tags": [ "Motor" ], "summary": "Bind a motor policy", "description": "Re-prices with the chosen insurer and compares `policy.premium` (and `total_basic`, `taxes` when sent); a difference over KES 1 is refused with `premium_mismatch`. Then matches or creates the client (risk manager, branch and sales person set on new clients only), stores the quote and raises the policy pending payment with 1–4 instalment debit notes. `client_key` is issued only when the client has no client-area key yet; otherwise it is null with `portal.note`, and existing keys keep working. A replay returns the key as null (`replay_note`). One vehicle per save — add more with POST /api/v1/policies/{uuid}/endorse (`add_vehicle`). Flexysure needs the chassis number (`chassis_no`) for the DMVIC certificate.\n\nRate limit: 3 requests per 15 seconds per API client (plus the platform limit).. Scope: bind.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. A unique value per save (a UUID). Retrying with the same key and body returns the first response with `Idempotent-Replayed: true`." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code (see GET /api/v1/sales-people). With X-Agent-Key the agent becomes the creator and only sees their own records." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key; required with X-Agent-Code." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "properties": { "name": { "type": "string", "examples": [ "Wanjiru Kamau" ] }, "phone": { "type": "string", "description": "Kenyan mobile, any format (0712…, +254712…).", "examples": [ "0712345678" ] }, "email": { "type": "string", "examples": [ "wanjiru@example.co.ke" ] }, "idno": { "type": "string", "description": "National ID or passport number (`id_no` also accepted).", "examples": [ "23456789" ] }, "pin": { "type": "string", "description": "KRA PIN (`kra_pin` also accepted)." }, "risk_manager_id": { "type": "integer", "description": "From GET /api/v1/risk-managers." }, "branch_id": { "type": "integer", "description": "From GET /api/v1/branches." }, "sales_person_id": { "type": "integer", "description": "From GET /api/v1/sales-people. `agentcode` (an agent code) is accepted instead." }, "client_no": { "type": "string", "description": "Flexysure only: link this existing client (one you can see) explicitly instead of matching." }, "force": { "type": "boolean", "description": "Flexysure only: add a new client even though `duplicate_client` matches exist." }, "type": { "type": "string", "enum": [ "individual", "corporate" ] } }, "required": [ "name", "phone" ], "description": "The insured. An existing client is reused only when the ID number or KRA PIN matches, the name agrees and the caller may see that client; any other match (phone only, a different name, someone else's client) is 409 `duplicate_client` listing the matches (client_no only for clients you can see). Then send `client_no` to link a client you can see, or `force: true` to add a new one. An existing client's sales person and risk manager are never changed by a save." }, "policy": { "type": "object", "properties": { "start_date": { "type": "string", "description": "Y-m-d; a past date starts today." }, "end_date": { "type": "string", "description": "Ignored for annual cover; for `tor` without `days` it sets the number of days." }, "insurer_id": { "type": "integer" }, "class": { "type": "string", "enum": [ "Motor", "Tuktuk", "Motorcycle" ] }, "coverage": { "type": "string" }, "scope": { "type": "string", "enum": [ "Comprehensive", "TPO" ] }, "cover_period": { "type": "string", "enum": [ "annual", "tor" ] }, "days": { "type": "integer" }, "total_basic": { "type": "number", "description": "Whole shillings; checked when sent." }, "taxes": { "type": "number", "description": "Whole shillings; checked when sent." }, "premium": { "type": "number", "description": "Gross premium, whole shillings. Must be within KES 1 of the server price." }, "premium_instalments": { "type": "integer", "description": "1–4 (default 1). One debit note per instalment, a month apart; the first one activates cover." }, "payment_mode": { "type": "string", "enum": [ "full", "ipf" ], "description": "Flexysure only. `ipf` = premium finance (always one instalment)." }, "limits_of_liability": { "type": "array", "items": {}, "description": "[{benefit_id, item, limit}] kept on the policy." } }, "required": [ "start_date", "insurer_id", "class", "scope", "premium" ] }, "taxes": { "type": "array", "items": {}, "description": "[{tax_id, rate, amount}] — accepted for compatibility; the server computes levies." }, "vehicles": { "type": "array", "items": {}, "description": "Exactly one: {regno|reg_no, chassis_no, make, model, yom, value, coverage, engine_no?, body_type?, tonnage?, pll?, basic_premium?, rate?, benefits[]?}." } }, "required": [ "client", "policy", "vehicles" ] }, "example": { "client": { "name": "Wanjiru Kamau", "email": "wanjiru@example.co.ke", "phone": "0712345678", "idno": "23456789", "risk_manager_id": 2, "branch_id": 1, "sales_person_id": 4 }, "policy": { "start_date": "2026-10-14", "end_date": "2027-10-13", "insurer_id": 1, "class": "Motor", "coverage": "Private", "scope": "Comprehensive", "total_basic": 35000, "taxes": 198, "premium": 35198, "premium_instalments": 2, "limits_of_liability": [ { "benefit_id": "3a9c1f0e7b2d", "item": "Windscreen", "limit": 50000 } ] }, "taxes": [ { "tax_id": 1, "rate": 0.2, "amount": 70 } ], "vehicles": [ { "coverage": "Private", "regno": "KDA 123A", "chassis_no": "NZE161-3012456", "make": "Toyota", "model": "Axio", "yom": 2018, "value": 1000000, "basic_premium": 35000, "rate": 3.5, "benefits": [] } ] } } } }, "responses": { "201": { "description": "Policy saved (Insurance Cloud shape plus uuid, policy_no, debit_note, portal)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Policy saved successfully.", "id": 452, "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "risknote": "RN-000452", "policy_no": "POL-000452", "client_no": "C-000123", "client_key": "fxck_…", "status": "pending_payment", "product_line": "motor", "start_date": "2026-10-14", "end_date": "2027-10-13", "payment_mode": "full", "instalments": 2, "premium": { "basic_premium": 35000, "basic_premium_minor": 3500000, "taxes": 198, "taxes_minor": 19800, "total": 35198, "total_minor": 3519800 }, "debit_note": { "number": "DN-000452-1/2", "due_on": "2026-10-14", "amount": 17599, "amount_minor": 1759900, "instalments": [ { "number": "DN-000452-1/2", "instalment_no": 1, "due_on": "2026-10-14", "amount": 17599, "amount_minor": 1759900 }, { "number": "DN-000452-2/2", "instalment_no": 2, "due_on": "2026-11-14", "amount": 17599, "amount_minor": 1759900 } ] }, "portal": { "client_no": "C-000123", "client_key": "fxck_…" }, "links": { "policy": "https://app.flexysure.com/api/v1/policies/0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c" } } } } }, "403": { "description": "`actor_forbidden` when the acting user may not create policies", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "409": { "description": "`price_changed` when rates changed mid-save; `duplicate_client` when the client is not matched automatically", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`validation_failed`, `premium_mismatch`, `no_quote` or `domain_rule`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "429": { "description": "More than 3 saves in 15 seconds for this API client", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "bind" ] }, { "bearer": [] } ], "x-scope": "bind", "x-rate-limit": "3 requests per 15 seconds per API client (plus the platform limit).", "x-idempotent": true, "x-flexysure-only": false } }, "/medical/limits": { "get": { "operationId": "get_medical_limits", "tags": [ "Medical" ], "summary": "List inpatient limits", "description": "Distinct inpatient limits offered by plans on the panel, ascending. Use one as `limit_from`/`limit_to` or `policy.inpatient_limit`.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Limits", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "limit": 1000000, "limit_minor": 100000000, "label": "KES 1,000,000" }, { "limit": 2000000, "limit_minor": 200000000, "label": "KES 2,000,000" } ] } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/medical/census-template": { "get": { "operationId": "get_medical_census_template", "tags": [ "Medical" ], "summary": "Download the member census template", "description": "The .xlsx template for a member list: Members (one row per person, with dropdowns), Categories (limits per staff category), How to fill and Example sheets. Send its rows as members[] and categories[] to the quote and save endpoints.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: quote.", "parameters": [ { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key the agent becomes the creator." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "responses": { "200": { "description": "The template (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), file name flexysure-medical-members-template.xlsx", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "quote" ] }, { "bearer": [] } ], "x-scope": "quote", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/medical/quote": { "post": { "operationId": "post_medical_quote", "tags": [ "Medical" ], "summary": "Price medical cover", "description": "One option per plan that accepts the family within the inpatient-limit range, cheapest first. Nothing is stored. With a census of several families: one option per insurer whose plans cover every category and price every family (each with `group` {families, lives, categories[]}), cheapest first, and `excluded` naming the insurers that could not and the families that stopped them.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: quote.", "parameters": [ { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key the agent becomes the creator." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "principal_age": { "type": "integer", "description": "Required unless members[] is sent.", "examples": [ 30 ] }, "spouse_age": { "type": "integer", "description": "0 or absent = no spouse." }, "children": { "type": "integer", "examples": [ 2 ] }, "limit_from": { "type": "integer", "description": "Lowest inpatient limit, whole shillings (0 = open)." }, "limit_to": { "type": "integer", "description": "Highest inpatient limit, whole shillings (0 = open)." }, "insurer_id": { "type": "array", "items": { "type": "integer" }, "description": "Flexysure only: limit to these insurers." }, "start_date": { "type": "string", "description": "Cover start (Y-m-d) the census ages are worked out on; default today." }, "members": { "type": "array", "items": {}, "description": "Flexysure only. A member census instead of ages: [{family_no, category, relationship principal|spouse|child (also self, employee, wife, husband, son, daughter, dependant), name, dob (Y-m-d or dd/mm/yyyy), gender?, id_no?}]. One row per person; the principal first in each family; spouse and children share the principal's family_no. One family prices as before; several families price a group scheme." }, "categories": { "type": "array", "items": {}, "description": "Flexysure only. Staff categories for a group scheme: [{code, description?, inpatient, outpatient, maternity, dental, optical}] in whole shillings (0 = not required). Per category the insurer's cheapest plan meeting every requested limit is chosen." } } }, "example": { "principal_age": 30, "spouse_age": 28, "children": 2, "limit_from": 500000, "limit_to": 2000000 } } } }, "responses": { "200": { "description": "Options (group options when the census lists several families)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "1 plan found.", "quote": { "principal_age": 30, "spouse_age": 28, "children": 2, "limit_from": 500000, "limit_to": 2000000 }, "options": [ { "insurer_id": 1, "insurer_name": "Savanna General", "monogram": "SG", "logo_url": null, "plan_id": 3, "plan_name": "Afya", "basic_premium": 50000, "basic_premium_minor": 5000000, "taxes": [ { "code": "TL", "name": "Training levy", "amount": 100, "amount_minor": 10000 } ], "taxes_total": 265, "taxes_total_minor": 26500, "total": 50265, "total_minor": 5026500, "sum_insured": 1000000, "sum_insured_minor": 100000000, "commission_rate_bps": 1000, "benefits": [ "Inpatient", "Outpatient" ], "limits": { "inpatient": 100000000, "outpatient": 10000000 }, "members": [ { "type": "principal", "age": 30, "premium": 20000, "premium_minor": 2000000 }, { "type": "spouse", "age": 28, "premium": 18000, "premium_minor": 1800000 } ], "instalments": [ { "parts": 1, "amounts": [ 50265 ], "amounts_minor": [ 5026500 ] } ], "ipf_offers": null, "ipf_reason": null } ] } } } }, "422": { "description": "`validation_failed` (census errors are row-numbered under `members`), `domain_rule` (ages out of range) or `no_quote`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "quote" ] }, { "bearer": [] } ], "x-scope": "quote", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/medical/save": { "post": { "operationId": "post_medical_save", "tags": [ "Medical" ], "summary": "Bind a medical policy", "description": "Members may be listed in any order; exactly one principal, at most one spouse, any number of children (type also accepts dependant, son, daughter, wife, husband). The plan is the insurer's plan with `inpatient_limit` (or `policy.plan_id`). The policy starts pending payment with 1–4 instalment debit notes. When members[] lists several family_no values (plus optional categories[]), the save binds a group scheme for the client (the employer): the chosen insurer's group option is re-priced from the census, the premium must match within KES 1, and every life joins one policy with its family_no, category and premium. `inpatient_limit` is then optional.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: bind.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per save; replays return the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key the agent becomes the creator." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "description": "Same block as POST /api/v1/motor/save." }, "members": { "type": "array", "items": {}, "description": "[{name, type principal|spouse|child (or relationship), dob (Y-m-d), product_name?, id_no?, family_no?, category?, gender?}]. Several family_no values = a group scheme." }, "categories": { "type": "array", "items": {}, "description": "Flexysure only. Staff categories for a group scheme: [{code, description?, inpatient, outpatient, maternity, dental, optical}] in whole shillings (0 = not required). Per category the insurer's cheapest plan meeting every requested limit is chosen." }, "policy": { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "type": "string", "description": "Cover is annual; returned in the response." }, "insurer_id": { "type": "integer" }, "inpatient_limit": { "type": "integer", "description": "Optional for a group scheme (a minimum for categories that ask for none)." }, "outpatient_limit": { "type": "integer" }, "maternity_limit": { "type": "integer" }, "dental_limit": { "type": "integer" }, "optical_limit": { "type": "integer" }, "basic": { "type": "number" }, "taxes": { "type": "number" }, "premium": { "type": "number" }, "premium_instalments": { "type": "integer", "description": "1–4." }, "plan_id": { "type": "integer", "description": "Flexysure only: the option's plan_id." } }, "required": [ "start_date", "insurer_id", "inpatient_limit", "premium" ] }, "taxes": { "type": "array", "items": {}, "description": "Accepted for compatibility; the server computes levies." } }, "required": [ "client", "members", "policy" ] }, "example": { "client": { "name": "Achieng Odhiambo", "phone": "0733000111", "idno": "27000111", "risk_manager_id": 2, "branch_id": 1 }, "members": [ { "name": "Achieng Odhiambo", "type": "principal", "dob": "1996-03-02", "product_name": "Afya" }, { "name": "Otieno Odhiambo", "type": "spouse", "dob": "1998-07-11" } ], "policy": { "start_date": "2026-10-14", "end_date": "2027-10-13", "insurer_id": 1, "inpatient_limit": 1000000, "outpatient_limit": 100000, "basic": 38000, "taxes": 211, "premium": 38211 }, "taxes": [] } } } }, "responses": { "201": { "description": "Policy saved (same shape as motor save)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Policy saved successfully.", "id": 453, "uuid": "9a1c…", "risknote": "RN-000453", "policy_no": "POL-000453", "client_no": "C-000125", "client_key": "fxck_…", "product_line": "medical", "portal": { "client_no": "C-000125", "client_key": "fxck_…" } } } } }, "422": { "description": "`validation_failed`, `premium_mismatch`, `no_quote` or `domain_rule`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "bind" ] }, { "bearer": [] } ], "x-scope": "bind", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": false } }, "/travel/quote": { "post": { "operationId": "post_travel_quote", "tags": [ "Travel" ], "summary": "Price a trip", "description": "Days are counted departure to return inclusive; the destination country maps to a region (Schengen, Africa, worldwide…) and every plan for that region or worldwide quotes. Nothing is stored.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: quote.", "parameters": [ { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key the agent becomes the creator." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rate_type": { "type": "string", "enum": [ "normal", "student", "inbound" ] }, "traveling_from": { "type": "string", "examples": [ "Kenya" ] }, "traveling_to": { "type": "string", "examples": [ "Germany" ] }, "number_of_travelers": { "type": "integer", "examples": [ 2 ] }, "departure_date": { "type": "string", "description": "Y-m-d, today or later." }, "return_date": { "type": "string" }, "insurer_id": { "type": "array", "items": { "type": "integer" }, "description": "Flexysure only." } }, "required": [ "rate_type", "traveling_to", "departure_date", "return_date" ] }, "example": { "rate_type": "normal", "traveling_from": "Kenya", "traveling_to": "Germany", "number_of_travelers": 2, "departure_date": "2026-11-01", "return_date": "2026-11-10" } } } }, "responses": { "200": { "description": "Options", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "1 plan found.", "quote": { "rate_type": "normal", "traveling_to": "Germany", "number_of_travelers": 2, "days": 10, "region": "schengen" }, "options": [ { "insurer_id": 2, "insurer_name": "Kilima Assurance", "plan_id": 7, "plan_name": "Schengen", "basic_premium": 5000, "basic_premium_minor": 500000, "taxes": [], "taxes_total": 63, "taxes_total_minor": 6300, "total": 5063, "total_minor": 506300, "days": 10, "travellers": 2, "region": "schengen", "per_traveller": 2500, "per_traveller_minor": 250000, "sum_insured": 4500000, "sum_insured_minor": 450000000 } ] } } } }, "422": { "description": "`validation_failed`, `domain_rule` or `no_quote`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "quote" ] }, { "bearer": [] } ], "x-scope": "quote", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/travel/save": { "post": { "operationId": "post_travel_save", "tags": [ "Travel" ], "summary": "Bind a travel policy", "description": "Re-prices the trip for the number of travellers listed and checks `policy.premium` within KES 1. `policy.quoteId` (numeric) or `coverName` picks the plan; otherwise the insurer's cheapest plan. Each traveller needs a passport or ID number.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: bind.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per save; replays return the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key the agent becomes the creator." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "description": "Same block as POST /api/v1/motor/save." }, "policy": { "type": "object", "description": "{insurer_id, premium, basicPremium?, taxes?, sumInsured?, coverName?, quoteId?, start_date?, end_date?, rate_type?, premium_instalments?}." }, "travel_info": { "type": "object", "description": "{departure, return, travelling_from, travelling_to, trip_type, rate_type?}." }, "travellers": { "type": "array", "items": {}, "description": "[{name, dob, passport_no, id_no, phone, beneficiary_name, beneficiary_passport_id_no, benefitiary_relationship, benefitiary_phone_no}]." } }, "required": [ "client", "policy", "travel_info", "travellers" ] }, "example": { "client": { "name": "Kamau Njoroge", "phone": "0744000222", "email": "kamau@example.co.ke" }, "policy": { "start_date": "2026-11-01", "end_date": "2026-11-10", "insurer_id": 2, "basicPremium": 5000, "taxes": 63, "premium": 5063, "sumInsured": 4500000, "coverName": "Schengen" }, "travel_info": { "departure": "2026-11-01", "return": "2026-11-10", "travelling_from": "Kenya", "travelling_to": "Germany", "trip_type": "single" }, "travellers": [ { "name": "Kamau Njoroge", "dob": "1990-01-01", "passport_no": "AK123456", "id_no": "22113344", "phone": "0744000222", "beneficiary_name": "Wairimu Kamau", "beneficiary_passport_id_no": "22334455", "benefitiary_relationship": "Wife", "benefitiary_phone_no": "0700111222" } ] } } } }, "responses": { "201": { "description": "Policy saved (same shape as motor save)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Policy saved successfully.", "id": 454, "uuid": "c2d4…", "risknote": "RN-000454", "policy_no": "POL-000454", "client_no": "C-000126", "client_key": "fxck_…", "product_line": "travel", "start_date": "2026-11-01", "end_date": "2026-11-10" } } } }, "422": { "description": "`validation_failed`, `premium_mismatch`, `no_quote` or `domain_rule`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "bind" ] }, { "bearer": [] } ], "x-scope": "bind", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": false } }, "/standard/products": { "get": { "operationId": "get_standard_products", "tags": [ "Standard products" ], "summary": "List standard products", "description": "Every active product with its benefit schedule and each insurer's covers (`plan_id`, cover name, pricing basis). `needs_age` / `needs_sum_insured` say what the quote needs.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Products", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 4, "code": "PA", "name": "Personal accident", "description": "…", "brochure_url": null, "needs_age": true, "needs_sum_insured": false, "benefits": [ { "name": "Death", "limit": 1000000, "limit_minor": 100000000 } ], "covers": [ { "plan_id": 9, "insurer_id": 1, "insurer_name": "Savanna General", "cover_name": "PA Classic", "pricing": "age_band", "rate_bps": null, "ipf_eligible": false, "premium": null, "premium_minor": null, "sum_insured": 1000000, "sum_insured_minor": 100000000 } ] } ] } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/standard/quote": { "get": { "operationId": "get_standard_quote", "tags": [ "Standard products" ], "summary": "Price a standard product", "description": "Rate limit: 60 requests per minute per token (per-client override). Scope: quote.", "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "insurer_id", "in": "query", "required": false, "schema": { "type": "integer", "description": "One insurer, or `insurer_id[]=` for several." }, "description": "One insurer, or `insurer_id[]=` for several." }, { "name": "age", "in": "query", "required": false, "schema": { "type": "integer", "description": "Needed for age-band products." }, "description": "Needed for age-band products." }, { "name": "sum_insured", "in": "query", "required": false, "schema": { "type": "integer", "description": "Flexysure only. Whole shillings; needed for rate-on-sum-insured products." }, "description": "Flexysure only. Whole shillings; needed for rate-on-sum-insured products." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key the agent becomes the creator." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "responses": { "200": { "description": "Options", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "1 option found.", "quote": { "product_id": 4, "insurer_id": [ 1 ], "age": 30, "sum_insured": null }, "options": [ { "insurer_id": 1, "insurer_name": "Savanna General", "plan_id": 9, "plan_name": "PA Classic", "basic_premium": 4500, "basic_premium_minor": 450000, "taxes": [], "taxes_total": 60, "taxes_total_minor": 6000, "total": 4560, "total_minor": 456000, "product_id": 4, "product_code": "PA", "pricing": "age_band", "age": 30 } ] } } } }, "422": { "description": "`validation_failed` or `no_quote`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "quote" ] }, { "bearer": [] } ], "x-scope": "quote", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/standard/save": { "post": { "operationId": "post_standard_save", "tags": [ "Standard products" ], "summary": "Bind a standard product", "description": "Re-prices the product with the chosen insurer (`policy.plan_id` or `coverName` picks the cover) and checks `policy.premium` within KES 1. Age comes from `policy.age` or the client's `dob`. `benefits[]` (limits in shillings, rate in percent) is kept on the policy; otherwise the cover's schedule is used.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: bind.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per save; replays return the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key the agent becomes the creator." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client": { "type": "object", "description": "Same block as POST /api/v1/motor/save, plus optional `dob`." }, "policy": { "type": "object", "description": "{product_id, start_date, end_date?, insurer_id, coverName?, plan_id?, age?, basicPremium?, sumInsured?, taxes?, premium, premium_instalments?}." }, "taxes": { "type": "array", "items": {}, "description": "Accepted for compatibility; the server computes levies." }, "benefits": { "type": "array", "items": {}, "description": "[{name, limit, rate, premium}]." } }, "required": [ "client", "policy" ] }, "example": { "client": { "name": "Mutua Musyoka", "phone": "0755000333", "dob": "1996-01-20" }, "policy": { "product_id": 4, "start_date": "2026-10-14", "end_date": "2027-10-13", "insurer_id": 1, "coverName": "PA Classic", "basicPremium": 4500, "sumInsured": 1000000, "taxes": 60, "premium": 4560 }, "taxes": [], "benefits": [ { "name": "Death", "limit": 1000000, "rate": null, "premium": 0 } ] } } } }, "responses": { "201": { "description": "Policy saved (same shape as motor save)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "message": "Policy saved successfully.", "id": 455, "uuid": "e7f1…", "risknote": "RN-000455", "policy_no": "POL-000455", "client_no": "C-000127", "client_key": "fxck_…", "product_line": "standard" } } } }, "422": { "description": "`validation_failed`, `premium_mismatch`, `no_quote` or `domain_rule`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "bind" ] }, { "bearer": [] } ], "x-scope": "bind", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": false } }, "/policies": { "get": { "operationId": "get_policies", "tags": [ "Policies and quotes" ], "summary": "List policies", "description": "Newest first, cursor-paginated (`?limit=&cursor=`; Insurance Cloud style `?page=&per_page=` also works).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending_payment", "active", "cancelled", "expired", "renewed", "void" ] } }, { "name": "product_line", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "motor", "medical", "travel", "standard" ] } }, { "name": "insurer_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "starting", "in": "query", "required": false, "schema": { "type": "string", "description": "Cover starts on or after (Y-m-d)." }, "description": "Cover starts on or after (Y-m-d)." }, { "name": "ending", "in": "query", "required": false, "schema": { "type": "string", "description": "Cover ends on or before (Y-m-d)." }, "description": "Cover ends on or before (Y-m-d)." }, { "name": "client_no", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "1–100 (default 25)." }, "description": "1–100 (default 25)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "From links.next." }, "description": "From links.next." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key results narrow to that agent's records and writes are recorded against them." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "responses": { "200": { "description": "Policies", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 452, "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452", "risk_note_no": "RN-000452", "product_line": "motor", "status": "active", "status_label": "Active", "client": { "client_no": "C-000123", "name": "Wanjiru Kamau" }, "insurer": { "id": 1, "name": "Savanna General" }, "vehicle_class": "private", "cover_type": "comprehensive", "cover": "Comprehensive", "cover_name": null, "risk": "KDA 123A", "start_date": "2026-10-14", "end_date": "2027-10-13", "payment_mode": "full", "instalments": 1, "sum_insured": 1000000, "sum_insured_minor": 100000000, "basic_premium": 35000, "basic_premium_minor": 3500000, "taxes": 198, "taxes_minor": 19800, "premium": 35198, "premium_minor": 3519800, "billed": 35198, "billed_minor": 3519800, "paid": 35198, "paid_minor": 3519800, "balance": 0, "balance_minor": 0, "created_by": 4, "created_at": "2026-10-14T09:30:00+03:00", "activated_at": "2026-10-14T09:31:04+03:00", "cancelled_at": null } ], "meta": { "limit": 25, "has_more": false, "count": 1 }, "links": { "next": null } } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/policies/{uuid}": { "get": { "operationId": "get_policies_uuid", "tags": [ "Policies and quotes" ], "summary": "Read a policy", "description": "The list row plus client details, vehicles, members, travellers, benefits, debit notes, receipts allocated to them, certificates, endorsements, refunds, a claims summary and links.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Policy uuid (from a save response or the list)." }, "description": "Policy uuid (from a save response or the list)." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key results narrow to that agent's records and writes are recorded against them." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "responses": { "200": { "description": "Policy", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 452, "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452", "risk_note_no": "RN-000452", "product_line": "motor", "status": "active", "status_label": "Active", "client": { "client_no": "C-000123", "name": "Wanjiru Kamau" }, "insurer": { "id": 1, "name": "Savanna General" }, "vehicle_class": "private", "cover_type": "comprehensive", "cover": "Comprehensive", "cover_name": null, "risk": "KDA 123A", "start_date": "2026-10-14", "end_date": "2027-10-13", "payment_mode": "full", "instalments": 1, "sum_insured": 1000000, "sum_insured_minor": 100000000, "basic_premium": 35000, "basic_premium_minor": 3500000, "taxes": 198, "taxes_minor": 19800, "premium": 35198, "premium_minor": 3519800, "billed": 35198, "billed_minor": 3519800, "paid": 35198, "paid_minor": 3519800, "balance": 0, "balance_minor": 0, "created_by": 4, "created_at": "2026-10-14T09:30:00+03:00", "activated_at": "2026-10-14T09:31:04+03:00", "cancelled_at": null, "limits": { "cover_period": "annual", "days": 365 }, "travel_info": null, "vehicles": [ { "id": 77, "reg_no": "KDA123A", "chassis_no": "NZE161-3012456", "make": "Toyota", "model": "Axio", "year": 2018, "on_cover": true, "value": 1000000, "value_minor": 100000000 } ], "members": [], "travellers": [], "benefits": [], "debit_notes": [ { "number": "DN-000452", "kind": "premium", "instalment_no": 1, "instalment_of": 1, "due_on": "2026-10-14", "status": "settled", "amount": 35198, "amount_minor": 3519800, "settled": 35198, "settled_minor": 3519800, "outstanding": 0, "outstanding_minor": 0 } ], "receipts": [ { "number": "RCT-000311", "channel": "mpesa", "reference": "SJK3ABCD12", "received_at": "2026-10-14T09:31:00+03:00", "debit_note": "DN-000452", "allocated": 35198, "allocated_minor": 3519800 } ], "certificates": [ { "certificate_no": "C12345678", "vehicle_id": 77, "stage": 1, "stage_of": 1, "period_from": "2026-10-14", "period_to": "2027-10-13", "status": "issued" } ], "endorsements": [], "refunds": [], "claims": { "count": 0, "open": 0, "items": [] }, "links": { "self": "https://app.flexysure.com/api/v1/policies/0d7b1f1e-…", "web": "https://app.flexysure.com/policies/0d7b1f1e-…" } } } } } }, "404": { "description": "Not found or not visible to the caller", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/policies/{uuid}/endorse": { "post": { "operationId": "post_policies_uuid_endorse", "tags": [ "Policies and quotes" ], "summary": "Endorse a policy", "description": "Mid-term change to an active policy, priced pro rata to expiry with current rates. A positive change raises an endorsement debit note; a negative one a credit and refund. `changes` by type: add_vehicle {reg_no, chassis_no, make, model, year, body_type, value}; remove_vehicle {vehicle_id}; change_value {value, vehicle_id?}; change_cover {cover_type comprehensive|tpo}; change_dates {end_on}; add_member {name, type, dob?, premium}; remove_member {member_id}; other {description, premium_delta}. Amounts in whole shillings.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: bind.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Policy uuid (from a save response or the list)." }, "description": "Policy uuid (from a save response or the list)." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; replays return the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key results narrow to that agent's records and writes are recorded against them." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "add_vehicle", "remove_vehicle", "change_value", "change_cover", "change_dates", "add_member", "remove_member", "other" ] }, "effective_on": { "type": "string", "description": "Y-m-d inside the cover period (default today)." }, "changes": { "type": "object" } }, "required": [ "type" ] }, "example": { "type": "change_value", "effective_on": "2027-01-10", "changes": { "value": 1200000 } } } } }, "responses": { "201": { "description": "Endorsement and the updated policy", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "endorsement": { "uuid": "1f2e…", "number": "END-000031", "type": "change_value", "effective_on": "2027-01-10", "status": "issued", "narrative": "Sum insured KES 1,000,000 → KES 1,200,000", "changes": { "value": 1200000 }, "debit_note": "DN-000460", "premium_delta": 5404, "premium_delta_minor": 540400, "taxes_delta": 24, "taxes_delta_minor": 2400, "gross_delta": 5428, "gross_delta_minor": 542800 }, "policy": { "id": 452, "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452", "risk_note_no": "RN-000452", "product_line": "motor", "status": "active", "status_label": "Active", "client": { "client_no": "C-000123", "name": "Wanjiru Kamau" }, "insurer": { "id": 1, "name": "Savanna General" }, "vehicle_class": "private", "cover_type": "comprehensive", "cover": "Comprehensive", "cover_name": null, "risk": "KDA 123A", "start_date": "2026-10-14", "end_date": "2027-10-13", "payment_mode": "full", "instalments": 1, "sum_insured": 1000000, "sum_insured_minor": 100000000, "basic_premium": 35000, "basic_premium_minor": 3500000, "taxes": 198, "taxes_minor": 19800, "premium": 35198, "premium_minor": 3519800, "billed": 35198, "billed_minor": 3519800, "paid": 35198, "paid_minor": 3519800, "balance": 0, "balance_minor": 0, "created_by": 4, "created_at": "2026-10-14T09:30:00+03:00", "activated_at": "2026-10-14T09:31:04+03:00", "cancelled_at": null, "limits": { "cover_period": "annual", "days": 365 }, "travel_info": null, "vehicles": [ { "id": 77, "reg_no": "KDA123A", "chassis_no": "NZE161-3012456", "make": "Toyota", "model": "Axio", "year": 2018, "on_cover": true, "value": 1000000, "value_minor": 100000000 } ], "members": [], "travellers": [], "benefits": [], "debit_notes": [ { "number": "DN-000452", "kind": "premium", "instalment_no": 1, "instalment_of": 1, "due_on": "2026-10-14", "status": "settled", "amount": 35198, "amount_minor": 3519800, "settled": 35198, "settled_minor": 3519800, "outstanding": 0, "outstanding_minor": 0 } ], "receipts": [ { "number": "RCT-000311", "channel": "mpesa", "reference": "SJK3ABCD12", "received_at": "2026-10-14T09:31:00+03:00", "debit_note": "DN-000452", "allocated": 35198, "allocated_minor": 3519800 } ], "certificates": [ { "certificate_no": "C12345678", "vehicle_id": 77, "stage": 1, "stage_of": 1, "period_from": "2026-10-14", "period_to": "2027-10-13", "status": "issued" } ], "endorsements": [], "refunds": [], "claims": { "count": 0, "open": 0, "items": [] }, "links": { "self": "https://app.flexysure.com/api/v1/policies/0d7b1f1e-…", "web": "https://app.flexysure.com/policies/0d7b1f1e-…" } } } } } } }, "403": { "description": "`actor_forbidden`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`validation_failed` or `domain_rule` (not active, type not for this line…)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "bind" ] }, { "bearer": [] } ], "x-scope": "bind", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/policies/{uuid}/cancellation-quote": { "get": { "operationId": "get_policies_uuid_cancellation_quote", "tags": [ "Policies and quotes" ], "summary": "Preview a cancellation", "description": "What cancelling on `effective_on` would do, without changing anything: unearned premium (pro rata or short-period scale, levies not refunded) and the estimated refund after unpaid premium. `outcome` is `cancel`, `void` (never paid — nothing to refund) or `not_cancellable`.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Policy uuid (from a save response or the list)." }, "description": "Policy uuid (from a save response or the list)." }, { "name": "effective_on", "in": "query", "required": false, "schema": { "type": "string", "description": "Y-m-d (default today)." }, "description": "Y-m-d (default today)." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key results narrow to that agent's records and writes are recorded against them." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "responses": { "200": { "description": "Breakdown", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "policy_no": "POL-000452", "status": "active", "cancellable": true, "outcome": "cancel", "effective_on": "2027-01-10", "method": "pro_rata", "cover_days": 365, "days_on_risk": 88, "remaining_days": 277, "months_on_risk": 3, "basic_premium": 35000, "basic_premium_minor": 3500000, "earned": 8438, "earned_minor": 843800, "unearned_basic": 26562, "unearned_basic_minor": 2656200, "unearned_levies": 0, "unearned_levies_minor": 0, "unearned": 26562, "unearned_minor": 2656200, "billed": 35198, "billed_minor": 3519800, "paid": 35198, "paid_minor": 3519800, "estimated_refund": 26562, "estimated_refund_minor": 2656200, "note": "Levies and stamp duty are not refunded…" } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/policies/{uuid}/cancel": { "post": { "operationId": "post_policies_uuid_cancel", "tags": [ "Policies and quotes" ], "summary": "Cancel a policy", "description": "Cancels an active policy (or voids one never paid): credits the unearned premium, reverses commission on it, cancels certificates and records a refund to the client (or to Flexysure Finance first for a premium-financed policy). Backdating is limited to 30 days; future dates are refused.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: bind.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Policy uuid (from a save response or the list)." }, "description": "Policy uuid (from a save response or the list)." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; replays return the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key results narrow to that agent's records and writes are recorded against them." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "examples": [ "Client requested cancellation" ] }, "effective_on": { "type": "string", "description": "Y-m-d (default today)." } }, "required": [ "reason" ] }, "example": { "reason": "Vehicle sold", "effective_on": "2027-01-10" } } } }, "responses": { "200": { "description": "The cancelled policy with its refunds", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 452, "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452", "risk_note_no": "RN-000452", "product_line": "motor", "status": "cancelled", "status_label": "Cancelled", "client": { "client_no": "C-000123", "name": "Wanjiru Kamau" }, "insurer": { "id": 1, "name": "Savanna General" }, "vehicle_class": "private", "cover_type": "comprehensive", "cover": "Comprehensive", "cover_name": null, "risk": "KDA 123A", "start_date": "2026-10-14", "end_date": "2027-10-13", "payment_mode": "full", "instalments": 1, "sum_insured": 1000000, "sum_insured_minor": 100000000, "basic_premium": 35000, "basic_premium_minor": 3500000, "taxes": 198, "taxes_minor": 19800, "premium": 35198, "premium_minor": 3519800, "billed": 35198, "billed_minor": 3519800, "paid": 35198, "paid_minor": 3519800, "balance": 0, "balance_minor": 0, "created_by": 4, "created_at": "2026-10-14T09:30:00+03:00", "activated_at": "2026-10-14T09:31:04+03:00", "cancelled_at": null, "limits": { "cover_period": "annual", "days": 365 }, "travel_info": null, "vehicles": [ { "id": 77, "reg_no": "KDA123A", "chassis_no": "NZE161-3012456", "make": "Toyota", "model": "Axio", "year": 2018, "on_cover": true, "value": 1000000, "value_minor": 100000000 } ], "members": [], "travellers": [], "benefits": [], "debit_notes": [ { "number": "DN-000452", "kind": "premium", "instalment_no": 1, "instalment_of": 1, "due_on": "2026-10-14", "status": "settled", "amount": 35198, "amount_minor": 3519800, "settled": 35198, "settled_minor": 3519800, "outstanding": 0, "outstanding_minor": 0 } ], "receipts": [ { "number": "RCT-000311", "channel": "mpesa", "reference": "SJK3ABCD12", "received_at": "2026-10-14T09:31:00+03:00", "debit_note": "DN-000452", "allocated": 35198, "allocated_minor": 3519800 } ], "certificates": [ { "certificate_no": "C12345678", "vehicle_id": 77, "stage": 1, "stage_of": 1, "period_from": "2026-10-14", "period_to": "2027-10-13", "status": "issued" } ], "endorsements": [], "refunds": [ { "uuid": "7c8d…", "number": "RF-000012", "kind": "cancellation", "payee": "client", "status": "pending", "paid_at": null, "reference": null, "amount": 26562, "amount_minor": 2656200 } ], "claims": { "count": 0, "open": 0, "items": [] }, "links": { "self": "https://app.flexysure.com/api/v1/policies/0d7b1f1e-…", "web": "https://app.flexysure.com/policies/0d7b1f1e-…" } } } } } }, "403": { "description": "`actor_forbidden` (agents cannot cancel)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`validation_failed` or `domain_rule`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "bind" ] }, { "bearer": [] } ], "x-scope": "bind", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/policies/{uuid}/renewal-quote": { "post": { "operationId": "post_policies_uuid_renewal_quote", "tags": [ "Policies and quotes" ], "summary": "Raise a renewal quote", "description": "Re-quotes the same risk with current rates for the next period and links the quote to the policy. Convert it like any other quote (travel cover is not renewed).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: bind.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Policy uuid (from a save response or the list)." }, "description": "Policy uuid (from a save response or the list)." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; replays return the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key results narrow to that agent's records and writes are recorded against them." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "responses": { "201": { "description": "Quote", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 91, "uuid": "3e4f…", "quote_no": "Q-000091", "product_line": "motor", "status": "presented", "valid_until": "2027-11-12", "renews_policy_id": 452, "options": [ { "option_id": 310, "insurer_id": 1, "insurer_name": "Savanna General", "rate": 3.5, "total": 35198, "total_minor": 3519800 } ] } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`domain_rule` (not renewable, already renewed…)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "bind" ] }, { "bearer": [] } ], "x-scope": "bind", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/quotes/{uuid}": { "get": { "operationId": "get_quotes_uuid", "tags": [ "Policies and quotes" ], "summary": "Read a quote", "description": "A stored quote of any product line with its options (whole shillings beside cents), inputs, validity and — once converted — the policy it became.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. Agent code; with X-Agent-Key results narrow to that agent's records and writes are recorded against them." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. The agent's key." } ], "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 88, "uuid": "5b0f…", "quote_no": "Q-000088", "product_line": "motor", "status": "presented", "valid_until": "2026-10-28", "client": { "client_no": "C-000124", "name": "Otieno Ouma" }, "inputs": { "vehicle_class": "private", "cover_type": "comprehensive", "value": 1000000, "year": 2018 }, "policy": null, "options": [ { "option_id": 301, "insurer_id": 1, "insurer_name": "Savanna General", "rate": 3.5, "basic_premium": 35000, "basic_premium_minor": 3500000, "total": 35198, "total_minor": 3519800 } ] } } } } }, "404": { "description": "Not found or not visible to the caller", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/payment/stk/push": { "post": { "operationId": "post_payment_stk_push", "tags": [ "Payments" ], "summary": "Send an M-Pesa STK push", "description": "Sends a \"Lipa na M-Pesa\" prompt to the customer's phone. `account` may be a debit note number, a policy number, a risk note number or a premium-finance loan ref (IPF-…). A policy resolves to its oldest unpaid debit note. If the policy has a signed premium-finance loan waiting for its deposit, the prompt is for the deposit (purpose `ipf_deposit`) and paying it hands the loan to Flexysure Finance. An active (or in-arrears) loan ref is an instalment repayment to Flexysure Finance (purpose `ipf_repayment`): when the customer pays, the money is booked in Flexysure Finance's books against the loan (fees, then interest, then principal of the oldest unpaid instalment), never as a brokerage receipt, and the loan's `repaid` and `arrears` update. To clear a loan early, use `POST /ipf/loans/{uuid}/early-settlement` (purpose `ipf_settlement`). The amount may not exceed what is outstanding on that account. Daraja takes whole shillings, so cents are rounded up.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: pay.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string", "description": "Debit note number, policy number, risk note number or IPF loan ref.", "examples": [ "DN-000123" ] }, "amount": { "type": "number", "description": "Amount in shillings, at least 1 and at most the outstanding balance.", "examples": [ 30175 ] }, "phone": { "type": "string", "description": "Safaricom number: 07XXXXXXXX or 2547XXXXXXXX (01… and 2541… also accepted).", "examples": [ "0712345678" ] } }, "required": [ "account", "amount", "phone" ] }, "example": { "account": "DN-000123", "amount": 30175, "phone": "0712345678" } } } }, "responses": { "200": { "description": "Prompt sent: Insurance Cloud fields plus `stk_request_uuid` to poll", "content": { "application/json": { "schema": { "type": "object" }, "example": { "merchant_request_id": "29115-34620561-1", "checkout_request_id": "ws_CO_14102026101500123", "stk_request_uuid": "9b2f0f5e-6d0b-4c1e-9d55-2b8f3c1a7e10", "status": "pending", "status_label": "Waiting for customer", "purpose": "premium", "account": "DN-000123", "phone": "0712 345 678", "amount": 30175, "amount_minor": 3017500, "result_code": null, "result_desc": null, "mpesa_receipt": null, "receipt_number": null, "debit_note": "DN-000123", "ipf_loan_ref": null, "created_at": "2026-10-14T10:15:00+03:00", "updated_at": "2026-10-14T10:15:00+03:00", "customer_message": "We sent an M-Pesa prompt to 0712 345 678. The customer enters their PIN to pay." } } } }, "404": { "description": "`account_not_found`: no debit note, policy, risk note or loan with that reference in your organisation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`amount_exceeds_balance` (with `outstanding`), `nothing_outstanding`, `financed_by_lender`, `loan_not_payable` (loan not running: pending, closed or cancelled), `payment_refused` or `validation_failed`. No money moved.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "pay" ] }, { "bearer": [] } ], "x-scope": "pay", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": false } }, "/payment/stk/{uuid}": { "get": { "operationId": "get_payment_stk_uuid", "tags": [ "Payments" ], "summary": "Get STK push status", "description": "`pending` until the customer answers the prompt, then `paid` (with `mpesa_receipt` and the Flexysure `receipt_number`) or `failed` (with Daraja's `result_code` and `result_desc`, for example 1032 cancelled by the customer).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: pay.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "`stk_request_uuid` from the push response." }, "description": "`stk_request_uuid` from the push response." } ], "responses": { "200": { "description": "The STK request", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "merchant_request_id": "29115-34620561-1", "checkout_request_id": "ws_CO_14102026101500123", "stk_request_uuid": "9b2f0f5e-6d0b-4c1e-9d55-2b8f3c1a7e10", "status": "paid", "status_label": "Paid", "purpose": "premium", "account": "DN-000123", "phone": "0712 345 678", "amount": 30175, "amount_minor": 3017500, "result_code": 0, "result_desc": "The service request is processed successfully.", "mpesa_receipt": "SKD1A2B3C4", "receipt_number": "RCT-000412", "debit_note": "DN-000123", "ipf_loan_ref": null, "created_at": "2026-10-14T10:15:00+03:00", "updated_at": "2026-10-14T10:15:00+03:00", "customer_message": "We sent an M-Pesa prompt to 0712 345 678. The customer enters their PIN to pay." } } } } }, "404": { "description": "Unknown or not visible to this token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "pay" ] }, { "bearer": [] } ], "x-scope": "pay", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/receipts": { "get": { "operationId": "get_receipts", "tags": [ "Payments" ], "summary": "List receipts", "description": "Money received by the organisation, newest first, with what each receipt paid. Cursor paginated (`limit`, `cursor`); `page`/`per_page` also accepted. Agent-scoped clients see receipts for their own clients and policies.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: pay.", "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "mpesa_stk", "mpesa_c2b", "bank", "cash", "cheque", "refund" ], "description": "How the money came in." }, "description": "How the money came in." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "description": "Received on or after this date (YYYY-MM-DD).", "examples": [ "2026-10-01" ] }, "description": "Received on or after this date (YYYY-MM-DD).", "example": "2026-10-01" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "description": "Received on or before this date.", "examples": [ "2026-10-31" ] }, "description": "Received on or before this date.", "example": "2026-10-31" }, { "name": "client_no", "in": "query", "required": false, "schema": { "type": "string", "description": "Only this client's receipts." }, "description": "Only this client's receipts." }, { "name": "policy", "in": "query", "required": false, "schema": { "type": "string", "description": "Policy uuid, policy number or risk note: receipts allocated to its debit notes." }, "description": "Policy uuid, policy number or risk note: receipts allocated to its debit notes." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page size, 1–100 (default 25)." }, "description": "Page size, 1–100 (default 25)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Opaque cursor from `links.next`." }, "description": "Opaque cursor from `links.next`." } ], "responses": { "200": { "description": "A page of receipts", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "number": "RCT-000412", "channel": "mpesa_stk", "reference": "SKD1A2B3C4", "amount": 30175, "amount_minor": 3017500, "allocated": 30175, "allocated_minor": 3017500, "unallocated": 0, "unallocated_minor": 0, "payer_phone": "254712345678", "received_at": "2026-10-14T10:16:02+03:00", "status": "allocated", "client": { "client_no": "C000231", "name": "Wanjiru Kamau" }, "allocations": [ { "debit_note": "DN-000123", "policy_no": "POL/2026/000123", "policy_uuid": "5d0c…", "amount": 30175, "amount_minor": 3017500, "allocated_at": "2026-10-14T10:16:02+03:00" } ] } ], "meta": { "limit": 25, "has_more": false, "count": 1 }, "links": { "next": null } } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "pay" ] }, { "bearer": [] } ], "x-scope": "pay", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/receipts/{number}": { "get": { "operationId": "get_receipts_number", "tags": [ "Payments" ], "summary": "Get a receipt", "description": "Rate limit: 60 requests per minute per token (per-client override). Scope: pay.", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string", "description": "Receipt number.", "examples": [ "RCT-000412" ] }, "description": "Receipt number.", "example": "RCT-000412" } ], "responses": { "200": { "description": "The receipt with its allocations", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "number": "RCT-000412", "channel": "mpesa_stk", "reference": "SKD1A2B3C4", "amount": 30175, "amount_minor": 3017500, "allocated": 30175, "allocated_minor": 3017500, "unallocated": 0, "unallocated_minor": 0, "payer_phone": "254712345678", "received_at": "2026-10-14T10:16:02+03:00", "status": "allocated", "client": { "client_no": "C000231", "name": "Wanjiru Kamau" }, "allocations": [ { "debit_note": "DN-000123", "policy_no": "POL/2026/000123", "policy_uuid": "5d0c…", "amount": 30175, "amount_minor": 3017500, "allocated_at": "2026-10-14T10:16:02+03:00" } ] } } } } }, "404": { "description": "Unknown receipt", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "pay" ] }, { "bearer": [] } ], "x-scope": "pay", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/clients/{client_no}/balance": { "get": { "operationId": "get_clients_client_no_balance", "tags": [ "Payments" ], "summary": "Get a client's balance", "description": "Open debit notes, credits (unallocated receipts and credit notes not yet refunded) and premium-finance balances. `due` is what the client owes the organisation; debit notes Flexysure Finance is paying are listed with `payable_by: lender` and left out of `due`. `ipf_outstanding` is owed to Flexysure Finance (paybill and account in `repay_to`).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: pay.", "parameters": [ { "name": "client_no", "in": "path", "required": true, "schema": { "type": "string", "description": "Client number.", "examples": [ "C000231" ] }, "description": "Client number.", "example": "C000231" } ], "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "client": { "client_no": "C000231", "name": "Wanjiru Kamau" }, "currency": "KES", "due": 30175, "due_minor": 3017500, "credits": 0, "credits_minor": 0, "net_due": 30175, "net_due_minor": 3017500, "ipf_outstanding": 46500, "ipf_outstanding_minor": 4650000, "open_debit_notes": [ { "number": "DN-000123", "kind": "Premium", "policy_no": "POL/2026/000123", "policy_uuid": "5d0c…", "due_on": "2026-10-14", "amount": 30175, "amount_minor": 3017500, "paid": 0, "paid_minor": 0, "outstanding": 30175, "outstanding_minor": 3017500, "payable_by": "client" } ], "unallocated_receipts": [], "credit_notes": [], "ipf_loans": [ { "uuid": "1f7e…", "loan_ref": "IPF-000017", "status": "active", "policy_no": "POL/2026/000099", "outstanding": 46500, "outstanding_minor": 4650000, "arrears": 0, "arrears_minor": 0, "arrears_days": 0, "repay_to": { "paybill": "700100", "account": "IPF-000017" } } ], "as_of": "2026-10-14T10:20:00+03:00" } } } } }, "404": { "description": "Unknown client", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "pay" ] }, { "bearer": [] } ], "x-scope": "pay", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/prospects": { "post": { "operationId": "post_prospects", "tags": [ "Prospects" ], "summary": "Create a prospect", "description": "Insurance Cloud compatible. `status` is matched case-insensitively to new, contacted, quoted, negotiating, won or lost (\"New\" works); anything else is 422. Expected premium and commission are derived from `products[]`.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: crm.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; a replay returns the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "p_name": { "type": "string", "description": "Prospect (person or company) name.", "examples": [ "Kilima Farm Supplies" ] }, "status": { "type": "string", "enum": [ "New", "Contacted", "Quoted", "Negotiating", "Won", "Lost" ], "description": "Pipeline stage.", "examples": [ "New" ] }, "email": { "type": "string", "description": "Contact email.", "examples": [ "ops@kilimafarm.co.ke" ] }, "phone": { "type": "string", "description": "Kenyan mobile (07…, 01…, +2547…). Stored as 07XXXXXXXX.", "examples": [ "0712345678" ] }, "sector": { "type": "string", "examples": [ "Agriculture" ] }, "insurer_id": { "type": "integer", "description": "Preferred insurer (GET /insurers).", "examples": [ 1 ] }, "alt_name": { "type": "string", "description": "Alternative contact person." }, "alt_phone": { "type": "string" }, "alt_email": { "type": "string" }, "start_date": { "type": "string", "description": "Y-m-d.", "examples": [ "2026-10-14" ] }, "due_date": { "type": "string", "description": "Y-m-d. When the deal should close." }, "follow_up_date": { "type": "string", "description": "Y-m-d. Drives the follow-ups due/overdue lists." }, "notes": { "type": "string" }, "rating": { "type": "string", "description": "`hot`, `warm` or `cold` (any case), or Insurance Cloud's 1–5: 4–5 hot, 3 warm, 1–2 cold.", "examples": [ "hot" ] }, "business_source_id": { "type": "integer", "description": "Walk-in, Referral, Web, Agent, Bancassurance." }, "prospect_type_id": { "type": "integer", "description": "Individual, SME, Corporate, SACCO member." }, "products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "examples": [ "Motor private comprehensive" ] }, "product_id": { "type": "integer", "description": "Standard product id (GET /products), if any." }, "comm_rate": { "type": "number", "description": "Commission rate in percent.", "examples": [ 10 ] }, "premium": { "type": "number", "description": "Expected premium, whole shillings.", "examples": [ 85000 ] }, "commission": { "type": "number", "description": "Shillings. Derived from premium × comm_rate when omitted." } }, "required": [ "product" ] }, "description": "Products being discussed. Expected premium and commission are the sums of these rows." }, "assign_to": { "type": "array", "items": { "type": "integer" }, "description": "Staff user ids (GET /sales-people, /risk-managers). Assigned agents can see the prospect.", "examples": [ [ 4 ] ] } }, "required": [ "p_name", "status" ] }, "example": { "p_name": "Kilima Farm Supplies", "status": "New", "phone": "0712345678", "email": "ops@kilimafarm.co.ke", "rating": "hot", "follow_up_date": "2026-10-17", "products": [ { "product": "Motor private comprehensive", "comm_rate": 10, "premium": 85000 } ], "assign_to": [ 4 ] } } } }, "responses": { "201": { "description": "Prospect created", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "message": "Prospect created.", "prospect": { "id": 42, "uuid": "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f", "p_name": "Kilima Farm Supplies", "status": "New", "expected_prem": 85000, "expected_comm": 8500, "created_at": "2026-10-14T09:00:00+03:00" } } } } }, "422": { "description": "Validation failed (unknown status, insurer or assignee from another organisation…)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "crm" ] }, { "bearer": [] } ], "x-scope": "crm", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": false }, "get": { "operationId": "get_prospects", "tags": [ "Prospects" ], "summary": "List prospects", "description": "Newest first, cursor paginated (`limit`, `cursor`; `page`/`per_page` also accepted).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Pipeline stage (any case).", "examples": [ "negotiating" ] }, "description": "Pipeline stage (any case).", "example": "negotiating" }, { "name": "rating", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "hot", "warm", "cold" ] } }, { "name": "follow_up", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "today", "overdue" ], "description": "Open prospects whose follow-up is due today or overdue." }, "description": "Open prospects whose follow-up is due today or overdue." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Name, email or phone." }, "description": "Name, email or phone." }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": "integer", "description": "Staff user id." }, "description": "Staff user id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 25, max 100." }, "description": "Default 25, max 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "From `links.next`." }, "description": "From `links.next`." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Prospects", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "uuid": "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f", "name": "Kilima Farm Supplies", "status": "negotiating", "status_label": "Negotiating", "rating": "hot", "email": "ops@kilimafarm.co.ke", "phone": "0712345678", "sector": "Agriculture", "insurer": { "id": 1, "name": "Savanna General" }, "follow_up_date": "2026-10-17", "follow_up_state": "upcoming", "expected_premium": 85000, "expected_premium_minor": 8500000, "expected_commission": 8500, "expected_commission_minor": 850000, "products": [ { "product": "Motor private comprehensive", "product_id": null, "product_line": "motor", "comm_rate": 10, "comm_rate_bps": 1000, "premium": 85000, "premium_minor": 8500000, "commission": 8500, "commission_minor": 850000 } ], "assignees": [ { "id": 4, "name": "Kevin Kiprop", "role": "agent", "code": "KK01" } ], "client": null, "created_at": "2026-10-14T09:00:00+03:00" } ], "meta": { "limit": 25, "has_more": false, "count": 1 }, "links": { "next": null } } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/prospects/{uuid}": { "get": { "operationId": "get_prospects_uuid", "tags": [ "Prospects" ], "summary": "Get a prospect", "description": "The prospect with its products, assignees and activity timeline (newest first).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Prospect uuid.", "examples": [ "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f" ] }, "description": "Prospect uuid.", "example": "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f" }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Prospect", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f", "name": "Kilima Farm Supplies", "status": "negotiating", "status_label": "Negotiating", "rating": "hot", "email": "ops@kilimafarm.co.ke", "phone": "0712345678", "sector": "Agriculture", "insurer": { "id": 1, "name": "Savanna General" }, "follow_up_date": "2026-10-17", "follow_up_state": "upcoming", "expected_premium": 85000, "expected_premium_minor": 8500000, "expected_commission": 8500, "expected_commission_minor": 850000, "products": [ { "product": "Motor private comprehensive", "product_id": null, "product_line": "motor", "comm_rate": 10, "comm_rate_bps": 1000, "premium": 85000, "premium_minor": 8500000, "commission": 8500, "commission_minor": 850000 } ], "assignees": [ { "id": 4, "name": "Kevin Kiprop", "role": "agent", "code": "KK01" } ], "client": null, "created_at": "2026-10-14T09:00:00+03:00", "activities": [ { "id": 7, "type": "call", "type_label": "Call", "body": "Wants a quote by Friday.", "user": { "id": 4, "name": "Kevin Kiprop", "role": "agent", "code": "KK01" }, "occurred_at": "2026-10-14T10:00:00+03:00" } ] } } } } }, "404": { "description": "Not found or not visible to this caller", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true }, "patch": { "operationId": "patch_prospects_uuid", "tags": [ "Prospects" ], "summary": "Update a prospect", "description": "Send only what changes. `name` or Insurance Cloud's `p_name`; `products` replaces the product list (totals re-derived); `assign_to` replaces the assignees. A status change is written to the timeline. Winning goes through the convert endpoint.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: crm.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Prospect uuid.", "examples": [ "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f" ] }, "description": "Prospect uuid.", "example": "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; a replay returns the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Or `p_name`." }, "status": { "type": "string", "enum": [ "new", "contacted", "quoted", "negotiating", "lost" ] }, "lost_reason": { "type": "string", "description": "Why the prospect was lost." }, "email": { "type": "string", "description": "Contact email.", "examples": [ "ops@kilimafarm.co.ke" ] }, "phone": { "type": "string", "description": "Kenyan mobile (07…, 01…, +2547…). Stored as 07XXXXXXXX.", "examples": [ "0712345678" ] }, "sector": { "type": "string", "examples": [ "Agriculture" ] }, "insurer_id": { "type": "integer", "description": "Preferred insurer (GET /insurers).", "examples": [ 1 ] }, "alt_name": { "type": "string", "description": "Alternative contact person." }, "alt_phone": { "type": "string" }, "alt_email": { "type": "string" }, "start_date": { "type": "string", "description": "Y-m-d.", "examples": [ "2026-10-14" ] }, "due_date": { "type": "string", "description": "Y-m-d. When the deal should close." }, "follow_up_date": { "type": "string", "description": "Y-m-d. Drives the follow-ups due/overdue lists." }, "notes": { "type": "string" }, "rating": { "type": "string", "description": "`hot`, `warm` or `cold` (any case), or Insurance Cloud's 1–5: 4–5 hot, 3 warm, 1–2 cold.", "examples": [ "hot" ] }, "business_source_id": { "type": "integer", "description": "Walk-in, Referral, Web, Agent, Bancassurance." }, "prospect_type_id": { "type": "integer", "description": "Individual, SME, Corporate, SACCO member." }, "products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "string", "examples": [ "Motor private comprehensive" ] }, "product_id": { "type": "integer", "description": "Standard product id (GET /products), if any." }, "comm_rate": { "type": "number", "description": "Commission rate in percent.", "examples": [ 10 ] }, "premium": { "type": "number", "description": "Expected premium, whole shillings.", "examples": [ 85000 ] }, "commission": { "type": "number", "description": "Shillings. Derived from premium × comm_rate when omitted." } }, "required": [ "product" ] }, "description": "Products being discussed. Expected premium and commission are the sums of these rows." }, "assign_to": { "type": "array", "items": { "type": "integer" }, "description": "Staff user ids (GET /sales-people, /risk-managers). Assigned agents can see the prospect.", "examples": [ [ 4 ] ] } } }, "example": { "status": "Negotiating", "follow_up_date": "2026-10-20" } } } }, "responses": { "200": { "description": "Updated prospect", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f", "name": "Kilima Farm Supplies", "status": "negotiating", "status_label": "Negotiating", "rating": "hot", "email": "ops@kilimafarm.co.ke", "phone": "0712345678", "sector": "Agriculture", "insurer": { "id": 1, "name": "Savanna General" }, "follow_up_date": "2026-10-17", "follow_up_state": "upcoming", "expected_premium": 85000, "expected_premium_minor": 8500000, "expected_commission": 8500, "expected_commission_minor": 850000, "products": [ { "product": "Motor private comprehensive", "product_id": null, "product_line": "motor", "comm_rate": 10, "comm_rate_bps": 1000, "premium": 85000, "premium_minor": 8500000, "commission": 8500, "commission_minor": 850000 } ], "assignees": [ { "id": 4, "name": "Kevin Kiprop", "role": "agent", "code": "KK01" } ], "client": null, "created_at": "2026-10-14T09:00:00+03:00" } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Validation failed or `won` sent (use convert)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "crm" ] }, { "bearer": [] } ], "x-scope": "crm", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/prospects/{uuid}/activities": { "post": { "operationId": "post_prospects_uuid_activities", "tags": [ "Prospects" ], "summary": "Log prospect activity", "description": "Adds a note, call or meeting to the timeline and can move the follow-up date in the same call. A call or meeting moves a new prospect to contacted.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: crm.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Prospect uuid.", "examples": [ "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f" ] }, "description": "Prospect uuid.", "example": "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; a replay returns the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "note", "call", "meeting" ] }, "body": { "type": "string", "examples": [ "Called; wants a quote by Friday." ] }, "occurred_at": { "type": "string", "description": "ISO 8601, not in the future. Default now." }, "follow_up_date": { "type": "string", "description": "Y-m-d. New follow-up date." } }, "required": [ "type", "body" ] }, "example": { "type": "call", "body": "Called; wants a quote by Friday.", "follow_up_date": "2026-10-17" } } } }, "responses": { "201": { "description": "Activity logged", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 7, "type": "call", "type_label": "Call", "body": "Called; wants a quote by Friday.", "user": { "id": 4, "name": "Kevin Kiprop", "role": "agent", "code": "KK01" }, "occurred_at": "2026-10-14T10:00:00+03:00" } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "crm" ] }, { "bearer": [] } ], "x-scope": "crm", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/prospects/{uuid}/convert": { "post": { "operationId": "post_prospects_uuid_convert", "tags": [ "Prospects" ], "summary": "Convert a prospect to a client", "description": "Marks the prospect won and creates its client, or links an existing client with the same phone, ID number or KRA PIN. Converting twice returns the same client. Lost prospects cannot be converted.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: crm.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Prospect uuid.", "examples": [ "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f" ] }, "description": "Prospect uuid.", "example": "9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; a replay returns the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "individual", "corporate" ] }, "phone": { "type": "string", "description": "Needed when the prospect has none." }, "id_no": { "type": "string" }, "kra_pin": { "type": "string" }, "date_of_birth": { "type": "string" }, "physical_address": { "type": "string" }, "branch_id": { "type": "integer" }, "risk_manager_id": { "type": "integer" }, "sales_person_id": { "type": "integer" } } }, "example": { "type": "corporate", "kra_pin": "P051234567X" } } } }, "responses": { "200": { "description": "Prospect (won) and its client", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "prospect": { "uuid": "9b1f…", "status": "won", "client": { "client_no": "C-00042", "name": "Kilima Farm Supplies" } }, "client": { "client_no": "C-00042", "name": "Kilima Farm Supplies", "type": "corporate" } } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Lost prospect, or no phone number (`domain_rule`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "crm" ] }, { "bearer": [] } ], "x-scope": "crm", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/clients": { "get": { "operationId": "get_clients", "tags": [ "Clients" ], "summary": "List clients", "description": "Newest first, cursor paginated (`limit`, `cursor`; `page`/`per_page` also accepted).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string", "description": "Name, client number, phone, ID number or KRA PIN." }, "description": "Name, client number, phone, ID number or KRA PIN." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "individual", "corporate" ] } }, { "name": "sales_person_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "risk_manager_id", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 25, max 100." }, "description": "Default 25, max 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Clients", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 42, "client_no": "C-00042", "type": "individual", "name": "Wanjiru Kamau", "id_no": "27845123", "kra_pin": "A001234567Z", "phone": "0712345678", "email": "wanjiru@example.com", "date_of_birth": "1988-04-02", "physical_address": "Kilimani, Nairobi", "branch": { "id": 1, "name": "Head office" }, "risk_manager": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "sales_person": { "id": 4, "name": "Kevin Kiprop", "role": "agent", "code": "KK01" }, "business_source": { "id": 2, "name": "Referral" }, "prospect_type": null, "sector": null, "alt_name": null, "alt_phone": null, "alt_email": null, "kyc_status": "unverified", "onboarded_via": "api", "created_at": "2026-10-14T09:00:00+03:00", "updated_at": "2026-10-14T09:00:00+03:00" } ], "meta": { "limit": 25, "has_more": false, "count": 1 }, "links": { "next": null } } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true }, "post": { "operationId": "post_clients", "tags": [ "Clients" ], "summary": "Create a client", "description": "Numbers the client (C-00001…), normalises phone and identity numbers and records who added it. The salesperson defaults to the acting agent; the risk manager to the acting account executive.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: crm.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; a replay returns the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "individual", "corporate" ], "description": "Default individual." }, "name": { "type": "string", "examples": [ "Wanjiru Kamau" ] }, "phone": { "type": "string", "description": "Kenyan mobile. Checked for duplicates.", "examples": [ "0712345678" ] }, "email": { "type": "string", "examples": [ "wanjiru@example.com" ] }, "id_no": { "type": "string", "description": "National ID / passport. Checked for duplicates.", "examples": [ "27845123" ] }, "kra_pin": { "type": "string", "description": "KRA PIN. Checked for duplicates.", "examples": [ "A001234567Z" ] }, "date_of_birth": { "type": "string", "description": "Y-m-d." }, "physical_address": { "type": "string" }, "branch_id": { "type": "integer", "description": "GET /branches. Defaults to the acting user's branch." }, "risk_manager_id": { "type": "integer", "description": "GET /risk-managers." }, "sales_person_id": { "type": "integer", "description": "GET /sales-people. The salesperson sees the client (and its policies and claims)." }, "business_source_id": { "type": "integer" }, "prospect_type_id": { "type": "integer" }, "sector": { "type": "string" }, "alt_name": { "type": "string", "description": "Alternative contact." }, "alt_phone": { "type": "string" }, "alt_email": { "type": "string" }, "force": { "type": "boolean", "description": "Create or save even when another client has the same phone, ID number or KRA PIN." } }, "required": [ "name", "phone" ] }, "example": { "type": "individual", "name": "Wanjiru Kamau", "phone": "0712345678", "id_no": "27845123", "email": "wanjiru@example.com", "sales_person_id": 4 } } } }, "responses": { "201": { "description": "Client created", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 42, "client_no": "C-00042", "type": "individual", "name": "Wanjiru Kamau", "id_no": "27845123", "kra_pin": "A001234567Z", "phone": "0712345678", "email": "wanjiru@example.com", "date_of_birth": "1988-04-02", "physical_address": "Kilimani, Nairobi", "branch": { "id": 1, "name": "Head office" }, "risk_manager": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "sales_person": { "id": 4, "name": "Kevin Kiprop", "role": "agent", "code": "KK01" }, "business_source": { "id": 2, "name": "Referral" }, "prospect_type": null, "sector": null, "alt_name": null, "alt_phone": null, "alt_email": null, "kyc_status": "unverified", "onboarded_via": "api", "created_at": "2026-10-14T09:00:00+03:00", "updated_at": "2026-10-14T09:00:00+03:00" } } } } }, "409": { "description": "`duplicate_client`: `matches[]` lists `{client_no, name, matched[]}` (name hidden from agents for clients they cannot see)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "crm" ] }, { "bearer": [] } ], "x-scope": "crm", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/clients/{client_no}": { "get": { "operationId": "get_clients_client_no", "tags": [ "Clients" ], "summary": "Get a client", "description": "Rate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "client_no", "in": "path", "required": true, "schema": { "type": "string", "description": "Client number.", "examples": [ "C-00042" ] }, "description": "Client number.", "example": "C-00042" }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Client", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 42, "client_no": "C-00042", "type": "individual", "name": "Wanjiru Kamau", "id_no": "27845123", "kra_pin": "A001234567Z", "phone": "0712345678", "email": "wanjiru@example.com", "date_of_birth": "1988-04-02", "physical_address": "Kilimani, Nairobi", "branch": { "id": 1, "name": "Head office" }, "risk_manager": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "sales_person": { "id": 4, "name": "Kevin Kiprop", "role": "agent", "code": "KK01" }, "business_source": { "id": 2, "name": "Referral" }, "prospect_type": null, "sector": null, "alt_name": null, "alt_phone": null, "alt_email": null, "kyc_status": "unverified", "onboarded_via": "api", "created_at": "2026-10-14T09:00:00+03:00", "updated_at": "2026-10-14T09:00:00+03:00" } } } } }, "404": { "description": "Not found or not visible to this caller", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true }, "patch": { "operationId": "patch_clients_client_no", "tags": [ "Clients" ], "summary": "Update a client", "description": "Send only what changes. A new phone, ID number or KRA PIN that belongs to another client answers 409 `duplicate_client` unless `force` is true. Changes are audited.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: crm.", "parameters": [ { "name": "client_no", "in": "path", "required": true, "schema": { "type": "string", "description": "Client number.", "examples": [ "C-00042" ] }, "description": "Client number.", "example": "C-00042" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; a replay returns the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "individual", "corporate" ] }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string", "examples": [ "wanjiru@example.com" ] }, "id_no": { "type": "string", "description": "National ID / passport. Checked for duplicates.", "examples": [ "27845123" ] }, "kra_pin": { "type": "string", "description": "KRA PIN. Checked for duplicates.", "examples": [ "A001234567Z" ] }, "date_of_birth": { "type": "string", "description": "Y-m-d." }, "physical_address": { "type": "string" }, "branch_id": { "type": "integer", "description": "GET /branches. Defaults to the acting user's branch." }, "risk_manager_id": { "type": "integer", "description": "GET /risk-managers." }, "sales_person_id": { "type": "integer", "description": "GET /sales-people. The salesperson sees the client (and its policies and claims)." }, "business_source_id": { "type": "integer" }, "prospect_type_id": { "type": "integer" }, "sector": { "type": "string" }, "alt_name": { "type": "string", "description": "Alternative contact." }, "alt_phone": { "type": "string" }, "alt_email": { "type": "string" }, "force": { "type": "boolean", "description": "Create or save even when another client has the same phone, ID number or KRA PIN." } } }, "example": { "email": "wanjiru.kamau@example.com", "physical_address": "Lavington, Nairobi" } } } }, "responses": { "200": { "description": "Updated client", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 42, "client_no": "C-00042", "type": "individual", "name": "Wanjiru Kamau", "id_no": "27845123", "kra_pin": "A001234567Z", "phone": "0712345678", "email": "wanjiru@example.com", "date_of_birth": "1988-04-02", "physical_address": "Kilimani, Nairobi", "branch": { "id": 1, "name": "Head office" }, "risk_manager": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "sales_person": { "id": 4, "name": "Kevin Kiprop", "role": "agent", "code": "KK01" }, "business_source": { "id": 2, "name": "Referral" }, "prospect_type": null, "sector": null, "alt_name": null, "alt_phone": null, "alt_email": null, "kyc_status": "unverified", "onboarded_via": "api", "created_at": "2026-10-14T09:00:00+03:00", "updated_at": "2026-10-14T09:00:00+03:00" } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "409": { "description": "`duplicate_client`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "crm" ] }, { "bearer": [] } ], "x-scope": "crm", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/claims": { "get": { "operationId": "get_claims", "tags": [ "Claims" ], "summary": "List claims", "description": "Newest first, cursor paginated.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "registered", "documents_pending", "submitted_to_insurer", "under_assessment", "approved", "repudiated", "settled", "closed", "withdrawn" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Legal", "Non Legal" ] } }, { "name": "claim_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "accidental_damage", "theft", "third_party", "medical", "travel", "death", "disability", "other" ] } }, { "name": "policy", "in": "query", "required": false, "schema": { "type": "string", "description": "Policy uuid." }, "description": "Policy uuid." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "description": "Reported on or after (Y-m-d)." }, "description": "Reported on or after (Y-m-d)." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "description": "Reported on or before (Y-m-d)." }, "description": "Reported on or before (Y-m-d)." }, { "name": "overdue", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only claims past their status SLA." }, "description": "Only claims past their status SLA." }, { "name": "open", "in": "query", "required": false, "schema": { "type": "boolean", "description": "true = still being worked; false = settled, closed or withdrawn." }, "description": "true = still being worked; false = settled, closed or withdrawn." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 25, max 100." }, "description": "Default 25, max 100." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Claims", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "uuid": "5c2e8a1b-7f3d-4e6a-9b0c-1d2e3f4a5b6c", "claim_no": "CLM/2026/00012", "status": "under_assessment", "status_label": "Under assessment", "next_statuses": [ "approved", "repudiated", "documents_pending", "withdrawn" ], "claim_type": "accidental_damage", "claim_type_label": "Accidental damage", "legal": false, "legal_label": "Non Legal", "policy": { "uuid": "1a2b…", "policy_no": "SG/MP/2026/000123", "product_line": "motor" }, "client": { "client_no": "C-00042", "name": "Wanjiru Kamau" }, "insurer": { "id": 1, "name": "Savanna General" }, "risk_item": "KDA 123A", "incident_on": "2026-10-10", "reported_on": "2026-10-11", "description": "Rear bumper damaged at the Nyayo roundabout.", "claimant": { "name": null, "phone": null, "relationship": null }, "insurer_ref": "SG-CL-88812", "currency": "KES", "amounts": { "estimate": 150000, "estimate_minor": 15000000, "reserve": 140000, "reserve_minor": 14000000, "approved": 0, "approved_minor": 0, "paid": 0, "paid_minor": 0, "excess": 15000, "excess_minor": 1500000, "outstanding": 0, "outstanding_minor": 0 }, "sla": { "due_at": "2026-11-01T09:00:00+03:00", "overdue": false, "label": "18 days left", "days_in_status": 3 }, "assigned_to": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "settled_on": null, "closed_on": null, "created_at": "2026-10-11T09:00:00+03:00" } ], "meta": { "limit": 25, "has_more": false, "count": 1 }, "links": { "next": null } } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true }, "post": { "operationId": "post_claims", "tags": [ "Claims" ], "summary": "Register a claim", "description": "Only active, expired or cancelled policies carry claims, and the incident date must fall inside the cover period (before cancellation). The claim number is CLM//; for motor the risk item defaults to the vehicle registration.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: claims.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; a replay returns the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "string", "description": "Policy uuid." }, "claim_type": { "type": "string", "enum": [ "accidental_damage", "theft", "third_party", "medical", "travel", "death", "disability", "other" ] }, "incident_on": { "type": "string", "description": "Y-m-d, not in the future." }, "description": { "type": "string" }, "reported_on": { "type": "string", "description": "Y-m-d. Default today." }, "legal": { "type": "boolean", "description": "A lawyer or court is involved. Or send Insurance Cloud's `type`: Legal | Non Legal." }, "risk_item": { "type": "string", "description": "Registration, member or traveller name." }, "claimant_name": { "type": "string" }, "claimant_phone": { "type": "string" }, "claimant_relationship": { "type": "string", "enum": [ "self", "driver", "spouse", "relative", "employee", "third_party", "other" ] }, "insurer_ref": { "type": "string" }, "estimate": { "type": "number", "description": "Shillings (or `estimate_minor`)." }, "excess": { "type": "number", "description": "Shillings (or `excess_minor`)." }, "assigned_to": { "type": "integer", "description": "Staff user who handles the claim." }, "note": { "type": "string", "description": "First timeline note." } }, "required": [ "policy", "claim_type", "incident_on", "description" ] }, "example": { "policy": "1a2b3c4d-…", "claim_type": "accidental_damage", "incident_on": "2026-10-10", "description": "Rear bumper damaged at the Nyayo roundabout.", "estimate": 150000, "excess": 15000, "type": "Non Legal" } } } }, "responses": { "201": { "description": "Claim registered (with its timeline)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "5c2e8a1b-7f3d-4e6a-9b0c-1d2e3f4a5b6c", "claim_no": "CLM/2026/00012", "status": "under_assessment", "status_label": "Under assessment", "next_statuses": [ "approved", "repudiated", "documents_pending", "withdrawn" ], "claim_type": "accidental_damage", "claim_type_label": "Accidental damage", "legal": false, "legal_label": "Non Legal", "policy": { "uuid": "1a2b…", "policy_no": "SG/MP/2026/000123", "product_line": "motor" }, "client": { "client_no": "C-00042", "name": "Wanjiru Kamau" }, "insurer": { "id": 1, "name": "Savanna General" }, "risk_item": "KDA 123A", "incident_on": "2026-10-10", "reported_on": "2026-10-11", "description": "Rear bumper damaged at the Nyayo roundabout.", "claimant": { "name": null, "phone": null, "relationship": null }, "insurer_ref": "SG-CL-88812", "currency": "KES", "amounts": { "estimate": 150000, "estimate_minor": 15000000, "reserve": 140000, "reserve_minor": 14000000, "approved": 0, "approved_minor": 0, "paid": 0, "paid_minor": 0, "excess": 15000, "excess_minor": 1500000, "outstanding": 0, "outstanding_minor": 0 }, "sla": { "due_at": "2026-11-01T09:00:00+03:00", "overdue": false, "label": "18 days left", "days_in_status": 3 }, "assigned_to": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "settled_on": null, "closed_on": null, "created_at": "2026-10-11T09:00:00+03:00", "events": [ { "status_from": null, "status_to": "registered", "note": null, "details": null, "user": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "occurred_at": "2026-10-11T09:00:00+03:00" } ], "documents": [ { "uuid": "77aa…", "kind": "police_abstract", "kind_label": "Police abstract", "original_name": "abstract.pdf", "mime": "application/pdf", "size": 182211, "sha256": "e3b0…", "uploaded_at": "2026-10-12T11:00:00+03:00" } ] } } } } }, "422": { "description": "Validation failed, unknown policy, or a claims rule (`domain_rule`: policy not on cover, incident outside the cover period…)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "claims" ] }, { "bearer": [] } ], "x-scope": "claims", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/claims/{uuid}": { "get": { "operationId": "get_claims_uuid", "tags": [ "Claims" ], "summary": "Get a claim", "description": "The claim with its timeline (`events`, oldest first) and documents.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: read.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Claim uuid.", "examples": [ "5c2e8a1b-7f3d-4e6a-9b0c-1d2e3f4a5b6c" ] }, "description": "Claim uuid.", "example": "5c2e8a1b-7f3d-4e6a-9b0c-1d2e3f4a5b6c" }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Claim", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "5c2e8a1b-7f3d-4e6a-9b0c-1d2e3f4a5b6c", "claim_no": "CLM/2026/00012", "status": "under_assessment", "status_label": "Under assessment", "next_statuses": [ "approved", "repudiated", "documents_pending", "withdrawn" ], "claim_type": "accidental_damage", "claim_type_label": "Accidental damage", "legal": false, "legal_label": "Non Legal", "policy": { "uuid": "1a2b…", "policy_no": "SG/MP/2026/000123", "product_line": "motor" }, "client": { "client_no": "C-00042", "name": "Wanjiru Kamau" }, "insurer": { "id": 1, "name": "Savanna General" }, "risk_item": "KDA 123A", "incident_on": "2026-10-10", "reported_on": "2026-10-11", "description": "Rear bumper damaged at the Nyayo roundabout.", "claimant": { "name": null, "phone": null, "relationship": null }, "insurer_ref": "SG-CL-88812", "currency": "KES", "amounts": { "estimate": 150000, "estimate_minor": 15000000, "reserve": 140000, "reserve_minor": 14000000, "approved": 0, "approved_minor": 0, "paid": 0, "paid_minor": 0, "excess": 15000, "excess_minor": 1500000, "outstanding": 0, "outstanding_minor": 0 }, "sla": { "due_at": "2026-11-01T09:00:00+03:00", "overdue": false, "label": "18 days left", "days_in_status": 3 }, "assigned_to": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "settled_on": null, "closed_on": null, "created_at": "2026-10-11T09:00:00+03:00", "events": [ { "status_from": null, "status_to": "registered", "note": null, "details": null, "user": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "occurred_at": "2026-10-11T09:00:00+03:00" } ], "documents": [ { "uuid": "77aa…", "kind": "police_abstract", "kind_label": "Police abstract", "original_name": "abstract.pdf", "mime": "application/pdf", "size": 182211, "sha256": "e3b0…", "uploaded_at": "2026-10-12T11:00:00+03:00" } ] } } } } }, "404": { "description": "Not found or not visible to this caller", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/claims/{uuid}/status": { "post": { "operationId": "post_claims_uuid_status", "tags": [ "Claims" ], "summary": "Update claim status", "description": "Moves the claim to one of `next_statuses` and/or records amounts and a note (omit `status` to keep it). Approving needs an approved amount; settling needs a paid amount and stamps the settlement date. Every call writes one timeline event.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: claims.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Claim uuid.", "examples": [ "5c2e8a1b-7f3d-4e6a-9b0c-1d2e3f4a5b6c" ] }, "description": "Claim uuid.", "example": "5c2e8a1b-7f3d-4e6a-9b0c-1d2e3f4a5b6c" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; a replay returns the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "registered", "documents_pending", "submitted_to_insurer", "under_assessment", "approved", "repudiated", "settled", "closed", "withdrawn" ] }, "note": { "type": "string" }, "amounts": { "type": "object", "properties": { "estimate": { "type": "number", "description": "Estimate in whole shillings (or `estimate_minor` in cents)." }, "reserve": { "type": "number", "description": "Reserve in whole shillings (or `reserve_minor` in cents)." }, "approved": { "type": "number", "description": "Approved in whole shillings (or `approved_minor` in cents)." }, "paid": { "type": "number", "description": "Paid in whole shillings (or `paid_minor` in cents)." }, "excess": { "type": "number", "description": "Excess in whole shillings (or `excess_minor` in cents)." }, "insurer_ref": { "type": "string", "description": "The underwriter's claim reference." } } } } }, "example": { "status": "approved", "note": "Assessor report accepted.", "amounts": { "approved": 135000 } } } } }, "responses": { "200": { "description": "Updated claim", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "5c2e8a1b-7f3d-4e6a-9b0c-1d2e3f4a5b6c", "claim_no": "CLM/2026/00012", "status": "under_assessment", "status_label": "Under assessment", "next_statuses": [ "approved", "repudiated", "documents_pending", "withdrawn" ], "claim_type": "accidental_damage", "claim_type_label": "Accidental damage", "legal": false, "legal_label": "Non Legal", "policy": { "uuid": "1a2b…", "policy_no": "SG/MP/2026/000123", "product_line": "motor" }, "client": { "client_no": "C-00042", "name": "Wanjiru Kamau" }, "insurer": { "id": 1, "name": "Savanna General" }, "risk_item": "KDA 123A", "incident_on": "2026-10-10", "reported_on": "2026-10-11", "description": "Rear bumper damaged at the Nyayo roundabout.", "claimant": { "name": null, "phone": null, "relationship": null }, "insurer_ref": "SG-CL-88812", "currency": "KES", "amounts": { "estimate": 150000, "estimate_minor": 15000000, "reserve": 140000, "reserve_minor": 14000000, "approved": 0, "approved_minor": 0, "paid": 0, "paid_minor": 0, "excess": 15000, "excess_minor": 1500000, "outstanding": 0, "outstanding_minor": 0 }, "sla": { "due_at": "2026-11-01T09:00:00+03:00", "overdue": false, "label": "18 days left", "days_in_status": 3 }, "assigned_to": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "settled_on": null, "closed_on": null, "created_at": "2026-10-11T09:00:00+03:00", "events": [ { "status_from": null, "status_to": "registered", "note": null, "details": null, "user": { "id": 2, "name": "Faith Njeri", "role": "account_exec", "code": null }, "occurred_at": "2026-10-11T09:00:00+03:00" } ], "documents": [ { "uuid": "77aa…", "kind": "police_abstract", "kind_label": "Police abstract", "original_name": "abstract.pdf", "mime": "application/pdf", "size": 182211, "sha256": "e3b0…", "uploaded_at": "2026-10-12T11:00:00+03:00" } ] } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Transition not allowed or amount missing (`domain_rule`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "claims" ] }, { "bearer": [] } ], "x-scope": "claims", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/claims/{uuid}/documents": { "post": { "operationId": "post_claims_uuid_documents", "tags": [ "Claims" ], "summary": "Attach a claim document", "description": "multipart/form-data. PDF, JPG or PNG up to 10 MB. Stored privately with a SHA-256; noted on the timeline. Closed and withdrawn claims take no more documents.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: claims.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Claim uuid.", "examples": [ "5c2e8a1b-7f3d-4e6a-9b0c-1d2e3f4a5b6c" ] }, "description": "Claim uuid.", "example": "5c2e8a1b-7f3d-4e6a-9b0c-1d2e3f4a5b6c" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. Unique per write; a replay returns the first response." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "description": "The file (binary form field)." }, "kind": { "type": "string", "enum": [ "claim_form", "police_abstract", "driving_licence", "logbook", "photos", "assessor_report", "repair_quote", "medical_report", "invoice", "discharge_voucher", "other" ] }, "note": { "type": "string" } }, "required": [ "file", "kind" ] } } } }, "responses": { "201": { "description": "Document stored", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "77aa…", "kind": "police_abstract", "kind_label": "Police abstract", "original_name": "abstract.pdf", "mime": "application/pdf", "size": 182211, "sha256": "e3b0…", "uploaded_at": "2026-10-12T11:00:00+03:00" } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Wrong file type or size, or claim finished", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "claims" ] }, { "bearer": [] } ], "x-scope": "claims", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/ipf/offers": { "get": { "operationId": "get_ipf_offers", "tags": [ "Premium finance" ], "summary": "Get finance offers for a policy", "description": "One offer per repayment period the lender offers (deposit, financed amount, interest, fees, instalment, APR) and whether this policy can apply now. A policy must be saved with premium finance as its payment mode and be awaiting payment.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: finance.", "parameters": [ { "name": "policy", "in": "query", "required": true, "schema": { "type": "string", "description": "Policy uuid." }, "description": "Policy uuid." } ], "responses": { "200": { "description": "Offers and eligibility", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "policy": { "uuid": "5d0c…", "policy_no": "POL/2026/000099", "payment_mode": "ipf", "status": "pending_payment" }, "lender": { "code": "FLEXY", "name": "Flexysure Premium Finance" }, "eligible": true, "reason": null, "gross_premium": 50000, "gross_premium_minor": 5000000, "offers": [ { "tenor_months": 6, "deposit": 10000, "deposit_minor": 1000000, "principal": 40000, "principal_minor": 4000000, "interest": 6000, "interest_minor": 600000, "fees": 500, "fees_minor": 50000, "total_repayable": 46500, "total_repayable_minor": 4650000, "instalment": 7749, "instalment_minor": 774900, "last_instalment": 7755, "last_instalment_minor": 775500, "apr_percent": 47.6 } ] } } } } }, "403": { "description": "`ipf_not_offered` (SACCO or microfinance organisation)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Unknown policy", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "finance" ] }, { "bearer": [] } ], "x-scope": "finance", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/ipf/applications": { "post": { "operationId": "post_ipf_applications", "tags": [ "Premium finance" ], "summary": "Apply for premium finance", "description": "Submits the application to Flexysure Finance, who decide in their portal. Calling this confirms the client agreed to the terms and to sharing their details with the lender; the time is recorded as `consent_at`. The application is owned by the API client's actor user (or the user who created the client).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: finance.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy": { "type": "string", "description": "Policy uuid (payment mode `ipf`, awaiting payment)." }, "tenor_months": { "type": "integer", "description": "One of the offered repayment periods.", "examples": [ 6 ] } }, "required": [ "policy", "tenor_months" ] }, "example": { "policy": "5d0c8a1e-…", "tenor_months": 6 } } } }, "responses": { "201": { "description": "Application submitted (`status: submitted`)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "0c8d6a3e-2f4b-4d0a-9f3e-6b7d1c2a9e44", "status": "submitted", "status_label": "With lender", "next_step": "Waiting for Flexysure Finance to decide.", "policy": { "uuid": "5d0c…", "policy_no": "POL/2026/000099", "risk_note_no": "RN/2026/000099" }, "client": { "client_no": "C000231", "name": "Wanjiru Kamau" }, "lender": { "code": "FLEXY", "name": "Flexysure Premium Finance" }, "tenor_months": 6, "gross_premium": 50000, "gross_premium_minor": 5000000, "deposit": 10000, "deposit_minor": 1000000, "principal": 40000, "principal_minor": 4000000, "interest": 6000, "interest_minor": 600000, "fees": 500, "fees_minor": 50000, "total_repayable": 46500, "total_repayable_minor": 4650000, "apr_percent": 47.6, "consent_at": "2026-10-14T09:00:00+03:00", "decided_at": null, "decline_reason": null, "loan_uuid": null, "loan_ref": null, "created_at": "2026-10-14T09:00:00+03:00" } } } } }, "403": { "description": "`ipf_not_offered`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Unknown policy", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Not eligible, already applied, or a period the lender does not offer (`errors.ipf` / `errors.tenor_months`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "finance" ] }, { "bearer": [] } ], "x-scope": "finance", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/ipf/applications/{uuid}": { "get": { "operationId": "get_ipf_applications_uuid", "tags": [ "Premium finance" ], "summary": "Get an application", "description": "Poll this (or subscribe to `ipf.application.decided`) to learn the lender's decision. Once signed, `loan_uuid` points at the loan.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: finance.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Application uuid." }, "description": "Application uuid." } ], "responses": { "200": { "description": "Application", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "0c8d6a3e-2f4b-4d0a-9f3e-6b7d1c2a9e44", "status": "approved", "status_label": "Approved", "next_step": "Send the signing code (POST …/otp), then sign with it (POST …/sign).", "policy": { "uuid": "5d0c…", "policy_no": "POL/2026/000099", "risk_note_no": "RN/2026/000099" }, "client": { "client_no": "C000231", "name": "Wanjiru Kamau" }, "lender": { "code": "FLEXY", "name": "Flexysure Premium Finance" }, "tenor_months": 6, "gross_premium": 50000, "gross_premium_minor": 5000000, "deposit": 10000, "deposit_minor": 1000000, "principal": 40000, "principal_minor": 4000000, "interest": 6000, "interest_minor": 600000, "fees": 500, "fees_minor": 50000, "total_repayable": 46500, "total_repayable_minor": 4650000, "apr_percent": 47.6, "consent_at": "2026-10-14T09:00:00+03:00", "decided_at": "2026-10-14T09:30:00+03:00", "decline_reason": null, "loan_uuid": null, "loan_ref": null, "created_at": "2026-10-14T09:00:00+03:00" } } } } }, "403": { "description": "`ipf_not_offered`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Unknown application", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "finance" ] }, { "bearer": [] } ], "x-scope": "finance", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/ipf/applications/{uuid}/otp": { "post": { "operationId": "post_ipf_applications_uuid_otp", "tags": [ "Premium finance" ], "summary": "Send the agreement signing code", "description": "Texts a 6-digit code to the client's phone for signing the approved agreement (charged to the SMS balance). `sent` is true only when the SMS was queued or sent; otherwise `sent: false` with `reason`. Each call replaces the previous code; it expires after `expires_in` seconds and allows 5 tries. Only a hash is stored. In the demo the code also comes back as `demo_otp`.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: finance.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Application uuid." }, "description": "Application uuid." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "responses": { "200": { "description": "`{sent: true}`, or `{sent: false, reason}` when the SMS could not go", "content": { "application/json": { "schema": { "type": "object" }, "example": { "sent": true, "message_status": "sent", "phone": "0712 345 678", "expires_in": 600, "demo_otp": "483920", "demo_note": "Demo mode: the code is returned here instead of being sent by SMS." } } } }, "403": { "description": "`ipf_not_offered`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Unknown application", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Not approved yet (`errors.ipf`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "finance" ] }, { "bearer": [] } ], "x-scope": "finance", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/ipf/applications/{uuid}/sign": { "post": { "operationId": "post_ipf_applications_uuid_sign", "tags": [ "Premium finance" ], "summary": "Sign the agreement", "description": "Checks the code and books the loan in `pending_deposit`. The signature evidence is the sha256 of the agreement text, the caller's IP and the time. Next: collect the deposit with `POST /ipf/loans/{uuid}/deposit`.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: finance.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Application uuid." }, "description": "Application uuid." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "otp": { "type": "string", "description": "The 6-digit code the client received.", "examples": [ "483920" ] } }, "required": [ "otp" ] }, "example": { "otp": "483920" } } } }, "responses": { "201": { "description": "Loan created", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "1f7e2b9c-8a3d-4e6f-b1c2-3d4e5f6a7b8c", "loan_ref": "IPF-000017", "status": "pending_deposit", "status_label": "Awaiting deposit", "application_uuid": "0c8d6a3e-…", "policy": { "uuid": "5d0c…", "policy_no": "POL/2026/000099", "status": "active" }, "client": { "client_no": "C000231", "name": "Wanjiru Kamau" }, "lender": { "code": "FLEXY", "name": "Flexysure Premium Finance", "paybill": "700100" }, "repay_to": { "paybill": "700100", "account": "IPF-000017" }, "tenor_months": 6, "apr_percent": 47.6, "total_repayable": 46500, "total_repayable_minor": 4650000, "repaid": 0, "repaid_minor": 0, "outstanding": 38751, "outstanding_minor": 3875100, "principal_outstanding": 33334, "principal_outstanding_minor": 3333400, "repaid_split": { "fees": 83, "fees_minor": 8300, "interest": 1000, "interest_minor": 100000, "principal": 6666, "principal_minor": 666600 }, "arrears": 0, "arrears_minor": 0, "arrears_days": 0, "next_due": null, "schedule": [], "links": { "agreement": "https://app.flexysure.com/api/v1/ipf/loans/1f7e…/agreement" } } } } } }, "403": { "description": "`ipf_not_offered`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Unknown application", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Wrong or expired code, tries left in the message (`errors.otp`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "finance" ] }, { "bearer": [] } ], "x-scope": "finance", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/ipf/loans/{uuid}": { "get": { "operationId": "get_ipf_loans_uuid", "tags": [ "Premium finance" ], "summary": "Get a loan", "description": "Terms, repayment schedule, what has been repaid (split fees, then interest, then principal inside each instalment), what is outstanding, arrears and how many days the oldest missed instalment is late. The schedule appears once Flexysure Finance has paid the underwriter.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: finance.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Loan uuid." }, "description": "Loan uuid." } ], "responses": { "200": { "description": "Loan", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "1f7e2b9c-8a3d-4e6f-b1c2-3d4e5f6a7b8c", "loan_ref": "IPF-000017", "status": "active", "status_label": "Active", "application_uuid": "0c8d6a3e-…", "policy": { "uuid": "5d0c…", "policy_no": "POL/2026/000099", "status": "active" }, "client": { "client_no": "C000231", "name": "Wanjiru Kamau" }, "lender": { "code": "FLEXY", "name": "Flexysure Premium Finance", "paybill": "700100" }, "repay_to": { "paybill": "700100", "account": "IPF-000017" }, "tenor_months": 6, "apr_percent": 47.6, "total_repayable": 46500, "total_repayable_minor": 4650000, "repaid": 7749, "repaid_minor": 774900, "outstanding": 38751, "outstanding_minor": 3875100, "principal_outstanding": 33334, "principal_outstanding_minor": 3333400, "repaid_split": { "fees": 83, "fees_minor": 8300, "interest": 1000, "interest_minor": 100000, "principal": 6666, "principal_minor": 666600 }, "arrears": 0, "arrears_minor": 0, "arrears_days": 0, "next_due": { "seq": 2, "due_on": "2026-12-14", "amount": 7749, "amount_minor": 774900 }, "schedule": [ { "seq": 1, "due_on": "2026-11-14", "principal": 6666, "principal_minor": 666600, "interest": 1000, "interest_minor": 100000, "fees": 83, "fees_minor": 8300, "amount_due": 7749, "amount_due_minor": 774900, "amount_paid": 7749, "amount_paid_minor": 774900, "status": "paid" } ], "links": { "agreement": "https://app.flexysure.com/api/v1/ipf/loans/1f7e…/agreement" } } } } } }, "403": { "description": "`ipf_not_offered`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Unknown loan", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "finance" ] }, { "bearer": [] } ], "x-scope": "finance", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/ipf/loans/{uuid}/agreement": { "get": { "operationId": "get_ipf_loans_uuid_agreement", "tags": [ "Premium finance" ], "summary": "Download the signed agreement", "description": "The agreement the client signed as a one-page PDF (`application/pdf`), with the e-signature record: time, document fingerprint and IP.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: finance.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Loan uuid." }, "description": "Loan uuid." } ], "responses": { "200": { "description": "PDF file", "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf" } } } }, "403": { "description": "`ipf_not_offered`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Unknown loan", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "finance" ] }, { "bearer": [] } ], "x-scope": "finance", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/ipf/loans/{uuid}/deposit": { "post": { "operationId": "post_ipf_loans_uuid_deposit", "tags": [ "Premium finance" ], "summary": "Collect the deposit by M-Pesa", "description": "Sends an STK push for the deposit (purpose `ipf_deposit`). When the customer pays, the receipt is allocated to the policy's debit note and the loan moves to `pending_disbursement`; cover starts after Flexysure Finance pays the underwriter. Poll with `GET /payment/stk/{uuid}`.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: finance.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Loan uuid." }, "description": "Loan uuid." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "07XXXXXXXX or 2547XXXXXXXX.", "examples": [ "0712345678" ] } }, "required": [ "phone" ] }, "example": { "phone": "0712345678" } } } }, "responses": { "200": { "description": "Prompt sent (same shape as `POST /payment/stk/push`)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "merchant_request_id": "29115-34620561-1", "checkout_request_id": "ws_CO_14102026101500123", "stk_request_uuid": "9b2f…", "status": "pending", "purpose": "ipf_deposit", "account": "DN-000099", "amount": 10000, "amount_minor": 1000000, "ipf_loan_ref": "IPF-000017" } } } }, "403": { "description": "`ipf_not_offered`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Unknown loan", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`deposit_not_due` or `payment_refused`. No money moved.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "finance" ] }, { "bearer": [] } ], "x-scope": "finance", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/ipf/loans/{uuid}/early-settlement": { "post": { "operationId": "post_ipf_loans_uuid_early_settlement", "tags": [ "Premium finance" ], "summary": "Quote or start early settlement", "description": "With `?quote=1`: the payoff figure for today and nothing else. Without it: the same quote plus an STK push for the payoff amount (`phone` required). Payoff rule: unpaid principal on every instalment, plus unpaid interest and fees on instalments already due (due date on or before today), plus interest on the current instalment accrued pro rata by days from the previous due date (or one month before the first) to today. Interest and fees on later instalments are waived. Rounded up to the shilling, never more than the contractual outstanding balance, valid today only. Use a new Idempotency-Key for each quote. When the customer pays the prompt (purpose `ipf_settlement`), the payoff is recomputed for the payment date: paying at least that much closes the loan (`status` `closed`), the remaining interest and fees are waived (schedule lines `waived`), anything above the payoff is kept as a borrower credit, and the loan timeline shows \"Settled early\". Paying less than the payoff counts as an ordinary instalment and the loan stays open. Poll `GET /payment/stk/{uuid}` and `GET /ipf/loans/{uuid}`.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: finance.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Loan uuid." }, "description": "Loan uuid." }, { "name": "quote", "in": "query", "required": false, "schema": { "type": "boolean", "description": "`1` to get the payoff figure without sending a prompt." }, "description": "`1` to get the payoff figure without sending a prompt." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Required unless `quote=1`. 07XXXXXXXX or 2547XXXXXXXX.", "examples": [ "0712345678" ] } } } } } }, "responses": { "200": { "description": "Quote (`data`), and `stk` when a prompt was sent", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "loan_ref": "IPF-000017", "as_of": "2026-12-01", "payoff": 34200, "payoff_minor": 3420000, "principal": 33334, "principal_minor": 3333400, "interest_accrued": 866, "interest_accrued_minor": 86600, "fees_due": 0, "fees_due_minor": 0, "outstanding": 38750, "outstanding_minor": 3875000, "waived": 4550, "waived_minor": 455000, "rule": "Unpaid principal + interest and fees on instalments already due + interest accrued pro rata on the current instalment to today; later interest and fees are waived. Valid today only." } } } } }, "403": { "description": "`ipf_not_offered`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Unknown loan", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`not_settleable` (loan not running), `validation_failed` (`phone` missing without `quote=1`) or `payment_refused`. No money moved.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "finance" ] }, { "bearer": [] } ], "x-scope": "finance", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/erp/clients": { "get": { "operationId": "get_erp_clients", "tags": [ "ERP exports" ], "summary": "Export clients", "description": "Rate limit: 5 requests per minute per API client (Insurance Cloud parity), on top of the platform limit. Scope: read.", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 1." }, "description": "Default 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 15, max 100." }, "description": "Default 15, max 100." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Clients", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "clients": [ { "id": 42, "client_no": "C-00042", "name": "Wanjiru Kamau", "phone": "0712345678", "email": "wanjiru@example.com", "idno": "27845123", "pin": "A001234567Z", "sales_person": "Kevin Kiprop", "agents": [ { "id": 4, "name": "Kevin Kiprop", "code": "KK01" } ] } ], "meta": { "current_page": 1, "per_page": 15, "total": 1, "last_page": 1 }, "links": { "next": null, "prev": null } } } } }, "429": { "description": "More than 5 calls in a minute", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "5 requests per minute per API client (Insurance Cloud parity), on top of the platform limit", "x-idempotent": false, "x-flexysure-only": false } }, "/erp/policies": { "get": { "operationId": "get_erp_policies", "tags": [ "ERP exports" ], "summary": "Export policies", "description": "Status mapping: 1 = active (`active`); 0 = inactive (awaiting payment, cancelled, expired, renewed, void); 2 = all (default). In the response `status` is 1 or 0 and `status_label` carries Flexysure's status. `starting`/`ending` filter on the cover start date. `transaction` is \"New business\" or \"Renewal\"; `receipted` is what has been paid against the policy's debit notes and `balance` what is still owed.\n\nRate limit: 5 requests per minute per API client (Insurance Cloud parity), on top of the platform limit. Scope: read.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "0 inactive, 1 active, 2 all (default)." }, "description": "0 inactive, 1 active, 2 all (default)." }, { "name": "starting", "in": "query", "required": false, "schema": { "type": "string", "description": "Cover starting on or after (Y-m-d)." }, "description": "Cover starting on or after (Y-m-d)." }, { "name": "ending", "in": "query", "required": false, "schema": { "type": "string", "description": "Cover starting on or before (Y-m-d)." }, "description": "Cover starting on or before (Y-m-d)." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 1." }, "description": "Default 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 15, max 100." }, "description": "Default 15, max 100." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Policies", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "policies": [ { "id": 123, "uuid": "1a2b…", "status": 1, "status_label": "Active", "transaction": "New business", "policy_no": "SG/MP/2026/000123", "product_id": null, "insurer": "Savanna General", "client": "Wanjiru Kamau", "client_no": "C-00042", "product": "Comprehensive", "product_line": "motor", "start_date": "2026-10-14", "end_date": "2027-10-13", "risk_note": "RN-00123", "premium": 35587, "receipted": 35587, "balance": 0, "sales_person": "Kevin Kiprop", "agents": [ { "id": 4, "name": "Kevin Kiprop", "code": "KK01" } ] } ], "meta": { "current_page": 1, "per_page": 15, "total": 1, "last_page": 1 }, "links": { "next": null, "prev": null } } } } }, "429": { "description": "More than 5 calls in a minute", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "5 requests per minute per API client (Insurance Cloud parity), on top of the platform limit", "x-idempotent": false, "x-flexysure-only": false } }, "/erp/claims": { "get": { "operationId": "get_erp_claims", "tags": [ "ERP exports" ], "summary": "Export claims", "description": "`claim_type` is Insurance Cloud's Legal / Non Legal; `cause` is the kind of loss. `starting`/`ending` filter on the reported date. `claim_amount` is the estimate, `paid_amount` what has been paid.\n\nRate limit: 5 requests per minute per API client (Insurance Cloud parity), on top of the platform limit. Scope: read.", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "Legal", "Non Legal" ] } }, { "name": "starting", "in": "query", "required": false, "schema": { "type": "string", "description": "Reported on or after (Y-m-d)." }, "description": "Reported on or after (Y-m-d)." }, { "name": "ending", "in": "query", "required": false, "schema": { "type": "string", "description": "Reported on or before (Y-m-d)." }, "description": "Reported on or before (Y-m-d)." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 1." }, "description": "Default 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 20, max 100." }, "description": "Default 20, max 100." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "responses": { "200": { "description": "Claims", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "claims": [ { "id": 12, "uuid": "5c2e…", "claim_no": "CLM/2026/00012", "policy_no": "SG/MP/2026/000123", "incident_date": "2026-10-10", "claim_type": "Non Legal", "cause": "Accidental damage", "product": "Motor", "item": "KDA 123A", "status": "Under assessment", "client": { "name": "Wanjiru Kamau", "client_no": "C-00042" }, "insurer": "Savanna General", "currency": "KES", "claim_amount": 150000, "paid_amount": 0, "sales_person": "Kevin Kiprop", "agents": [ { "id": 4, "name": "Kevin Kiprop", "code": "KK01" } ] } ], "meta": { "current_page": 1, "per_page": 20, "total": 1, "last_page": 1 }, "links": { "next": null, "prev": null } } } } }, "429": { "description": "More than 5 calls in a minute", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "read" ] }, { "bearer": [] } ], "x-scope": "read", "x-rate-limit": "5 requests per minute per API client (Insurance Cloud parity), on top of the platform limit", "x-idempotent": false, "x-flexysure-only": false } }, "/client/login": { "post": { "operationId": "post_client_login", "tags": [ "Client area" ], "summary": "Request a sign-in code", "description": "Send the email or phone saved on the client record (or its login). If both are sent both must match the same account. The same six-digit code goes by SMS and email and expires after 5 minutes. No bearer token is needed; when the same contact is a client of more than one organisation, send the organisation's bearer token to choose. The answer never reveals whether an account exists: unknown, disabled or (without a token) ambiguous contacts get the same 200 body, and `channels` is always `[\"email\", \"sms\"]`, but no code is sent and the `otp_id` never verifies.\n\nRate limit: 3 codes per 5 minutes per identifier and per account.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Saved email (max 255). Required without phone.", "examples": [ "jane@example.com" ] }, "phone": { "type": "string", "description": "Saved phone (max 50). Required without email.", "examples": [ "0712345678" ] } } }, "example": { "email": "jane@example.com" } } } }, "responses": { "200": { "description": "Code sent (the same body for contacts that cannot sign in)", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "message": "OTP sent successfully", "otp_id": "9b1f…", "expires_in": 300, "channels": [ "email", "sms" ] } } } }, "403": { "description": "Insecure request (`https_required`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "409": { "description": "With a bearer token: the contact is on several clients of that organisation (`ambiguous_client`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "429": { "description": "More than 3 codes in 5 minutes for this identifier or account", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [], "x-scope": null, "x-rate-limit": "3 codes per 5 minutes per identifier and per account", "x-idempotent": false, "x-flexysure-only": false } }, "/client/verify-otp": { "post": { "operationId": "post_client_verify_otp", "tags": [ "Client area" ], "summary": "Verify the code and get the client key", "description": "Consumes the code and returns the user with `client_no` and a new `client_key`, which replaces any earlier key. Five wrong codes exhaust the request; ask for a new code.\n\nRate limit: 60 requests per minute per token (per-client override).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "otp_id": { "type": "string", "description": "UUID from login." }, "otp": { "type": "string", "description": "The six-digit code.", "examples": [ "123456" ] } }, "required": [ "otp_id", "otp" ] }, "example": { "otp_id": "9b1f…", "otp": "123456" } } } }, "responses": { "200": { "description": "Signed in", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "message": "Login successful", "user": { "name": "Jane Doe", "email": "jane@example.com", "phone": "0712345678", "department_id": null, "department": null, "company": null, "client_no": "C-00042", "national_id": "12345678", "kra_pin": "A012345678Z", "client_key": "fxck_…", "is_admin": true, "risk_manager_id": 2 } } } } }, "403": { "description": "Locked or disabled account; insecure request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Wrong, expired or used code (`invalid_otp`, with `attempts_left`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "429": { "description": "Attempts exhausted (`otp_attempts_exhausted`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [], "x-scope": null, "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/logout": { "post": { "operationId": "post_client_logout", "tags": [ "Client area" ], "summary": "Sign out (revoke the client key)", "description": "Rate limit: 60 requests per minute per token (per-client override).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_no": { "type": "string", "description": "Client number." }, "client_key": { "type": "string", "description": "The key to revoke." } }, "required": [ "client_no", "client_key" ] }, "example": { "client_no": "C-00042", "client_key": "fxck_…" } } } }, "responses": { "200": { "description": "Signed out", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "message": "Logout successful" } } } }, "403": { "description": "Insecure request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input, or invalid or already revoked key (`invalid_client_credentials`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [], "x-scope": null, "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/register": { "post": { "operationId": "post_client_register", "tags": [ "Client area" ], "summary": "Register a client with its own login", "description": "Creates an individual or corporate client in the token's organisation, a customer login for the contact and a client key. For a corporate client the company is the client and the contact is its login. An existing login with that email, or a client with that ID number or KRA PIN, returns 403: sign in by code instead.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: portal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "individual", "corporate" ], "description": "Client type." }, "company": { "type": "object", "properties": { "name": { "type": "string", "description": "Max 255." }, "phone": { "type": "string", "description": "Max 50." }, "email": { "type": "string", "description": "Max 255." }, "kra_pin": { "type": "string", "description": "Max 50." } }, "required": [ "name", "phone", "email", "kra_pin" ], "description": "Required for corporate." }, "contact": { "type": "object", "properties": { "name": { "type": "string", "description": "Max 255." }, "phone": { "type": "string", "description": "Max 50." }, "email": { "type": "string", "description": "Max 255; becomes the login." }, "id_no": { "type": "string", "description": "Required for individual. Max 50." }, "kra_pin": { "type": "string", "description": "Optional. Max 50." }, "password": { "type": "string", "description": "At least 8 characters (for the web customer portal)." } }, "required": [ "name", "phone", "email", "password" ], "description": "The person who signs in." } }, "required": [ "type", "contact" ] }, "example": { "type": "individual", "contact": { "name": "Jane Doe", "phone": "0712345678", "email": "jane@example.com", "id_no": "12345678", "password": "secret123" } } } } }, "responses": { "201": { "description": "Client, login and key created", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "client": { "id": 42, "client_no": "C-00042", "client_name": "Jane Doe" }, "user": { "name": "Jane Doe", "email": "jane@example.com", "phone": "0712345678", "department_id": null, "department": null, "company": null, "client_no": "C-00042", "national_id": "12345678", "kra_pin": "A012345678Z", "client_key": "fxck_…", "is_admin": true, "risk_manager_id": 2 } } } } }, "403": { "description": "Account already exists (`account_exists`); insecure request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ] }, { "bearer": [] } ], "x-scope": "portal", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/details": { "get": { "operationId": "get_client_details", "tags": [ "Client area" ], "summary": "Client details and documents", "description": "Rate limit: 5 requests per minute per client (per client and policy on the detail). Scope: portal.", "responses": { "200": { "description": "Client and KYC documents", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "client": { "id": 42, "client_no": "C-00042", "client_name": "Jane Doe", "email": "jane@example.com", "mobile": "0712345678", "pin": "A012345678Z", "national_id": "12345678" }, "client_documents": [ { "id": "5d0c…", "name": "National ID", "url": "https://…/api/v1/client/files/kyc/5d0c…?expires=…&signature=…", "download_url": "https://…&download=1…" } ] } } } }, "400": { "description": "Insecure (non-HTTPS) request (`https_required`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input, or `invalid_client_credentials` (unknown, revoked or other-organisation client key)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ], "clientNo": [], "clientKey": [] }, { "bearer": [], "clientNo": [], "clientKey": [] } ], "x-scope": "portal", "x-rate-limit": "5 requests per minute per client (per client and policy on the detail)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/policies": { "post": { "operationId": "post_client_policies", "tags": [ "Client area" ], "summary": "List the client's policies", "description": "Paginated. Later pages are POSTed to the same URL with the same filters and `page` (the links are not GET endpoints).\n\nRate limit: 5 requests per minute per client (per client and policy on the detail). Scope: portal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "1 active, 0 any other status, 2 all." }, "insurer_id": { "type": "integer", "description": "One underwriter." }, "product_id": { "type": "integer", "description": "One standard product; takes precedence over exclude_product_ids." }, "exclude_product_ids": { "type": "array", "items": { "type": "integer" }, "description": "Products to leave out." }, "starting": { "type": "string", "description": "Y-m-d. With ending: policies starting in the window." }, "ending": { "type": "string", "description": "Y-m-d, on or after starting." }, "page": { "type": "integer", "description": "Default 1." }, "per_page": { "type": "integer", "description": "1–100, default 15." } }, "required": [ "status" ] }, "example": { "status": 2, "page": 1, "per_page": 15 } } } }, "responses": { "200": { "description": "Policies with meta and links", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "policies": [ { "id": 125, "status": 1, "transaction": "New Business", "policy_no": "POL-001", "product_id": null, "insurer": "Savanna General", "client": "Jane Doe", "product": "MOTOR", "sub_cover": "Comprehensive", "currency": "KES", "start_date": "2026-09-01", "end_date": "2027-08-31", "sales_type": "Cash", "risk_note": "RN-00001", "sum_insured": 1000000, "premium": 50000, "receipted": 20000, "balance": 30000 } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 15, "total": 1 }, "links": { "first": "https://…/api/v1/client/policies?page=1", "prev": null, "next": null, "last": "https://…/api/v1/client/policies?page=1" } } } } }, "400": { "description": "Insecure (non-HTTPS) request (`https_required`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input, or `invalid_client_credentials` (unknown, revoked or other-organisation client key)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ], "clientNo": [], "clientKey": [] }, { "bearer": [], "clientNo": [], "clientKey": [] } ], "x-scope": "portal", "x-rate-limit": "5 requests per minute per client (per client and policy on the detail)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/policies/all": { "post": { "operationId": "post_client_policies_all", "tags": [ "Client area" ], "summary": "List all the client's policies (no pagination)", "description": "Same filters as the paginated list, without `page` and `per_page`. At most 500 policies, newest first; `truncated` is true when there were more (page through POST /client/policies instead).\n\nRate limit: 5 requests per minute per client (per client and policy on the detail). Scope: portal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 0, 1, 2 ], "description": "1 active, 0 any other status, 2 all." }, "insurer_id": { "type": "integer", "description": "One underwriter." }, "product_id": { "type": "integer", "description": "One standard product." }, "exclude_product_ids": { "type": "array", "items": { "type": "integer" }, "description": "Products to leave out." }, "starting": { "type": "string", "description": "Y-m-d." }, "ending": { "type": "string", "description": "Y-m-d." } }, "required": [ "status" ] }, "example": { "status": 1 } } } }, "responses": { "200": { "description": "Policies", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "policies": [ { "id": 125, "status": 1, "transaction": "New Business", "policy_no": "POL-001", "product_id": null, "insurer": "Savanna General", "client": "Jane Doe", "product": "MOTOR", "sub_cover": "Comprehensive", "currency": "KES", "start_date": "2026-09-01", "end_date": "2027-08-31", "sales_type": "Cash", "risk_note": "RN-00001", "sum_insured": 1000000, "premium": 50000, "receipted": 20000, "balance": 30000 } ], "truncated": false } } } }, "400": { "description": "Insecure (non-HTTPS) request (`https_required`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input, or `invalid_client_credentials` (unknown, revoked or other-organisation client key)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ], "clientNo": [], "clientKey": [] }, { "bearer": [], "clientNo": [], "clientKey": [] } ], "x-scope": "portal", "x-rate-limit": "5 requests per minute per client (per client and policy on the detail)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/policy/{id}": { "get": { "operationId": "get_client_policy_id", "tags": [ "Client area" ], "summary": "Policy detail", "description": "Totals, receipt allocations (with receipt PDFs), vehicles, claims, documents (risk note, invoices, motor certificates) and the client's KYC documents. Document links are temporary signed URLs valid for 30 minutes. `marine_dmvic` is always null (Flexysure has no marine line).\n\nRate limit: 5 requests per minute per client (per client and policy on the detail). Scope: portal.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "description": "Policy id from the policies list.", "examples": [ 125 ] }, "description": "Policy id from the policies list.", "example": 125 } ], "responses": { "200": { "description": "Policy", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "policy": { "id": 125, "status": 1, "transaction": "New Business", "policy_no": "POL-001", "product_id": null, "insurer": "Savanna General", "client": "Jane Doe", "product": "MOTOR", "sub_cover": "Comprehensive", "currency": "KES", "start_date": "2026-09-01", "end_date": "2027-08-31", "sales_type": "Cash", "risk_note": "RN-00001", "sum_insured": 1000000, "premium": 50000, "receipted": 20000, "balance": 30000, "marine_dmvic": null, "risk_note_link": "https://…/risk-note?expires=…&signature=…", "invoice_link": "https://…/debit-notes/77?expires=…", "receipt_allocations": [ { "amount": 20000, "reference": "RCT-00012", "auth_date": "2026-09-01 10:02:11", "receipt_url": "https://…/receipts/12?expires=…" } ], "vehicles": [ { "id": 9, "reg_no": "KDA 123A", "make": "Toyota", "model": "Axio", "year": 2018, "chassis_no": "NZE161-…", "engine_no": "1NZ-…", "body_type": "Saloon", "value": 1000000 } ], "claims": [], "policy_documents": [ { "id": "risk-note-125", "name": "Risk note RN-00001", "source": "system", "url": "https://…" } ], "client_documents": [] } } } } }, "404": { "description": "Not this client's policy (unknown ids and other clients' or organisations' policies answer the same)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "An id that is not a number, or invalid client credentials", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "400": { "description": "Insecure (non-HTTPS) request (`https_required`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ], "clientNo": [], "clientKey": [] }, { "bearer": [], "clientNo": [], "clientKey": [] } ], "x-scope": "portal", "x-rate-limit": "5 requests per minute per client (per client and policy on the detail)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/statement": { "post": { "operationId": "post_client_statement", "tags": [ "Client area" ], "summary": "Statement of account", "description": "Read from the ledger (client receivables): billed amounts are debits; receipts, premium-finance funding and credit notes are credits. The first row is the opening balance; each row carries the running balance; zero debit or credit cells are empty strings. A statement covers at most 366 days (422 `range_too_long`).\n\nRate limit: 10 requests per minute per client. Scope: portal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "starting": { "type": "string", "description": "Y-m-d.", "examples": [ "2026-01-01" ] }, "ending": { "type": "string", "description": "Y-m-d, on or after starting, at most 366 days in all.", "examples": [ "2026-12-31" ] } }, "required": [ "starting", "ending" ] }, "example": { "starting": "2026-01-01", "ending": "2026-12-31" } } } }, "responses": { "200": { "description": "Statement", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "client": "Jane Doe", "client_no": "C-00042", "starting": "2026-01-01", "ending": "2026-12-31", "opening_balance": 0, "closing_balance": 30000, "total_debit": 50000, "total_credit": 20000, "statement": [ { "date": "2026-01-01", "reference": "", "insurer_ref": "", "transaction": "", "insurer": "", "policy_no": "", "narration": "Opening Balance", "dr": "", "cr": "", "balance": 0 }, { "date": "2026-09-01", "reference": "DN-00077", "insurer_ref": "", "transaction": "Debit note", "insurer": "Savanna General", "policy_no": "POL-001", "narration": "Debit note raised DN-00077 for POL-001", "dr": 50000, "cr": "", "balance": 50000 }, { "date": "2026-09-01", "reference": "RCT-00012", "insurer_ref": "", "transaction": "Receipt", "insurer": "Savanna General", "policy_no": "POL-001", "narration": "Receipt RCT-00012 allocated to DN-00077", "dr": "", "cr": 20000, "balance": 30000 } ] } } } }, "400": { "description": "Insecure (non-HTTPS) request (`https_required`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input, or `invalid_client_credentials` (unknown, revoked or other-organisation client key)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ], "clientNo": [], "clientKey": [] }, { "bearer": [], "clientNo": [], "clientKey": [] } ], "x-scope": "portal", "x-rate-limit": "10 requests per minute per client", "x-idempotent": false, "x-flexysure-only": false } }, "/client/loans": { "get": { "operationId": "get_client_loans", "tags": [ "Client area" ], "summary": "Premium-finance loans", "description": "Rate limit: 60 requests per minute per token (per-client override). Scope: portal.", "responses": { "200": { "description": "Loans", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "uuid": "1c2d…", "loan_ref": "IPF-00003", "status": "active", "status_label": "Active", "policy_id": 125, "policy_no": "POL-001", "lender": "Flexysure Premium Finance", "currency": "KES", "principal_minor": 4000000, "total_repayable_minor": 4650000, "repaid_minor": 775000, "balance_minor": 3875000, "arrears_minor": 0, "tenor_months": 6, "next_due": { "date": "2026-11-14", "amount_minor": 775000 } } ] } } } }, "400": { "description": "Insecure (non-HTTPS) request (`https_required`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input, or `invalid_client_credentials` (unknown, revoked or other-organisation client key)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ], "clientNo": [], "clientKey": [] }, { "bearer": [], "clientNo": [], "clientKey": [] } ], "x-scope": "portal", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/client/loans/{uuid}": { "get": { "operationId": "get_client_loans_uuid", "tags": [ "Client area" ], "summary": "Premium-finance loan with schedule", "description": "Rate limit: 60 requests per minute per token (per-client override). Scope: portal.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Loan uuid." }, "description": "Loan uuid." } ], "responses": { "200": { "description": "Loan, schedule and repayments", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "uuid": "1c2d…", "loan_ref": "IPF-00003", "balance_minor": 3875000, "schedule": [ { "seq": 1, "due_on": "2026-11-14", "amount_due_minor": 775000, "amount_paid_minor": 0, "status": "due" } ], "repayments": [] } } } } }, "404": { "description": "Not this client's loan", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "400": { "description": "Insecure (non-HTTPS) request (`https_required`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input, or `invalid_client_credentials` (unknown, revoked or other-organisation client key)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ], "clientNo": [], "clientKey": [] }, { "bearer": [], "clientNo": [], "clientKey": [] } ], "x-scope": "portal", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/client/policy/{id}/pay": { "post": { "operationId": "post_client_policy_id_pay", "tags": [ "Client area" ], "summary": "Pay a policy by M-Pesa", "description": "Sends an STK push for the earliest open debit note of the policy (for a premium-finance policy awaiting its deposit, the deposit). `amount` is in shillings and defaults to what is outstanding on that note. The payment is confirmed by the M-Pesa callback; watch the policy or the `payment.*` webhooks.\n\nRate limit: 5 requests per minute per client (per client and policy on the detail). Scope: portal.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "description": "Policy id." }, "description": "Policy id." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Safaricom number to prompt.", "examples": [ "0712345678" ] }, "amount": { "type": "number", "description": "Shillings; at most the outstanding amount." } }, "required": [ "phone" ] }, "example": { "phone": "0712345678" } } } }, "responses": { "202": { "description": "Prompt sent", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "stk_request_id": 31, "merchant_request_id": "29115-…", "checkout_request_id": "ws_CO_…", "purpose": "premium", "account": "DN-00077", "phone": "254712345678", "amount_minor": 3000000, "status": "pending", "message": "Check your phone and enter your M-Pesa PIN to pay." } } } } }, "404": { "description": "Not this client's policy (or no such policy)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Nothing to pay, amount too high, invalid phone, or an id that is not a number", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ], "clientNo": [], "clientKey": [] }, { "bearer": [], "clientNo": [], "clientKey": [] } ], "x-scope": "portal", "x-rate-limit": "5 requests per minute per client (per client and policy on the detail)", "x-idempotent": true, "x-flexysure-only": true } }, "/client/claims": { "get": { "operationId": "get_client_claims", "tags": [ "Client area" ], "summary": "The client's claims", "description": "Cursor pagination (`limit`, `cursor`) or `page` / `per_page`.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: portal.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "1–100, default 25." }, "description": "1–100, default 25." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "From links.next." }, "description": "From links.next." } ], "responses": { "200": { "description": "Claims", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "7a1e…", "claim_no": "CLM/2026/00004", "policy_id": 125, "policy_no": "POL-001", "status": "registered", "status_label": "Registered", "type": "Accidental damage", "legal": "Non Legal", "item": "KDA 123A", "incident_date": "2026-10-01", "estimate": 80000, "narration": "Rear-ended at a junction." } ], "meta": { "limit": 25, "has_more": false, "count": 1 }, "links": { "next": null } } } } }, "400": { "description": "Insecure (non-HTTPS) request (`https_required`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input, or `invalid_client_credentials` (unknown, revoked or other-organisation client key)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ], "clientNo": [], "clientKey": [] }, { "bearer": [], "clientNo": [], "clientKey": [] } ], "x-scope": "portal", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true }, "post": { "operationId": "post_client_claims", "tags": [ "Client area" ], "summary": "Lodge a claim", "description": "Registers a claim on one of the client's policies (active, expired or cancelled; the incident must fall inside the cover period). The broker's claims team takes it from there.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: portal.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_id": { "type": "integer", "description": "Policy id." }, "claim_type": { "type": "string", "enum": [ "accidental_damage", "theft", "third_party", "medical", "travel", "death", "disability", "other" ], "description": "Kind of loss." }, "incident_on": { "type": "string", "description": "Y-m-d, inside the cover period, not in the future." }, "description": { "type": "string", "description": "What happened." }, "risk_item": { "type": "string", "description": "Defaults to the vehicle registration on motor policies." }, "claimant_name": { "type": "string", "description": "Defaults to the client." }, "claimant_phone": { "type": "string", "description": "Defaults to the client's phone." }, "claimant_relationship": { "type": "string", "description": "self, driver, spouse, relative, employee, third_party…" }, "estimate": { "type": "number", "description": "Estimated loss in shillings." } }, "required": [ "policy_id", "claim_type", "incident_on", "description" ] }, "example": { "policy_id": 125, "claim_type": "accidental_damage", "incident_on": "2026-10-01", "description": "Rear-ended at a junction.", "estimate": 80000 } } } }, "responses": { "201": { "description": "Claim registered", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "7a1e…", "claim_no": "CLM/2026/00004", "status": "registered" } } } } }, "404": { "description": "Not this client's policy", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "Invalid input or a claims rule (`domain_rule`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "401": { "description": "Missing or invalid bearer token", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "portal" ], "clientNo": [], "clientKey": [] }, { "bearer": [], "clientNo": [], "clientKey": [] } ], "x-scope": "portal", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/client/files/kyc/{uuid}": { "get": { "operationId": "get_client_files_kyc_uuid", "tags": [ "Client area" ], "summary": "Client document (signed link)", "description": "Temporary signed URL (30 minutes). No headers needed; an expired or altered link returns 403. Add `download=1` (already part of `download_url`) to download instead of viewing.\n\nRate limit: 60 requests per minute per token (per-client override).", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "Document id." }, "description": "Document id." } ], "responses": { "200": { "description": "The file", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Expired or invalid signature", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [], "x-scope": null, "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/files/policies/{policy}/risk-note": { "get": { "operationId": "get_client_files_policies_policy_risk_note", "tags": [ "Client area" ], "summary": "Risk note PDF (signed link)", "description": "Temporary signed URL (30 minutes). No headers needed; an expired or altered link returns 403.\n\nRate limit: 60 requests per minute per token (per-client override).", "parameters": [ { "name": "policy", "in": "path", "required": true, "schema": { "type": "string", "description": "Policy uuid." }, "description": "Policy uuid." } ], "responses": { "200": { "description": "PDF", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Expired or invalid signature", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [], "x-scope": null, "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/files/debit-notes/{note}": { "get": { "operationId": "get_client_files_debit_notes_note", "tags": [ "Client area" ], "summary": "Invoice or credit note PDF (signed link)", "description": "Temporary signed URL (30 minutes). No headers needed; an expired or altered link returns 403.\n\nRate limit: 60 requests per minute per token (per-client override).", "parameters": [ { "name": "note", "in": "path", "required": true, "schema": { "type": "integer", "description": "Debit note id." }, "description": "Debit note id." } ], "responses": { "200": { "description": "PDF", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Expired or invalid signature", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [], "x-scope": null, "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/files/receipts/{receipt}": { "get": { "operationId": "get_client_files_receipts_receipt", "tags": [ "Client area" ], "summary": "Receipt PDF (signed link)", "description": "Temporary signed URL (30 minutes). No headers needed; an expired or altered link returns 403.\n\nRate limit: 60 requests per minute per token (per-client override).", "parameters": [ { "name": "receipt", "in": "path", "required": true, "schema": { "type": "integer", "description": "Receipt id." }, "description": "Receipt id." } ], "responses": { "200": { "description": "PDF", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Expired or invalid signature", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [], "x-scope": null, "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/client/files/certificates/{certificate}": { "get": { "operationId": "get_client_files_certificates_certificate", "tags": [ "Client area" ], "summary": "Motor certificate PDF (signed link)", "description": "Temporary signed URL (30 minutes). No headers needed; an expired or altered link returns 403.\n\nRate limit: 60 requests per minute per token (per-client override).", "parameters": [ { "name": "certificate", "in": "path", "required": true, "schema": { "type": "integer", "description": "Certificate id." }, "description": "Certificate id." } ], "responses": { "200": { "description": "PDF", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Expired or invalid signature", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [], "x-scope": null, "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/dmvic": { "post": { "operationId": "post_dmvic", "tags": [ "Motor certificates (DMVIC)" ], "summary": "Issue certificates for a risk note", "description": "Issues the next eligible certificate stage for each listed vehicle on the policy. `start_date` and `expiring` must fall inside the policy cover; the certificate period itself follows the paid stage. Repeating the call for an issued stage returns the existing certificate. `email` and `phone` are accepted for Insurance Cloud compatibility.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: certificate.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "risknote": { "type": "string", "description": "Risk note number (policy number also accepted).", "examples": [ "RN/2026/000123" ] }, "email": { "type": "string", "description": "Policyholder email." }, "phone": { "type": "string", "description": "Policyholder phone." }, "vehicles": { "type": "array", "items": { "type": "object", "properties": { "registration": { "type": "string", "examples": [ "KDA 123A" ] }, "start_date": { "type": "string", "examples": [ "2026-10-14" ] }, "expiring": { "type": "string", "examples": [ "2027-10-13" ] } }, "required": [ "registration", "start_date", "expiring" ] }, "description": "Vehicles on the risk note to certify." } }, "required": [ "risknote", "vehicles" ] }, "example": { "risknote": "RN/2026/000123", "email": "wanjiru@example.test", "phone": "0712345678", "vehicles": [ { "registration": "KDA 123A", "start_date": "2026-10-14", "expiring": "2027-10-13" } ] } } } }, "responses": { "200": { "description": "`{success: true, message, data: [certificate]}`", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Certificate C12345678 issued.", "data": [ { "certificate_number": "C12345678", "status": "issued", "class": "C", "cover_code": 100, "stage": 1, "stage_of": 1, "registration": "KDA 123A", "chassis": "NZE161-3012456", "policy_no": "POL/2026/000123", "risknote": "RN/2026/000123", "start_date": "2026-10-14", "expiring": "2027-10-13", "issued_at": "2026-10-14T10:17:00+03:00", "cancelled_at": null, "error_code": null, "error_text": null } ] } } } }, "404": { "description": "Unknown risk note", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`certificate_not_issued` (policy not active, stage not paid, double insurance, DMVIC refusal; `data` holds the attempt) or `validation_failed` (vehicle not on the risk note, dates outside cover)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "certificate" ] }, { "bearer": [] } ], "x-scope": "certificate", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": false } }, "/dmvic/agent": { "post": { "operationId": "post_dmvic_agent", "tags": [ "Motor certificates (DMVIC)" ], "summary": "Issue a certificate as an agent", "description": "Insurance Cloud's agent issuance: identifies the agent by `X-Agent-Code` and `X-Agent-Key`, checks the policy is theirs and issues the next eligible stage (`CertificateStages`). The headers are required here.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: certificate.", "parameters": [ { "name": "X-Agent-Code", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Required. The agent's code (see GET /sales-people)." }, { "name": "X-Agent-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Required. The agent's key." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_id": { "type": "string", "description": "Policy id, uuid, policy number or risk note number.", "examples": [ "5d0c8a1e-…" ] } }, "required": [ "policy_id" ] }, "example": { "policy_id": "5d0c8a1e-…" } } } }, "responses": { "200": { "description": "`{success: true, message, data: [certificate], stage, of}`", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Certificate C12345678 issued.", "data": [ { "certificate_number": "C12345678", "status": "issued", "class": "C", "cover_code": 100, "stage": 1, "stage_of": 1, "registration": "KDA 123A", "chassis": "NZE161-3012456", "policy_no": "POL/2026/000123", "risknote": "RN/2026/000123", "start_date": "2026-10-14", "expiring": "2027-10-13", "issued_at": "2026-10-14T10:17:00+03:00", "cancelled_at": null, "error_code": null, "error_text": null } ], "stage": 1, "of": 1 } } } }, "400": { "description": "`agent_headers_required`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "403": { "description": "`agent_denied` (headers do not match) or `policy_not_agents` (the policy was written by someone else)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "Unknown policy", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`not_eligible` (not active, next instalment unpaid, every stage issued) or `certificate_not_issued`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "certificate" ] }, { "bearer": [] } ], "x-scope": "certificate", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": false } }, "/dmvic/get-certificate": { "post": { "operationId": "post_dmvic_get_certificate", "tags": [ "Motor certificates (DMVIC)" ], "summary": "Download a certificate", "description": "The certificate as a PDF file (`application/pdf`, attachment). Flexysure's rendering is marked SAMPLE; DMVIC's own PDF is the certificate of record. Only issued certificates download.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: certificate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "CertificateNumber": { "type": "string", "description": "DMVIC certificate number.", "examples": [ "C12345678" ] } }, "required": [ "CertificateNumber" ] }, "example": { "CertificateNumber": "C12345678" } } } }, "responses": { "200": { "description": "PDF file", "content": { "application/pdf": { "schema": { "type": "string", "contentMediaType": "application/pdf" } } } }, "404": { "description": "Unknown certificate", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`certificate_not_active` (cancelled, failed or still requested)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "certificate" ] }, { "bearer": [] } ], "x-scope": "certificate", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/dmvic/double-insurance": { "post": { "operationId": "post_dmvic_double_insurance", "tags": [ "Motor certificates (DMVIC)" ], "summary": "Check for double insurance", "description": "Asks DMVIC whether the vehicle already has cover overlapping the period. `clear: true` means none; otherwise `data` lists the overlapping certificates. Read-only.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: certificate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "registration": { "type": "string", "examples": [ "KDA 123A" ] }, "chassis": { "type": "string", "examples": [ "NZE161-3012456" ] }, "start_date": { "type": "string", "examples": [ "2026-10-14" ] }, "expiring": { "type": "string", "examples": [ "2027-10-13" ] } }, "required": [ "registration", "start_date", "expiring" ] }, "example": { "registration": "KDA 123A", "start_date": "2026-10-14", "expiring": "2027-10-13" } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "No overlapping cover on DMVIC for this period.", "clear": true, "data": [] } } } }, "502": { "description": "`dmvic_unavailable`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "certificate" ] }, { "bearer": [] } ], "x-scope": "certificate", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/dmvic/stock": { "post": { "operationId": "post_dmvic_stock", "tags": [ "Motor certificates (DMVIC)" ], "summary": "Get certificate stock", "description": "Blank certificate stock DMVIC holds for an underwriter, by certificate class. `insurer` is the DMVIC member company id (`dmvic_member_id` from GET /insurers).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: certificate.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "insurer": { "type": "integer", "description": "DMVIC member company id.", "examples": [ 901 ] } }, "required": [ "insurer" ] }, "example": { "insurer": 901 } } } }, "responses": { "200": { "description": "`{success: true, data: [...]}`", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Stock for Savanna General.", "insurer": { "id": 1, "name": "Savanna General", "member_company_id": 901 }, "data": [ { "classification_id": 3, "title": "Type C - Private", "stock": 480 } ] } } } }, "404": { "description": "No insurer with that member id in your organisation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`dmvic_rejected`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "certificate" ] }, { "bearer": [] } ], "x-scope": "certificate", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/dmvic/cancel": { "post": { "operationId": "post_dmvic_cancel", "tags": [ "Motor certificates (DMVIC)" ], "summary": "Cancel a certificate", "description": "Cancels the certificate with DMVIC. DMVIC only allows this within its cancellation window (24 hours after issue); after that the certificate stays issued and the reason comes back as `dmvic_rejected`. Cancelling an already cancelled certificate succeeds.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: certificate.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Unique value per write (a UUID). Replays within 24 hours return the stored response with Idempotent-Replayed: true." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "certificate_number": { "type": "string", "examples": [ "C12345678" ] }, "reason": { "type": "string", "enum": [ "INSURED_REQUESTED", "AMEND_PASSENGER_COUNT", "CHANGE_SCOPE_OF_COVER", "POLICY_NOT_TAKEN_UP", "VEHICLE_SOLD", "AMEND_INSURED_DETAILS", "AMEND_VEHICLE_DETAILS", "SUSPECTED_FRAUD", "NON_PAYMENT", "MISSING_KYC", "GOVERNMENT_REQUEST", "SUBJECT_MATTER_CEASED", "CHANGE_PERIOD_OF_INSURANCE", "INSURER_DECLINED_COVER", "WRITTEN_OFF", "STOLEN" ], "description": "DMVIC cancellation reason.", "examples": [ "INSURED_REQUESTED" ] } }, "required": [ "certificate_number", "reason" ] }, "example": { "certificate_number": "C12345678", "reason": "INSURED_REQUESTED" } } } }, "responses": { "200": { "description": "`{success: true, message, data: certificate}`", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "message": "Certificate C12345678 cancelled: Insured requested.", "data": { "certificate_number": "C12345678", "status": "cancelled", "class": "C", "cover_code": 100, "stage": 1, "stage_of": 1, "registration": "KDA 123A", "chassis": "NZE161-3012456", "policy_no": "POL/2026/000123", "risknote": "RN/2026/000123", "start_date": "2026-10-14", "expiring": "2027-10-13", "issued_at": "2026-10-14T10:17:00+03:00", "cancelled_at": "2026-10-14T11:00:00+03:00", "error_code": null, "error_text": null } } } } }, "404": { "description": "Unknown certificate", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "`dmvic_rejected` or `validation_failed`", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "certificate" ] }, { "bearer": [] } ], "x-scope": "certificate", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": true } }, "/certificates/{number}/verify": { "get": { "operationId": "get_certificates_number_verify", "tags": [ "Motor certificates (DMVIC)" ], "summary": "Verify a certificate", "description": "`state` is `valid`, `expired`, `future` (cover not started), `cancelled`, `not_issued` or `mismatch` (the registration you passed is not the certified vehicle).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: certificate.", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "C12345678" ] }, "example": "C12345678" }, { "name": "registration", "in": "query", "required": false, "schema": { "type": "string", "description": "Check the certificate belongs to this vehicle.", "examples": [ "KDA123A" ] }, "description": "Check the certificate belongs to this vehicle.", "example": "KDA123A" } ], "responses": { "200": { "description": "Verification", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "state": "valid", "valid": true, "insurer": "Savanna General", "certificate_number": "C12345678", "status": "issued", "class": "C", "cover_code": 100, "stage": 1, "stage_of": 1, "registration": "KDA 123A", "chassis": "NZE161-3012456", "policy_no": "POL/2026/000123", "risknote": "RN/2026/000123", "start_date": "2026-10-14", "expiring": "2027-10-13", "issued_at": "2026-10-14T10:17:00+03:00", "cancelled_at": null, "error_code": null, "error_text": null } } } } }, "404": { "description": "Unknown certificate", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "certificate" ] }, { "bearer": [] } ], "x-scope": "certificate", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/sms/send": { "post": { "operationId": "post_sms_send", "tags": [ "SMS" ], "summary": "Send SMS (batch)", "description": "Sends every item and reports each one. 200 when all were sent; 207 Multi-Status when any failed (the others still went). `transaction` labels the messages (default \"API SMS\"); an item's own `transaction` wins. `uuid` in each result can be fetched with GET /sms/{uuid}.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: messaging.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required. A replay returns the first response and sends nothing." }, { "name": "X-Agent-Code", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Agent code of the selling agent; the call runs with that agent's visibility." }, { "name": "X-Agent-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The agent's API key (required with X-Agent-Code)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction": { "type": "string", "description": "Default label for the batch.", "examples": [ "Renewal reminder" ] }, "sms": { "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string", "examples": [ "0712345678" ] }, "message": { "type": "string", "examples": [ "Dear Wanjiru, your motor policy renews on 13 Oct." ] }, "policy_id": { "type": "integer", "description": "Links the message to a policy (and its client)." }, "transaction": { "type": "string" } }, "required": [ "phone", "message" ] }, "description": "1 to 500 messages." } }, "required": [ "sms" ] }, "example": { "transaction": "Renewal reminder", "sms": [ { "phone": "0712345678", "message": "Dear Wanjiru, your motor policy renews on 13 Oct.", "policy_id": 123 }, { "phone": "12", "message": "Hello" } ] } } } }, "responses": { "200": { "description": "All sent", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "partial", "message": "1 SMS sent, 1 failed.", "summary": { "total": 2, "sent": 1, "failed": 1, "units": 1 }, "results": [ { "index": 0, "phone": "0712345678", "message": "Dear Wanjiru, your motor policy renews on 13 Oct.", "policy_id": 123, "transaction": "Renewal reminder", "sent": true, "error": null, "uuid": "0c9d…", "units": 1 }, { "index": 1, "phone": "12", "message": "Hello", "policy_id": null, "transaction": "Renewal reminder", "sent": false, "error": "Enter a Kenyan mobile number like 0712 345 678.", "uuid": null, "units": 0 } ] } } } }, "207": { "description": "Some or all failed: see `results[].error`", "content": { "application/json": { "schema": { "type": "object" } } } }, "422": { "description": "Validation failed (missing phone/message, policy from another organisation)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "messaging" ] }, { "bearer": [] } ], "x-scope": "messaging", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": true, "x-flexysure-only": false } }, "/sms/sent": { "get": { "operationId": "get_sms_sent", "tags": [ "SMS" ], "summary": "List sent SMS", "description": "The organisation's SMS outbox, newest first, between `from` and `to` (inclusive; default the first of this month to today).\n\nRate limit: 60 requests per minute per token (per-client override). Scope: messaging.", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "description": "Y-m-d. Default first of this month." }, "description": "Y-m-d. Default first of this month." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "description": "Y-m-d. Default today." }, "description": "Y-m-d. Default today." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Default 50, max 100." }, "description": "Default 50, max 100." } ], "responses": { "200": { "description": "Sent SMS", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "filters": { "from": "2026-10-01", "to": "2026-10-14" }, "summary": { "total": 1, "per_page": 50, "current_page": 1, "last_page": 1 }, "sms": [ { "id": 881, "uuid": "0c9d…", "phone": "0712345678", "message": "Dear Wanjiru, your motor policy renews on 13 Oct.", "policy_id": 123, "transaction": "Renewal reminder", "added_by": "api", "status": "sent", "units": 1, "error": null, "sent_at": "2026-10-14T09:00:01+03:00", "delivered_at": null, "created_at": "2026-10-14T09:00:00+03:00", "updated_at": "2026-10-14T09:00:01+03:00" } ] } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "messaging" ] }, { "bearer": [] } ], "x-scope": "messaging", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/sms/balance": { "get": { "operationId": "get_sms_balance", "tags": [ "SMS" ], "summary": "SMS balance", "description": "Units left. One unit sends one 160-character segment.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: messaging.", "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "type": "object" }, "example": { "status": "success", "balance": 4820 } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "messaging" ] }, { "bearer": [] } ], "x-scope": "messaging", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": false } }, "/sms/{uuid}": { "get": { "operationId": "get_sms_uuid", "tags": [ "SMS" ], "summary": "Get an SMS", "description": "One message from the outbox with its delivery status.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: messaging.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "schema": { "type": "string", "description": "From `results[].uuid` of POST /sms/send." }, "description": "From `results[].uuid` of POST /sms/send." } ], "responses": { "200": { "description": "SMS", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 881, "uuid": "0c9d…", "phone": "0712345678", "message": "Dear Wanjiru…", "policy_id": 123, "transaction": "Renewal reminder", "added_by": "api", "status": "sent", "units": 1, "error": null, "sent_at": "2026-10-14T09:00:01+03:00", "delivered_at": null, "created_at": "2026-10-14T09:00:00+03:00", "updated_at": "2026-10-14T09:00:01+03:00" } } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "messaging" ] }, { "bearer": [] } ], "x-scope": "messaging", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/webhooks": { "get": { "operationId": "get_webhooks", "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "Every endpoint registered for the token's organisation, newest first. Secrets are never returned here; see secret_hint.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: webhooks.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page, 1–100 (default 25)." }, "description": "Rows per page, 1–100 (default 25)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Opaque cursor from links.next." }, "description": "Opaque cursor from links.next." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Insurance-Cloud style page number (alternative to cursor)." }, "description": "Insurance-Cloud style page number (alternative to cursor)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page when using page." }, "description": "Rows per page when using page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": "b1f1c0de-1234-4abc-9def-0123456789ab", "url": "https://erp.simba.co.ke/flexysure/webhooks", "description": "Core ERP", "events": [ "payment.received", "policy.activated" ], "active": true, "secret_hint": "whsec_…k9Qz", "secret_rotated_at": null, "last_delivered_at": "2026-10-14T09:31:06+03:00", "last_failed_at": null, "created_at": "2026-10-01T08:00:00+03:00" } ], "meta": { "limit": 25, "has_more": false, "count": 1 }, "links": { "next": null } } } } }, "401": { "description": "unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "403": { "description": "insufficient_scope, or agent_key_cannot_manage_webhooks for a key acting as an agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "webhooks" ] }, { "bearer": [] } ], "x-scope": "webhooks", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true }, "post": { "operationId": "post_webhooks", "tags": [ "Webhooks" ], "summary": "Create a webhook endpoint", "description": "Registers a receiver URL. The response carries the signing `secret` exactly once; store it. Pass events [\"*\"] to receive everything, now and in future.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: webhooks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Absolute http(s) URL, max 2048 characters." }, "description": { "type": "string", "description": "Label shown in Settings, max 160 characters." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event names from GET /webhooks/events, or [\"*\"]." }, "active": { "type": "boolean", "description": "Default true." } }, "required": [ "url", "events" ] }, "example": { "url": "https://erp.simba.co.ke/flexysure/webhooks", "description": "Core ERP", "events": [ "payment.received", "policy.activated" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "b1f1c0de-1234-4abc-9def-0123456789ab", "url": "https://erp.simba.co.ke/flexysure/webhooks", "description": "Core ERP", "events": [ "payment.received", "policy.activated" ], "active": true, "secret_hint": "whsec_…k9Qz", "secret_rotated_at": null, "last_delivered_at": "2026-10-14T09:31:06+03:00", "last_failed_at": null, "created_at": "2026-10-01T08:00:00+03:00", "secret": "whsec_3Qf8sZl2pV9xK1mN0bT7cR4dE6gH8jL5wY2aU7oP" } } } } }, "401": { "description": "unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "403": { "description": "insufficient_scope, or agent_key_cannot_manage_webhooks for a key acting as an agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "422": { "description": "validation_failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "webhooks" ] }, { "bearer": [] } ], "x-scope": "webhooks", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/webhooks/events": { "get": { "operationId": "get_webhooks_events", "tags": [ "Webhooks" ], "summary": "List the event catalogue", "description": "Every event name a webhook endpoint can subscribe to, with a one-line description.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: webhooks.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "event": "payment.received", "description": "A receipt was recorded (M-Pesa STK, C2B or manual)." } ] } } } }, "401": { "description": "unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "403": { "description": "insufficient_scope, or agent_key_cannot_manage_webhooks for a key acting as an agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "webhooks" ] }, { "bearer": [] } ], "x-scope": "webhooks", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/webhooks/{id}": { "get": { "operationId": "get_webhooks_id", "tags": [ "Webhooks" ], "summary": "Get one webhook endpoint", "description": "By its UUID.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: webhooks.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Endpoint id." }, "description": "Endpoint id." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": "b1f1c0de-1234-4abc-9def-0123456789ab", "url": "https://erp.simba.co.ke/flexysure/webhooks", "description": "Core ERP", "events": [ "payment.received", "policy.activated" ], "active": true, "secret_hint": "whsec_…k9Qz", "secret_rotated_at": null, "last_delivered_at": "2026-10-14T09:31:06+03:00", "last_failed_at": null, "created_at": "2026-10-01T08:00:00+03:00" } } } } }, "401": { "description": "unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "403": { "description": "insufficient_scope, or agent_key_cannot_manage_webhooks for a key acting as an agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "webhooks" ] }, { "bearer": [] } ], "x-scope": "webhooks", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true }, "delete": { "operationId": "delete_webhooks_id", "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "description": "Removes the endpoint and its delivery history. Pending deliveries are dropped.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: webhooks.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Endpoint id." }, "description": "Endpoint id." } ], "responses": { "204": { "description": "No content" }, "401": { "description": "unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "403": { "description": "insufficient_scope, or agent_key_cannot_manage_webhooks for a key acting as an agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "webhooks" ] }, { "bearer": [] } ], "x-scope": "webhooks", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/webhooks/{id}/deliveries": { "get": { "operationId": "get_webhooks_id_deliveries", "tags": [ "Webhooks" ], "summary": "List deliveries for an endpoint", "description": "Newest first, with the exact body that was signed and sent, the attempt count, the receiver's HTTP status and the next retry time.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: webhooks.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Endpoint id." }, "description": "Endpoint id." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "pending | retrying | delivered | failed" }, "description": "pending | retrying | delivered | failed" }, { "name": "event", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by event name." }, "description": "Filter by event name." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page, 1–100 (default 25)." }, "description": "Rows per page, 1–100 (default 25)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "Opaque cursor from links.next." }, "description": "Opaque cursor from links.next." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Insurance-Cloud style page number (alternative to cursor)." }, "description": "Insurance-Cloud style page number (alternative to cursor)." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Rows per page when using page." }, "description": "Rows per page when using page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": [ { "id": 9821, "event": "payment.received", "event_id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "status": "delivered", "attempt": 1, "response_code": 200, "last_error": null, "signed_at": "2026-10-14T09:31:05+03:00", "delivered_at": "2026-10-14T09:31:06+03:00", "next_attempt_at": null, "created_at": "2026-10-14T09:31:05+03:00", "payload": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "payment.received", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "receipt": { "number": "RCT-000311" } } } } ], "meta": { "limit": 25, "has_more": false, "count": 1 }, "links": { "next": null } } } } }, "401": { "description": "unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "403": { "description": "insufficient_scope, or agent_key_cannot_manage_webhooks for a key acting as an agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "webhooks" ] }, { "bearer": [] } ], "x-scope": "webhooks", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } }, "/webhook-deliveries/{id}/retry": { "post": { "operationId": "post_webhook_deliveries_id_retry", "tags": [ "Webhooks" ], "summary": "Retry a delivery now", "description": "Queues one more attempt of a delivery (any status), keeping the same Flexysure-Delivery id. Fails with 409 when the endpoint is disabled.\n\nRate limit: 60 requests per minute per token (per-client override). Scope: webhooks.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "description": "Delivery id from the deliveries list." }, "description": "Delivery id from the deliveries list." } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object" }, "example": { "data": { "id": 9821, "event": "payment.received", "event_id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "status": "pending", "attempt": 1, "response_code": 200, "last_error": null, "signed_at": "2026-10-14T09:31:05+03:00", "delivered_at": "2026-10-14T09:31:06+03:00", "next_attempt_at": null, "created_at": "2026-10-14T09:31:05+03:00", "payload": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "payment.received", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "receipt": { "number": "RCT-000311" } } } } } } } }, "401": { "description": "unauthenticated", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "403": { "description": "insufficient_scope, or agent_key_cannot_manage_webhooks for a key acting as an agent", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "404": { "description": "not_found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "409": { "description": "endpoint_disabled", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } }, "default": { "$ref": "#/components/responses/problem" } }, "security": [ { "oauth2": [ "webhooks" ] }, { "bearer": [] } ], "x-scope": "webhooks", "x-rate-limit": "60 requests per minute per token (per-client override)", "x-idempotent": false, "x-flexysure-only": true } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth2 client-credentials grant. Create a client on Settings → API keys, then POST client_id and client_secret to the token URL.", "flows": { "clientCredentials": { "tokenUrl": "https://flexysure.intrepidprojects.co.ke/api/v1/oauth/token", "scopes": { "read": "Read reference data, policies, receipts and other records", "quote": "Price motor, medical, travel and standard products", "bind": "Save quotes and issue policies", "pay": "Start M-Pesa payments and read payment status", "certificate": "Issue, fetch and cancel DMVIC motor certificates", "finance": "Premium finance: offers, applications, loans and repayments", "crm": "Prospects and clients", "claims": "Register and track claims", "messaging": "Send SMS and read the outbox", "portal": "Client area on behalf of a customer", "webhooks": "Register webhook endpoints and read deliveries" } } } }, "bearer": { "type": "http", "scheme": "bearer", "description": "The access_token from POST /oauth/token, sent as Authorization: Bearer ." }, "clientNo": { "type": "apiKey", "in": "header", "name": "X-Client-No", "description": "Client-area endpoints: the client number returned by verify-otp or register." }, "clientKey": { "type": "apiKey", "in": "header", "name": "X-Client-Key", "description": "Client-area endpoints: the client key (fxck_…) returned by verify-otp or register." } }, "schemas": { "problem": { "type": "object", "description": "RFC 9457 problem details (application/problem+json). Every error from /api/v1 has this shape.", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri", "description": "https://flexysure.com/problems/" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "description": "Machine-readable error code, e.g. validation_failed, insufficient_scope." }, "instance": { "type": "string", "description": "The request id (same as the X-Request-Id header)." }, "errors": { "type": "object", "description": "Validation errors by field (422 validation_failed).", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "example": { "type": "https://flexysure.com/problems/validation_failed", "title": "Validation failed", "status": 422, "detail": "The vehicle.year field is required.", "code": "validation_failed", "instance": "9b1d0c4e-2f3a-4b5c-8d6e-7f8091a2b3c4", "errors": { "vehicle.year": [ "The vehicle.year field is required." ] } } } }, "responses": { "problem": { "description": "Error (RFC 9457 problem document)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem" } } } } } }, "webhooks": { "payment.received": { "post": { "operationId": "webhook_payment_received", "tags": [ "Webhooks" ], "summary": "payment.received", "description": "A receipt was recorded: M-Pesa STK, paybill (C2B), bank or cash. Fires before allocation, so allocated_minor may still be 0.\n\nFired by: Receipt created.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "payment.received", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "receipt": { "number": "RCT-000311", "channel": "mpesa_stk", "external_ref": "QKX7H2M9PL", "status": "unallocated", "payer_phone": "254712345678", "received_at": "2026-10-14T09:31:04+03:00", "amount": 30175, "amount_minor": 3017500, "allocated_minor": 0 }, "client": { "client_no": "C000123", "name": "Wanjiru Kamau", "type": "individual", "phone": "0712345678", "email": "wanjiru@example.co.ke" } } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "policy.issued": { "post": { "operationId": "webhook_policy_issued", "tags": [ "Webhooks" ], "summary": "policy.issued", "description": "A policy record exists and is awaiting payment (status pending_payment). The vehicle may not be attached yet; policy.activated carries it.\n\nFired by: Policy created.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "policy.issued", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452", "risk_note_no": "RN-000452", "product_line": "motor", "vehicle_class": "private", "cover_type": "comprehensive", "status": "pending_payment", "start_on": "2026-10-14", "end_on": "2027-10-13", "payment_mode": "full", "instalments": 1, "sum_insured": { "amount": 850000, "amount_minor": 85000000 }, "basic_premium": { "amount": 30000, "amount_minor": 3000000 }, "taxes": { "amount": 175, "amount_minor": 17500 }, "gross_premium": { "amount": 30175, "amount_minor": 3017500 }, "activated_at": null, "cancelled_at": null, "cancel_reason": null }, "client": { "client_no": "C000123", "name": "Wanjiru Kamau", "type": "individual", "phone": "0712345678", "email": "wanjiru@example.co.ke" }, "insurer": { "id": 3, "name": "Savanna General" }, "vehicle": null } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "policy.activated": { "post": { "operationId": "webhook_policy_activated", "tags": [ "Webhooks" ], "summary": "policy.activated", "description": "Cover went live: the first debit note was settled (cash) or Flexysure Finance disbursed the loan.\n\nFired by: Policy status pending_payment → active.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "policy.activated", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452", "risk_note_no": "RN-000452", "product_line": "motor", "vehicle_class": "private", "cover_type": "comprehensive", "status": "active", "start_on": "2026-10-14", "end_on": "2027-10-13", "payment_mode": "full", "instalments": 1, "sum_insured": { "amount": 850000, "amount_minor": 85000000 }, "basic_premium": { "amount": 30000, "amount_minor": 3000000 }, "taxes": { "amount": 175, "amount_minor": 17500 }, "gross_premium": { "amount": 30175, "amount_minor": 3017500 }, "activated_at": "2026-10-14T09:31:04+03:00", "cancelled_at": null, "cancel_reason": null }, "client": { "client_no": "C000123", "name": "Wanjiru Kamau", "type": "individual", "phone": "0712345678", "email": "wanjiru@example.co.ke" }, "insurer": { "id": 3, "name": "Savanna General" }, "vehicle": { "reg_no": "KDA 123A", "chassis_no": "NZE141-3012456", "make": "Toyota", "model": "Axio", "year": 2018, "value": { "amount": 850000, "amount_minor": 85000000 } } } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "policy.endorsed": { "post": { "operationId": "webhook_policy_endorsed", "tags": [ "Webhooks" ], "summary": "policy.endorsed", "description": "An endorsement was issued on a policy (premium delta positive, negative or zero).\n\nFired by: Endorsement status → issued.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "policy.endorsed", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "endorsement": { "uuid": "2b9d8c7e-1f2a-4b3c-8d9e-0f1a2b3c4d5e", "number": "END/2026/000012", "type": "change_value", "status": "issued", "effective_on": "2026-11-01", "premium_delta": { "amount": 2500, "amount_minor": 250000 }, "taxes_delta": { "amount": 11, "amount_minor": 1100 }, "gross_delta": { "amount": 2511, "amount_minor": 251100 }, "changes": { "sum_insured_minor": { "from": 85000000, "to": 95000000 } }, "issued_at": "2026-10-20T11:02:00+03:00" }, "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452" } } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "policy.cancelled": { "post": { "operationId": "webhook_policy_cancelled", "tags": [ "Webhooks" ], "summary": "policy.cancelled", "description": "A policy was cancelled (client request, non-payment of premium finance, or other).\n\nFired by: Policy status → cancelled.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "policy.cancelled", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452", "risk_note_no": "RN-000452", "product_line": "motor", "vehicle_class": "private", "cover_type": "comprehensive", "status": "cancelled", "start_on": "2026-10-14", "end_on": "2027-10-13", "payment_mode": "full", "instalments": 1, "sum_insured": { "amount": 850000, "amount_minor": 85000000 }, "basic_premium": { "amount": 30000, "amount_minor": 3000000 }, "taxes": { "amount": 175, "amount_minor": 17500 }, "gross_premium": { "amount": 30175, "amount_minor": 3017500 }, "activated_at": "2026-10-14T09:31:04+03:00", "cancelled_at": "2026-12-01T08:15:00+03:00", "cancel_reason": "Client request" }, "client": { "client_no": "C000123", "name": "Wanjiru Kamau", "type": "individual", "phone": "0712345678", "email": "wanjiru@example.co.ke" }, "insurer": { "id": 3, "name": "Savanna General" }, "vehicle": { "reg_no": "KDA 123A", "chassis_no": "NZE141-3012456", "make": "Toyota", "model": "Axio", "year": 2018, "value": { "amount": 850000, "amount_minor": 85000000 } } } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "policy.renewal_due": { "post": { "operationId": "webhook_policy_renewal_due", "tags": [ "Webhooks" ], "summary": "policy.renewal_due", "description": "An active policy entered a renewal window. Fired by the daily job at 60, 30 and 7 days before end_on.\n\nFired by: flexysure:webhooks-renewal-due (daily 06:30).", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "policy.renewal_due", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452", "risk_note_no": "RN-000452", "product_line": "motor", "vehicle_class": "private", "cover_type": "comprehensive", "status": "active", "start_on": "2026-10-14", "end_on": "2027-10-13", "payment_mode": "full", "instalments": 1, "sum_insured": { "amount": 850000, "amount_minor": 85000000 }, "basic_premium": { "amount": 30000, "amount_minor": 3000000 }, "taxes": { "amount": 175, "amount_minor": 17500 }, "gross_premium": { "amount": 30175, "amount_minor": 3017500 }, "activated_at": "2026-10-14T09:31:04+03:00", "cancelled_at": null, "cancel_reason": null }, "client": { "client_no": "C000123", "name": "Wanjiru Kamau", "type": "individual", "phone": "0712345678", "email": "wanjiru@example.co.ke" }, "insurer": { "id": 3, "name": "Savanna General" }, "vehicle": { "reg_no": "KDA 123A", "chassis_no": "NZE141-3012456", "make": "Toyota", "model": "Axio", "year": 2018, "value": { "amount": 850000, "amount_minor": 85000000 } }, "renewal": { "days_to_expiry": 30, "window": "30d", "as_of": "2027-09-13" } } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "certificate.issued": { "post": { "operationId": "webhook_certificate_issued", "tags": [ "Webhooks" ], "summary": "certificate.issued", "description": "DMVIC issued the motor certificate. verify_url opens the public roadside check.\n\nFired by: DmvicCertificate status → issued.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "certificate.issued", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "certificate": { "certificate_no": "C12345678", "class": "C", "cover_code": "100", "status": "issued", "period_from": "2026-10-14", "period_to": "2027-10-13", "issued_at": "2026-10-14T09:31:12+03:00", "cancelled_at": null, "verify_url": "https://app.flexysure.com/verify/C12345678" }, "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452", "risk_note_no": "RN-000452" }, "vehicle": { "reg_no": "KDA 123A", "chassis_no": "NZE141-3012456", "make": "Toyota", "model": "Axio", "year": 2018, "value": { "amount": 850000, "amount_minor": 85000000 } } } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "certificate.cancelled": { "post": { "operationId": "webhook_certificate_cancelled", "tags": [ "Webhooks" ], "summary": "certificate.cancelled", "description": "A motor certificate was cancelled at DMVIC (policy cancelled, vehicle removed, non-payment).\n\nFired by: DmvicCertificate status → cancelled.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "certificate.cancelled", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "certificate": { "certificate_no": "C12345678", "class": "C", "cover_code": "100", "status": "cancelled", "period_from": "2026-10-14", "period_to": "2027-10-13", "issued_at": "2026-10-14T09:31:12+03:00", "cancelled_at": "2026-12-01T08:15:30+03:00", "verify_url": "https://app.flexysure.com/verify/C12345678" }, "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452", "risk_note_no": "RN-000452" }, "vehicle": { "reg_no": "KDA 123A", "chassis_no": "NZE141-3012456", "make": "Toyota", "model": "Axio", "year": 2018, "value": { "amount": 850000, "amount_minor": 85000000 } } } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "claim.registered": { "post": { "operationId": "webhook_claim_registered", "tags": [ "Webhooks" ], "summary": "claim.registered", "description": "A claim was registered on a policy.\n\nFired by: Claim created.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "claim.registered", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "claim": { "uuid": "7e6d5c4b-3a29-4180-9f8e-7d6c5b4a3928", "claim_no": "CLM/2026/000007", "claim_type": "accidental_damage", "legal": false, "status": "registered", "incident_on": "2026-11-20", "reported_on": "2026-11-21", "risk_item": "KDA 123A", "insurer_ref": null, "estimate": { "amount": 120000, "amount_minor": 12000000 }, "reserve": { "amount": 0, "amount_minor": 0 }, "approved": { "amount": 0, "amount_minor": 0 }, "paid": { "amount": 0, "amount_minor": 0 } }, "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452" } } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "claim.updated": { "post": { "operationId": "webhook_claim_updated", "tags": [ "Webhooks" ], "summary": "claim.updated", "description": "A claim changed status. previous_status tells you where it came from.\n\nFired by: Claim status changed.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "claim.updated", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "claim": { "uuid": "7e6d5c4b-3a29-4180-9f8e-7d6c5b4a3928", "claim_no": "CLM/2026/000007", "claim_type": "accidental_damage", "legal": false, "status": "approved", "incident_on": "2026-11-20", "reported_on": "2026-11-21", "risk_item": "KDA 123A", "insurer_ref": "SG/CLM/88213", "estimate": { "amount": 120000, "amount_minor": 12000000 }, "reserve": { "amount": 120000, "amount_minor": 12000000 }, "approved": { "amount": 104000, "amount_minor": 10400000 }, "paid": { "amount": 0, "amount_minor": 0 } }, "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452" }, "previous_status": "under_assessment" } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "prospect.created": { "post": { "operationId": "webhook_prospect_created", "tags": [ "Webhooks" ], "summary": "prospect.created", "description": "A prospect was added to the CRM pipeline (web form, API or staff).\n\nFired by: Prospect created.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "prospect.created", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "prospect": { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Mwangi Hardware Ltd", "status": "new", "email": "info@mwangihardware.co.ke", "phone": "0722000111", "sector": "Retail", "rating": "warm", "follow_up_date": "2026-10-20", "expected_premium": { "amount": 180000, "amount_minor": 18000000 }, "expected_commission": { "amount": 18000, "amount_minor": 1800000 } } } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "ipf.application.decided": { "post": { "operationId": "webhook_ipf_application_decided", "tags": [ "Webhooks" ], "summary": "ipf.application.decided", "description": "Flexysure Finance approved or declined a premium-finance application. decision is approved or declined.\n\nFired by: IpfApplication status submitted → approved | declined.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "ipf.application.decided", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "application": { "uuid": "4c3b2a19-8d7e-4f60-9a1b-2c3d4e5f6a7b", "status": "approved", "tenor_months": 6, "gross_premium": { "amount": 50000, "amount_minor": 5000000 }, "deposit": { "amount": 10000, "amount_minor": 1000000 }, "principal": { "amount": 40000, "amount_minor": 4000000 }, "interest": { "amount": 6000, "amount_minor": 600000 }, "fees": { "amount": 500, "amount_minor": 50000 }, "total_repayable": { "amount": 46500, "amount_minor": 4650000 }, "apr_bps": 5600, "decided_at": "2026-10-14T10:02:00+03:00", "decline_reason": null }, "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452" }, "client": { "client_no": "C000123", "name": "Wanjiru Kamau", "type": "individual", "phone": "0712345678", "email": "wanjiru@example.co.ke" }, "decision": "approved" } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "ipf.loan.disbursed": { "post": { "operationId": "webhook_ipf_loan_disbursed", "tags": [ "Webhooks" ], "summary": "ipf.loan.disbursed", "description": "Flexysure Finance paid the underwriter; the loan is active and the policy is live. Includes the repayment schedule.\n\nFired by: IpfLoan status pending_disbursement → active.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "ipf.loan.disbursed", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "loan": { "uuid": "5d4c3b2a-1908-4f7e-8d6c-5b4a39281706", "loan_ref": "IPF-000087", "status": "active", "tenor_months": 6, "principal": { "amount": 40000, "amount_minor": 4000000 }, "interest": { "amount": 6000, "amount_minor": 600000 }, "fees": { "amount": 500, "amount_minor": 50000 }, "total_repayable": { "amount": 46500, "amount_minor": 4650000 }, "repaid": { "amount": 0, "amount_minor": 0 }, "outstanding": { "amount": 46500, "amount_minor": 4650000 }, "first_due_on": "2026-11-14", "disbursed_at": "2026-10-14T15:40:00+03:00" }, "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452" }, "client": { "client_no": "C000123", "name": "Wanjiru Kamau", "type": "individual", "phone": "0712345678", "email": "wanjiru@example.co.ke" }, "schedule": [ { "seq": 1, "due_on": "2026-11-14", "amount_due": { "amount": 7750, "amount_minor": 775000 }, "status": "due" }, { "seq": 2, "due_on": "2026-12-14", "amount_due": { "amount": 7750, "amount_minor": 775000 }, "status": "due" } ] } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "ipf.instalment.missed": { "post": { "operationId": "webhook_ipf_instalment_missed", "tags": [ "Webhooks" ], "summary": "ipf.instalment.missed", "description": "A premium-finance instalment is overdue and the loan moved into arrears. overdue lists every unpaid, past-due instalment.\n\nFired by: IpfLoan status active → in_arrears | cancellation_pending (flexysure:ipf-arrears).", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "ipf.instalment.missed", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "loan": { "uuid": "5d4c3b2a-1908-4f7e-8d6c-5b4a39281706", "loan_ref": "IPF-000087", "status": "in_arrears", "tenor_months": 6, "principal": { "amount": 40000, "amount_minor": 4000000 }, "interest": { "amount": 6000, "amount_minor": 600000 }, "fees": { "amount": 500, "amount_minor": 50000 }, "total_repayable": { "amount": 46500, "amount_minor": 4650000 }, "repaid": { "amount": 0, "amount_minor": 0 }, "outstanding": { "amount": 46500, "amount_minor": 4650000 }, "first_due_on": "2026-11-14", "disbursed_at": "2026-10-14T15:40:00+03:00" }, "policy": { "uuid": "0d7b1f1e-7a2c-4f3b-9a8e-2c1d5f6a7b8c", "policy_no": "POL-000452" }, "client": { "client_no": "C000123", "name": "Wanjiru Kamau", "type": "individual", "phone": "0712345678", "email": "wanjiru@example.co.ke" }, "overdue": [ { "seq": 1, "due_on": "2026-11-14", "amount_due": { "amount": 7750, "amount_minor": 775000 }, "amount_paid": { "amount": 0, "amount_minor": 0 }, "outstanding": { "amount": 7750, "amount_minor": 775000 } } ] } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "message.sent": { "post": { "operationId": "webhook_message_sent", "tags": [ "Webhooks" ], "summary": "message.sent", "description": "An SMS or email left the outbox (status sent or delivered).\n\nFired by: Message status → sent | delivered.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "message.sent", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "message": { "uuid": "8f7e6d5c-4b3a-4291-8079-6f5e4d3c2b1a", "channel": "sms", "to": "254712345678", "subject": null, "template_key": "policy.issued", "transaction": "Policy issued", "status": "sent", "provider": "africastalking", "provider_ref": "ATXid_9f1", "units": 1, "sent_at": "2026-10-14T09:31:08+03:00" } } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } }, "ping": { "post": { "operationId": "webhook_ping", "tags": [ "Webhooks" ], "summary": "ping", "description": "Sent by the \"Send test event\" button in Settings → Webhooks. Not in the catalogue; delivered to the chosen endpoint regardless of its subscriptions.\n\nFired by: Settings → Webhooks → Send test event.", "parameters": [ { "name": "Flexysure-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=1760423465,v1=5f2b1c…e9a3 — t is the unix time of signing, v1 the hex HMAC-SHA256 of \"{t}.{body}\" with the endpoint secret. Several v1 parts may appear during a rotation." }, { "name": "Flexysure-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "The event name, e.g. payment.received." }, { "name": "Flexysure-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "UUID of the event. Identical on every retry: use it to ignore duplicates." }, { "name": "User-Agent", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Flexysure-Webhooks/1.0" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id; equals the Flexysure-Delivery header and stays the same on retries." }, "event": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string", "const": "v1" }, "tenant": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "data": { "type": "object" } } }, "example": { "id": "6f1c2b3a-4d5e-4f60-8a71-9b2c3d4e5f60", "event": "ping", "created_at": "2026-10-14T09:31:05+03:00", "api_version": "v1", "tenant": { "code": "SIMBA", "name": "Simba Risk Brokers" }, "data": { "message": "Test event from Flexysure. If you can read this, your receiver and secret are set up correctly.", "sent_by": "Achieng Odhiambo" } } } } }, "responses": { "2XX": { "description": "Any 2xx acknowledges the delivery. Anything else (or a timeout) is retried after 1 m, 5 m, 30 m, 2 h and 12 h, then marked failed." } } } } } }