API reference

Send SMS

POST /api/v1/json/bulk/sms sends one message to up to 2,000 recipients and returns a message ID per recipient. Parameters, examples in four languages, and every response you can get back.

POST/api/v1/json/bulk/sms

Send one SMS message to one or more recipients. Requires an API key (see Authentication).

Parameters

Parameter	Type	Description
`from` Required	string	A sender ID registered and active on your account for SMS (2 to 11 characters). Matched case-insensitively. Example: `Unicom360`
`to` Required	string \| string[]	One number, or an array of 1 to 2,000 numbers, in international format without a plus sign (260971234567). A leading plus sign or a local 09x/07x prefix is accepted and normalised. Example: `["260971234567", "260961234567"]`
`message` Required	string	The text, 1 to 1,200 characters, GSM 7-bit characters only. Billed in 160-character units. Example: `Your verification code is 482193. It expires in 5 minutes.`
`user_reference_id` Optional	string	Your own reference for this send. A reference already used for the same recipient and sender ID is refused, which makes retries safe. Example: `order-10421`
`callback_url` Optional	string	HTTPS URL that receives a POST with the delivery status of each message. See Delivery webhooks. Example: `https://example.com/webhooks/unicom360/sms`
`source` Optional	string	A label for the system that sent the message, shown in your reports. Example: `crm`

fromRequiredstring: A sender ID registered and active on your account for SMS (2 to 11 characters). Matched case-insensitively.
Example: Unicom360
toRequiredstring | string[]: One number, or an array of 1 to 2,000 numbers, in international format without a plus sign (260971234567). A leading plus sign or a local 09x/07x prefix is accepted and normalised.
Example: ["260971234567", "260961234567"]
messageRequiredstring: The text, 1 to 1,200 characters, GSM 7-bit characters only. Billed in 160-character units.
Example: Your verification code is 482193. It expires in 5 minutes.
user_reference_idOptionalstring: Your own reference for this send. A reference already used for the same recipient and sender ID is refused, which makes retries safe.
Example: order-10421
callback_urlOptionalstring: HTTPS URL that receives a POST with the delivery status of each message. See Delivery webhooks.
Example: https://example.com/webhooks/unicom360/sms
sourceOptionalstring: A label for the system that sent the message, shown in your reports.
Example: crm

Example request

curl -X POST https://api.unicom360.com/api/v1/json/bulk/sms \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Unicom360",
    "to": ["260971234567", "260961234567"],
    "message": "Your verification code is 482193. It expires in 5 minutes.",
    "callback_url": "https://example.com/webhooks/unicom360/sms"
  }'

Responses

200 acceptedjson

{
  "api_reference": "1764184470578998353",
  "data": [
    {
      "message_id": "dff31690-b450-4000-a6b7-141d8523ef10",
      "status": "ACKNOWLEDGED",
      "mobile_number": "260971234567"
    },
    {
      "message_id": "dff31690-b450-4001-a6b7-141d8523ef10",
      "status": "ACKNOWLEDGED",
      "mobile_number": "260961234567"
    }
  ],
  "message": "successful",
  "success": true
}

One entry per recipient, but not in the order given once a request has more than ten recipients. Match each entry to its recipient by mobile_number, never by position: it is the number as the gateway normalised it (260971234567 for +260971234567 or 0971234567), or as you sent it when it could not be parsed. status is ACKNOWLEDGED for a number the gateway accepted, or Invalid mobile number for one it could not parse. Keep message_id: delivery callbacks and the portal refer to it.

200 business errorjson

{
  "message": "INSUFFICIENT_BUNDLE",
  "success": false,
  "api_reference": "1764184470578998353"
}

The request was well formed but could not be sent. The HTTP status is still 200: check success, not the status code. Other messages: Invalid From Sender ID, From Sender ID not allowed, Recipient list size is invalid, duplicate user reference id, Invalid parameters provided.

400 validation errorjson

{
  "message": "Missing required keys: [\"message\"]",
  "success": false,
  "api_reference": "1764184470578998353"
}

A required field is missing or has the wrong type. Nothing was sent.

401 authentication errorjson

{
  "message": "AUTHENTICATION_FAILED",
  "success": false,
  "api_reference": "1764184470578998353"
}

See Authentication for every code. A credential over its per-minute limit gets 429 with RATE_LIMIT_EXCEEDED.

Notes

Requests with up to five recipients are handed to the carrier immediately; larger batches are queued and drained continuously.
Zambian numbers (prefix 260) are delivered on all networks. Numbers outside Zambia bill against a separate international SMS bundle and are only accepted in requests of up to five recipients; in larger batches they come back with status Invalid mobile number.
If any recipient row fails validation (for example a message over 1,200 characters or containing non-GSM characters) the whole request is refused with Invalid parameters provided and nothing is sent.

Before you send

from must be a sender ID that is registered on your account for SMS and approved. See Sender IDs.
The text must be GSM 7-bit and at most 1,200 characters; it is billed per 160 characters. See Message text.
Send user_reference_id on anything you might retry. See Your own reference.

Tracking delivery

ACKNOWLEDGED is acceptance, not delivery. Give a callback_url to be told when each message is SENT, DELIVERED or FAILED; the payload carries the same message_id this response returns. See Delivery webhooks.