Developer Guide

PieSms SMS API

Use the PieSms REST API to send SMS messages and check SMS credit balance. Authenticate requests with your API key and secret, then submit JSON payloads to the endpoints below.

Base URL

https://piesmsapi.pienet.co.tz

Authentication

Basic Auth

Content Type

application/json

Getting API Credentials

Create your PieSms account and verify it.
Log in to your dashboard.
Open `Settings` and go to `Account Credentials`.
Generate your API key and secret.
Store the secret safely because it is shown only once.
Use the generated credentials for Basic Authentication.

POST

Send SMS

https://piesmsapi.pienet.co.tz/v1/send

Headers

Field	Type	Description
Authorization	string	Basic authentication header built from api_key:secret_key.
Content-Type	string	Use application/json.

Request Body

Field	Type	Description
source_addr	string	Sender ID or source address. If text, it should be active on the portal and within the allowed character limit.
schedule_time	string	Optional scheduled send time. Format: yyyy-mm-dd hh:mm
encoding	string	Message encoding flag. Use the value expected by your SMS setup, for example 0.
message	string	SMS content to be delivered.
recipients	array	List of recipients. Each item should contain recipient_id and dest_addr.
recipient_id	string \| number	Unique recipient reference returned back in delivery-related handling.
dest_addr	string	Destination mobile number in international format, for example 255700000001. Do not include +.

Example Request Body

{
  "source_addr": "INFO",
  "schedule_time": "",
  "encoding": "0",
  "message": "Hello world",
  "recipients": [
    {
      "recipient_id": 1,
      "dest_addr": "255700000001"
    },
    {
      "recipient_id": 2,
      "dest_addr": "255700000002"
    }
  ]
}

Example Response

{
  "successful": true,
  "request_id": 67,
  "code": 100,
  "message": "Message Submitted Successfully",
  "valid": 1,
  "invalid": 0,
  "duplicates": 0
}

GET

Check Balance

https://piesmsapi.pienet.co.tz/v1/balance

Headers

Field	Type	Description
Authorization	string	Basic authentication header built from api_key:secret_key.
Content-Type	string	Use application/json.

Example Response

{
  "data": {
    "credit_balance": 100
  }
}

Authentication Example

Use HTTP Basic Authentication where the username is your API key and the password is your secret key.

Authorization: Basic base64(api_key:secret_key)

Code Samples

cURL

curl -X POST "https://piesmsapi.pienet.co.tz/v1/send" \
  -H "Authorization: Basic <base64_api_key_colon_secret_key>" \
  -H "Content-Type: application/json" \
  -d '{
  "source_addr": "INFO",
  "schedule_time": "",
  "encoding": "0",
  "message": "Hello world",
  "recipients": [
    {
      "recipient_id": 1,
      "dest_addr": "255700000001"
    },
    {
      "recipient_id": 2,
      "dest_addr": "255700000002"
    }
  ]
}'

JavaScript

const apiKey = "your_api_key";
const secretKey = "your_secret_key";

const payload = {
  "source_addr": "INFO",
  "schedule_time": "",
  "encoding": "0",
  "message": "Hello world",
  "recipients": [
    {
      "recipient_id": 1,
      "dest_addr": "255700000001"
    },
    {
      "recipient_id": 2,
      "dest_addr": "255700000002"
    }
  ]
};

fetch("https://piesmsapi.pienet.co.tz/v1/send", {
  method: "POST",
  headers: {
    Authorization: "Basic " + btoa(apiKey + ":" + secretKey),
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

PHP

<?php
$apiKey = "your_api_key";
$secretKey = "your_secret_key";

$payload = {
  "source_addr" => "INFO",
  "schedule_time" => "",
  "encoding" => "0",
  "message" => "Hello world",
  "recipients" => [
    {
      "recipient_id" => 1,
      "dest_addr" => "255700000001"
    },
    {
      "recipient_id" => 2,
      "dest_addr" => "255700000002"
    }
  ]
};

$ch = curl_init("https://piesmsapi.pienet.co.tz/v1/send");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Basic " . base64_encode($apiKey . ":" . $secretKey),
  "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>