Bulk SMS API for Developers

Introduction

Welcome to the PiloSMS API documentation! Our API provides powerful and flexible tools that allow you to integrate the capabilities of PiloSMS directly into your applications, enhancing your communication strategies and streamlining your messaging processes.

With PiloSMS API, you can:

Send bulk SMS messages efficiently to any Ghanaian number.
Manage contacts and groups effortlessly.
Get wallet balance

Whether you are a developer looking to integrate SMS functionalities into your application or a business aiming to improve customer engagement, the PiloSMS API offers a robust solution to meet your needs. Our API is designed to be easy to use, secure, and scalable, ensuring that you can leverage the full potential of PiloSMS services seamlessly.

For any assistance, feel free to reach out to our support team.

Send Message (POST)

Endpoint

https://api.pilosms.com/v1/send-message

Field	Type	Required	Description
apikey	parameter	Yes	A unique key needed for authorisation. Can be generated from your pilosms integration page
sender	string	Yes	Sender ID with which message would be sent. Register a sender
message	string	Yes	Message to be sent
receipients	string	Yes	List of all numbers message will be sent to. Numbers should be international format and comma separated. E.g. 23324xxxxxxx,23320xxxxxxx

				
					curl --location 'https://api.pilosms.com/v1/send-message?apikey=XXX_SECRET' \
--form 'sender="PiloSMS"' \
--form 'message="This is a test message"' \
--form 'receipients="233248...,233207"'

				
					const formdata = new FormData();
formdata.append("sender", "PiloSMS");
formdata.append("message", "This is a test message");
formdata.append("receipients", "233248...,233207");

const requestOptions = {
  method: "POST",
  body: formdata,
  redirect: "follow"
};

fetch("https://api.pilosms.com/v1/send-message?apikey=XXX_SECRET", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

				
					<?php

$apikey = "XXX_SECRETKEY";

$payload = [
  'sender' => 'PiloSMS',
  'message' => 'This is a test message',
  'receipients' => '233248...,233207...'
];

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.pilosms.com/v1/send-message?apikey=$apikey",
  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 => $payload,
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

				
					package main

import (
  "fmt"
  "bytes"
  "mime/multipart"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.pilosms.com/v1/send-message?apikey=XXX_SECRET"
  method := "POST"

  payload := &bytes.Buffer{}
  writer := multipart.NewWriter(payload)
  _ = writer.WriteField("sender", "PiloSMS")
  _ = writer.WriteField("message", "This is a test message")
  _ = writer.WriteField("receipients", "233248...,233207")
  err := writer.Close()
  if err != nil {
    fmt.Println(err)
    return
  }


  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Set("Content-Type", writer.FormDataContentType())
  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := ioutil.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

				
					import requests

url = "https://api.pilosms.com/v1/send-message?apikey=XXX_SECRET"

payload = {'sender': 'PiloSMS',
'message': 'This is a test message',
'receipients': '233248...,233207'}
files=[

]
headers = {}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

				
					OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = new MultipartBody.Builder().setType(MultipartBody.FORM)
  .addFormDataPart("sender","PiloSMS")
  .addFormDataPart("message","This is a test message")
  .addFormDataPart("receipients","233248...,233207")
  .build();
Request request = new Request.Builder()
  .url("https://api.pilosms.com/v1/send-message?apikey=XXX_SECRET")
  .method("POST", body)
  .build();
Response response = client.newCall(request).execute();

				
					require "uri"
require "net/http"

url = URI("https://api.pilosms.com/v1/send-message?apikey=XXX_SECRET")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
form_data = [['sender', 'PiloSMS'],['message', 'This is a test message'],['receipients', '233248...,233207']]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_body

				
					using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

namespace SendMessageApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            
            var payload = new
            {
                sender = "PiloSMS",
                message = "This is a test message",
                receipients = "233248...,233207..."
            };

            var jsonPayload = System.Text.Json.JsonSerializer.Serialize(payload);

            using (var client = new HttpClient())
            {
                client.DefaultRequestHeaders.Add("api_key", apiKey);
                var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

                var response = await client.PostAsync("https://api.pilosms.com/v1/send-message?apiKey=XXX_SECRETKEY", content);

                if (response.IsSuccessStatusCode)
                {
                    var responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Success: " + responseBody);
                }
                else
                {
                    Console.WriteLine("Error: " + response.StatusCode);
                    var responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Response: " + responseBody);
                }
            }
        }
    }
}

Sample Response (JSON)

				
					{
    "status": 1001,
    "detail": "Message(s) processed successfully",
    "total_cost": 0.06,
    "errors": {
        "count": 0,
        "list": []
    },
    "duplicates": {
        "count": 0,
        "list": []
    }
}

Get Balance (GET)

Endpoint

https://api.pilosms.com/v1/check-balance

Field	Type	Required	Description
api_key	String	Yes	A unique key needed for authorisation. Can be generated from your pilosms integration page

				
					curl --location 'https://api.pilosms.com/v1/check-balance?apikey=XXX_SECRET'

				
					const apiKey = "XXX_SECRETKEY";
const url = `https://api.pilosms.com/v1/check-balance?apikey=${apiKey}`;

fetch(url, {
  method: 'GET'
})
.then(response => response.json())
.then(data => {
  console.log('Success:', data);
})
.catch(error => {
  console.error('Error:', error);
});

				
					<?php

$apikey = "XXX_SECRETKEY";

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.pilosms.com/v1/check-balance?apikey=$apikey",
  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',
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

				
					package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
)

func main() {
	apiKey := "XXX_SECRETKEY"
	url := fmt.Sprintf("https://api.pilosms.com/v1/check-balance?apikey=%s", apiKey)

	resp, err := http.Get(url)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	defer resp.Body.Close()

	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Response: %s\n", body)
}

				
					import requests

api_key = "XXX_SECRETKEY"
url = f"https://api.pilosms.com/v1/check-balance?apikey={api_key}"

response = requests.get(url)

if response.status_code == 200:
    print("Success:", response.json())
else:
    print("Error:", response.status_code, response.text)

				
					import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class CheckBalance {

    public static void main(String[] args) {
        String apiKey = "XXX_SECRETKEY";
        String urlString = "https://api.pilosms.com/v1/check-balance?apikey=" + apiKey;

        try {
            URL url = new URL(urlString);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("GET");
            conn.setRequestProperty("Accept", "application/json");

            int responseCode = conn.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                BufferedReader in = new BufferedReader(new InputStreamReader(conn.getInputStream()));
                String inputLine;
                StringBuilder response = new StringBuilder();

                while ((inputLine = in.readLine()) != null) {
                    response.append(inputLine);
                }
                in.close();

                // Print the response
                System.out.println("Success: " + response.toString());
            } else {
                System.out.println("Error: " + responseCode);
            }

            conn.disconnect();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

				
					require 'net/http'
require 'uri'
require 'json'

api_key = "XXX_SECRETKEY"
url = URI.parse("https://api.pilosms.com/v1/check-balance?apikey=#{api_key}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url.request_uri)
request['Accept'] = 'application/json'

response = http.request(request)

if response.code.to_i == 200
  puts "Success: #{response.body}"
else
  puts "Error: #{response.code}"
  puts "Response: #{response.body}"
end

				
					using System;
using System.Net.Http;
using System.Threading.Tasks;

namespace CheckBalanceApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            string apiKey = "XXX_SECRETKEY";
            string url = $"https://api.pilosms.com/v1/check-balance?apikey={apiKey}";

            using (HttpClient client = new HttpClient())
            {
                client.DefaultRequestHeaders.Accept.Add(new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

                HttpResponseMessage response = await client.GetAsync(url);

                if (response.IsSuccessStatusCode)
                {
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Success: " + responseBody);
                }
                else
                {
                    Console.WriteLine("Error: " + response.StatusCode);
                    string responseBody = await response.Content.ReadAsStringAsync();
                    Console.WriteLine("Response: " + responseBody);
                }
            }
        }
    }
}

Sample Response (JSON)

				
					{
  "balance": 39.29,
  "units": 1309,
  "last_topup": {
    "date": "2024-06-06 10:02:04",
    "amount": "25",
    "status": "success"
  }
}

Response Codes

The following response codes interpret the status of API requests.

Response Code	Description
1001	Message sent successfully
1002	One or more parameters are missing
1003	Invalid API key
1004	API key inactive
1005	Insufficient balance
1006	No valid numbers could be processed
1007	Sender name not registered/approved

Login

Bulk SMS API for Developers

Table of Content

Introduction

Send Message (POST)

Endpoint

Sample Response (JSON)

Get Balance (GET)

Endpoint

Sample Response (JSON)

Response Codes

PLATFORM

PAGES

LEGAL

PRODUCTS