SMS

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

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.

Method	Path	Summary	Scope
POST	/api/v1/sms/send	Send SMS (batch)	messaging
GET	/api/v1/sms/sent	List sent SMS	messaging
GET	/api/v1/sms/balance	SMS balance	messaging
GET	/api/v1/sms/{uuid}	Get an SMS Flexysure only	messaging

POST /api/v1/sms/send

Send SMS (batch)

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}.

Scope: messaging
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 `messaging`)
Idempotency-Key	Required. A replay returns the first response and sends nothing.
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
transaction	string	No	Default label for the batch. Example: `Renewal reminder`
sms	object[]	Yes	1 to 500 messages.
sms[].phone	string	Yes	Example: `0712345678`
sms[].message	string	Yes	Example: `Dear Wanjiru, your motor policy renews on 13 Oct.`
sms[].policy_id	integer	No	Links the message to a policy (and its client).
sms[].transaction	string	No

Example

Request cURL

curl -X POST 'https://flexysure.intrepidprojects.co.ke/api/v1/sms/send' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 29b894cc-0e5b-4b89-ab6b-6e5453c09291' \
  -H 'X-Agent-Code: KK01' \
  -H "X-Agent-Key: $AGENT_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction": "Renewal reminder",
    "sms": [
        {
            "phone": "0712345678",
            "message": "Dear Wanjiru, your motor policy renews on 13 Oct.",
            "policy_id": 123
        },
        {
            "phone": "12",
            "message": "Hello"
        }
    ]
}'

Request body (JSON)

Request body JSON

{
    "transaction": "Renewal reminder",
    "sms": [
        {
            "phone": "0712345678",
            "message": "Dear Wanjiru, your motor policy renews on 13 Oct.",
            "policy_id": 123
        },
        {
            "phone": "12",
            "message": "Hello"
        }
    ]
}

Response JSON

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

Responses

Status	Meaning
200	All sent
207	Some or all failed: see `results[].error`
422	Validation failed (missing phone/message, policy from another organisation)

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

GET /api/v1/sms/sent

List sent SMS

The organisation's SMS outbox, newest first, between from and to (inclusive; default the first of this month to today).

Scope: messaging
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Safe to repeat (read only).

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `messaging`)

Parameters

Name	In	Type	Required	Description
from	query	string	No	Y-m-d. Default first of this month.
to	query	string	No	Y-m-d. Default today.
page	query	integer	No
per_page	query	integer	No	Default 50, max 100.

Example

Request cURL

curl -X GET 'https://flexysure.intrepidprojects.co.ke/api/v1/sms/sent' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json'

Response JSON

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

Responses

Status	Meaning
200	Sent SMS

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

GET /api/v1/sms/balance

SMS balance

Units left. One unit sends one 160-character segment.

Scope: messaging
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Safe to repeat (read only).

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `messaging`)

Example

Request cURL

curl -X GET 'https://flexysure.intrepidprojects.co.ke/api/v1/sms/balance' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json'

Response JSON

{
    "status": "success",
    "balance": 4820
}

Responses

Status	Meaning
200	Balance

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

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

Get an SMS

One message from the outbox with its delivery status.

Scope: messaging
Authentication: Bearer token
Rate limit: 60 requests per minute per token (per-client override)
Idempotency: Safe to repeat (read only).

Headers

Header	Meaning
Authorization	Bearer <access_token> (scope `messaging`)

Parameters

Name	In	Type	Required	Description
uuid	path	string	Yes	From `results[].uuid` of POST /sms/send.

Example

Request cURL

curl -X GET 'https://flexysure.intrepidprojects.co.ke/api/v1/sms/{uuid}' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Accept: application/json'

Response JSON

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

Responses

Status	Meaning
200	SMS
404	Not found

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