API documentation

Base URL

All requests use HTTPS and JSON. Replace the base URL if you self-host — production:

https://aionmessaging.com/api/v1/

Authentication

Create an API key in Dashboard → API Keys. Send it on every request using either header:

X-API-Key: sk_your_key_here
Authorization: Bearer sk_your_key_here

Endpoint map

All routes below are live under https://aionmessaging.com/api/v1/ and require a valid API key. Optional channels depend on platform configuration.

Lookup: Phone lookup requires carrier lookup to be configured by the platform admin. Whatsapp: WhatsApp requires platform WhatsApp Business setup before API sends succeed. Email: Email API requires a verified customer domain and sender address. Voice: Voice API requires voice gateway credentials configured by the platform admin.

Quick start & code examples

Copy any snippet below — replace sk_YOUR_KEY and MYBRAND with your API key and approved sender ID.

Send a single SMS

POST https://aionmessaging.com/api/v1/sms/send

Body (JSON):

• to — E.164 phone number (e.g. +233545629414)
• sender_id — Your approved sender ID name
• message — Text (max 1600 characters)
• priority — Optional boolean; use true for priority/OTP route (higher rate, faster delivery)

cURL

curl -X POST "https://aionmessaging.com/api/v1/sms/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_YOUR_KEY" \
  -d '{
    "to": "+233545629414",
    "sender_id": "MYBRAND",
    "message": "Your verification code is 482910"
  }'

PHP

$ch = curl_init('https://aionmessaging.com/api/v1/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-API-Key: sk_YOUR_KEY',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'to'        => '+233545629414',
        'sender_id' => 'MYBRAND',
        'message'   => 'Your verification code is 482910',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);

JavaScript (Node / fetch)

const res = await fetch('https://aionmessaging.com/api/v1/sms/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sk_YOUR_KEY',
  },
  body: JSON.stringify({
    to: '+233545629414',
    sender_id: 'MYBRAND',
    message: 'Your verification code is 482910',
  }),
});
const data = await res.json();

Python

import requests

r = requests.post(
    'https://aionmessaging.com/api/v1/sms/send',
    headers={'X-API-Key': 'sk_YOUR_KEY'},
    json={
        'to': '+233545629414',
        'sender_id': 'MYBRAND',
        'message': 'Your verification code is 482910',
    },
    timeout=30,
)
print(r.json())

Success response (200)

{
  "success": true,
  "message_id": "12345",
  "status": "submitted",
  "cost": 0.06,
  "billed_via": "wallet",
  "balance": 42.50
}

Event package credits are used automatically when available (billed_via: "package"). Wallet is charged only when the gateway accepts the message. Failed sends return 422 with an error and no charge.

Bulk send

POST https://aionmessaging.com/api/v1/sms/bulk

{
  "to": ["+233545629414", "+233501112233"],
  "sender_id": "MYBRAND",
  "message": "Flash sale ends tonight!",
  "priority": false,
  "schedule_at": "2026-06-20 09:00:00"
}

schedule_at is optional (MySQL datetime). Set priority: true for OTP/transactional routing. Package credits are applied first; remaining messages are billed from wallet at queue time.

OTP verification

POST https://aionmessaging.com/api/v1/verify/start — send a one-time code.

{
  "phone": "+233545629414",
  "sender_id": "MYBRAND"
}

POST https://aionmessaging.com/api/v1/verify/check — validate the code.

{
  "verification_id": 42,
  "code": "482910"
}

Phone number lookup Requires setup

POST https://aionmessaging.com/api/v1/lookup/phone

{
  "phone": "+233545629414"
}

Returns valid, carrier, country, and per-lookup cost.

Message status

GET https://aionmessaging.com/api/v1/sms/{id}

curl "https://aionmessaging.com/api/v1/sms/12345" \
  -H "X-API-Key: sk_YOUR_KEY"

Returns status (queued, submitted, sent, delivered, failed), provider_status, timestamps, and cost.

Wallet balance

GET https://aionmessaging.com/api/v1/balance

curl "https://aionmessaging.com/api/v1/balance" -H "X-API-Key: sk_YOUR_KEY"

Wallet top-up

Fund the wallet that owns your API key from your own app. Checkout runs on Aion’s Paystack account — you do not need your own Paystack keys. After payment, Aion credits that account automatically.

1. POST /wallet/topup with the credit amount (wallet currency). Optionally pass return_url (HTTPS) so the user returns to your app after checkout.
2. Open the returned checkout_url in a browser or webview.
3. User pays (card / mobile money). Money settles to Aion; the pending top-up is tied to your API key’s user.
4. Poll GET /wallet/topup/{reference} until status is completed (or use return_url?reference=…&status=… then poll once).
5. Confirm with GET /balance if needed.

A service fee is added server-side (same as dashboard top-up). Paystack charges the GHS equivalent.

POST https://aionmessaging.com/api/v1/wallet/topup

curl -X POST "https://aionmessaging.com/api/v1/wallet/topup" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_YOUR_KEY" \
  -d '{
    "amount": 100.00,
    "return_url": "https://your-app.example/topup/done"
  }'

{
  "success": true,
  "reference": "TOPUP_AB12CD_1710000000",
  "checkout_url": "https://checkout.paystack.com/…",
  "currency": "GHS",
  "amount_credit": 100,
  "fee": 1.8,
  "fee_rate": 0.018,
  "total_wallet": 101.8,
  "total_charged_ghs": 101.8,
  "status": "pending"
}

GET https://aionmessaging.com/api/v1/wallet/topup/{reference}

curl "https://aionmessaging.com/api/v1/wallet/topup/TOPUP_AB12CD_1710000000" \
  -H "X-API-Key: sk_YOUR_KEY"

{
  "success": true,
  "reference": "TOPUP_AB12CD_1710000000",
  "status": "completed",
  "amount": 100,
  "type": "topup",
  "gateway": "paystack",
  "balance": 142.5,
  "currency": "GHS",
  "created_at": "2026-07-31 18:00:00"
}

Wallet transactions

GET https://aionmessaging.com/api/v1/wallet/transactions?limit=50&offset=0 — recent top-ups, debits, refunds, and adjustments for your account (limit max 100).

curl "https://aionmessaging.com/api/v1/wallet/transactions?limit=20" \
  -H "X-API-Key: sk_YOUR_KEY"

List sender IDs

GET https://aionmessaging.com/api/v1/senderids — returns approved sender IDs for your account.

Send WhatsApp Requires setup

POST https://aionmessaging.com/api/v1/whatsapp/send

curl -X POST "https://aionmessaging.com/api/v1/whatsapp/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_YOUR_KEY" \
  -d '{
    "to": "+233545629414",
    "message": "Your order #4821 is ready for pickup."
  }'

Requires WhatsApp Business to be enabled on your account and configured by the platform admin. Configure inbound webhook at POST /webhooks/whatsapp/inbound for chatbot auto-replies (requires Chatbot add-on).

Send email Available

POST https://aionmessaging.com/api/v1/email/send

curl -X POST "https://aionmessaging.com/api/v1/email/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_YOUR_KEY" \
  -d '{
    "to": "customer@example.com",
    "subject": "Receipt for your payment",
    "message": "Thank you for your purchase."
  }'

Voice call (TTS) Requires setup

POST https://aionmessaging.com/api/v1/voice/send

curl -X POST "https://aionmessaging.com/api/v1/voice/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_YOUR_KEY" \
  -d '{
    "to": "+233545629414",
    "message": "This is a reminder that your appointment is tomorrow at 9 AM."
  }'

Message status (any channel)

GET https://aionmessaging.com/api/v1/messages/{id} — same fields as SMS status, plus channel (sms, whatsapp, email, voice, ussd).

Delivery reports & webhooks

Delivery updates are captured automatically and stored on each message. Poll GET /sms/{id} or view Dashboard → Message History.

Status lifecycle: submitted → sent → delivered (or failed with automatic wallet refund).

Inbound SMS & opt-out (STOP)

Configure your SMS provider to POST inbound messages to:

POST https://aionmessaging.com/webhooks/inbound/sms

Accepted JSON/form fields: From/from, To/to (sender ID or number), Message/message. Replies appear in Dashboard → SMS Inbox.

When a recipient texts STOP, UNSUBSCRIBE, or similar keywords, they are added to your opt-out list. Single and bulk API sends to opted-out numbers return 422.

HTTP status codes

• 200 — Success
• 401 — Invalid or missing API key
• 422 — Validation error or insufficient balance
• 429 — Rate limit — retry with backoff
• 500 — Server error — retry later