REST API · v1

The SMS API for Ghanaian websites.

Send SMS from your shop, school portal, church app or booking system. Each send uses the credits on your AkotoCreative account, with the same prices and refunds as the dashboard.

Get your API key Create free account

curl -X POST https://akotoansahcrafix.netlify.app/api/v1/sms/send \
  -H "Authorization: Bearer akc_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "AmaFabrics",
    "message": "Your order #1042 is ready for pickup.",
    "recipients": ["0241234567", "0201234567"]
  }'

Base URL

base url

https://akotoansahcrafix.netlify.app/api/v1

All requests and responses use JSON. Successful responses look like { "ok": true, "data": { … } }. Errors look like { "ok": false, "error": { "code", "message" } } with a matching HTTP status.

Authentication

Create an API key under Dashboard → API keys. The full key is shown only once, so store it somewhere safe, such as an environment variable on your server. Send it in the Authorization header of every request:

header

Authorization: Bearer akc_live_YOUR_KEY

Call the API from your server (PHP, Node.js, Python and so on), never from browser JavaScript. Anyone who can see your key can spend your credits. If a key leaks, revoke it in your dashboard straight away.

Send SMS

POST/api/v1/sms/send

Sends one message to up to 5,000 Ghanaian numbers. Numbers can be written as 024…, +233… or 233…. Duplicates are removed and invalid numbers are skipped and listed in the response. Credits are taken before sending, and any batch the network rejects is refunded.

Field	Type	Description
sender_id	string	An approved sender ID on your account (3–11 letters or numbers).
message	string	The text to send. Up to 6 SMS parts (918 characters).
recipients	string[] or string	Phone numbers as an array, or one string separated by commas or new lines.

200 response

{
  "ok": true,
  "data": {
    "id": 1287,
    "status": "sent",
    "recipients": 2,
    "delivered": 2,
    "segments": 1,
    "credits_used": 2,
    "invalid_recipients": []
  }
}

status is sent when every number was accepted, or partial when some batches failed and were refunded. Cost is the number of recipients × SMS parts. A part is 160 standard characters, or 70 when the message has emoji or special letters.

Check a send

GET/api/v1/messages/{id}

Returns the result of an earlier send, using the id from the send response.

200 response

{
  "ok": true,
  "data": {
    "id": 1287,
    "status": "sent",
    "sender_id": "AmaFabrics",
    "message": "Your order #1042 is ready for pickup.",
    "recipients": 2,
    "segments": 1,
    "credits_used": 2,
    "error": null,
    "created_at": "2026-10-24T09:41:00.000Z"
  }
}

Balance

GET/api/v1/balance

Your remaining SMS credits. Top up in the dashboard with Mobile Money or card.

200 response

{ "ok": true, "data": { "credits": 4820 } }

Sender IDs

GET/api/v1/sender-ids

Sender IDs you can send with right now. Request new ones in your dashboard. They are registered with the networks before they are approved.

200 response

{ "ok": true, "data": { "sender_ids": ["AmaFabrics"] } }

Errors

Check the HTTP status and the error.code field. Messages are safe to show to your staff.

Status	Code	Meaning
401	unauthorized	The API key is missing, wrong or revoked.
400	invalid_json	The request body is not valid JSON.
422	invalid_request	A field is missing or has the wrong format.
422	no_valid_recipients	None of the numbers are valid Ghana phone numbers.
422	too_many_recipients	More than 5,000 numbers in one request.
422	message_too_long	The message is longer than 6 SMS parts.
402	insufficient_credits	Your balance is too low for this send. Nothing was sent.
403	sender_id_not_approved	The sender ID is not approved for your account.
502	delivery_failed	The network rejected every batch. All credits were refunded.
500	server_error	Something went wrong on our side. Try again shortly.