API Documentation

UniSMS API is an SMS API service in the Philippines. This guide will help you integrate SMS functionality into your applications.

Base URL
https://unismsapi.com/api
Authentication

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.

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"}'

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

POST /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

201 Created 400 Bad Request 401 Unauthorized 422 Unprocessable Entity
GET /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

pending retrying sent failed

Response Codes

200 OK 401 Unauthorized 404 Not Found
POST /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

201 Created 400 Bad Request 401 Unauthorized 422 Unprocessable Entity
GET /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

pending retrying sent failed

Response Codes

200 OK 401 Unauthorized 404 Not Found
POST /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

201 Created 400 Bad Request 401 Unauthorized 422 Unprocessable Entity
GET /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

pending retrying sent failed

Response Codes

200 OK 401 Unauthorized 404 Not Found
GET /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

200 OK 401 Unauthorized

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 SenderID

Quick 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"}'