Flexi API overview
The Flexi API accepts a range of input field names and maps them into a known SMS schema. This is useful when moving from another provider or connecting an existing system that already emits SMS-style JSON payloads.
HTTP POSTSubmit SMS messages using a simple HTTPS JSON request.
Flexible JSONCommon aliases such as to, mobile, destination, body, and message are recognised.
WebhooksReceive delivery results and inbound SMS messages at your own HTTPS endpoint.
Quick start
Send a POST request to the Flexi API endpoint with a JSON body containing the recipient, sender, and message content.
HTTP requestPOST /flexi/sms
POST https://flexiapi.tnz.co.nz/api/v2.04/flexi/sms
Content-Type: application/json; encoding='utf-8'
Accept: application/json; encoding='utf-8'
{
"to": "+6421000001",
"from": "5555",
"body": "Hello, this is a test."
}
Accepted does not mean delivered. A successful API response means the message request has been accepted for processing. Delivery is reported later through result reporting and webhooks.
Send SMS
| Endpoint | https://flexiapi.tnz.co.nz/api/v2.04/flexi/sms |
|---|
| Method | POST |
|---|
| Content type | application/json; encoding='utf-8' |
|---|
| Required setup | Create an API-enabled user in the TNZ Dashboard and use the generated API credential with your request. |
|---|
Example with message reference and callback URL
JSON request bodyapplication/json
{
"destination_number": "+6421000001",
"format": "SMS",
"content": "Hello, this is a test.",
"message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7",
"callback_url": "https://www.example.com/webhook"
}
Webhooks
Use webhooks to receive asynchronous updates after the original API request. Your endpoint should accept HTTPS POST requests, respond quickly with a 2xx status, and process events idempotently.
Result webhook
The Result webhook is used for delivery-status events after a submitted message has been processed by the network. Store your original message reference, match webhook events to your message record, and update your internal message state.
Example result payload
Result webhook payloadapplication/json
{
"Version": "v3.00",
"Sender": "application@domain.com",
"APIKey": "ta8wr7ymd",
"Type": "SMS",
"Destination": "+6421000001",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"ReceivedID": null,
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"JobNumber": "10AB20CE",
"SentTimeLocal": "2025-06-13 08:44:16",
"SendTimeUTC": "2025-06-12 20:44:16",
"SentTimeUTC_RFC3339": "2025-06-12T20:44:16.000Z",
"Status": "Success",
"Result": "delivered",
"Message": null,
"Price": 0.1,
"Detail": "SMSParts:2",
"URL": "https://www.example.com/data"
}
Inbound SMS webhook
The Inbound SMS webhook is used when TNZ receives an inbound SMS for your account, such as a customer reply, keyword response, or short-code message. Use it to ingest replies into a CRM, helpdesk, database, or automation workflow.
Example inbound SMS payload
Inbound SMS webhook payloadapplication/json
{
"Version": "v3.00",
"Sender": "application@domain.com",
"APIKey": "ta8wr7ymd",
"Type": "SMSReply",
"Destination": "+6421000001",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"ReceivedID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"JobNumber": "10AB20CE",
"SentTimeLocal": "2025-06-13 08:44:16",
"SendTimeUTC": "2025-06-12 20:44:16",
"SentTimeUTC_RFC3339": "2025-06-12T20:44:16.000Z",
"Status": "RECEIVED",
"Result": "RECEIVED",
"Message": "This is a received message from a mobile phone.",
"Price": 0.1,
"Detail": "InputToNumber:021-777909",
"URL": "https://www.example.com/data"
}
FAQ
Can I send internationally?
Yes. International delivery is supported. Pricing and sender restrictions may vary by destination.
Is there a request-size limit?
The Flexi API documentation states a 20MB server-side maximum request size. Your HTTP client or application framework may have a smaller limit.
Why are long messages split?
SMS is billed and delivered in message parts. Longer messages are split into concatenated parts.
Is HTTPS supported?
Yes. Use HTTPS for API submissions and webhook endpoints.