Developers · REST API

Evaluate the API in five minutes.

One key, one endpoint, your own phones doing the sending. Everything below runs against https://kisoasms.marindrano.com.

Full API reference OpenAPI document

The full reference lives in the dashboard and needs sign-in; the OpenAPI document is public.

The whole API on one card

Base URL: https://kisoasms.marindrano.com/v1
Auth: Authorization: Bearer kiso_…
Send: POST /v1/messages
Status: GET /v1/messages/{id}
Batch: up to 500 recipients
Quota: 1,000 / day by default

01 · Authentication

One key in one header.

Create a scoped API key in the dashboard — it is shown once, then stored hashed. Send it as a bearer token on every request.

Authentication

curl https://kisoasms.marindrano.com/v1/messages \
  -H "Authorization: Bearer kiso_live_4f8a2c1d9e6b7a03"

Scope each key to the integration that uses it, set an expiry, and rotate or revoke it any time. Requests without a valid key are rejected before anything else happens.

02 · Send

POST once, track each message.

Send to one number or up to 500. Each recipient becomes its own message with its own id and status.

Send — request

curl -X POST https://kisoasms.marindrano.com/v1/messages \
  -H "Authorization: Bearer kiso_live_4f8a2c1d9e6b7a03" \
  -H "Content-Type: application/json" \
  -d '{"to": ["+261 34 12 345 67"], "text": "Votre code est le 482 913"}'

Send — response

{
  "id": "msg_01h9k4b2c7d3e5f6",
  "status": "queued"
}

GSM-7 and Unicode are both accepted; long SMS is split into segments, up to 1,600 characters.
Choose a specific phone and SIM, or let any eligible phone take the message.
Resend a message, or cancel it before it goes out.

03 · Status

Read the status any time.

Poll the message, or let a webhook tell you. Either way the status is one of nine values.

Status — request

curl https://kisoasms.marindrano.com/v1/messages/msg_01h9k4b2c7d3e5f6 \
  -H "Authorization: Bearer kiso_live_4f8a2c1d9e6b7a03"

Status — response

{
  "id": "msg_01h9k4b2c7d3e5f6",
  "status": "delivered"
}

queued
claimed
sending
sent
delivered
failed
expired
cancelled
unknown

The happy path runs queued → claimed → sending → sent → delivered. Anything else — failed, expired, cancelled, unknown — is terminal and stays readable on the message.

04 · Webhooks

Signed callbacks with retries.

Point a webhook at your HTTPS endpoint and Kisoasms calls it on every event you subscribe to, retrying failures and keeping a delivery log you can replay.

Webhook — example payload

{
  "event": "message.delivered",
  "data": {
    "id": "msg_01h9k4b2c7d3e5f6",
    "status": "delivered"
  }
}

message.queued
message.claimed
message.sending
message.sent
message.delivered
message.failed
message.expired
message.cancelled
message.unknown
incoming.received
mobile_money.detected

05 · Idempotency

Retry without double-sending.

Attach an idempotency key to a send request. If the connection drops and you retry with the same key, you get the original message back — not a second SMS your customer pays for twice.

1 · Generate a unique key per message you intend to send once — a UUID works.
2 · Send it with the request. The first send creates the message.
3 · Retry with the same key as often as you need; only the first request sends.

06 · Limits

Quotas you can plan around.

Guardrails, stated up front — not discovered at 2 a.m. when a campaign goes out.

1,000 a day by default: Each organization sends up to 1,000 messages a day, configurable up to 100,000.
500 recipients per request: One POST carries up to 500 numbers; each becomes its own message with its own status.
1,600 characters: GSM-7 and Unicode accepted, long SMS split into segments, up to 1,600 characters per message.
24-hour expiry: Messages no phone can send expire from the queue after 24 hours and read expired.

07 · Errors

Failures stay visible.

Two kinds of failure, both readable on the message or the response — never silent.

Rejected requests
Missing or invalid keys, malformed bodies, over-quota sends — rejected before any phone is involved, with the reason in the response.
Failed messages
A message the network refuses reads failed; one no phone claims in time reads expired; a withdrawn one reads cancelled. Poll the status or catch the matching webhook.
Missed webhooks
Failed deliveries are retried and kept in the delivery log, so replay them instead of guessing what you missed.

Read the full reference next.

Every endpoint, field and event, rendered from the same OpenAPI document the API is validated against — so it cannot drift from what the gateway actually does.