Developers

API Reference

Everything you can do in the dashboard, you can do from your own code. Send text blasts to your customers, organize your contact lists, and schedule recurring campaigns all through a simple, secure API that fits right into the tools you already use.

Overview

The SMS Philippines APIs let you integrate SMS broadcasting, contact management, and campaign scheduling directly into your applications. All requests must be authenticated and sent over HTTPS.

Protocol

HTTPS only

Format

JSON (UTF-8)

Auth

Bearer Token

Authentication

Authenticate every request by including your API key in the Authorization header. Generate and rotate keys from your dashboard under Settings → API Keys.

bash

curl -X POST https://api.sms-broadcast.smsphilippines.com/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mobiles": "639171234567", "message": "Hello", "sender_name": "ZENGLOBAL" }'

Security tip: Never share your API key publicly or commit it to version control. Rotate it immediately if compromised.

Base URLs

Each API has its own base URL. Endpoints below are relative to the base URL of their group.

API	Base URL
Broadcast Send	https://api.sms-broadcast.smsphilippines.com
Broadcast History	https://api.sms-broadcast-history.smsphilippines.com
Contact	https://api.contact.smsphilippines.com
SMS Campaign	https://api.sms-campaign.smsphilippines.com

Response Envelope

Every response success or failure uses the same shape. Branch on error.code, not on HTTP status or message text codes are stable, messages may be reworded.

json

// success
{ "success": true,  "data": { ... }, "error": null }

// failure
{ "success": false, "data": null,   "error": { "code": "...", "message": "..." } }

Broadcast API

Send one-off SMS blasts to one or more mobile numbers and look up delivery history for your account.

Base URLhttps://api.sms-broadcast.smsphilippines.com

POST/

Send a broadcast

Sends one message to one or more comma-separated PH mobile numbers. Mobile numbers may be in +63, 63, or 09 format +63 is recommended. For international numbers, use the country code prefix (e.g., +1, +44). sender_name must be registered and approved on your account.

Example Request

bash

curl -X POST https://api.sms-broadcast.smsphilippines.com/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mobiles": "639171234567,639181234567", "message": "Hello from SMS Philippines!", "sender_name": "ZENGLOBAL" }'

Request Body

json

{
  "mobiles": "639171234567,639181234567",
  "message": "Hello from SMS Philippines!",
  "sender_name": "ZENGLOBAL"
}

Response

json

{
  "success": true,
  "data": {
    "batch_id": "9c2b6e3e-0e59-4a1a-9d0e-2b6e3e0e59a1",
    "credits_deducted": 2,
    "queued_count": 2,
    "sender_name": "ZENGLOBAL"
  },
  "error": null
}

GET/history

List send history

Returns your recent sends, newest first. Mobile numbers are masked and messages truncated this endpoint confirms delivery outcomes, not full content.

Example Request

bash

curl -X GET https://api.sms-broadcast.smsphilippines.com/history \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "data": [
    { "mobile_number": "0917****567", "message": "Hello from SMS Philippines!", "status": "sent" },
    { "mobile_number": "0918****567", "message": "Hello from SMS Philippines!", "status": "sent" }
  ],
  "page": { "limit": 25, "count": 2, "has_more": false, "next_cursor": null }
}

Contact API

Manage contact groups and contacts. Mobile numbers are accepted in 09XXXXXXXXX, +639XXXXXXXXX, or 639XXXXXXXXX form and normalized to 639XXXXXXXXX. Typical flow: create a group, create contacts, then add those contacts to the group.

Base URLhttps://api.contact.smsphilippines.com

POST/groups

Create a group

Group names must be unique per account.

Example Request

bash

curl -X POST https://api.contact.smsphilippines.com/groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Weekend Sale", "description": "Customers opted in for weekend promos" }'

Request Body

json

{
  "name": "Weekend Sale",
  "description": "Customers opted in for weekend promos"
}

Response

json

{
  "success": true,
  "data": {
    "group": {
      "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "name": "Weekend Sale",
      "description": "Customers opted in for weekend promos",
      "created_at": "2026-09-10T02:00:00.000Z"
    }
  },
  "error": null
}

GET/groups

List groups

Each group includes a live contact_count.

Example Request

bash

curl -X GET https://api.contact.smsphilippines.com/groups \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "success": true,
  "data": {
    "groups": [
      { "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "name": "Weekend Sale", "description": "Customers opted in for weekend promos", "created_at": "2026-09-10T02:00:00.000Z", "contact_count": 2 }
    ],
    "returned": 1
  },
  "error": null
}

POST/contacts

Create contacts

contact may be a single object or an array. Accepted immediately and processed in the background (202) the contacts are not necessarily queryable the instant this call returns.

Example Request

bash

curl -X POST https://api.contact.smsphilippines.com/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact": [ { "mobile_number": "09171234567", "first_name": "Juan", "last_name": "Dela Cruz" }, { "mobile_number": "09181234567", "first_name": "Maria", "last_name": "Santos" } ] }'

Request Body

json

{
  "contact": [
    { "mobile_number": "09171234567", "first_name": "Juan", "last_name": "Dela Cruz" },
    { "mobile_number": "09181234567", "first_name": "Maria", "last_name": "Santos" }
  ]
}

Response

json

{
  "success": true,
  "data": {
    "upload_id": "4b1e6f2a-1c2d-4e3f-9a0b-1c2d3e4f5a6b",
    "accepted": 2,
    "chunks": 1,
    "message": "Accepted 2 contacts for processing"
  },
  "error": null
}

POST/groups/contacts

Add contacts to a group

All-or-nothing: if any contact_id doesn't belong to your account, nothing is added and the response lists the offending ids.

Example Request

bash

curl -X POST https://api.contact.smsphilippines.com/groups/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "contact_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"] }'

Request Body

json

{
  "group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "contact_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]
}

Response

json

{
  "success": true,
  "data": { "group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed", "requested": 1, "added": 1, "already_members": 0 },
  "error": null
}

SMS Campaign API

Schedule one-time or recurring SMS campaigns to a contact group, check progress, and cancel them. A campaign is one or more messages published together under one campaign.id. All times are Asia/Manila (UTC+8) wall-clock.

Base URLhttps://api.sms-campaign.smsphilippines.com

POST/publish

Schedule a one-time campaign

scheduled_at is a future PHT wall-clock timestamp (YYYY-MM-DD HH:MM:SS). campaign.id and each messages[].id are yours to choose (UUIDs recommended). sender_name is validated on publish and again before each send.

Example Request

bash

curl -X POST https://api.sms-campaign.smsphilippines.com/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign": { "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b", "status": "active", "sender_name": "ZENGLOBAL", "contact_group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" }, "messages": [ { "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c", "step": 1, "message": "Hi! Don't miss our sale this weekend.", "is_recurring": false, "scheduled_at": "2026-09-20 09:00:00" } ] }'

Request Body

json

{
  "campaign": {
    "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
    "status": "active",
    "sender_name": "ZENGLOBAL",
    "contact_group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
  },
  "messages": [
    {
      "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c",
      "step": 1,
      "message": "Hi! Don't miss our sale this weekend.",
      "is_recurring": false,
      "scheduled_at": "2026-09-20 09:00:00"
    }
  ]
}

Response

json

{
  "success": true,
  "action": "active",
  "sender_name": "ZENGLOBAL",
  "messages": [
    { "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c", "status": "scheduled", "next_run": "2026-09-20 09:00:00" }
  ]
}

POST/publish

Schedule a recurring campaign (weekly)

recurrence_days picks which weekdays to send on [5] sends every Friday, [1,3,5] sends Mon/Wed/Fri. recurrence_time is 24-hour HH:MM PHT, no seconds.

recurrence_days values

Value	Day
0	Sunday
1	Monday
2	Tuesday
3	Wednesday
4	Thursday
5	Friday
6	Saturday

Example Request

bash

curl -X POST https://api.sms-campaign.smsphilippines.com/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign": { "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b", "status": "active", "sender_name": "ZENGLOBAL", "contact_group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" }, "messages": [ { "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c", "step": 1, "message": "Weekly reminder: we're open until 9pm every Friday!", "is_recurring": true, "recurrence_frequency": "weekly", "recurrence_days": [5], "recurrence_time": "09:00", "recurrence_start": "2026-09-20", "recurrence_end": "2026-12-31" } ] }'

Request Body

json

{
  "campaign": {
    "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
    "status": "active",
    "sender_name": "ZENGLOBAL",
    "contact_group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
  },
  "messages": [
    {
      "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c",
      "step": 1,
      "message": "Weekly reminder: we're open until 9pm every Friday!",
      "is_recurring": true,
      "recurrence_frequency": "weekly",
      "recurrence_days": [5],
      "recurrence_time": "09:00",
      "recurrence_start": "2026-09-20",
      "recurrence_end": "2026-12-31"
    }
  ]
}

Response

json

{
  "success": true,
  "action": "active",
  "sender_name": "ZENGLOBAL",
  "messages": [
    { "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c", "status": "scheduled", "next_run": "2026-09-20 09:00:00" }
  ]
}

POST/publish

Schedule a recurring campaign (daily)

recurrence_frequency: "daily" sends every day from recurrence_start. recurrence_days and recurrence_day_of_month are not used and can be omitted. recurrence_time is 24-hour HH:MM PHT.

Recurrence fields

Field	Used for daily	Description
recurrence_frequency	Yes	Set to "daily".
recurrence_time	Yes	24-hour HH:MM PHT send time.
recurrence_start	Yes	First send date (YYYY-MM-DD).
recurrence_end	Optional	Stop date (YYYY-MM-DD). Omit to recur indefinitely.
recurrence_days	No	Not used for daily omit.
recurrence_day_of_month	No	Not used for daily omit.

Example Request

bash

curl -X POST https://api.sms-campaign.smsphilippines.com/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign": { "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b", "status": "active", "sender_name": "ZENGLOBAL", "contact_group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" }, "messages": [ { "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c", "step": 1, "message": "Today's daily deal is live check it out!", "is_recurring": true, "recurrence_frequency": "daily", "recurrence_time": "08:00", "recurrence_start": "2026-09-20", "recurrence_end": "2026-10-20" } ] }'

Request Body

json

{
  "campaign": {
    "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
    "status": "active",
    "sender_name": "ZENGLOBAL",
    "contact_group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
  },
  "messages": [
    {
      "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c",
      "step": 1,
      "message": "Today's daily deal is live check it out!",
      "is_recurring": true,
      "recurrence_frequency": "daily",
      "recurrence_time": "08:00",
      "recurrence_start": "2026-09-20",
      "recurrence_end": "2026-10-20"
    }
  ]
}

Response

json

{
  "success": true,
  "action": "active",
  "sender_name": "ZENGLOBAL",
  "messages": [
    { "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c", "status": "scheduled", "next_run": "2026-09-20 08:00:00" }
  ]
}

POST/publish

Schedule a recurring campaign (monthly)

recurrence_day_of_month picks the day of the month to send on (valid 1-31). recurrence_days is not used for monthly. recurrence_end is omitted here, so this recurs indefinitely until paused or stopped.

Recurrence fields

Field	Used for monthly	Description
recurrence_frequency	Yes	Set to "monthly".
recurrence_day_of_month	Yes	Day of month to send (1-31).
recurrence_time	Yes	24-hour HH:MM PHT send time.
recurrence_start	Yes	First send date (YYYY-MM-DD).
recurrence_end	Optional	Stop date (YYYY-MM-DD). Omit to recur indefinitely.
recurrence_days	No	Not used for monthly omit.

Example Request

bash

curl -X POST https://api.sms-campaign.smsphilippines.com/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign": { "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b", "status": "active", "sender_name": "ZENGLOBAL", "contact_group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" }, "messages": [ { "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c", "step": 1, "message": "Your statement is ready view it in the app.", "is_recurring": true, "recurrence_frequency": "monthly", "recurrence_day_of_month": 15, "recurrence_time": "10:00", "recurrence_start": "2026-09-15" } ] }'

Request Body

json

{
  "campaign": {
    "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
    "status": "active",
    "sender_name": "ZENGLOBAL",
    "contact_group_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"
  },
  "messages": [
    {
      "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c",
      "step": 1,
      "message": "Your statement is ready view it in the app.",
      "is_recurring": true,
      "recurrence_frequency": "monthly",
      "recurrence_day_of_month": 15,
      "recurrence_time": "10:00",
      "recurrence_start": "2026-09-15"
    }
  ]
}

Response

json

{
  "success": true,
  "action": "active",
  "sender_name": "ZENGLOBAL",
  "messages": [
    { "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c", "status": "scheduled", "next_run": "2026-09-15 10:00:00" }
  ]
}

POST/publish

Pause a campaign (unpublish)

Set campaign.status to unpublish (pause), stop, or delete and POST the same campaign.id with the message ids to cancel. Publish again with status: active to resume.

Example Request

bash

curl -X POST https://api.sms-campaign.smsphilippines.com/publish \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign": { "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b", "status": "unpublish" }, "messages": [{ "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c" }] }'

Request Body

json

{
  "campaign": { "id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b", "status": "unpublish" },
  "messages": [{ "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c" }]
}

Response

json

{
  "success": true,
  "action": "unpublish",
  "messages": [{ "id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c", "status": "paused" }]
}

GET/campaign-status?campaign_id={campaign_id}

Get campaign status

Read-only view of every message in a campaign, scoped to your account. Provide campaign_id, message_id, or both. Optional ?status=sent&status=failed repeatable filter. All timestamps are PHT wall-clock.

Example Request

bash

curl -X GET https://api.sms-campaign.smsphilippines.com/campaign-status?campaign_id={campaign_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

json

{
  "success": true,
  "campaign_id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
  "timezone": "Asia/Manila (UTC+8)",
  "summary": { "total": 2, "by_status": { "scheduled": 1, "sent": 1 }, "next_run": "2026-09-27 09:00:00", "truncated": false },
  "messages": [
    { "message_id": "8f14e45f-ceea-4d3e-9d0d-1c2e3f4a5b6c", "campaign_id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b", "step": 1, "status": "sent", "next_run": "2026-09-27 09:00:00", "last_run": "2026-09-20 09:00:03" }
  ]
}

POST/terminate-campaign

Terminate an entire campaign

Cancels every message in the campaign in one call. Calling again on an already-terminated campaign returns count: 0 rather than an error.

Example Request

bash

curl -X POST https://api.sms-campaign.smsphilippines.com/terminate-campaign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b" }'

Request Body

json

{
  "campaign_id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b"
}

Response

json

{
  "success": true,
  "count": 1,
  "campaign_id": "c1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b"
}

Errors

The APIs use standard HTTP status codes. Error responses include an error.code you can branch on programmatically.

Code	Name	Description
200	OK	The request was successful.
202	Accepted	Request accepted for background processing (contacts, imports).
400	Bad Request	Missing or invalid fields e.g. MISSING_SENDER_NAME, SENDER_NAME_NOT_FOUND.
401	Unauthorized	Missing or invalid API key (MISSING_AUTH).
404	Not Found	The campaign or resource was not found on your account.
413	Payload Too Large	Import file exceeds the 15MB limit.
429	Too Many Requests	Rate limit exceeded. Retry after the indicated delay.
500	Server Error	An unexpected error occurred. Try again later.