Synqtel limited Reseller - Messaging Documentation

Overview

The SMS API allows you to send SMS messages through our bulk and shortcode messaging gateway. This documentation provides everything you need to integrate SMS functionality into your application.

Note: You need an API Key to use this API. If you have already signed up, you can get your API Key from your account.

API Endpoint

POST https://api.synqtel.com/sms/sendsms Bulk SMS

Authentication

All API requests require authentication using your API key in the request header.

Header Parameter

Header	Type	Description	Required
`h_api_key`	String	Your API key (64 characters)	Yes
`Content-Type`	String	Must be `application/json`	Yes

Example Header


--header 'h_api_key: ' \
--header 'Content-Type: application/json'


CURLOPT_HTTPHEADER => array(
    'h_api_key: ',
    'Content-Type: application/json'
)

Send Single SMS

Send a message to a mobile subscriber using a Sender Name (alphanumeric sender ID).

POST https://api.synqtel.com/sms/sendsms Bulk SMS

Request Parameters

Field	Type	Description	Required
`mobile`	String	The customer mobile number (e.g., 722xxx, 0722xxx, +254722xxx)	Yes
`sender_name`	String	The origination alphanumeric or numeric code (e.g., "Synqtel")	Yes
`message`	String	The message to send (max 920 characters or 6 SMS units)	Yes
`response_type`	String	[Optional] Either "json" or "plain", defaults to "json"	No
`service_id`	Integer	Service identifier (always 0 for bulk messaging)	Yes
`link_id`	String	[Optional] For shortcode messages only	No

Code Examples


curl --location --request POST 'https://api.synqtel.com/sms/sendsms' \
--header 'h_api_key: ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "mobile": "+254722310558",
    "response_type": "json",
    "sender_name": "Synqtel",
    "service_id": 0,
    "message": "This is a message.\n\nRegards\nSynqTel Limited"
}'


$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.synqtel.com/sms/sendsms',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => '{
        "mobile": "+254722310558",
        "response_type": "json",
        "sender_name": "Synqtel",
        "service_id": 0,
        "message": "This is a message.\n\nRegards\nSynqTel Limited"
    }',
    CURLOPT_HTTPHEADER => array(
        'h_api_key: ',
        'Content-Type: application/json'
    ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Response Example

Success Response

Status: 1000 - Success


[
    {
        "status_code": "1000",
        "status_desc": "Success",
        "message_id": 8738598,
        "mobile_number": "+254722310558",
        "network_id": "1",
        "message_cost": "0.75",
        "credit_balance": "9871"
    }
]

Error Response

Status: 1001 - Invalid short code


[
    {
        "status_code": "1001",
        "status_desc": "Invalid short code",
        "message_id": "0",
        "mobile_number": "+254722310558",
        "network_id": "",
        "message_cost": "",
        "credit_balance": ""
    }
]

Send Multiple SMS

Send multiple SMS messages to different recipients in a single API call.

POST https://api.synqtel.com/sms/sendmultiple Bulk SMS

Request Parameters

Field	Type	Description	Required
`serviceId`	Integer	The Service Id (0 for bulk SMS)	Yes
`shortcode`	String	Sender Name for whitelabeling	Yes
`messages`	Array	List of message objects	Yes
`messages[].mobile`	String	Recipient phone number	Yes
`messages[].message`	String	Message content	Yes
`messages[].client_ref`	String/Integer	Reference for delivery reports	No

Code Example


curl --location --request POST 'https://api.synqtel.com/sms/sendmultiple' \
--header 'Content-Type: application/json' \
--header 'h_api_key: ' \
--data-raw '{
    "serviceId": "0",
    "shortcode": "Synqtel",
    "messages": [
        {
            "mobile": "+254722310558",
            "message": "This is a first message",
            "client_ref": 6481
        },
        {
            "mobile": "+254712244244",
            "message": "This is a second message",
            "client_ref": 6092
        }
    ]
}'


$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.synqtel.com/sms/sendmultiple',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => '{
        "serviceId": "0",
        "shortcode": "Synqtel",
        "messages": [
            {
                "mobile": "+254722310558",
                "message": "This is a first message",
                "client_ref": 6481
            },
            {
                "mobile": "+254712244244",
                "message": "This is a second message",
                "client_ref": 6092
            }
        ]
    }',
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'h_api_key: '
    ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Response Example

Success Response

Status: 1000 - Success


{
    "status_code": 1000,
    "status_desc": "Success",
    "credit_balance": "-10615.0000",
    "schedule_details": [
        {
            "message_id": 335951830,
            "client_ref": 60970,
            "mobile": "+254722310558",
            "schedule_status": "1",
            "schedule_desc": "Success",
            "network_id": "1",
            "message_cost": 1
        },
        {
            "message_id": 335951831,
            "client_ref": 64871,
            "mobile": "254705941419",
            "schedule_status": "1",
            "schedule_desc": "Success",
            "network_id": "1",
            "message_cost": 1
        }
    ]
}

Validate Mobile Number

Validate and check the network a mobile number belongs to.

GET https://api.synqtel.com/sms/mobile Bulk SMS

Request Parameters

Field	Type	Description	Required
`mobile`	String	The mobile number to validate	Yes
`return`	String	[Optional] Return type: "json" or mobile number only	No

Code Example


curl --location --request GET 'https://api.synqtel.com/sms/mobile?mobile=712244243&return=json' \
--header 'h_api_key: '


$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.synqtel.com/sms/mobile?return=json&mobile=712244243',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => array(
        'h_api_key: '
    ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Delivery Reports

Receive delivery reports from Mobile Network Operators in real-time.

POST /client.endpoint/dlr Shortcode

Note: This endpoint should be configured on your server to receive delivery reports.

Request Parameters

Field	Type	Description	Required
`messageId`	Integer	The messageId returned with every successful request	Yes
`dlrTime`	DateTime	DateTime for the time of delivery (YYYY-MM-DD HH:MM:SS)	Yes
`dlrStatus`	Integer	Delivery status value as integer	Yes
`dlrDesc`	String	Description of the delivery report status	Yes
`tat`	Integer	Time taken for system to get report (in seconds)	No
`network`	Integer	Numeric indicator of the Network	No
`destaddr`	String	The mobile number the message was sent to	Yes
`sourceaddr`	String	The SenderId which originated the message	Yes
`origin`	String	The network name (e.g., "Safaricom")	No

Example Delivery Report


curl --location --request POST '/client.endpoint/dlr' \
--header 'Content-Type: application/json' \
--data-raw '{
    "messageId": "27312989",
    "dlrTime": "2022-02-22 11:46:42",
    "dlrStatus": "1",
    "dlrDesc": "DeliveredToTerminal",
    "tat": 10005,
    "network": "1",
    "destaddr": "254767209917",
    "sourceaddr": "118",
    "origin": "Safaricom"
}'


$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => '/client.endpoint/dlr',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => '{
        "messageId": "27312989",
        "dlrTime": "2022-02-22 11:46:42",
        "dlrStatus": "1",
        "dlrDesc": "DeliveredToTerminal",
        "tat": 10005,
        "network": "1",
        "destaddr": "254767209917",
        "sourceaddr": "118",
        "origin": "Safaricom"
    }'
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Account Balance

Get your current account balance using your API key.

GET https://api.synqtel.com/sms/getbalance Bulk SMS

Request Parameters

Field	Type	Description	Required
`response_type`	String	[Optional] Either "json" or "plain", defaults to "json"	No

Code Example


curl --location --request GET 'https://api.synqtel.com/sms/getbalance' \
--header 'h_api_key: adeedccd2199f41f7e731e3150b4c8009de4cded064b6407a310573e28978680' \
--header 'Content-Type: application/json' \
--data-raw '{"response_type":"json"}'


$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.synqtel.com/sms/getbalance',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_POSTFIELDS => '{"response_type":"json"}',
    CURLOPT_HTTPHEADER => array(
        'h_api_key: adeedccd2199f41f7e731e3150b4c8009de4cded064b6407a310573e28978680',
        'Content-Type: application/json'
    ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Status Codes

Reference table for all API response status codes and their descriptions.

Status ID	Code	Description	Type
1	1000	Success	success
2	1001	Invalid short code	error
3	1002	Network not allowed	error
4	1003	Invalid mobile number	error
5	1004	Low bulk credits	error
6	1005	Internal system error	error
7	1006	Invalid credentials	error
8	1007	Db connection failed	error
9	1008	Db selection failed	error
10	1009	Data type not supported	error
11	1010	Request type not supported	error
12	1011	Invalid user state or account suspended	error
13	1012	Mobile number in DND	error
14	1013	Invalid API Key	error
15	1014	IP not allowed	error

API Tester

Test the SMS API endpoints directly from this documentation.

POST https://api.synqtel.com/sms/sendsms

Note: This is a client-side tester. For security, API calls will be simulated. In a real implementation, this would make actual API calls.

Select Endpoint

API Key

Request Body

Overview

API Endpoint

Authentication

Header Parameter

Example Header

Send Single SMS

Request Parameters

Code Examples

Response Example

Success Response

Error Response

Send Multiple SMS

Request Parameters

Code Example

Response Example

Success Response

Validate Mobile Number

Request Parameters

Code Example

Delivery Reports

Request Parameters

Example Delivery Report

Account Balance

Request Parameters

Code Example

Status Codes

API Tester

Test Results

Response