MobiBlast API v1

Developer documentation

Send SMS to any Nigerian network directly from your application. The MobiBlast API is a simple JSON REST API — create an API key, POST a message, and you’re live. This guide covers everything you need to integrate in minutes.

⚡

Fast

Sub-second submission to the gateway

🔁

Idempotent

Safe retries, no double sends

📩

Delivery reports

Track every message end to end

Authentication

Every request is authenticated with an API key sent as a Bearer token. Create and manage keys in your dashboard under Settings → API Keys. Keep your keys secret — they carry your account’s sending privileges and balance.

Authorization header

Authorization: Bearer vak_live_xxxxxxxxxxxxxxxxxxxxxxxx

You can also pass the key in an x-api-key header. All responses use the envelope { status, message, data }.

Base URL

All endpoints are versioned under /api/v1.

Base URL

https://api.mobiblast.ng/api/v1

# Local development
https://smsapi.hyelda.org/api/v1

Send a single SMS

Submit one message to a single recipient. Nigerian numbers in any format (080…, 234…, +234…) are normalised automatically.

POST/api/v1/messages

Body parameters

Field	Type	Required	Description
to	string	required	Recipient phone number (080…, 234…, or +234…).
message	string	required	The message text. Long messages are split into pages automatically.
senderId	string	optional	An approved sender ID. Defaults to the platform sender.
route	string	optional	PROMOTIONAL (default) or CORPORATE (requires approval).

Example request

cURL

curl -X POST https://smsapi.hyelda.org/api/v1/messages \
  -H "Authorization: Bearer vak_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345" \
  -d '{
    "to": "08031234567",
    "message": "Your OTP is 123456",
    "route": "CORPORATE"
  }'

Node.js

const res = await fetch("https://smsapi.hyelda.org/api/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": "Bearer vak_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "08031234567",
    message: "Your OTP is 123456",
    route: "PROMOTIONAL",
  }),
});
const { data } = await res.json();
console.log(data.messageId, data.status);

Response

200 OK

{
  "status": 200,
  "message": "Queued",
  "data": {
    "messageId": "68f5955d-7bd5-48f2-8665-e5775cfd0a13",
    "to": "2348031234567",
    "senderId": "MobiBlast",
    "route": "PROMOTIONAL",
    "segments": 1,
    "unitsCharged": "1",
    "status": "QUEUED"
  }
}

Send bulk SMS

Send the same message to a saved contact group or an explicit list of numbers. Units are reserved up-front and the campaign is fanned out and throttled for you.

POST/api/v1/messages/bulk

Field	Type	Required	Description
message	string	required	The message text.
numbers	string[]	optional	Explicit recipient list (use this OR groupId).
groupId	string	optional	A contact group ID to send to.
name	string	optional	Campaign label (defaults to “API campaign”).
senderId	string	optional	Approved sender ID.
route	string	optional	PROMOTIONAL or CORPORATE.

cURL

curl -X POST https://smsapi.hyelda.org/api/v1/messages/bulk \
  -H "Authorization: Bearer vak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Weekend sale — 30% off!",
    "numbers": ["08031110001", "08052220002"],
    "route": "PROMOTIONAL"
  }'

200 OK

{
  "status": 200,
  "message": "Queued",
  "data": {
    "campaignId": "20d604c3-98ae-48f1-adb3-d86ed41925f3",
    "billable": 2,
    "dndBlocked": 0,
    "unitsReserved": "2",
    "status": "QUEUED"
  }
}

Message status

Fetch the current delivery status of a message by its ID.

GET/api/v1/messages/{id}

cURL

curl https://smsapi.hyelda.org/api/v1/messages/68f5955d-7bd5-48f2-8665-e5775cfd0a13 \
  -H "Authorization: Bearer vak_live_xxx"

Statuses progress: QUEUED → SENT → DELIVERED, or FAILED / DND_BLOCKED.

Check balance

Return your current credit-unit balance.

GET/api/v1/balance

cURL

curl https://smsapi.hyelda.org/api/v1/balance -H "Authorization: Bearer vak_live_xxx"

200 OK

{ "status": 200, "message": "OK", "data": { "units": "2999" } }

Routes

Declare a route on each send:

PROMOTIONAL

Default. Best value for marketing. Cannot reach DND-registered numbers.

CORPORATE

Premium delivery for transactional SMS; reaches DND numbers. Requires account approval and costs more units per page.

Idempotency

Pass an Idempotency-Key header on single sends. If you retry the same request with the same key, the original result is returned and the message is not sent or charged twice — perfect for safe retries on flaky networks.

Header

Idempotency-Key: order-12345

Errors

Failures return a consistent envelope with an appropriate HTTP status code.

Error response

{
  "status": false,
  "message": "FAILED",
  "data": "Insufficient credit units"
}

Field	Type	Required	Description
401	auth	optional	Missing or invalid API key.
400	validation	optional	Bad input — e.g. invalid phone number or insufficient units.
403	forbidden	optional	Corporate route not enabled, or account suspended.
404	not found	optional	Message or resource not found.

Ready to build?

Grab a test key and send your first message in minutes.

Get your API key