The CentSMS API is a standard RESTful API. Queries are made via HTTP(S) protocol and the response returned is a standard JSON document.

To get started using the CentSMS API, you must have a CentSMS account in good standing. You must also know your account username and API key.

API Query Format

  • Queries should be made to this URL: https://api.centsms.com/v1/
  • The API uses basic HTTP authentication; the username is your CentSMS account username, and the password is your API key.
  • A JSON document with the following items must be POSTED to the query:
    • “to” - An array of phone numbers to send the message to
    • “message” - The message content to be delivered
    • "attachments" - [optional] an array of URLs of media to attach to the message

API Response Format

The response is a JSON document with the following items:

  • “status” - Either “OK”, or “Error”
  • “reason” - Contain the reason for an error
  • “messages” - (only present if status is “OK”) Contains a list of the recipient phone numbers and the delivery status for each one.

Example response for successful API call:

status: 'OK',
reason: '',
messages: { '12125551212': 'sent', ‘12125551313’, ‘sent’ }

Example response for unsuccessful API call:

status: 'Error',
reason: 'Invalid Credentials'

Example query using cURL

curl https://api.centsms.com/v1/ \
-u "username:apikey" \
-H "Content-type: application/json" \
-d '{
"to": ["16175551313","17815551212"],
"message": "This is a test message",

Example query using Python

import requests
url = "https://api.centsms.com/v1/"
user = "myuser"
apikey = "mypass"
phones = ['17815551212']
message = "Welcome to CentSMS!"

auth_values = (user, apikey)
payload = {'to' : phones, 'message': message}
response = requests.post(url, auth=auth_values, json=payload)

Example query using PHP

$url = "https://api.centsms.com/v1/";
$user = "myuser";
$apikey = "mypass";
$data = array();
$data['to'] = array("17815551212");
$data['message'] = "Welcome to CentSMS!";

$json = json_encode($data);
$process = curl_init($url);
curl_setopt($process, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
curl_setopt($process, CURLOPT_HEADER, 1);
curl_setopt($process, CURLOPT_USERPWD, $user . ":" . $apikey);
curl_setopt($process, CURLOPT_TIMEOUT, 30);
curl_setopt($process, CURLOPT_POST, 1);
curl_setopt($process, CURLOPT_POSTFIELDS, $json);
curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($process);
print $return;

Example query using Node.js

var Client = require('node-rest-client').Client;
var auth = { user: "myuser", password: "mypass" };
var client = new Client(auth);

var args = {
data: { to: ["17815551212"], message : "Welcome to CentSMS!" },
headers: { "Content-Type": "application/json" }
client.post("http://api.centsms.com/v1/", args, function (data, response) {