Send SMS
Overview
Use Send SMS when your application needs to submit one templated SMS and receive an order identifier for tracking.
Endpoint
POST /api/v1/sms/sends
Authentication: Bearer access token.
Before You Begin
You need an authenticated merchant API user, an approved template, an authorized sender or enabled auto routing, and a recipient phone number.
The selected template controls what var means. If the template contains {{var}}, var is required and replaces that placeholder. If the template contains no placeholder, var must be empty. Rendered content must fit in one SMS.
Request fields
| Field | Type | Required | Rules |
|---|---|---|---|
phone_number | string | Yes | E.164 format, max 32 chars, example +639171234567. |
template_id | string | Yes | 4-16 chars, approved template logical ID. |
sender_id | string | Yes | Authorized sender logical ID, such as SID-1, or AUTO when FutureSMS has enabled auto routing for your merchant. |
var | string or null | Depends on template | Template variable value. For {{var}} templates, max 24 characters. |
client_order_id | string or null | No | Merchant-side reference, 12-128 chars. |
dlr_address | string or null | No | Order-level delivery report callback override, max 255 chars. |
Response fields
| Field | Meaning |
|---|---|
order_id | FutureSMS business order identifier. |
order_status | Initial order state, usually pending. |
message_status | Delivery state, initially null until a report is available. |
created_at | UTC creation time. |
Behavior
202 Accepted means FutureSMS accepted the request for processing. It does not mean final delivery. Use GET /api/v1/sms/orders/{order_id} or the DLR callback to track delivery.
When a request is accepted, FutureSMS:
- Confirms the API user belongs to an active merchant.
- Checks the template is approved and visible to that merchant.
- Resolves
AUTOto a configured sender when auto routing is enabled, or checks the requested sender is authorized for that merchant. - Normalizes and validates the recipient phone number.
- Renders the template content.
- Applies account and destination policy checks.
- Confirms the request can be processed for the account.
- Creates a pending order.
- Dispatches the order asynchronously.
Account state is updated by the order processing flow after the message is accepted for processing.
Delivery reports
If dlr_address is present on the order, FutureSMS uses it as the callback target for matched delivery reports. If it is not present, FutureSMS can use the merchant-level DLR address configured for the account.
Status codes
| Status | Meaning |
|---|---|
202 | Request accepted for processing. |
401 | Missing, invalid, or expired access token. |
403 | Authenticated caller is not allowed to send with this merchant, template, sender, or auto-routing setup. |
404 | Referenced sender, template, or auto-routing setup is not available to the caller. |
409 | Request conflicts with an existing business rule or merchant reference. |
422 | Request shape or field validation failed. |
Common validation failures include invalid E.164 phone number, client_order_id already used by the same merchant, unavailable destination, missing var for a variable template, var supplied for a fixed template, rendered message too long, unavailable auto routing when sender_id is AUTO, or unsafe callback URL.
Examples
{
"phone_number": "+639171234567",
"template_id": "TPL-1",
"sender_id": "SID-1",
"var": "Alice",
"client_order_id": "client-ord-20260325-0001",
"dlr_address": "https://merchant-a.example.com/dlr"
}
{
"phone_number": "+639171234567",
"template_id": "TPL-1",
"sender_id": "AUTO",
"var": "Alice",
"client_order_id": "client-ord-20260325-0002",
"dlr_address": "https://merchant-a.example.com/dlr"
}
{
"message": "Accepted",
"details": null,
"data": {
"order_id": "SDPS260325103012A1B2C3D",
"order_status": "pending",
"message_status": null,
"created_at": "2026-03-25T10:30:12Z"
},
"meta": null
}