SMS API reference

Endpoints

Request fields

*Supply either recipient or recipients. The single endpoint accepts both; the bulk endpoint expects recipients.

curl -X POST https://api.sendozi.com/v1/sms/send \
  -H "Authorization: Bearer $SENDOZI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-48291-otp" \
  -d '{
    "sender": "Sendozi",
    "recipient": "+2348012345678",
    "message": "Your Northstar code is [code]. It expires in [minutes] minutes.",
    "template_id": "tpl_your_approved_otp_template",
    "event_type": "otp",
    "event_reference": "login-user_42-attempt_003",
    "route": "transactional"
  }'

curl -X POST https://api.sendozi.com/v1/sms/bulk \
  -H "Authorization: Bearer $SENDOZI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campaign-2026-08-21" \
  -d '{
    "sender": "Sendozi",
    "recipients": ["+2348012345678", "+2349012345678", "+2347012345678"],
    "message": "Term two resumes on Monday 8 September. Fees are due by Friday.",
    "route": "promotional"
  }'

Choosing a route

Every SMS request must declare route as either "transactional" or "promotional". Sendozi does not default it, because the two travel different routes with different delivery behaviour against the Nigerian DND register.

• "transactional" and its alias "otp" select the corporate route: OTPs, alerts, receipts and service notices, which reach DND-active subscribers.
• "promotional" and its alias "promo" select the marketing route, which the networks filter for DND-active subscribers.
• Anything else returns 400 invalid_request with a resolution naming the two valid values.
• Both routes bill at the same rate. The route affects delivery, not price.
• A sender ID is approved for one route, against the sample message in its request letter. A send whose sms_type does not match its sender ID's route returns 403 sender_id_route_mismatch before the wallet is touched, in both directions.
• Sender IDs created before the routes were separated report sms_route: "unclassified" and cannot send on either route. They return 403 sender_id_unclassified until Sendozi Operations records the route the operator approved, or you resubmit under the correct one.
• Transactional API requests accept exactly one submitted recipient. An array, comma-separated list, or a duplicated number returns 400 transactional_bulk_not_allowed before any wallet reservation or provider dispatch.

The transactional versus promotional guide works through the grey cases; the DND guide explains the register itself.

Recipient format

Nigerian mobile numbers only. Sendozi accepts 08012345678, 8012345678, 2348012345678 and +2348012345678, normalizes each to E.164, and rejects invalid or international numbers.

Cost and pages

SMS is billed per page, resolved from the character count of the whole message, at ₦7.00 per page. The response carries customer_price_kobo so you always know what a send cost - including in sandbox, where it is reported but not charged.

Message response

{
  "success": true,
  "data": {
    "message_id": "msg_1f4c0a2b",
    "channel": "sms",
    "mode": "production",
    "sender": "Sendozi",
    "recipient": "+2348012345678",
    "sms_type": "transactional",
    "status": "submitted",
    "status_timeline": [
      { "status": "accepted", "at": "2026-08-21T09:14:20.004Z" },
      { "status": "submitted", "at": "2026-08-21T09:14:21.882Z" }
    ],
    "request_id": "req_8ecdcb4ce2ae4290",
    "customer_price_kobo": 700,
    "created_at": "2026-08-21T09:14:20.004Z",
    "sent_at": "2026-08-21T09:14:21.882Z",
    "delivered_at": null
  },
  "request_id": "req_8ecdcb4ce2ae4290"
}

status moves from accepted to submitted to delivered or failed. Read delivery reports and webhooks before building anything that reacts to it.

Sender IDs

GET /v1/sms/sender-ids returns the sender IDs registered for your workspace with their status per network. A production send using an unapproved sender is refused with sender_id_not_approved rather than being rerouted under another name. Registration itself happens in the Console; see the sender ID guide.

What can stop a production send

Production sends run thirteen checks in a fixed order and return the first failure without charging. Sandbox sends run the first four only.

1. Platform maintenance mode - provider_not_configured
2. Recipients valid for the channel - invalid_recipient
3. Content passes policy checks - message_policy_violation
4. No recipient is suppressed - recipient_suppressed
5. API key is active - api_key_blocked
6. Workspace is active - workspace_suspended
7. KYC approved and production access granted - kyc_required
8. Channel active for the workspace - channel_not_active
9. Sender ID approved - sender_id_not_approved
10. Wallet exists and is not frozen - wallet_frozen
11. Balance covers the estimated cost - insufficient_balance
12. Provider available - provider_not_configured