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

⬇ Download Postman collectionImport into Postman, set baseUrl + apiKey, and test in minutes.

⚠️ route is required on every send — pass PROMOTIONAL or TRANSACTIONAL.

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://sms.vasacquico.com/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	required	PROMOTIONAL or TRANSACTIONAL (transactional requires approval).
reference	string	optional	Your own unique id (max 64). Auto-generated if omitted. Use it to check status; a repeat send with the same reference returns the original (not re-sent).

Example request

cURL

curl -X POST https://sms.vasacquico.com/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": "TRANSACTIONAL",
    "reference": "order-12345"
  }'

Node.js

const res = await fetch("https://sms.vasacquico.com/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",
    "reference": "order-12345",
    "to": "2348031234567",
    "senderId": "MobiBlast",
    "route": "PROMOTIONAL",
    "segments": 1,
    "amountCharged": "1",
    "status": "QUEUED"
  }
}

Send bulk SMS

Send the same message to a saved contact group or an explicit list of numbers. Funds 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	required	PROMOTIONAL or TRANSACTIONAL.

cURL

curl -X POST https://sms.vasacquico.com/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,
    "amountReserved": "2",
    "status": "QUEUED"
  }
}

Message status

Fetch the current delivery status of a message by its system ID or your own reference.

GET/api/v1/messages/{id-or-reference}

cURL

# by system id
curl https://sms.vasacquico.com/api/v1/messages/68f5955d-7bd5-48f2-8665-e5775cfd0a13 \
  -H "Authorization: Bearer vak_live_xxx"

# …or by your own reference
curl https://sms.vasacquico.com/api/v1/messages/order-12345 \
  -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://sms.vasacquico.com/api/v1/balance -H "Authorization: Bearer vak_live_xxx"

200 OK

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

Routes

Declare a route on each send:

PROMOTIONAL

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

TRANSACTIONAL

Premium delivery for transactional SMS; reaches DND numbers. Requires account approval and costs more 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

The body reference field gives the same safety without a header: a repeat send with a reference you've already used returns the original message. Use reference when you also want a permanent id to check status by; use Idempotency-Key for pure retry safety.

Errors

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

Error response

{
  "status": false,
  "message": "FAILED",
  "data": "Insufficient balance"
}

Field	Type	Required	Description
401	auth	optional	Missing or invalid API key.
400	validation	optional	Bad input — e.g. invalid phone number or insufficient balance.
403	forbidden	optional	Transactional 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