Last updated: June 7th, 2024

API Introduction

The Flexi API accepts a range of inputs and dynamically determines how to process your SMS message.

It is designed to be an ultra simple API integration specifically for SMS so that you can seamlessly redirect your existing endpoints into the TNZ network by simply changing the URL and Authorization header.

The Flexi API has been tested with Twilio, eTXT, mTXT, GroupText, MessageMedia, 3CX and a range of other tools.


Register your account

If you don't have an account, head to https://www.tnz.co.nz/Customer/SignUp/ and register.


Create & Export Your API Auth Token

To use the API, an Auth Token is required in the Authorization HTTP header.

To export your Auth Token:

  1. Login to the TNZ Dashboard
  2. Navigate to 'Users'
  3. Create a new user or select an existing one
  4. Enable API access (if it's not already enabled)
  5. Click on the 'API' tab
  6. Enable 'Auth Token' and create a new Auth Token
  7. Click the ' Copy' button to copy it to your clipboard
  8. Paste the Auth Token into the Authorization Header in your application or code

At any time, you can refresh your Auth Token by clicking the button and exporting your new Auth Token. This action will invalidate any apps using your old Auth Token.

Auth Tokens can be used for multiple use-cases, with SubAccount and Department values helping in tracking reporting and billing.

API v2.04 utilizes JWT token Authentication. For OAuth2 authentication options, contact your TNZ representative.


Understanding the API basics

This flexible API allows you to send multiple message types. For a brief overview of the API, see the TNZ API Structure guide.

The API URL:
https://flexiapi.tnz.co.nz/api/v2.04/flexi/sms

  • [Version] is the API Version ('v2.04')
  • [MessageType] is the type of message (currently only 'sms' is supported)


The API HTTP Headers:

The HTTP Headers define the API call's formatting -


Content-Type="application/json; encoding='utf-8'"
Accept="application/json; encoding='utf-8'"
Authorization="Basic [Auth Token]"

** The 'Accept' header is optional but encouraged


You can find your Auth Token in the TNZ Dashboard.



The API Body:

The Body contains your message details.

The Flexi API is designed to be flexible! Input any parameters and the API will do its best to match and send your SMS.


{
"to": "+6421000001",
"from": "5555",
"body": "Hello, this is a test."
}


API - Send SMS

Request:

API URL:        https://flexiapi.tnz.co.nz/api/v2.04/flexi/sms
HTTP Method:    POST
HTTP Headers:   Content-Type="application/json; encoding='utf-8'"
                Accept="application/json; encoding='utf-8'"

                Authorization="Basic [Your Auth Token]"
{
  "to": "+6421000001",
  "from": "5555",
  "body": "Hello, this is a test."
}

Response:

  • 200 OK - Message Accepted
  • 400 BAD REQUEST - Invalid Variables
  • 401 Unauthorized - Invalid Auth Token
  • 500 Internal Server Error - API Server Fault

Note:

A "Success" response indicates that the API has accepted your parameters, not that the message has been delivered. Refer to the API - Status Reporting section for delivery results.

For a list of error messages, see TNZ API Errors.

API - Examples



{
  "to": "+6421000001",
  "from": "5555",
  "body": "Hello, this is a test."
}
{
  "to_number": "+6421000001",
  "from_number": "5555",
  "message": "Hello, this is a test."
}
{
  "mobile": "+6421000001",
  "message": "Hello, this is a test."
}
{
  "destination": "+6421000001",
  "message": "Hello, this is a test."
}
{
  "messages": [
    {
      "destination_number": "+6421000001"
      "content": "Hello, this is a test.",
    }
  ]
}
{
  "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",
}

Aliases for To:

to tonumber
to_number tosms
to_sms tomobile
to_mobile mobile
mobilenumber mobile_number
handset number
destination destinationnumber
destination_number destinationmobile
recipient msisdn
target

Aliases for From:

from fromnumber
from_number fromsms
from_sms frommobile
from_mobile source
sourcenumber source_number
sourcemobile

Aliases for Message:

message message_text
messagetext text
body sms
content

Frequently Asked Questions

Can messages be sent internationally?

Yes, full international delivery is supported.

Is there a maximum request size?

The maximum request size supported is 20MB. This is our server side limitation. Your client side limitation may be smaller.

When I send SMS messages, the text is cut off at 160 characters. Why?

SMS messages are sent and charged in blocks of characters. One text message is 160 characters. By default, we will limit your message to three-message-parts in length (459 characters using the GSM character set, or 210 characters using Unicode/UCS-2). This can be increased on request. See the SMS Message Parts and Concatenated SMS guide for further information.

Is HTTPS, SSL, or TLS supported?

Yes, encrypted submissions are accepted across the API via HTTPS. SSL/TLS is also supported for outbound email messages provided the receiving email server supports this.
");