Medical

4 endpoints · base URL https://flexysure.intrepidprojects.co.ke/api/v1

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.

Method	Path	Summary	Scope
GET	/api/v1/medical/limits	List inpatient limits	read
GET	/api/v1/medical/census-template	Download the member census template Flexysure only	quote
POST	/api/v1/medical/quote	Price medical cover	quote
POST	/api/v1/medical/save	Bind a medical policy	bind

GET /api/v1/medical/limits

List inpatient limits

Distinct inpatient limits offered by plans on the panel, ascending. Use one as limit_from/limit_to or policy.inpatient_limit.

Scope: read
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Safe to repeat (read only).
Agent headers: Accepts X-Agent-Code and X-Agent-Key: the call runs as that agent and sees only the agent's own records.

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `read` or `quote`)
X-Agent-Code	Optional. Agent code of the selling agent; the call runs with that agent's visibility.
X-Agent-Key	Optional, with X-Agent-Code. The agent's API key; a mismatch returns 403 `agent_denied`.

Example

Request cURL

curl -X GET 'https://flexysure.intrepidprojects.co.ke/api/v1/medical/limits' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY"

Response JSON

{
    "data": [
        {
            "limit": 1000000,
            "limit_minor": 100000000,
            "label": "KES 1,000,000"
        },
        {
            "limit": 2000000,
            "limit_minor": 200000000,
            "label": "KES 2,000,000"
        }
    ]
}

Responses

Status	Meaning
200	Limits

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.

GET /api/v1/medical/census-template Flexysure only

Download the member census template

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.

Scope: quote
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Safe to repeat (read only).
Agent headers: Accepts X-Agent-Code and X-Agent-Key: the call runs as that agent and sees only the agent's own records.

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `quote`)
X-Agent-Code	Optional. Agent code; with X-Agent-Key the agent becomes the creator.
X-Agent-Key	Optional. The agent's key.

Example

Request cURL

curl -X GET 'https://flexysure.intrepidprojects.co.ke/api/v1/medical/census-template' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY"

Response JSON

(binary .xlsx)

Responses

Status	Meaning
200	The template (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), file name flexysure-medical-members-template.xlsx

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.

POST /api/v1/medical/quote

Price medical cover

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.

Scope: quote
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Not keyed. Check before retrying.
Agent headers: Accepts X-Agent-Code and X-Agent-Key: the call runs as that agent and sees only the agent's own records.

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `quote`)
X-Agent-Code	Optional. Agent code; with X-Agent-Key the agent becomes the creator.
X-Agent-Key	Optional. The agent's key.

Body fields

Field	Type	Required	Description
principal_age	integer	No	Required unless members[] is sent. Example: `30`
spouse_age	integer	No	0 or absent = no spouse.
children	integer	No	Example: `2`
limit_from	integer	No	Lowest inpatient limit, whole shillings (0 = open).
limit_to	integer	No	Highest inpatient limit, whole shillings (0 = open).
insurer_id	integer[]	No	Flexysure only: limit to these insurers.
start_date	string	No	Cover start (Y-m-d) the census ages are worked out on; default today.
members	array	No	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	array	No	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

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/medical/quote' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "principal_age": 30,
    "spouse_age": 28,
    "children": 2,
    "limit_from": 500000,
    "limit_to": 2000000
}'

Request body (JSON)

Request body JSON

{
    "principal_age": 30,
    "spouse_age": 28,
    "children": 2,
    "limit_from": 500000,
    "limit_to": 2000000
}

Response JSON

{
    "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
        }
    ]
}

Responses

Status	Meaning
200	Options (group options when the census lists several families)
422	`validation_failed` (census errors are row-numbered under `members`), `domain_rule` (ages out of range) or `no_quote`

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.

POST /api/v1/medical/save

Bind a medical policy

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.

Scope: bind
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Required: send an Idempotency-Key; a retry with the same key replays the first response.
Agent headers: Accepts X-Agent-Code and X-Agent-Key: the call runs as that agent and sees only the agent's own records.

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `bind`)
Idempotency-Key	Required. Unique per save; replays return the first response.
X-Agent-Code	Optional. Agent code; with X-Agent-Key the agent becomes the creator.
X-Agent-Key	Optional. The agent's key.

Body fields

Field	Type	Required	Description
client	object	Yes	Same block as POST /api/v1/motor/save.
members	array	Yes	[{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	array	No	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	object	Yes
policy.start_date	string	Yes
policy.end_date	string	No	Cover is annual; returned in the response.
policy.insurer_id	integer	Yes
policy.inpatient_limit	integer	Yes	Optional for a group scheme (a minimum for categories that ask for none).
policy.outpatient_limit	integer	No
policy.maternity_limit	integer	No
policy.dental_limit	integer	No
policy.optical_limit	integer	No
policy.basic	number	No
policy.taxes	number	No
policy.premium	number	Yes
policy.premium_instalments	integer	No	1–4.
policy.plan_id	integer	No	Flexysure only: the option's plan_id.
taxes	array	No	Accepted for compatibility; the server computes levies.

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/medical/save' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 8182b8ca-83a1-48db-a3b6-1fe97d4f99e3' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "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": []
}'

Request body (JSON)

Request body JSON

{
    "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": []
}

Response JSON

{
    "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_…"
    }
}

Responses

Status	Meaning
201	Policy saved (same shape as motor save)
422	`validation_failed`, `premium_mismatch`, `no_quote` or `domain_rule`

Errors are problem documents; the common codes (401, 403 insufficient_scope, 422, 429) apply to every endpoint.