SMS API Documentation — REST API for SMS Gateway

Authentication

All API requests require authentication using an API key. Include your API key in the request header or as a query parameter. You can generate an API key from your account dashboard after registration.

Code Examples

GET /v1/account HTTP/1.1
Host: api.zancommunication.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

<?php
$apiKey = 'YOUR_API_KEY';
$headers = [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json',
];

import requests

api_key = 'YOUR_API_KEY'
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

Send SMS

Use this endpoint to send a single SMS message to one recipient. For bulk sending to multiple recipients, see the Bulk SMS endpoint.

POST https://api.zancommunication.com/v1/send Send Single SMS

Send an SMS message to a single recipient.

Parameters

Name	Type	Required	Description
`to`*	string	Required	Recipient phone number (with country code, e.g., 8801712345678)
`message`*	string	Required	SMS message content (max 160 characters for single SMS)
`sender_id`	string	Optional	Custom sender ID or mask name (if masking SMS is enabled)
`type`	string	Optional	SMS type: 'text' (default) or 'unicode' for Bengali/special characters

✓ Success Response

JSON

{
  "status": "success",
  "message_id": "ZAN_MSG_20250101_001",
  "to": "8801712345678",
  "queued_at": "2025-01-01T10:00:00Z",
  "credits_used": 1
}

✗ Error Response

JSON

{
  "status": "error",
  "code": "INVALID_RECIPIENT",
  "message": "The recipient phone number is invalid."
}

POST https://api.zancommunication.com/v1/send/bulk Send Bulk SMS

Send SMS to multiple recipients in a single API call.

Parameters

Name	Type	Required	Description
`recipients`*	array	Required	Array of recipient phone numbers
`message`*	string	Required	SMS message content
`sender_id`	string	Optional	Custom sender ID (if masking enabled)
`schedule_at`	string	Optional	ISO 8601 datetime to schedule the SMS

✓ Success Response

JSON

{
  "status": "success",
  "campaign_id": "ZAN_CAMP_20250101_001",
  "total_recipients": 1000,
  "queued": 1000,
  "credits_used": 1000
}

✗ Error Response

JSON

{
  "status": "error",
  "code": "INSUFFICIENT_CREDITS",
  "message": "Your account does not have enough credits."
}

Code Examples

<?php
$apiKey = 'YOUR_API_KEY';
$url = 'https://api.zancommunication.com/v1/send';

$data = [
    'to'      => '8801712345678',
    'message' => 'Your OTP is 123456. Valid for 5 minutes.',
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

echo $result['message_id'];

import requests

api_key = 'YOUR_API_KEY'
url = 'https://api.zancommunication.com/v1/send'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

payload = {
    'to': '8801712345678',
    'message': 'Your OTP is 123456. Valid for 5 minutes.'
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()
print(result['message_id'])

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const url = 'https://api.zancommunication.com/v1/send';

const response = await axios.post(url, {
  to: '8801712345678',
  message: 'Your OTP is 123456. Valid for 5 minutes.'
}, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

console.log(response.data.message_id);

curl -X POST https://api.zancommunication.com/v1/send \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "8801712345678",
    "message": "Your OTP is 123456. Valid for 5 minutes."
  }'

Delivery Report

Check the delivery status of a sent message using its message ID. You can also configure a webhook URL in your account dashboard to receive real-time delivery callbacks.

GET https://api.zancommunication.com/v1/report/{message_id} Get Delivery Status

Retrieve the delivery status of a specific message by its ID.

Parameters

Name	Type	Required	Description
`message_id`*	string	Required	The message ID returned when the SMS was sent

✓ Success Response

JSON

{
  "status": "success",
  "message_id": "ZAN_MSG_20250101_001",
  "to": "8801712345678",
  "delivery_status": "delivered",
  "sent_at": "2025-01-01T10:00:00Z",
  "delivered_at": "2025-01-01T10:00:02Z",
  "credits_used": 1
}

✗ Error Response

JSON

{
  "status": "error",
  "code": "MESSAGE_NOT_FOUND",
  "message": "No message found with the provided ID."
}

Code Examples

<?php
$apiKey = 'YOUR_API_KEY';
$messageId = 'ZAN_MSG_20250101_001';
$url = 'https://api.zancommunication.com/v1/report/' . $messageId;

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $result['delivery_status']; // 'delivered', 'failed', 'pending'

{
  "event": "delivery_update",
  "message_id": "ZAN_MSG_20250101_001",
  "to": "8801712345678",
  "delivery_status": "delivered",
  "delivered_at": "2025-01-01T10:00:02Z",
  "carrier": "Grameenphone"
}

Account & Balance

Retrieve your account information and SMS credit balance.

GET https://api.zancommunication.com/v1/account/balance Check Balance

Get the current SMS credit balance for your account.

✓ Success Response

JSON

{
  "status": "success",
  "credits": 45230,
  "currency": "BDT",
  "plan": "non-masking"
}

✗ Error Response

JSON

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired API key."
}

Error Codes

When an API request fails, the response body will contain an error code and a human-readable message. Use the error code to handle specific failure scenarios programmatically.

Error Code	HTTP Status	Description
UNAUTHORIZED	401	API key is missing, invalid, or expired.
INVALID_RECIPIENT	422	The recipient phone number format is invalid.
INVALID_MESSAGE	422	Message content is empty or exceeds maximum length.
INSUFFICIENT_CREDITS	402	Your account does not have enough SMS credits.
RATE_LIMIT_EXCEEDED	429	You have exceeded the API rate limit. Slow down requests.
SENDER_ID_INVALID	422	The sender ID / mask name is not registered or invalid.
MESSAGE_NOT_FOUND	404	No message found with the provided message ID.
SERVER_ERROR	500	An internal server error occurred. Contact support if persistent.