API documentation

Quick start

1. Create a merchant account. A free trial is set up automatically.
2. Open API tokens in the dashboard and generate a token. Copy it right away; it is shown once.
3. Send your first message:

curl -X POST https://ms.cartela-bingo.com/api/v1/sms/send \
  -H "Authorization: Bearer alr_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+251911223344",
    "message": "Your code is 482913"
  }'

Authentication

Authenticate every request with your merchant token in the Authorization header. Tokens start with alr_.

Authorization: Bearer alr_your_token

Tokens are tied to your merchant account and can only reach your own messages and account. Revoking a token in the dashboard takes effect immediately. Keep tokens on your server; never ship them in a browser or mobile app.

Send SMS

POST https://ms.cartela-bingo.com/api/v1/sms/send queues one message per recipient for delivery.

Response — 202 Accepted

{
  "ok": true,
  "data": {
    "batchId": "batch_9f2c…",
    "messages": [
      { "id": "5c5b7556-b6b9-4e91-9e41-8e105582becb", "to": "+251911223344", "status": "queued" }
    ],
    "quota": { "limit": 2000, "used": 18, "remaining": 1982 }
  }
}

A 202 means the message is queued, not yet delivered. Use the message id to check status below.

Message status

GET https://ms.cartela-bingo.com/api/v1/sms/:id

{
  "ok": true,
  "data": {
    "id": "5c5b7556-b6b9-4e91-9e41-8e105582becb",
    "to": "+251911223344",
    "message": "Your code is 482913",
    "status": "delivered",
    "deliveryStatus": "delivered",
    "createdAt": "2026-10-07T20:03:11.000Z",
    "updatedAt": "2026-10-07T20:03:14.000Z"
  }
}

List and filter your messages with GET https://ms.cartela-bingo.com/api/v1/sms?status=failed&limit=50&page=1 (also accepts ids=id1,id2).

Statuses progress queued → pending (being processed) → sent → delivered, or failed. You can only read messages sent by your own account.

Retry failed SMS

POST https://ms.cartela-bingo.com/api/v1/sms/:id/retry puts a failed message back in the queue. To retry several at once use POST https://ms.cartela-bingo.com/api/v1/sms/retry:

curl -X POST https://ms.cartela-bingo.com/api/v1/sms/retry \
  -H "Authorization: Bearer alr_your_token" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["5c5b7556-b6b9-4e91-9e41-8e105582becb"] }'

{ "ok": true, "data": { "retried": ["5c5b7556-…"], "skipped": [] } }

Only failed messages are retried; others are listed in skipped. A retry reuses the original message, so it does not use extra quota.

Bulk upload

Send to many recipients from a spreadsheet. POST https://ms.cartela-bingo.com/api/v1/sms/bulk accepts an .xlsx or .csv file (up to 1,000 rows, 2 MB). Column 1 is the phone number and column 2 is an optional message of up to 100 characters; a header row is detected automatically. You can also upload from the Bulk upload page in your dashboard.

curl -X POST https://ms.cartela-bingo.com/api/v1/sms/bulk \
  -H "Authorization: Bearer alr_your_token" \
  -F "file=@recipients.xlsx" \
  -F "message=Your order has shipped"   # default for rows without a message
  # add -F dryRun=1 to validate the file without sending

Valid rows are queued; invalid rows come back in rejected with the row number and the reason. If the valid rows would exceed your quota nothing is queued and you receive 429 quota_exceeded. JSON is also accepted: { "messages": [{ "to": "+2519…", "message": "Hi" }] }.

Account & usage

GET https://ms.cartela-bingo.com/api/v1/account returns your plan, quota and current usage.

{
  "ok": true,
  "data": {
    "merchant": { "id": "…", "businessName": "Acme Ltd", "status": "active" },
    "plan": { "name": "Starter", "status": "active", "smsQuota": 2000, "tokenLimit": 3 },
    "usage": { "smsSent": 18, "tokens": 2 }
  }
}

Errors

Failed requests return a non-2xx status and a machine-readable code:

{ "ok": false, "error": { "code": "quota_exceeded", "message": "Plan SMS quota exceeded", "remaining": 0 } }

Quotas & limits

• Each plan includes a number of SMS per billing period and an API token limit.
• Up to 100 recipients per request and 100 characters per message.
• Free trial accounts always send the default message Test123, whatever text you supply. Subscribe to a plan to send your own content.
• When a request would exceed your quota nothing is queued and you receive 429 quota_exceeded with your remaining balance.