API Documentation
UniSMS API is an SMS API service in the Philippines. This guide will help you integrate SMS functionality into your applications.
https://unismsapi.com/api
All API requests require Basic Authentication using your API key. Use your API Secret key as the username and empty for the password.
API_SECRET_KEY:
Authorization: Basic Base64Encode(API_SECRET_KEY:)
(Most libraries automatically encode this to Base64)
Example code from a cUrl request.
Sender ID
Your new account will be given a random sender id for you to use to test our platform. A sender ID is required to send SMS to comply with telco policies. Once you are done with testing, please apply for a sender id to continue.
Endpoints
/sms
Send SMS
Send an SMS message to a recipient. The message will be queued for delivery.
Request Body
{
"content": "Your message here",
"sender_id": "UniSMS",
"recipient": "+639123456789"
}
Request Body With Metadata
Use metadata for your internal recording and info
{
"metadata": {
"template": "order_confirmation",
"order_id": "12345"
},
"content": "Your message here",
"sender_id": "UniSMS",
"recipient": "+639123456789"
}
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
recipient |
string |
Yes | Phone number in E.164 format (e.g., +639123456789) |
content |
string |
Yes | SMS message content (max 160 characters) |
sender_id |
string |
Yes | Your sender ID (e.g., UniSMS) |
metadata |
object |
No | Custom key-value pairs for tracking messages (e.g., order_id, template) |
NOTE: A sender ID is required for all messages. Register and use this form to get your sender ID. Please prepare your business documents.
Example Response
{
"message": {
"status": "sent",
"metadata": {
"source": "onboarding"
},
"content": "Welcome to UniSMS",
"created": "2026-03-16T14:32:44Z",
"reference_id": "msg_84e8b93b-6315-46af-a686",
"recipient": "+639055310560",
"fail_reason": null
}
}
Response Codes
/sms/:reference_id
Get SMS Status
Retrieve the status of a previously sent SMS message using its reference ID.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
reference_id |
string |
The unique reference ID returned when sending the SMS |
Example Response
{
"message": {
"status": "sent",
"metadata": {},
"content": "Welcome to UniSMS",
"created": "2026-03-16T14:32:44Z",
"reference_id": "msg_84e8b93b-6315-46af-a686",
"recipient": "+639055310560",
"fail_reason": null
}
}
Message Statuses
Response Codes
/blast
Blast SMS
Multiple recipients, one message. Perfect for alerts, announcements, promotions where the message content are the same but must be delivered to different recipients.
If one of the recipient phone number is invalid, that number will be ignored.
If you ran out of credits while sending bulk message, only the message with enough credits will be sent up to that point and the rest will be ignored.
Request Body
{
"metadata": {
"campaign": "spring_sale_2026"
},
"content": "Your bulk message here",
"sender_id": "UniSMS",
"recipients": [
"+639123456789",
"+639987654321",
"+639555123456"
]
}
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
recipients |
array |
Yes | Array of phone numbers in E.164 format |
content |
string |
Yes | SMS message content (max 160 characters) |
sender_id |
string |
Yes | Your sender ID (e.g., UniSMS) |
metadata |
object |
No | Custom key-value pairs for tracking messages |
Example Response
{
"total": 3,
"blast_id": "blast_4a3f8b2c-9d1e-4f5a-8b7c-2d6e0a1b3c4d"
}
Using the Blast ID
After sending a blast, use the returned blast_id to check the status
of all messages in that blast.
Response Codes
/blast/:blast_id
Get Blast Status
Retrieve the status of all messages sent in a specific blast using the blast ID.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
blast_id |
string |
The blast ID returned when creating the blast |
Example Response
{
"messages": [
{
"status": "sent",
"metadata": {
"campaign": "spring_sale_2026"
},
"content": "Your bulk message here",
"created": "2026-03-16T14:32:44Z",
"reference_id": "msg_84e8b93b-6315-46af-a686",
"recipient": "+639123456789",
"fail_reason": null
},
{
"status": "sent",
"metadata": {
"campaign": "spring_sale_2026"
},
"content": "Your bulk message here",
"created": "2026-03-16T14:32:45Z",
"reference_id": "msg_95f9c44c-7426-57bc-b797",
"recipient": "+639987654321",
"fail_reason": null
},
{
"status": "pending",
"metadata": {
"campaign": "spring_sale_2026"
},
"content": "Your bulk message here",
"created": "2026-03-16T14:32:46Z",
"reference_id": "msg_a6g0d55d-8537-68cd-c808",
"recipient": "+639555123456",
"fail_reason": null
}
],
"total": 3
}
Message Statuses
Response Codes
/bulk
Bulk SMS
Different recipients, different messages. Perfect for personalized messages like sending greetings with different names, personalized notifications, or bulk messages that need unique content for each recipient. Messages are sent simultaneously.
If one of the message object is invalid, it will be ignored.
If you ran out of credits while sending bulk message, only the message with enough credits will be sent up to that point and the rest will be ignored.
Request Body
{
"messages": [
{
"content": "Hello John, your order is ready!",
"sender_id": "UniSMS",
"recipient": "+639123456789"
},
{
"content": "Hello Maria, your order is ready!",
"sender_id": "UniSMS",
"recipient": "+639987654321"
},
{
"metadata": {
"order_id": "12345"
},
"content": "Hello Peter, your order is ready!",
"sender_id": "UniSMS",
"recipient": "+639555123456"
}
]
}
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
messages |
array |
Yes | Array of message objects with unique recipient and content |
messages[].recipient |
string |
Yes | Phone number in E.164 format |
messages[].content |
string |
Yes | SMS message content (max 160 characters) |
messages[].sender_id |
string |
Yes | Your sender ID (e.g., UniSMS) |
messages[].metadata |
object |
No | Custom key-value pairs for tracking individual messages |
Example Response
{
"total": 3,
"bulk_id": "bulk_4a3f8b2c-9d1e-4f5a-8b7c-2d6e0a1b3c4d"
}
Using the Bulk ID
After sending bulk messages, use the returned bulk_id
to check the status
of all messages in that bulk request.
Response Codes
/bulk/:bulk_id
Get Bulk Status
Retrieve the status of all messages sent in a specific bulk request using the bulk ID.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
bulk_id |
string |
The bulk ID returned when creating the bulk request |
Example Response
{
"messages": [
{
"status": "sent",
"metadata": {},
"content": "Hello John, your order is ready!",
"created": "2026-03-16T14:32:44Z",
"reference_id": "msg_84e8b93b-6315-46af-a686",
"recipient": "+639123456789",
"fail_reason": null
},
{
"status": "sent",
"metadata": {},
"content": "Hello Maria, your order is ready!",
"created": "2026-03-16T14:32:45Z",
"reference_id": "msg_95f9c44c-7426-57bc-b797",
"recipient": "+639987654321",
"fail_reason": null
},
{
"status": "pending",
"metadata": {
"order_id": "12345"
},
"content": "Hello Peter, your order is ready!",
"created": "2026-03-16T14:32:46Z",
"reference_id": "msg_a6g0d55d-8537-68cd-c808",
"recipient": "+639555123456",
"fail_reason": null
}
],
"total": 3
}
Message Statuses
Response Codes
/account
Get Account
Retrieve your account information including email, SMS credits, SID tokens, and account status.
A possible case is to use this endpoint to regularly check if you have enough credits in your account.
Example Response
{
"status": "active",
"email": "[email protected]",
"sid_tokens": 2,
"sms_credits": 100
}
Response Fields
| Field | Type | Description |
|---|---|---|
email |
string |
Your registered email address |
sms_credits |
integer |
Your current SMS credit balance |
sid_tokens |
integer |
Your available SID tokens for custom sender ID |
status |
string |
Your account status (e.g., active, inactive) |
Response Codes
Webhooks
Webhooks allow you to receive real-time notifications when SMS messages are processed. Instead of polling the API for status updates, you can configure a webhook URL to receive HTTP POST requests whenever an event occurs.
Configuring Webhooks
To receive webhooks, configure your webhook URL in the dashboard. Your URL must:
- Use HTTPS (secure endpoint)
- Be publicly accessible
- Accept POST requests
Event Types
| Event | Description |
|---|---|
message.sent |
Triggered when an SMS is successfully sent |
message.failed |
Triggered when SMS sending fails |
message.retrying |
Triggered when the system is retrying to send SMS |
Payload Structure
All webhook payloads follow a consistent structure:
{
"id": "msg_84e8b93b-6315-46af-a686",
"message": {
"status": "sent",
"metadata": {},
"content": "Welcome to UniSMS",
"created": "2026-03-16T14:32:44Z",
"reference_id": "msg_84e8b93b-6315-46af-a686",
"recipient": "+639055310560",
"fail_reason": null
},
"event": "message.sent"
}
Payload Fields
| Field | Type | Description |
|---|---|---|
event |
string |
The event type (e.g., "message.sent") |
id |
string |
The reference ID of the message |
message |
object |
The full message object with current status |
PHP SDK
The official UniSMS PHP SDK for sending and retrieving SMS messages. Built with Vanilla PHP - no external dependencies required.
Installation
Download the UniSms.php
file from the
GitHub repository
and require it in your project.
Send a Message
<?php
require_once './UniSms.php';
$secret_key = "sk_XXXXXXXXXXXXXXXXXXXXXXXXX";
$client = new UniSms($secret_key);
$client->recipient = "+63912345678";
$client->content = "Hello world";
// Send message
$client->send();
Get a Message
<?php
require_once './UniSms.php';
$secret_key = "sk_XXXXXXXXXXXXXXXXXXXXXXXXX";
$client = new UniSms($secret_key);
// Get a message
$client->get("msg_b788f2bf-5816-47c1-8eb0-f018a699d7bc");
Sample Codes
Here you'll find a collection of sample codes to help you create your first SMS request.
cURL
curl -X POST https://unismsapi.com/api/sms \
-u YOUR_SECRET_KEY: \
-H "Content-Type: application/json" \
-d '{"recipient": "+639123456789", "content": "Hello from UniSMS!", "sender_id": "UniSMS"}'
Node.js
const axios = require('axios');
const response = await axios.post('https://unismsapi.com/api/sms', {
recipient: '+639123456789',
content: 'Hello from UniSMS!',
sender_id: 'UniSMS'
}, {
auth: {
username: 'YOUR_SECRET_KEY',
password: ''
},
headers: {
'Content-Type': 'application/json'
}
});
console.log(response.data);
Python
import requests
from requests.auth import HTTPBasicAuth
response = requests.post(
'https://unismsapi.com/api/sms',
json={
'recipient': '+639123456789',
'content': 'Hello from UniSMS!',
'sender_id': 'UniSMS'
},
auth=HTTPBasicAuth('YOUR_SECRET_KEY', ''),
headers={
'Content-Type': 'application/json'
}
)
print(response.json())
PHP
<?php
$client = new GuzzleHttp\Client();
$response = $client->post('https://unismsapi.com/api/sms', [
'json' => [
'recipient' => '+639123456789',
'content' => 'Hello from UniSMS!',
'sender_id' => 'UniSMS'
],
'auth' => [
'YOUR_SECRET_KEY',
''
],
'headers' => [
'Content-Type' => 'application/json'
]
]);
echo $response->getBody();
Ruby
require 'httparty'
response = HTTParty.post(
'https://unismsapi.com/api/sms',
body: {
recipient: '+639123456789',
content: 'Hello from UniSMS!',
sender_id: 'UniSMS'
}.to_json,
basic_auth: [
'YOUR_SECRET_KEY',
''
],
headers: {
'Content-Type' => 'application/json'
}
)
puts response.body
C#
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Net;
var client = new HttpClient();
var credentials = Convert.ToBase64String(Encoding.ASCII.GetBytes("YOUR_SECRET_KEY:"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);
var content = new StringContent(
JsonSerializer.Serialize(new {
recipient = "+639123456789",
content = "Hello from UniSMS!",
sender_id = "UniSMS"
}),
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://unismsapi.com/api/sms", content);
Console.WriteLine(await response.Content.ReadAsStringAsync());
VB.NET
Imports System.Net.Http
Imports System.Text
Imports System.Text.Json
Imports System.Net
Module SendSms
Async Function Main() As Task
Dim client As New HttpClient()
Dim credentials As String = Convert.ToBase64String(Encoding.ASCII.GetBytes("YOUR_SECRET_KEY:"))
client.DefaultRequestHeaders.Authorization = New AuthenticationHeaderValue("Basic", credentials)
Dim jsonData = JsonSerializer.Serialize(New With {
.recipient = "+639123456789",
.content = "Hello from UniSMS!",
.sender_id = "UniSMS"
})
Dim content As New StringContent(jsonData, Encoding.UTF8, "application/json")
Dim response = Await client.PostAsync("https://unismsapi.com/api/sms", content)
Console.WriteLine(Await response.Content.ReadAsStringAsync())
End Function
End Module
Java
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.io.OutputStream;
public class SendSms {
public static void main(String[] args) throws Exception {
URL url = new URL("https://unismsapi.com/api/sms");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");
String auth = "YOUR_SECRET_KEY:";
String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes(StandardCharsets.UTF_8));
conn.setRequestProperty("Authorization", "Basic " + encodedAuth);
conn.setDoOutput(true);
String jsonBody = "{\"recipient\": \"+639123456789\", \"content\": \"Hello from UniSMS!\", \"sender_id\": \"UniSMS\"}";
try (OutputStream os = conn.getOutputStream()) {
os.write(jsonBody.getBytes(StandardCharsets.UTF_8));
}
int responseCode = conn.getResponseCode();
System.out.println("Response Code: " + responseCode);
}
}
Custom SenderID
Send SMS with your brand name. A SenderID is the identifier that appears when recipients receive your SMS. Your recipients will see your brand identifier (e.g., "UniSMS").
Register a SenderID
Send SMS with your brand name
A SenderID is the identifier that appears when recipients receive your SMS. You must register a sender ID to send messages. Your recipients will see your chosen identifier (e.g. "UniSMS").
Example:
From: UniSMS
Register your sender ID by contacting us. You can manage multiple sender IDs.
Register a SenderIDQuick Start
Get your API key from the dashboard, then make your first request:
curl -X POST https://unismsapi.com/api/sms \
-u your_api_key: \
-H "Content-Type: application/json" \
-d '{"recipient": "+639123456789", "content": "Hello from UniSMS!", "sender_id": "UniSMS"}'