API Documentation

Welcome to the UniSMS API documentation. 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!"}'

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",
  "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": "MySender",
  "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`	No	Custom sender ID (only for users with businesses. Leave blank if none.)
`metadata`	`object`	No	Custom key-value pairs for tracking messages (e.g., order_id, template)

NOTE: If your business require a custom SenderID for branding purposes, please reach out to support and have your business documents ready.

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": "MySender",
  "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`	No	Custom sender ID (only for verified businesses)
`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!",
      "recipient": "+639123456789"
    },
    {
      "content": "Hello Maria, your order is ready!",
      "recipient": "+639987654321"
    },
    {
      "metadata": {
        "order_id": "12345"
      },
      "content": "Hello Peter, your order is ready!",
      "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`	No	Custom sender ID (only for verified businesses)
`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

POST /otp

Send OTP

Our system can generate the OTP and verify the pin for you.

Use /otp to create the OTP and /otp/verify to verify the OTP.

The OTP is sent directly and will be delivered as soon as possible.

Request Body

The message content must include the #{PIN} variable which will be replaced with the actual OTP code.

{
  "content": "Hi, Your One-Time-Pin is #{PIN} and valid for 5 minutes. Do not share with others.",
  "sender_id": "MySender",
  "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. Must include `#Elixir.PIN` variable
`sender_id`	`string`	No	Custom sender ID (only for users with businesses)

Example Response

{
  "message": {
    "status": "sent",
    "metadata": {},
    "content": "Your verification code is: 123456",
    "created": "2026-03-16T14:32:44Z",
    "reference_id": "msg_84e8b93b-6315-46af-a686",
    "recipient": "+639123456789",
    "fail_reason": null
  }
}

Response Codes

201 Created 400 Bad Request 401 Unauthorized 422 Unprocessable Entity

POST /otp/verify

Verify OTP

Verify an OTP using the reference ID you received from the /otp endpoint and the PIN code received by the user.

Once an OTP pin is successfully verified, the pin will expire.

Request Body

{
  "pin": "123456",
  "reference_id": "msg_84e8b93b-6315-46af-a686"
}

Parameters

Field	Type	Required	Description
`reference_id`	`string`	Yes	Reference ID returned when sending the OTP
`pin`	`string`	Yes	OTP code entered by the user

Example Response - Success

{
  "code": 200,
  "message": "Success"
}

Example Response - Incorrect PIN

{
  "code": 406,
  "message": "Incorrect Pin."
}

Response Codes

200 OK 401 Unauthorized 404 Not Found 406 Not Acceptable 422 Unprocessable Entity

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

Configure Webhooks

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");

View on GitHub

Custom SenderID

Send SMS with your brand name instead of our default SenderID. Instead of "UniSMS", your recipients will see your custom brand identifier (e.g., "MyBusiness").

Custom SenderID

Send SMS with your brand name

A SenderID is the identifier that appears when recipients receive your SMS. Instead of our SenderID (UniSMS), they'll see your brand name (e.g. "MyBusiness").

Example:

From: UniSMS

With SenderID: MyBusiness

Available for verified businesses only. Contact us to apply.

Apply via Email

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

Get API Key Get Support