Clients

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

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.

Method	Path	Summary	Scope
GET	/api/v1/clients	List clients Flexysure only	read
POST	/api/v1/clients	Create a client Flexysure only	crm
GET	/api/v1/clients/{client_no}	Get a client Flexysure only	read
PATCH	/api/v1/clients/{client_no}	Update a client Flexysure only	crm

GET /api/v1/clients Flexysure only

List clients

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
search	query	string	No	Name, client number, phone, ID number or KRA PIN.
type	query	string	No	One of: `individual`, `corporate`
sales_person_id	query	integer	No
risk_manager_id	query	integer	No
limit	query	integer	No	Default 25, max 100.
cursor	query	string	No

Example

Request cURL

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

Response JSON

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

Responses

Status	Meaning
200	Clients

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

POST /api/v1/clients Flexysure only

Create a client

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.

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
type	string	No	Default individual. One of: `individual`, `corporate`
name	string	Yes	Example: `Wanjiru Kamau`
phone	string	Yes	Kenyan mobile. Checked for duplicates. Example: `0712345678`
email	string	No	Example: `wanjiru@example.com`
id_no	string	No	National ID / passport. Checked for duplicates. Example: `27845123`
kra_pin	string	No	KRA PIN. Checked for duplicates. Example: `A001234567Z`
date_of_birth	string	No	Y-m-d.
physical_address	string	No
branch_id	integer	No	GET /branches. Defaults to the acting user's branch.
risk_manager_id	integer	No	GET /risk-managers.
sales_person_id	integer	No	GET /sales-people. The salesperson sees the client (and its policies and claims).
business_source_id	integer	No
prospect_type_id	integer	No
sector	string	No
alt_name	string	No	Alternative contact.
alt_phone	string	No
alt_email	string	No
force	boolean	No	Create or save even when another client has the same phone, ID number or KRA PIN.

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/clients' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: a42cbdb5-89a1-4757-a314-467ddc61e6b1' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "individual",
    "name": "Wanjiru Kamau",
    "phone": "0712345678",
    "id_no": "27845123",
    "email": "wanjiru@example.com",
    "sales_person_id": 4
}'

Request body (JSON)

Request body JSON

{
    "type": "individual",
    "name": "Wanjiru Kamau",
    "phone": "0712345678",
    "id_no": "27845123",
    "email": "wanjiru@example.com",
    "sales_person_id": 4
}

Response JSON

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

Responses

Status	Meaning
201	Client created
409	`duplicate_client`: `matches[]` lists `{client_no, name, matched[]}` (name hidden from agents for clients they cannot see)
422	Validation failed

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

GET /api/v1/clients/{client_no} Flexysure only

Get a client

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
client_no	path	string	Yes	Client number. Example: `C-00042`

Example

Request cURL

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

Response JSON

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

Responses

Status	Meaning
200	Client
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/clients/{client_no} Flexysure only

Update a client

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.

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
client_no	path	string	Yes	Client number. Example: `C-00042`

Body fields

Field	Type	Required	Description
type	string	No	One of: `individual`, `corporate`
name	string	No
phone	string	No
email	string	No	Example: `wanjiru@example.com`
id_no	string	No	National ID / passport. Checked for duplicates. Example: `27845123`
kra_pin	string	No	KRA PIN. Checked for duplicates. Example: `A001234567Z`
date_of_birth	string	No	Y-m-d.
physical_address	string	No
branch_id	integer	No	GET /branches. Defaults to the acting user's branch.
risk_manager_id	integer	No	GET /risk-managers.
sales_person_id	integer	No	GET /sales-people. The salesperson sees the client (and its policies and claims).
business_source_id	integer	No
prospect_type_id	integer	No
sector	string	No
alt_name	string	No	Alternative contact.
alt_phone	string	No
alt_email	string	No
force	boolean	No	Create or save even when another client has the same phone, ID number or KRA PIN.

Example

Request cURL

curl -X PATCH 'https://flexysure.intrepidprojects.co.ke/api/v1/clients/C-00042' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 36b1568f-edef-4549-a4d4-f2fc1e5cb224' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "wanjiru.kamau@example.com",
    "physical_address": "Lavington, Nairobi"
}'

Request body (JSON)

Request body JSON

{
    "email": "wanjiru.kamau@example.com",
    "physical_address": "Lavington, Nairobi"
}

Response JSON

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

Responses

Status	Meaning
200	Updated client
404	Not found
409	`duplicate_client`
422	Validation failed

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