Prospects — Flexysure developers

Method	Path	Summary	Scope
POST	/api/v1/prospects	Create a prospect	crm
GET	/api/v1/prospects	List prospects Flexysure only	read
GET	/api/v1/prospects/{uuid}	Get a prospect Flexysure only	read
PATCH	/api/v1/prospects/{uuid}	Update a prospect Flexysure only	crm
POST	/api/v1/prospects/{uuid}/activities	Log prospect activity Flexysure only	crm
POST	/api/v1/prospects/{uuid}/convert	Convert a prospect to a client Flexysure only	crm

POST /api/v1/prospects

Create a prospect

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[].

Scope: crm
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 `crm`)
Idempotency-Key	Required. Unique per write; a replay returns the first response.
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`.

Body fields

Field	Type	Required	Description
p_name	string	Yes	Prospect (person or company) name. Example: `Kilima Farm Supplies`
status	string	Yes	Pipeline stage. One of: `New`, `Contacted`, `Quoted`, `Negotiating`, `Won`, `Lost` Example: `New`
email	string	No	Contact email. Example: `ops@kilimafarm.co.ke`
phone	string	No	Kenyan mobile (07…, 01…, +2547…). Stored as 07XXXXXXXX. Example: `0712345678`
sector	string	No	Example: `Agriculture`
insurer_id	integer	No	Preferred insurer (GET /insurers). Example: `1`
alt_name	string	No	Alternative contact person.
alt_phone	string	No
alt_email	string	No
start_date	string	No	Y-m-d. Example: `2026-10-14`
due_date	string	No	Y-m-d. When the deal should close.
follow_up_date	string	No	Y-m-d. Drives the follow-ups due/overdue lists.
notes	string	No
rating	string	No	`hot`, `warm` or `cold` (any case), or Insurance Cloud's 1–5: 4–5 hot, 3 warm, 1–2 cold. Example: `hot`
business_source_id	integer	No	Walk-in, Referral, Web, Agent, Bancassurance.
prospect_type_id	integer	No	Individual, SME, Corporate, SACCO member.
products	object[]	No	Products being discussed. Expected premium and commission are the sums of these rows.
products[].product	string	Yes	Example: `Motor private comprehensive`
products[].product_id	integer	No	Standard product id (GET /products), if any.
products[].comm_rate	number	No	Commission rate in percent. Example: `10`
products[].premium	number	No	Expected premium, whole shillings. Example: `85000`
products[].commission	number	No	Shillings. Derived from premium × comm_rate when omitted.
assign_to	integer[]	No	Staff user ids (GET /sales-people, /risk-managers). Assigned agents can see the prospect.

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/prospects' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: ef7ac5ef-a1ed-4fc2-ac73-f2de18d6056c' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "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
    ]
}'

Request body (JSON)

Request body JSON

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

Response JSON

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

Responses

Status	Meaning
201	Prospect created
422	Validation failed (unknown status, insurer or assignee from another organisation…)

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

GET /api/v1/prospects Flexysure only

List prospects

Newest first, cursor paginated (limit, cursor; page/per_page also accepted).

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`)
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`.

Parameters

Name	In	Type	Required	Description
status	query	string	No	Pipeline stage (any case). Example: `negotiating`
rating	query	string	No	One of: `hot`, `warm`, `cold`
follow_up	query	string	No	Open prospects whose follow-up is due today or overdue. One of: `today`, `overdue`
search	query	string	No	Name, email or phone.
assigned_to	query	integer	No	Staff user id.
limit	query	integer	No	Default 25, max 100.
cursor	query	string	No	From `links.next`.

Example

Request cURL

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

Response JSON

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

Responses

Status	Meaning
200	Prospects

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

GET /api/v1/prospects/{uuid} Flexysure only

Get a prospect

The prospect with its products, assignees and activity timeline (newest first).

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`)
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`.

Parameters

Name	In	Type	Required	Description
uuid	path	string	Yes	Prospect uuid. Example: `9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f`

Example

Request cURL

curl -X GET 'https://flexysure.intrepidprojects.co.ke/api/v1/prospects/9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY"

Response JSON

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

Responses

Status	Meaning
200	Prospect
404	Not found or not visible to this caller

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

PATCH /api/v1/prospects/{uuid} Flexysure only

Update a prospect

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.

Scope: crm
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 `crm`)
Idempotency-Key	Required. Unique per write; a replay returns the first response.
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`.

Parameters

Name	In	Type	Required	Description
uuid	path	string	Yes	Prospect uuid. Example: `9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f`

Body fields

Field	Type	Required	Description
name	string	No	Or `p_name`.
status	string	No	One of: `new`, `contacted`, `quoted`, `negotiating`, `lost`
lost_reason	string	No	Why the prospect was lost.
email	string	No	Contact email. Example: `ops@kilimafarm.co.ke`
phone	string	No	Kenyan mobile (07…, 01…, +2547…). Stored as 07XXXXXXXX. Example: `0712345678`
sector	string	No	Example: `Agriculture`
insurer_id	integer	No	Preferred insurer (GET /insurers). Example: `1`
alt_name	string	No	Alternative contact person.
alt_phone	string	No
alt_email	string	No
start_date	string	No	Y-m-d. Example: `2026-10-14`
due_date	string	No	Y-m-d. When the deal should close.
follow_up_date	string	No	Y-m-d. Drives the follow-ups due/overdue lists.
notes	string	No
rating	string	No	`hot`, `warm` or `cold` (any case), or Insurance Cloud's 1–5: 4–5 hot, 3 warm, 1–2 cold. Example: `hot`
business_source_id	integer	No	Walk-in, Referral, Web, Agent, Bancassurance.
prospect_type_id	integer	No	Individual, SME, Corporate, SACCO member.
products	object[]	No	Products being discussed. Expected premium and commission are the sums of these rows.
products[].product	string	Yes	Example: `Motor private comprehensive`
products[].product_id	integer	No	Standard product id (GET /products), if any.
products[].comm_rate	number	No	Commission rate in percent. Example: `10`
products[].premium	number	No	Expected premium, whole shillings. Example: `85000`
products[].commission	number	No	Shillings. Derived from premium × comm_rate when omitted.
assign_to	integer[]	No	Staff user ids (GET /sales-people, /risk-managers). Assigned agents can see the prospect.

Example

Request cURL

curl -X PATCH 'https://flexysure.intrepidprojects.co.ke/api/v1/prospects/9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 2fb47229-e5ea-4120-a0d0-ecd86fc311a9' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "Negotiating",
    "follow_up_date": "2026-10-20"
}'

Request body (JSON)

Request body JSON

{
    "status": "Negotiating",
    "follow_up_date": "2026-10-20"
}

Response JSON

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

Responses

Status	Meaning
200	Updated prospect
404	Not found
422	Validation failed or `won` sent (use convert)

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

POST /api/v1/prospects/{uuid}/activities Flexysure only

Log prospect activity

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.

Scope: crm
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 `crm`)
Idempotency-Key	Required. Unique per write; a replay returns the first response.
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`.

Parameters

Name	In	Type	Required	Description
uuid	path	string	Yes	Prospect uuid. Example: `9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f`

Body fields

Field	Type	Required	Description
type	string	Yes	One of: `note`, `call`, `meeting`
body	string	Yes	Example: `Called; wants a quote by Friday.`
occurred_at	string	No	ISO 8601, not in the future. Default now.
follow_up_date	string	No	Y-m-d. New follow-up date.

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/prospects/9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f/activities' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 73ad5e4c-331a-40ea-a330-5af77be86d5c' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "call",
    "body": "Called; wants a quote by Friday.",
    "follow_up_date": "2026-10-17"
}'

Request body (JSON)

Request body JSON

{
    "type": "call",
    "body": "Called; wants a quote by Friday.",
    "follow_up_date": "2026-10-17"
}

Response JSON

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

Responses

Status	Meaning
201	Activity logged
404	Not found

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

POST /api/v1/prospects/{uuid}/convert Flexysure only

Convert a prospect to a client

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.

Scope: crm
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 `crm`)
Idempotency-Key	Required. Unique per write; a replay returns the first response.
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`.

Parameters

Name	In	Type	Required	Description
uuid	path	string	Yes	Prospect uuid. Example: `9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f`

Body fields

Field	Type	Required	Description
type	string	No	One of: `individual`, `corporate`
phone	string	No	Needed when the prospect has none.
id_no	string	No
kra_pin	string	No
date_of_birth	string	No
physical_address	string	No
branch_id	integer	No
risk_manager_id	integer	No
sales_person_id	integer	No

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/prospects/9b1f3c5e-2d4a-4c1b-8f0e-6a7b8c9d0e1f/convert' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 83adda69-0759-495a-a57d-6040c8e8bfe3' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "corporate",
    "kra_pin": "P051234567X"
}'

Request body (JSON)

Request body JSON

{
    "type": "corporate",
    "kra_pin": "P051234567X"
}

Response JSON

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

Responses

Status	Meaning
200	Prospect (won) and its client
404	Not found
422	Lost prospect, or no phone number (`domain_rule`)

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