Last updated: July 1st 2024

API Introduction

Use just one API to send Email, SMS, Fax and Voice Calls -

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 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://api.tnz.co.nz/api/[Version]/[Action]/[MessageType]
https://api.tnz.co.nz/api/v2.04/send/sms

  • [Version] is the API Version ('v2.04')
  • [Action] defines the module ('send' a message or 'get' a status)
  • [MessageType] is the type of message ('email', 'sms', 'fax', etc.)


The API HTTP Headers:

The HTTP Headers define the API call's formatting -


> Headers for JSON formatted calls:

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

** The 'Accept' header is optional but encouraged


> Headers for XML formatted calls:

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

** Both 'Content-Type' and 'Accept' headers are mandatory


You can find your Auth Token in the TNZ Dashboard.



An API Send Example

An example for sending an outbound SMS using Raw JSON -

URL: https://api.tnz.co.nz/api/v2.04/send/sms

Headers:
   • Content-Type="application/json; encoding='utf-8'"
   • Accept="application/json; encoding='utf-8'"
   • Authorization="Basic eyJ0eXA....436k0-E4"    

Data:
{
  "MessageData": 
  {
    "Message": "Hello, this is a test.",
    "Destinations": [
        { "Recipient": "+6421000001" }
    ]
  }
}


Possible HTTP status values are:

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

An example JSON response value:

  • {
      "Result": "Success",
      "MessageID": "AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD""
    }
  • Status - 'Success' or 'Failed' indicates the outcome of your API POST (accepted or rejected by our server), not the delivery status of your message. For delivery tracking, refer to API - Status Reporting.
  • MessageID - A message tracking identifier (maximum 40 characters, alphanumeric). If you do not supply this field in your submitted MessageData, the API will return one for you in the response body (UUID v4, 36 characters).
  • Note - The API will verify that required fields are supplied, however it will not validate data. See TNZ API Errors for error descriptions.

API - Send Messages

Find instructions for each Message Type:

HTTP Method: POST

Sending Email - Send Email via REST API

 
 

Request:

API URL:        https://api.tnz.co.nz/api/v2.04/send/email
HTTP Method:    POST

    

Response:

SUCCESS Response
HTTP: 200 OK
FAILURE Response
HTTP: 400 Bad Request

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.


Field Descriptions:

HTTP Headers
Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c The Authorization header authenticates your API requests against your account (see Auth Token)
MessageData - Required Parameters
Parameter Example Value Description
EmailSubject Test Email Subject Subject field used in the email
SMTPFrom noreply@example.com Sets the email Sender/Return-Path at the SMTP level (this address receives bounce-back emails and is used for SPF/DKIM type authentication; 'FromEmail' is used if not specified)
From noreply Sets the email sender's Friendly Name (seen by the email recipient)
FromEmail noreply@example.com Sets the email sender's Email Address (seen by the email recipient; API 'Sender' is used if not specified)
CCEmail archives@example.com Adds a CC to the email
ReplyTo reply@example.com Adds a Reply-To to the email (if the recipient replies, the Reply To will receive the reply)
MessagePlain Hello,

This is a test message.

Thank you.
Content used for the message/plain section of the email (overrides 'Template')
Destinations > Recipient john.doe@example.com
recipient.three@example.com
recipient.four@example.com
Email address(es) to receive the message (for detailed formatting, see the Destinations parameter below)
MessageData - Advanced Parameters
Parameter Example Value Description
MessageID ID123456 A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body.
Reference Test1 Human readable message description (free format field, maximum 80 characters).
WebhookCallbackURL https://www.example.com/webhook Overrides your Sender's default Webhook URL. Requires a default webhook to be configured. A full path including https:// is required.
WebhookCallbackFormat JSON Overrides your Sender's default Webhook format ('JSON' or 'XML')
SendTime 2022-12-31T23:00 Delay sending until the specified date/time, a single point of time in a combined date and time representation ({date}T{time}; for example, 2022-08-29T04:00 in your local timezone, specified by your Sender setting or overridden using the TimeZone command).
TimeZone New Zealand User's local timezone (see Setting Timezones)
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
TemplateLocation Folder 01 Directory/location of Template to use
Template Template File Name Preloaded Template to use for email body (overridden by MessagePlain and/or MessageHTML parameters)
MessageHTML <html>Hello,<br /><br />This is a test message.<br /><br />Thank you.</html> Content used for the message/html section of the email (overrides 'Template' and 'MessagePlain')
Destinations > Recipient john.doe@example.com Recipient of the email
> Attention John Doe Recipient's name
> First Name John Recipient's first name
> Last Name Doe Recipient's last name
> Company Example Corp Recipient's company
> Custom1 Reference Number ABC123 Customisable tracking and personalisation field
> Custom2 Reference Code WWW222 Customisable tracking and personalisation field
> ContactID 6000000b-f002-4007-b00a-c00000000001 The Contact ID that corresponds to your Address Book contact
> GroupID 4000000b-f002-4007-b00a-c00000000002 The Group ID that corresponds to your Address Book group of contacts
> GroupCode My_Address_Book_Group The Group Code that corresponds to your Address Book group of contacts
Files > Name Sample.pdf Attachment's filename
> Data %%Base-64%% Base-64 encoded value of the attached file
HTTP Method: POST

Sending SMS - Send SMS/TXT via REST API

 
 

Request:

API URL:        https://api.tnz.co.nz/api/v2.04/send/sms
HTTP Method:    POST

    

Response:

SUCCESS Response
HTTP: 200 OK
FAILURE Response
HTTP: 400 Bad Request

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.


Field Descriptions:

HTTP Headers
Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c The Authorization header authenticates your API requests against your account (see Auth Token)
MessageData - Required Parameters
Parameter Example Value Description
Message Hello, this is a test message from Department01. Thank you. Plain or UTF-8 formatted SMS message
Destinations > Recipient +6421000001 Receiving mobile number. See the Destinations parameter below for more information.
MessageData - Advanced Parameters
Parameter Example Value Description
MessageID ID123456 A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body.
Reference Test1 Human readable message description (free format field, maximum 80 characters).
WebhookCallbackURL https://www.example.com/webhook Overrides your Sender's default Webhook URL. Requires a default webhook to be configured. A full path including https:// is required.
WebhookCallbackFormat JSON Overrides your Sender's default Webhook format ('JSON' or 'XML')
SendTime 2021-12-31T23:00 Delay sending until the specified date/time, a single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00 in your local timezone, specified by your Sender setting or overridden using the TimeZone command).
TimeZone New Zealand User's local timezone (see Setting Timezones)
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
FromNumber 6421000001 Setting SMS origination number, short code(s) will override in New Zealand - Not for New Zealand.
SMSEmailReply person.one@domain.com For email (SMTP) reply receipt notifications
CharacterConversion true Convert multi-byte characters into normalised GSM character format. ie. © to (C)
Message Hello [[FirstName]], view the [[Custom1]] link at [[Link:https://www.example.com/path/to/page.html]] or view the file at [[File1]] or reply at [[REPLY]] or OptOut at [[STOP]] An example Message that uses Personalisation, URL Shortener, File Link, Reply Link and Unsubscribe.
Destinations > Recipient +6421000001 Recipient of the SMS. See mobile number formatting for more information.

We recommend implementing a prefix check to limit potential Toll Fraud.
> Attention John Doe Recipient's name
> First Name John Recipient's first name
> Last Name Doe Recipient's last name
> Company Example Corp Recipient's company
> Custom1 Customisable tracking and personalisation field
> Custom2 Customisable tracking and personalisation field
> ContactID 6000000b-f002-4007-b00a-c00000000001 The Contact ID that corresponds to your Address Book contact
> GroupID 4000000b-f002-4007-b00a-c00000000002 The Group ID that corresponds to your Address Book group of contacts
> GroupCode My_Address_Book_Group The Group Code that corresponds to your Address Book group of contacts
Files > Name File Name.pdf Files referenced in [[File1]] commands (for MessageLink)
> Data %%Base-64%% Base-64 encoded value of the attached file
HTTP Method: POST

Sending Faxes - Send Fax via REST API

 
 

Request:

API URL:        https://api.tnz.co.nz/api/v2.04/send/fax
HTTP Method:    POST

    

Response:

SUCCESS Response
HTTP: 200 OK
FAILURE Response
HTTP: 400 Bad Request

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.


Field Descriptions:

HTTP Headers
Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c The Authorization header authenticates your API requests against your account (see Auth Token)
MessageData - Required Parameters
Parameter Example Value Description
Destinations > Recipient +6495005001 Receiving fax number. See the Destinations parameter below for more information.
Files > Name Sample.pdf Fax document's filename
> Data %%Base-64%% Base-64 encoded value of the document
MessageData - Advanced Parameters
Parameter Example Value Description
MessageID ID123456 A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body.
Reference Test1 Human readable message description (free format field, maximum 80 characters).
WebhookCallbackURL https://www.example.com/webhook Overrides your Sender's default Webhook URL. Requires a default webhook to be configured. A full path including https:// is required.
WebhookCallbackFormat JSON Overrides your Sender's default Webhook format ('JSON' or 'XML')
SendTime 2022-12-31T23:00 Delay sending until the specified date/time, a single point of time in a combined date and time representation ({date}T{time}; for example, 2022-08-29T04:00 in your local timezone, specified by your Sender setting or overridden using the TimeZone command).
TimeZone New Zealand User's local timezone (see Setting Timezones)
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
WatermarkFolder Folder01 Directory/location of Watermark file to use
WatermarkFirstPage Watermark File Name Watermark file to apply to the first page only
WatermarkAllPages Watermark File Name Watermark file to apply to all pages
Resolution High Quality of the fax image. High for better quality, low for lower quality (faster delivery speed)
CSID Station ID Called Subscriber Identification - Maximum 30 characters
Destinations > Recipient +6495005000 Recipient of the Fax. See number formatting for more information.

We recommend implementing a prefix check to limit potential Toll Fraud.

Fax does not support GroupID or GroupCode.
> Attention John Doe Recipient's name
> First Name John Recipient's first name
> Last Name Doe Recipient's last name
> Company Example Corp Recipient's company
> Custom1 Customisable tracking and personalisation field
> Custom2 Customisable tracking and personalisation field
HTTP Method: POST

Sending Voice (Voicemail) - Send VoiceCast via REST API

 
 

Request:

API URL:        https://api.tnz.co.nz/api/v2.04/send/voice
HTTP Method:    POST

    

Response:

SUCCESS Response
HTTP: 200 OK
FAILURE Response
HTTP: 400 Bad Request

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.


Field Descriptions:

HTTP Headers
Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c The Authorization header authenticates your API requests against your account (see Auth Token)
MessageData - Required Parameters
Parameter Example Value Description
MessageToPeople [Base64 encoded data] The audio data played if the call is answered by a human (WAV format, 16-bit, 8000hz)
Destinations > Recipient +6495005001 Receiving telephone number. See the Destinations parameter below for more information.
MessageData - Advanced Parameters
Parameter Example Value Description
MessageID ID123456 A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body.
Reference Test1 Human readable message description (free format field, maximum 80 characters).
WebhookCallbackURL https://www.example.com/webhook Overrides your Sender's default Webhook URL. Requires a default webhook to be configured. A full path including https:// is required.
WebhookCallbackFormat JSON Overrides your Sender's default Webhook format ('JSON' or 'XML')
SendTime 2021-12-31T23:00 Delay sending until the specified date/time, a single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00 in your local timezone, specified by your Sender setting or overridden using the TimeZone command).
TimeZone New Zealand User's local timezone (see Setting Timezones)
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
ReportTo report@example.com For email (SMTP) message delivery report notifications.
MessageToAnswerphones [Base64 encoded data] Enables Answering Machine/Voicemail detection. When an answering machine is detected, this message is played. The message should be in WAV format, 16-bit, 8000hz.
Keypads > Tone 1 Keypad for call connection (supports buttons 1-9)
> RouteNumber +64800123123 Connects the callee to the specified number (number must be in E164 format)
> Play [Base64 encoded data] Audio data played to B-Party when a keypad option is pressed (WAV format, 16-bit, 8000hz), eg "Thank you. You have pressed keypad 1."
> PlaySection Main Plays the MessageToPeople ('Main') or MessageToAnswerphones ('AnswerPhone'). Useful for replaying the message
KeypadOptionRequired false When this setting is turned on, the call recipient must press a valid keypad button. If they don't, their call attempt gets logged as a Failure with the Result "No Valid Option Selected," and it will be automatically retried until Retry Attempts are exhausted. Note: If Wrong Key is enabled, listeners can press any keypad button to mark a successful response.
CallRouteMessageToPeople [Base64 encoded data] Audio data played when a keypad option is pressed (WAV format, 16-bit, 8000hz), eg "Connecting you now."
CallRouteMessageToOperators [Base64 encoded data] Audio data played to the call centre representative answering the connected call (WAV format, 16-bit, 8000hz), eg "Incoming Text To Speech call."
CallRouteMessageOnWrongKey [Base64 encoded data] If Keypad buttons are specified, this option enables a Wrong Keypad message that is played if the callee presses an unregistered keypad button, or doesn't press a keypad button, eg "Sorry, you have pressed an invalid key. Please try again". You are best to not specify this message if using KeypadOptionRequired.
NumberOfOperators 5 Limits the maximum simultaneous calls (where multiple 'Destinations' are listed). Set 99999 for max throughput
AnswerPhoneMode NDAS Sets the action for when an Answering Machine is detected ('NDAS','NDAF','DAS','DAF'). See Answer Phone Detection for Voice.
RetryAttempts 3 Number of retry attempts if the call fails (for example, the recipients line is busy or unavailable). If an Alt Phone is specified, the contact's Main Phone will be attempted until RetryAttempts is exhausted, then the Alt Phone will be tried. RetryAttempts=0 means the call will not be retried.
RetryPeriod 1 Minutes apart when performing retries
CallerID +6495005000 Sets the Caller ID used on the call (must be E.164 format and previously whitelisted under your account)
Options Customisable field that allows advanced voice options including recording survey responses, recording phone numbers, playing IVR options, capturing DTMF tones for account numbers or credit card numbers, etc.
Destinations > Recipient +6495005000 Recipient of the call. See number formatting for more information.

We recommend implementing a prefix check to limit potential Toll Fraud.
> Attention John Doe Recipient's name
> First Name John Recipient's first name
> Last Name Doe Recipient's last name
> Company Example Corp Recipient's company
> Custom1 Customisable tracking and personalisation field
> Custom2 Customisable tracking and personalisation field
> ContactID 6000000b-f002-4007-b00a-c00000000001 The Contact ID that corresponds to your Address Book contact
> GroupID 4000000b-f002-4007-b00a-c00000000002 The Group ID that corresponds to your Address Book group of contacts
> GroupCode My_Address_Book_Group The Group Code that corresponds to your Address Book group of contacts
HTTP Method: POST

Sending Voice Text To Speech - Send TTS via REST API

 
 

Request:

API URL:        https://api.tnz.co.nz/api/v2.04/send/tts
HTTP Method:    POST

    

Response:

SUCCESS Response
HTTP: 200 OK
FAILURE Response
HTTP: 400 Bad Request

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.


Field Descriptions:

HTTP Headers
Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c The Authorization header authenticates your API requests against your account (see Auth Token)
MessageData - Required Parameters
Parameter Example Value Description
MessageToPeople Hello, this is a call from Department01. This is relevant information. Press one to be connected to our call centre. The text-to-speech message played if the call is answered by a human (may optionally include SSML commands)
Destinations > Recipient +6495005001 Receiving telephone number. See the Destinations parameter below for more information.
MessageData - Advanced Parameters
Parameter Example Value Description
MessageID ID123456 A Message Identifier helps you keep track of each message (maximum 40 characters, alphanumeric). Use a unique MessageID for each request. If you leave this field blank, the API will generate a 36-character UUID (v4) for you and include it in the response body.
Reference Test1 Human readable message description (free format field, maximum 80 characters).
WebhookCallbackURL https://www.example.com/webhook Overrides your Sender's default Webhook URL. Requires a default webhook to be configured. A full path including https:// is required.
WebhookCallbackFormat JSON Overrides your Sender's default Webhook format ('JSON' or 'XML')
SendTime 2021-12-31T23:00 Delay sending until the specified date/time, a single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00 in your local timezone, specified by your Sender setting or overridden using the TimeZone command).
TimeZone New Zealand User's local timezone (see Setting Timezones)
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
Department Department01 Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's Cost Tracking & Rebilling section.
ChargeCode BillingGroup01 Bespoke app cost allocation code (for invoice segmentation)
ReportTo report@example.com For email (SMTP) message delivery report notifications.
MessageToAnswerphones Hello, sorry we missed you. This is a call from Department 01. Please contact us on 0800 123123. Enables Answering Machine/Voicemail detection. When an answering machine is detected, this message is played. The message may include SSML Commands.
Keypads > Tone 1 Keypad for call connection (supports buttons 1-9)
> RouteNumber +64800123123 Connects the callee to the specified number (number must be in E164 format)
> Play You pressed Keypad 1 Message played to B-Party when a keypad option is pressed
> PlaySection Main Plays the MessageToPeople ('Main') or MessageToAnswerphones ('AnswerPhone'). Useful for replaying the message
KeypadOptionRequired false When this setting is turned on, the call recipient must press a valid keypad button. If they don't, their call attempt gets logged as a Failure with the Result "No Valid Option Selected," and it will be automatically retried until Retry Attempts are exhausted. Note: If Wrong Key is enabled, listeners can press any keypad button to mark a successful response.
CallRouteMessageToPeople Connecting you now. Text-to-speech message played when a keypad option is pressed
CallRouteMessageToOperators Incoming Text To Speech call. Text-to-speech message played to the call centre representative answering the connected call
CallRouteMessageOnWrongKey Sorry, you have pressed an invalid key. Please try again. If Keypad buttons are specified, this option enables a Wrong Keypad message that is played if the callee presses an unregistered keypad button, or doesn't press a keypad button. You are best to not specify this message if using KeypadOptionRequired.
NumberOfOperators 5 Limits the maximum simultaneous calls (where multiple 'Destinations' are listed). Set 99999 for max throughput
AnswerPhoneMode NDAS Sets the action for when an Answering Machine is detected ('NDAS','NDAF','DAS','DAF'). See Answer Phone Detection for Voice.
RetryAttempts 3 Number of retry attempts if the call fails (for example, the recipients line is busy or unavailable). If an Alt Phone is specified, the contact's Main Phone will be attempted until RetryAttempts is exhausted, then the Alt Phone will be tried. RetryAttempts=0 means the call will not be retried.
RetryPeriod 1 Minutes apart when performing retries
CallerID +6495005000 Sets the Caller ID used on the call (must be E.164 format and previously whitelisted under your account)
Voice Female1 Text-to-Speech voice to use (Male1, Female1, Nicole, Russell, Amy, Brian, Emma)
Options Customisable field that allows advanced voice options including recording survey responses, recording phone numbers, playing IVR options, capturing DTMF tones for account numbers or credit card numbers, etc.
Destinations > Recipient +6495005000 Recipient of the call. See number formatting for more information.

We recommend implementing a prefix check to limit potential Toll Fraud.
> Attention John Doe Recipient's name
> First Name John Recipient's first name
> Last Name Doe Recipient's last name
> Company Example Corp Recipient's company
> Custom1 Customisable tracking and personalisation field
> Custom2 Customisable tracking and personalisation field
> ContactID 6000000b-f002-4007-b00a-c00000000001 The Contact ID that corresponds to your Address Book contact
> GroupID 4000000b-f002-4007-b00a-c00000000002 The Group ID that corresponds to your Address Book group of contacts
> GroupCode My_Address_Book_Group The Group Code that corresponds to your Address Book group of contacts

Sending messages in test mode

Under MessageData you can specify an additional Mode=Test parameter.

Mode=Test means any messages will be handled by the API, instantly called a SUCCESS and the success report will be delivered to you. This is a useful way to end-to-end test without sending a live message.


...
  "MessageData" :
  {
      ...
      "Mode": "Test"
  }
...
                                            
HTTP Method: PATCH

API - Edit Messages - Edit a submitted message

Once a message has been sent, you can retry a failed message, reschedule a delayed message, abort a delayed message and edit the NumberOfOperators value on Voice/TTS messages.


Retry Sending - Resubmit a failed message

If your message is 'Failed' (sending completed and was unsuccessful), you can use this API module to retry sending.

The Retry is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message and only if the Status was Failed.


 
API URL:        https://api.tnz.co.nz/api/v2.04/set/resubmit/[MessageID]
HTTP Method:    PATCH

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required parameters

Parameter Example Value Description
MessageID ID123456 MessageID the Action should apply to
SendTime (Optional) 2021-12-31T23:00 Delay sending until the specified date/time, a single point of time in a combined date and time representation ({date}T{time}; for example, 2022-08-29T04:00 in your local timezone, specified by your Sender setting or overridden using the TimeZone command).

SUCCESS response parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
MessageID ID123456 MessageID the Action was applied to
Status Transmit State of the message prior to performing the Action ('Transmit', 'Pending', 'Delayed', 'CreditHold', 'Deleted')
JobNum ABCD1234 Eight digit alphanumeric tracking number (our internal Job Number)
Action Resubmit The Action performed

FAILED response parameters

Parameter Example Value Description
Result Failed Result of your API call (not the result of the message)
MessageID ID123456 MessageID provided in your request
Message Message not found Reason for the API call failure (see a list of possible values: TNZ API Errors)



HTTP Method: PATCH

Reschedule Sending - Adjust the Delayed Sending Date/Time

If you have an existing Delayed message (scheduled for sending at a future date/time), you can use this API module to adjust the sending date/time.

The adjustment is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message.


 
API URL:        https://api.tnz.co.nz/api/v2.04/set/reschedule/[MessageID]
HTTP Method:    PATCH

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required parameters

Parameter Example Value Description
MessageID ID123456 MessageID the Action should apply to
SendTime 2021-12-31T23:00 Reschedule sending for the specified date/time, a single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00 in your local timezone, specified by your Sender setting or overridden using the TimeZone command).

SUCCESS response parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
MessageID ID123456 MessageID the Action was applied to
Status Transmit State of the message prior to performing the Action ('Transmit', 'Pending', 'Delayed', 'CreditHold', 'Deleted')
JobNum ABCD1234 Eight digit alphanumeric tracking number (our internal Job Number)
Action Reschedule The Action performed

FAILED response parameters

Parameter Example Value Description
Result Failed Result of your API call (not the result of the message)
MessageID ID123456 MessageID provided in your request
Message Message not found Reason for the API call failure (see a list of possible values: TNZ API Errors)



HTTP Method: PATCH

Abort Sending - Cancel/Delete a Message from the Queue

If you have an existing Delayed message (scheduled for sending at a future date/time) you can use this API module to Cancel sending of the message.

The cancellation is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message.


 
API URL:        https://api.tnz.co.nz/api/v2.04/set/abort/[MessageID]
HTTP Method:    PATCH

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required parameters

Parameter Example Value Description
MessageID ID123456 MessageID the Action should apply to

SUCCESS response parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
MessageID ID123456 MessageID the Action was applied to
Status Delayed State of the message prior to performing the Action ('Transmit', 'Pending', 'Delayed', 'CreditHold', 'Deleted')
JobNum ABCD1234 Eight digit alphanumeric tracking number (our internal Job Number)
Action Abort The Action performed

FAILED response parameters

Parameter Example Value Description
Result Failed Result of your API call (not the result of the message)
MessageID ID123456 MessageID provided in your request
Message Message not found Reason for the API call failure (see a list of possible values: TNZ API Errors)



HTTP Method: PATCH

Adjust NumberOfOperators - Change the Voice/Text-to-Speech NumberOfOperators Value

When sending a Voice/Text-to-Speech message, you may specify the NumberOfOperators value (limits the quantity of simultaneous/concurrent calls). You can use this API module to adjust the NumberOfOperators value in real-time.

The cancellation is applied to a specific MessageID. If you use common MessageID values across multiple messages, it will apply to the most recent message.


 
API URL:        https://api.tnz.co.nz/api/v2.04/set/pacing/[MessageID]
HTTP Method:    PATCH

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required parameters

Parameter Example Value Description
MessageID ID123456 MessageID the Action should apply to
NumberOfOperators 4 NumberOfOperators value to apply

SUCCESS response parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
MessageID ID123456 MessageID the Action was applied to
Status Pending State of the message prior to performing the Action ('Transmit', 'Pending', 'Delayed', 'CreditHold', 'Deleted')
JobNum ABCD1234 Eight digit alphanumeric tracking number (our internal Job Number)
Action NumberOfOperators The Action performed

FAILED response parameters

Parameter Example Value Description
Result Failed Result of your API call (not the result of the message)
MessageID ID123456 MessageID provided in your request
Message Message not found Reason for the API call failure (see a list of possible values: TNZ API Errors)

API - Status Reporting - Reporting and event tracking

Delivery Reports advise whether delivery was successful. If not, it will describe why.

Each delivery report type is optional and multiple delivery report types can be used.



Web Dashboard - Tracking message statuses via the online dashboard

You will be supplied with a Web Dashboard login at registration. The Dashboard can be used to set up new sender/token pairs, as well as track sent and replied messages. You can drill into specific messages to view individual events, such as delivery attempts, retries, replies, results, clicks, etc.



SMTP Email - Receive message statuses via email

Delivery reports are emailed as an HTML email for viewing by an end-user. Your sales representative can enable this for you.

Whitelabelling of SMTP Email reports is available.



HTTP Method: POST

Webhook - Message statuses delivered via a webhook

To receive Delivery Reports via Webhook, please advise the URL to submit to.

Webhooks are delivered as an HTTP POST in either XML or JSON format (your preference; defined by the WebhookCallbackFormat in your outbound message).

Webhook failures are retried every five minutes for a maximum of 24 hours.


 
 
API URL:        https://www.example.com/webhook
HTTP Method:    POST
HTTP Headers:   Content-Type="application/json"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

{
  "Version": "2.04",
  "Sender": "application@domain.com",
  "APIKey": "ta8wr7ymd",
  "Type": "SMS",
  "Destination": "+6421000001",
  "ContactID": "7000000a-f002-4007-b00a-d00000000001",
  "ReceivedID": "",
  "MessageID": "1000000a-f002-4007-b00a-d00000000002",
  "SubAccount": "SubAccount01",
  "Department": "Department01",
  "JobNumber": "10C7B9A0",
  "SentTimeLocal": "2024-05-01 15:51:42",
  "SentTimeUTC": "2024-05-01 03:51:42",
  "SentTimeUTC_RFC3339": "2024-05-01T03:51:42.000Z",  
  "Status": "SUCCESS",
  "Result": "delivered",
  "Message": "",
  "Price": "0.10",
  "Detail": "SMSParts:1",
  "URL": "https://www.example.com/webhook"
}          

Copy code

API URL:        https://www.example.com/webhook
HTTP Method:    POST
HTTP Headers:   Content-Type="text/xml"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

<?xml version='1.0' encoding='UTF-8'?>
<root>
  <Version>2.04</Version>
  <Sender>application@domain.com</Sender>
  <APIKey>ta8wr7ymd</APIKey>
  <Type>SMS</Type>
  <Destination>+6421000001</Destination>
  <ContactID>7000000a-f002-4007-b00a-d00000000001</ContactID>
  <ReceivedID></ReceivedID>
  <MessageID>1000000a-f002-4007-b00a-d00000000002</MessageID>
  <SubAccount>SubAccount01</SubAccount>
  <Department>Department01</Department>
  <JobNumber>10C7B9A0</JobNumber>
  <SentTimeLocal>2024-05-01 15:51:42</SentTimeLocal>
  <SentTimeUTC>2024-05-01 03:51:42</SentTimeUTC>
  <SentTimeUTC_RFC3339>2024-05-01T03:51:42.000Z</SentTimeUTC_RFC3339>
  <Status>SUCCESS</Status>
  <Result>delivered</Result>
  <Message></Message>
  <Price>0.10</Price>
  <Detail>SMSParts:1</Detail>
  <URL>https://www.example.com/webhook</URL>
</root>          

Copy code

Parameters:

Parameter Example Value Description
Version 2.04 The API Version configured for the webhook
Sender application@domain.com Webhook sender authentication (can configure a unique Sender if required)
APIKey ta8wr7ymd Webhook token authentication (can configure a unique APIKey if required)
Type SMS Type of Message ('Email', 'SMS', 'Fax', 'Voice', 'TextToSpeech', 'SMSInbound' or 'SMSReply')
Destination +6421000001 Destination that the webhook is for (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format)
ContactID 7000000a-f002-4007-b00a-d00000000001 Displays the Address Book Contact ID. If unavailable, displays an empty field. UUID v4, 36 characters.
ReceivedID Tracking ID for inbound/reply SMS messages. Always blank for Status webhooks.
MessageID 1000000a-f002-4007-b00a-d00000000002 MessageID parameter supplied when sending your original API call. If you did not supply one, the API generated one for you.
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation
Department Department01 Used for reporting, billing and Web Dashboard segmentation
JobNumber 10C7B9A0 Eight digit alphanumeric tracking number (our internal Job Number)
SentTimeLocal 2024-05-01 15:51:42 Time the message was sent in the users local timezone (ISO 8601 format)
SentTimeUTC 2024-05-01 03:51:42 Time the message was sent in UTC (ISO 8601 format)
SentTimeUTC_RFC3339 2024-05-01T03:51:42.000Z Time the message was sent in UTC (RFC 3339 format)
Status SUCCESS For submission results, values are SUCCESS, FAILED, PENDING
For reply reports, this will be RECEIVED
For additional analytics, this will be UPDATED
Result Sent OK Final delivery result and/or the cause for a message delivery failure
For a list of possible values, see SMS, Fax, Voice, TextToSpeech
Email result codes are defined by the receiving email server
For reply reports, this will be RECEIVED
For additional analytics, this will be the event description
Message The message content. Always blank for Status webhooks.
Price 0.20 Your cost for this transaction, charged by us to you
Detail SMSParts:2 Additional message details:

'EmailSize' is the size of the email in bytes

'SMSParts' is the quantity of SMS Parts

'FaxPages' is the quantity of Fax Pages

'VoiceRemoteID' is the call recipient's phone number (this may differ from 'Destination' if failover Alt Phones are used)

'VoiceSeconds' is the call length in seconds

'VoiceTotalCallTime' is the total call time including unbillable call set-up and ringing time

'Prompts' defines the keypad options selected by the call recipient
URL https://www.example.com/webhook The URL this webhook is sent to


HTTP Method: GET

GET Status Poll - Track message statuses using a GET poll

API users are able to poll for the status of a message via the GET Status API.

The GET Poll should be configured to timeout after 48 hours with no result.


 
 
API URL:        https://api.tnz.co.nz/api/v2.04/get/status/[MessageID]
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required parameters

Parameter Example Value Description
MessageID ID123456 Your provided Message ID or TNZ Group generated Message ID

Success Response parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
MessageID AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Your provided Message ID or TNZ Group generated Message ID
Status Completed Current state of the message ('Unknown', 'Pending', 'Delayed', 'Completed', 'CreditHold')
JobNum 10AB20CE Eight digit alphanumeric tracking number (our internal Job Number)
Account 102030 Your TNZ Account
SubAccount Your supplied TNZ SubAccount
Department Your supplied TNZ Department
Reference Your supplied Reference
CreatedTimeLocal Time the message was created/generated in the users local timezone (ISO 8601 format)
CreatedTimeUTC Time the message was created/generated in UTC (ISO 8601 format)
CreatedTimeUTC_RFC3339 Time the message was created/generated in UTC (RFC 3339 format)
DelayedTimeLocal Time the message was scheduled for sending in the users local timezone (ISO 8601 format)
DelayedTimeUTC Time the message was scheduled for sending in UTC (ISO 8601 format)
DelayedTimeUTC_RFC3339 Time the message was scheduled for sending in UTC (RFC 3339 format)
Count 5 Total Destinations specified in the message
Complete 5 Total Destinations where message transmission has completed
Success 4 Total Destinations where message result is Success
Failed 1 Total Destinations where message result is Failed
Recipients > Type Text Type of Message ('Email', 'SMS', 'Fax', 'Voice', 'TextToSpeech', 'SMSInbound' or 'SMSReply')
> DestSeq 00000001 The ID of the destination in the list (increments per destination)
> Destination +6421000001 Destination send to (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format)
> ContactID 7000000a-f002-4007-b00a-d00000000001 Displays the Address Book Contact ID. If unavailable, displays an empty field.
> Status SUCCESS For submission results, values are SUCCESS, FAILED, PENDING
For reply reports, this will be RECEIVED
For additional analytics, this will be UPDATED
> Result delivered Final delivery result and/or the cause for a message delivery failure
For a list of possible values, see SMS, Fax, Voice, TextToSpeech
Email result codes are defined by the receiving email server
For reply reports, this will be RECEIVED
For additional analytics, this will be the event description
> SentTimeLocal 2024-05-01 15:51:42 Time the message was sent in the users local timezone (ISO 8601 format)
> SentTimeUTC 2024-05-01 03:51:42 Time the message was sent in UTC (ISO 8601 format)
> SentTimeUTC_RFC3339 2024-05-01T03:51:42.000Z Time the message was sent in UTC (RFC 3339 format)
> Attention Gary Jones The Attention value supplied in your original send request (for tracking)
> Company XYZ Corp The Company value supplied in your original send request (for tracking)
> Custom1-9 Variable data The Custom values supplied in your original send request (for tracking)
> RemoteID +6495005000 For Voice and Text-to-Speech, this is the call recipient's phone number (this may differ from 'Destination' if failover Alt Phones are used)
> Price 0.20 Your cost for this transaction, charged by us to you

Failed Response parameters

Parameter Example Value Description
Result Failed Result of your API call (not the result of the message)
MessageID AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Your provided Message ID or TNZ Group generated Message ID
Message Missing Sender Reason for the API call failure (see a list of possible values: TNZ API Errors)

API - Receive Messages - Track messages received

Currently, tracking SMS Received is supported.

Tracking of faxes and voicemail received is scheduled for a future release. Let your account manager know if this interests you.



Web Dashboard - Tracking messages received via the online dashboard

You will be supplied with a Web Dashboard login at registration. The Dashboard can be used to set up new sender/token pairs, as well as track sent and replied messages. You can drill into specific messages to view individual events, such as delivery attempts, retries, replies, results, clicks, etc.



SMTP Email - Track messages received via email

Reply message reports are emailed as an HTML email for viewing by an end-user.
Whitelabelling of SMTP Email reports is available.

When submitting SMS messages, specify the SMSEmailReply parameter.



Webhook - Messages received data delivered via a webhook

If you are set up to receive Status webhooks, you will also be receiving SMS Received webhooks.

To receive SMS replies via Webhook, please advise the URL to submit to.

Webhooks are delivered as an HTTP POST in either XML or JSON format (your preference; defined by the WebhookCallbackFormat in your outbound message).

Webhook failures are retried every five minutes for a maximum of 24 hours.

The mobile has 7 days to reply to a message. Any replies received after the 7 day window will be treated as a new message.


 
 
API URL:        https://www.example.com/webhook
HTTP Method:    POST
HTTP Headers:   Content-Type="application/json"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

{
  "Version": "2.04",
  "Sender": "application@domain.com",
  "APIKey": "ta8wr7ymd",
  "Type": "SMSReply",
  "Destination": "+6421000001",
  "ContactID": "7000000a-f002-4007-b00a-d00000000001",
  "ReceivedID": "5000000a-f002-4007-b00a-d00000000001",
  "MessageID": "1000000a-f002-4007-b00a-d00000000002",
  "SubAccount": "SubAccount01",
  "Department": "Department01",
  "JobNumber": "10C7B9A0",
  "SentTimeLocal": "2024-05-01 15:51:42",
  "SentTimeUTC": "2024-05-01 03:51:42",
  "SentTimeUTC_RFC3339": "2024-05-01T03:51:42.000Z",  
  "Status": "RECEIVED",
  "Result": "RECEIVED",
  "Message": "This is a reply.",
  "Price": "",
  "Detail": "InputToNumber:021-000 001",
  "URL": "https://www.example.com/webhook"
}          

Copy code

API URL:        https://www.example.com/webhook
HTTP Method:    POST
HTTP Headers:   Content-Type="application/json"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

{
  "Version": "2.04",
  "Sender": "application@domain.com",
  "APIKey": "ta8wr7ymd",
  "Type": "SMSReply",
  "Destination": "+6421000001",
  "ContactID": "7000000a-f002-4007-b00a-d00000000001",
  "ReceivedID": "5000000a-f002-4007-b00a-d00000000001",
  "MessageID": "1000000a-f002-4007-b00a-d00000000002",
  "SubAccount": "SubAccount01",
  "Department": "Department01",
  "JobNumber": "10C7B9A0",
  "SentTimeLocal": "2024-05-01 15:51:42",
  "SentTimeUTC": "2024-05-01 03:51:42",
  "SentTimeUTC_RFC3339": "2024-05-01T03:51:42.000Z",  
  "Status": "RECEIVED",
  "Result": "RECEIVED",
  "Message": "This is a reply.",
  "Price": "",
  "Detail": "InputToNumber:021-000 001",
  "URL": "https://www.example.com/webhook"
}          

Copy code

API URL:        https://www.example.com/webhook
HTTP Method:    POST
HTTP Headers:   Content-Type="text/xml"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <Version>2.04@domain.com</Version>
  <Sender>application@domain.com</Sender>
  <APIKey>ta8wr7ymd</APIKey>
  <Type>SMSReply</Type>
  <Destination>+6421000001</Destination>
  <ContactID>7000000a-f002-4007-b00a-d00000000001</ContactID>
  <ReceivedID>5000000a-f002-4007-b00a-d00000000001</ReceivedID>
  <MessageID>1000000a-f002-4007-b00a-d00000000002</MessageID>
  <SubAccount>SubAccount01</SubAccount>
  <Department>Department01</Department>
  <JobNumber>10C7B9A0</JobNumber>
  <SentTimeLocal>2024-05-01 15:51:42</SentTimeLocal>
  <SentTimeUTC>2024-05-01 03:51:42</SentTimeUTC>
  <SentTimeUTC_RFC3339>2024-05-01T03:51:42.000Z</SentTimeUTC_RFC3339>
  <Status>RECEIVED</Status>
  <Result>RECEIVED</Result>
  <Message>This is a reply.</Message>
  <Price></Price>
  <Detail>InputToNumber:021-000 001</Detail>
  <URL>https://www.example.com/webhook</URL>
</root>          

Copy code

API URL:        https://www.example.com/webhook
HTTP Method:    POST
HTTP Headers:   Content-Type="text/xml"
                X-Timestamp="2024-05-01T03:51:42.000Z"
                X-Sender="application@domain.com"
                Authorization="ta8wr7ymd"

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <Version>2.04@domain.com</Version>
  <Sender>application@domain.com</Sender>
  <APIKey>ta8wr7ymd</APIKey>
  <Type>SMSReply</Type>
  <Destination>+6421000001</Destination>
  <ContactID>7000000a-f002-4007-b00a-d00000000001</ContactID>
  <ReceivedID>5000000a-f002-4007-b00a-d00000000001</ReceivedID>
  <MessageID>1000000a-f002-4007-b00a-d00000000002</MessageID>
  <SubAccount>SubAccount01</SubAccount>
  <Department>Department01</Department>
  <JobNumber>10C7B9A0</JobNumber>
  <SentTimeLocal>2024-05-01 15:51:42</SentTimeLocal>
  <SentTimeUTC>2024-05-01 03:51:42</SentTimeUTC>
  <SentTimeUTC_RFC3339>2024-05-01T03:51:42.000Z</SentTimeUTC_RFC3339>
  <Status>RECEIVED</Status>
  <Result>RECEIVED</Result>
  <Message>This is a reply.</Message>
  <Price></Price>
  <Detail>InputToNumber:021-000 001</Detail>
  <URL>https://www.example.com/webhook</URL>
</root>          

Copy code

Parameters:

Parameter Example Value Description
Version 2.04 The API Version configured for the webhook
Sender application@domain.com Webhook sender authentication (can configure a unique Sender if required)
APIKey ta8wr7ymd Webhook token authentication (can configure a unique APIKey if required)
Type SMSReply Type of Message ('Email', 'SMS', 'Fax', 'Voice', 'TextToSpeech', 'SMSInbound' or 'SMSReply')
Destination +6421000001 Mobile number that sent the SMS (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format)
ContactID 7000000a-f002-4007-b00a-d00000000001 Displays the Address Book Contact ID. If unavailable, displays an empty field. UUID v4, 36 characters.
ReceivedID 5000000a-f002-4007-b00a-d00000000001 Tracking number for inbound/reply SMS messages. Each received SMS message will have a unique Received ID. UUID v4, 36 characters.
MessageID 1000000a-f002-4007-b00a-d00000000002 MessageID parameter supplied when sending your original API call. If you did not supply one, the API generated one for you.
SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation
Department Department01 Used for reporting, billing and Web Dashboard segmentation
JobNumber 10C7B9A0 Eight digit alphanumeric tracking number (our internal Job Number)
SentTimeLocal 2024-05-01 15:51:42 Time the reply message was received in the users local timezone (ISO 8601 format)
SentTimeUTC 2024-05-01 03:51:42 Time the reply message was received in UTC (ISO 8601 format)
SentTimeUTC_RFC3339 2024-05-01T03:51:42.000Z Time the reply message was received in UTC (RFC 3339 format)
Status RECEIVED For submission results, values are SUCCESS, FAILED, PENDING
For reply reports, this will be RECEIVED
For additional analytics, this will be UPDATED
Result RECEIVED Final delivery result and/or the cause for a message delivery failure
For reply reports, this will be RECEIVED
For additional analytics, this will be the event description
Message This is a reply. The received SMS message (if 'Type=SMSInbound' or 'Type=SMSReply')
Price Your cost for this transaction. Always empty for SMS Received webhooks.
Detail InputToNumber:021-777909 Additional message details:

'InputToNumber' displays the sender's 'Destination' in their submitted format
URL https://www.example.com/webhook The URL this webhook is sent to


HTTP Method: GET

GET SMS Received Poll - View all Inbound SMS using a GET poll

API users are able to poll for all received SMS messages in a given time-frame.


 
 
API URL:        https://api.tnz.co.nz/api/v2.04/get/sms/received?timePeriod=[minutes]
URL Parameters: timePeriod=[minutes] //optional
  dateFrom=[From Date] //optional
  dateTo=[To Date] //optional
  page=[Page Number] //optional
  recordsPerPage=[No. of Records Per Page] //optional
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

URL parameters

Parameter Example Value Description
TimePeriod 1440 Return results from the last x minutes (optional, required if dateFrom/dateTo is not used)
dateFrom 2022-08-01T00:00:00 Return results from the specified date in the API User's local time (optional, required if dateTo is set)
dateTo 2022-08-01T23:59:59 Return results to the specified date in API User's local time (optional, required if dateFrom is set)
recordsPerPage 20 Return x number of records per request (optional)
page 1 Current location of the result set (optional)

SUCCESS Response parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
Messages > ReceivedID 5000000a-f002-4007-b00a-d00000000001 Unique identifier for this message (UUID v4, 36 characters)
> MessageID 1000000a-f002-4007-b00a-d00000000002 MessageID parameter supplied when sending your original API call. If you did not supply one, the API generated one for you.
> JobNum 10C7B9A0 Eight digit alphanumeric tracking number (our internal Job Number)
> SubAccount SubAccount01 Used for reporting, billing and Web Dashboard segmentation
> Department Department01 Used for reporting, billing and Web Dashboard segmentation
> ReceivedTimeLocal 2023-09-01 14:02:03 Time the reply message was received in the users local timezone (ISO 8601 format)
> ReceivedTimeUTC 2023-09-01 02:02:03 Time the reply message was received in UTC (ISO 8601 format)
> ReceivedTimeUTC_RFC3339 2023-09-01T02:02:03.000Z Time the reply message was received in UTC (RFC 3339 format)
> From +6421000001 Sender of the SMS in E.164 internationalised format
> ContactID 7000000a-f002-4007-b00a-d00000000001 Displays the Address Book Contact ID. If unavailable, displays an empty field.
> MessageText This is a reply back from the mobile phone. Plain or UTF-8 formatted SMS message received
> Timezone New Zealand The users local timezone (Timezone list)
> Version v2.04 The API version used for this request

FAILED Response parameters

Parameter Example Value Description
Result Failed Result of your API call (not the result of the message)
Message Missing Sender Reason for the API call failure (see a list of possible values: TNZ API Errors)


HTTP Method: PATCH

GET SMS Reply Poll - Track individual reply SMS messages using a GET poll

API users are able to poll for replies to a specific SMS message, tracked using the MessageID on the outbound message.

The GET Poll should be configured to timeout after 48 hours with no result.


 
 
API URL:        https://api.tnz.co.nz/api/v2.04/get/sms/reply/[MessageID]
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required URL parameters

Parameter Example Value Description
MessageID ID123456 Your provided Message ID or TNZ Group generated Message ID

Success Response parameters

Parameter Example Value Description
Result Success Result of your API call (not the result of the message)
MessageID 1000000a-f002-4007-b00a-d00000000002 MessageID parameter supplied when sending your original API call. If you did not supply one, the API generated one for you.
Status Completed Status of the sent message
JobNum 10AB20CE Eight digit alphanumeric tracking number (our internal Job Number)
Account 102030 Your TNZ Account
SubAccount SubAccount01 Your supplied TNZ SubAccount
Department Department01 Your supplied TNZ Department
Reference Your supplied Reference
CreatedTimeLocal 2024-05-01 15:51:42 Time the message was created/generated in the users local timezone (ISO 8601 format)
CreatedTimeUTC 2024-05-01 03:51:42 Time the message was created/generated in UTC (ISO 8601 format)
CreatedTimeUTC_RFC3339 2024-05-01T03:51:42.000Z Time the message was created/generated in UTC (RFC 3339 format)
DelayedTimeLocal 2024-05-01 15:51:42 Time the message was scheduled for sending in the users local timezone (ISO 8601 format)
DelayedTimeUTC 2024-05-01 03:51:42 Time the message was scheduled for sending in UTC (ISO 8601 format)
DelayedTimeUTC_RFC3339 2024-05-01T03:51:42.000Z Time the message was scheduled for sending in UTC (RFC 3339 format)
Timezone New Zealand The users local timezone (Timezone list)
Count 5 Total Destinations specified in the message
Complete 5 Total Destinations where message transmission has completed
Success 4 Total Destinations where message result is Success
Failed 1 Total Destinations where message result is Failed
Price 0.20 Your cost for this transaction, charged by us to you
Recipients > Type Text Type of Message ('Email', 'SMS', 'Fax', 'Voice', 'TextToSpeech', 'SMSInbound' or 'SMSReply')
> DestSeq 00000001 The ID of the destination in the list (increments per destination)
> Destination +6421000001 Destination send to (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format)
> ContactID 7000000a-f002-4007-b00a-d00000000001 Displays the Address Book Contact ID. If unavailable, displays an empty field.
> MessageText This is an outbound message sent via API. The sent SMS message content
> Status SUCCESS For submission results, values are SUCCESS, FAILED, PENDING
For reply reports, this will be RECEIVED
For additional analytics, this will be UPDATED
> Result delivered Final delivery result and/or the cause for a message delivery failure
For a list of possible values, see SMS, Fax, Voice, TextToSpeech
Email result codes are defined by the receiving email server
For reply reports, this will be RECEIVED
For additional analytics, this will be the event description
> SentTimeLocal 2024-05-01 15:51:42 Time the message was sent in the users local timezone (ISO 8601 format)
> SentTimeUTC 2024-05-01 03:51:42 Time the message was sent in UTC (ISO 8601 format)
> SentTimeUTC_RFC3339 2024-05-01T03:51:42.000Z Time the message was sent in UTC (RFC 3339 format)
> Attention Gary Jones The Attention value supplied in your original send request (for tracking)
> Company XYZ Corp The Company value supplied in your original send request (for tracking)
> Custom1-9 Variable data The Custom values supplied in your original send request (for tracking)
> RemoteID +6495005000 Not applicable (used by Voice and Text-to-Speech)
> Price 0.20 Your cost for this transaction, charged by us to you
> SMSReplies > ReceivedID 5000000a-f002-4007-b00a-d00000000001 Unique identifier for this message (UUID v4, 36 characters)
> ReceivedTimeLocal 2024-05-01 15:51:42 Time the message was received in the users local timezone (ISO 8601 format)
> ReceivedTimeUTC 2024-05-01 03:51:42 Time the message was received in UTC (ISO 8601 format)
> ReceivedTimeUTC_RFC3339 2024-05-01T03:51:42.000Z Time the message was received in UTC (RFC 3339 format)
> Timezone New Zealand The users local timezone (Timezone list)
> From +6421000001 Sender of the SMS in E.164 internationalised format
> MessageText This is a reply back from the mobile phone. Plain or UTF-8 formatted SMS message received

Failed Response parameters

Parameter Example Value Description
Result Failed Result of your API call (not the result of the message)
MessageID AAAAAAAA-BBBB-BBBB-CCCC-DDDDDDDDDDDD Your provided Message ID or TNZ Group generated Message ID
Message Missing Sender Reason for the API call failure (see a list of possible values: TNZ API Errors)

HTTP Method: GET

List Contacts- Get Contact List via REST API

Displays all Contacts in your Address Book, including their names and contact information.

You may use the 'page' and 'recordsPerPage' functions to reduce the output size into manageable chunks.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/contact/list
URL Parameters: page=[Page Number] //optional
  recordsPerPage=[No. of Records Per Page] //optional
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Optional URL Parameters

Parameter Example Value Description
recordsPerPage 50 Specifies the number of records per page to be returned. If not provided, the default number (100) of records per page will be used.
page 1 Specifies the page number of the contact list to retrieve. If not provided, the default (1) behaviour will be followed.
HTTP Method: GET

Search Contacts- Find a Contact via REST API

Displays all Contacts in your Address Book that match your search criteria.

You may use the 'page' and 'recordsPerPage' functions to reduce the output size into manageable chunks.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/contact/search
URL Parameters: page=[Page Number]
  recordsPerPage=[No. of Records Per Page]
  EmailAddress=[full match]
  MobilePhone=[full match]
  MainPhone=[full match]
  Attention=[full match]
  FirstName=[full match]
  LastName=[full match]
  Company=[full match]
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Optional URL Parameters

Parameter Example Value Description
recordsPerPage 50 Specifies the number of records per page to be returned. If not provided, the default number (100) of records per page will be used.
page 1 Specifies the page number of the contact list to retrieve. If not provided, the default (1) behaviour will be followed.
EmailAddress test@test.com Searches the Address Book for a matching 'Email Address'. Full match (no wildcards).
MobilePhone +64 21 000 001 Searches the Address Book for a matching 'Mobile Phone'. Full match (no wildcards).
MainPhone 09 500 5000 Searches the Address Book for a matching 'Main Phone'. Full match (no wildcards).
Attention Trent Michaels Searches the Address Book for a matching 'Attention'. Full match (no wildcards).
FirstName Trent Searches the Address Book for a matching 'First Name'. Full match (no wildcards).
LastName Michaels Searches the Address Book for a matching 'Last Name'. Full match (no wildcards).
Company Test Corp Searches the Address Book for a matching 'Company'. Full match (no wildcards).
HTTP Method: GET

Get Detail on a Contact- Get Contact Detail via REST API

Displays one specific Contact in your Address Book, including their name and contact information.

Useful when reviewing a contact or exporting data from the Address Book.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/contact/[ContactID]
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
ContactID 17f2b37e-4706-41c8-8dcb-de90e24c2447 Specifies the unique identifier of the contact to retrieve.
HTTP Method: POST

Create a Contact - Create Contact via REST API

Create a new Address Book Contact. Useful when importing data into the Address Book.

The API will respond with your new contact's 'ContactID'. Save this ID for later updates.

Note: You must create the Contact first (and create the Group first) before creating an association to a Group with the 'Contact Groups' function.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/contact
HTTP Method:    POST

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Optional Request Body Properties

Property Example Value Description
ViewBy Account Specifies the visibility of the contact. Values can be "Account", "SubAccount", "Department" or "No" visibility option.
EditBy Account Specifies the permission level required to edit the contact. Values can be "Account", "SubAccount", "Department" or "No" permission option.
Attention Person Attention Indicates the attention or focus associated with the contact.
Title Ms Represents the title or honorific of the contact (e.g., Mr, Mrs, Ms).
Company TNZ Group LTD. Specifies the company or organization associated with the contact.
RecipDepartment Sales Dept. Indicates the department or division within the company associated with the contact.
FirstName Person first name Represents the first name of the contact.
LastName Person last name Represents the last name of the contact.
Position Sales Represent Specifies the job position or role of the contact.
StreetAddress 123 ABC st. Represents the street address or location of the contact.
Suburb My Suburb Specifies the suburb or district associated with the contact's address.
City Auckland Indicates the city or locality associated with the contact's address.
State NZ Represents the state or province associated with the contact's address.
Country New Zealand Specifies the country associated with the contact's address.
Postcode 1234 Represents the postal code or ZIP code associated with the contact's address.
MainPhone 092223333 Specifies the main phone number of the contact. This property typically used for Voice & Text-To-Speech messages.
AltPhone1 093334444 Represents an alternate phone number for the contact. This property typically used for Voice & Text-To-Speech messages.
AltPhone2 094445555 Represents a second alternate phone number for the contact. This property typically used for Voice & Text-To-Speech messages.
DirectPhone 094445555 Indicates the direct phone number of the contact.
MobilePhone 0211144489 Represents the mobile phone number of the contact. This property typically used for SMS messages.
FaxNumber 093334444 Specifies the fax number associated with the contact.
EmailAddress person1@example.com Represents the email address of the contact.
WebAddress https://www.tnz.co.nz Specifies the website address or URL associated with the contact.
Custom1...Custom4 Custom Value Represents custom fields or additional information associated with the contact.
HTTP Method: PATCH

Update a Contact - Update Contact via REST API

Update an existing Address Book Contact's information.

You must use the contact's 'ContactID' in the URL. You can find the ID when using the Create API or the List or Detail options.

You may update just one property (e.g. 'StreetAddress' only) or you may update multiple properties.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/contact/[ContactID]
HTTP Method:    PATCH

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
ContactID 17f2b37e-4706-41c8-8dcb-de90e24c2447 Specifies the unique identifier of the contact to retrieve.

Properties Request Body Properties

Property Example Value Description
ViewBy Account Specifies the visibility of the contact. Values can be "Account", "SubAccount", "Department" or "No" visibility option.
EditBy Account Specifies the permission level required to edit the contact. Values can be "Account", "SubAccount", "Department" or "No" permission option.
Attention Person Attention Indicates the attention or focus associated with the contact.
Title Ms Represents the title or honorific of the contact (e.g., Mr, Mrs, Ms).
Company TNZ Group LTD. Specifies the company or organization associated with the contact.
RecipDepartment Sales Dept. Indicates the department or division within the company associated with the contact.
FirstName Person first name Represents the first name of the contact.
LastName Person last name Represents the last name of the contact.
Position Sales Represent Specifies the job position or role of the contact.
StreetAddress 123 ABC st. Represents the street address or location of the contact.
Suburb My Suburb Specifies the suburb or district associated with the contact's address.
City Auckland Indicates the city or locality associated with the contact's address.
State NZ Represents the state or province associated with the contact's address.
Country New Zealand Specifies the country associated with the contact's address.
Postcode 1234 Represents the postal code or ZIP code associated with the contact's address.
MainPhone 092223333 Specifies the main phone number of the contact. This property typically used for Voice & Text-To-Speech messages.
AltPhone1 093334444 Represents an alternate phone number for the contact. This property typically used for Voice & Text-To-Speech messages.
AltPhone2 094445555 Represents a second alternate phone number for the contact. This property typically used for Voice & Text-To-Speech messages.
DirectPhone 094445555 Indicates the direct phone number of the contact.
MobilePhone 0211144489 Represents the mobile phone number of the contact. This property typically used for SMS messages.
FaxNumber 093334444 Specifies the fax number associated with the contact.
EmailAddress person1@example.com Represents the email address of the contact.
WebAddress https://www.tnz.co.nz Specifies the website address or URL associated with the contact.
Custom1...Custom4 Custom Value Represents custom fields or additional information associated with the contact.
HTTP Method: DELETE

Delete a Contact - Delete Contact via REST API

Delete an Address Book Contact.

You must use the contact's 'ContactID' in the URL. You can find the ID when using the Create API or the List or Detail options.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/contact/[ContactID]
HTTP Method:    DELETE

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
ContactID 17f2b37e-4706-41c8-8dcb-de90e24c2447 Specifies the unique identifier of the contact to retrieve.
HTTP Method: GET

List Groups- Get Group List via REST API

Displays all Groups in your Address Book.

You may use the 'page' and 'recordsPerPage' functions to reduce the output size into manageable chunks.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/group/list
URL Parameters: page=[Page Number] //optional
  recordsPerPage=[No. of Records Per Page] //optional
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Optional URL Parameters

Parameter Example Value Description
recordsPerPage 50 Specifies the number of records per page to be returned. If not provided, the default number (100) of records per page will be used.
page 1 Specifies the page number of the group list to retrieve. If not provided, the default (1) behaviour will be followed.
HTTP Method: GET

Get Detail on a Group- Get Group Detail via REST API

Displays information about a specific Group in your Address Book.

You must use the group's 'GroupID' in the URL. You can find the ID when using the Create API or the List or Detail options.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/group/[GroupID]
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
GroupID 4000000b-f002-4007-b00a-c00000000002 Specifies the ID or Code of the group to retrieve.
HTTP Method: POST

Create a Group - Create Group via REST API

Create a new Address Book Group.

The API will respond with your new group's 'GroupID'. Save this ID for later updates.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/group
HTTP Method:    POST

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required Request Body Properties

Property Example Value Description
GroupName Test Group Specifies the name of the group. If GroupCode is not specified, TNZ API will take group name and replace spaces with underscores.

Optional Request Body Properties

Property Example Value Description
GroupCode Test-Group Specifies the code or identifier for the group. Leave empty if you want the system to generate the code from the group name.
SubAccount Test SubAccount Specifies the subaccount associated with the group.
Department Test Department Specifies the department or division associated with the group.
ViewEditBy Account Specifies the visibility and edit permissions for the group. Values can be "Account", "SubAccount", "Department" or "No" permission option.
HTTP Method: PATCH

Update a Group - Update Group via REST API

Update an existing Address Book Group's information.

You must use the groups's 'GroupID' in the URL. You can find the ID when using the Create API or the List or Detail options.

You may update the Group's name and access rules, however, you cannot edit the Group's GroupID or GroupCode.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/group/[GroupID]
HTTP Method:    PATCH

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
GroupID 4000000b-f002-4007-b00a-c00000000002 Specifies the ID or Code of the group to be updated.

Optional Request Body Properties

Property Example Value Description
GroupName Test Group Specifies the name of the group. Unlike the 'Create' API, updating GroupName will NOT change the GroupCode.
SubAccount Test SubAccount Specifies the subaccount associated with the group.
Department Test Department Specifies the department or division associated with the group.
ViewEditBy Account Specifies the visibility and edit permissions for the group. Values can be "Account", "SubAccount", "Department" or "No" permission option.
HTTP Method: DELETE

Delete a Group - Delete Group via REST API

Delete an Address Book Group.

You must use the group's 'GroupID' in the URL. You can find the ID when using the Create API or the List or Detail options.

Deleting a Group will not delete any Contacts.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/group/[GroupID]
HTTP Method:    DELETE

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
GroupID 4000000b-f002-4007-b00a-c00000000002 Specifies the group ID or Code of the group to be deleted.
HTTP Method: GET

List Contact-to-Group Associations- Get Contact Group List via REST API

Lists the Groups a specific Contact is a member of.

You must use the appropriate 'ContactID' and 'GroupID'. You can find the ContactID and GroupID when creating entries or by using the List or Detail options.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/contact/[ContactID]/group/list
URL Parameters: page=[Page Number] //optional
  recordsPerPage=[No. of Records Per Page] //optional
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
ContactID 17f2b37e-4706-41c8-8dcb-de90e24c2447 Specifies the unique identifier of the contact to retrieve.

Optional URL Parameters

Parameter Example Value Description
recordsPerPage 50 Specifies the number of records per page to be returned. If not provided, the default number (100) of records per page will be used.
page 1 Specifies the page number of the group list to retrieve. If not provided, the default (1) behaviour will be followed.
HTTP Method: GET

Get Details on a Contact-to-Group Association- Get Contact Group Detail via REST API

Confirms whether a specific Contact is a member of a specific Group (this function is a 1:1 match and is used for verification purposes).

You must use the appropriate 'ContactID' and 'GroupID'. You can find the ContactID and GroupID when creating entries or by using the List or Detail options.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/contact/[ContactID]/group/[GroupID]
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
ContactID 17f2b37e-4706-41c8-8dcb-de90e24c2447 Specifies the unique identifier of the contact to retrieve.
Group Code Test_Group Specifies the unique identifier of the group to retrieve.
HTTP Method: POST

Create a Contact-to-Group Association - Create Contact Group via REST API

Adds a specific Contact to an existing Group.

You must use the appropriate 'ContactID' and 'GroupID'. You can find the ContactID and GroupID when creating entries or by using the List or Detail options.

You may only list one Group per API call. Adding a Contact to multiple Groups requires multiple API calls.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/contact/[ContactID]/group
HTTP Method:    POST

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
ContactID 17f2b37e-4706-41c8-8dcb-de90e24c2447 Specifies the unique identifier of the contact to create relationship.

Required Request body properties

Property Example Value Description
GroupID 4000000b-f002-4007-b00a-c00000000002 Specifies the ID or Code of the group to which the contact relationship should be added.
HTTP Method: DELETE

Delete a Contact-to-Group Association - Delete Contact Group via REST API

Removes a specific Contact from an existing Group. This function removes the Contact-to-Group association and does not delete any Contacts or any Groups.

You must use the appropriate 'ContactID' and 'GroupID'. You can find the ContactID and GroupID when creating entries or by using the List or Detail options.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/contact/[ContactID]/group/[GroupID]
HTTP Method:    DELETE

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
ContactID 17f2b37e-4706-41c8-8dcb-de90e24c2447 Specifies the unique identifier of the contact to delete.
GroupID 4000000b-f002-4007-b00a-c00000000002 Specifies the ID or Code of the group to be deleted.
HTTP Method: GET

List Group-to-Contact Associations- Get Group Contact List via REST API

Lists all Contacts in a specific Group.

You must use the appropriate 'ContactID' and 'GroupID'. You can find the ContactID and GroupID when creating entries or by using the List or Detail options.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/group/[GroupID]/contact/list
URL Parameters: page=[Page Number] //optional
  recordsPerPage=[No. of Records Per Page] //optional
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
GroupID 4000000b-f002-4007-b00a-c00000000002 Specifies the ID or Code of the group to be deleted.

Optional URL Parameters

Parameter Example Value Description
recordsPerPage 50 Specifies the number of records per page to be returned. If not provided, the default number (100) of records per page will be used.
page 1 Specifies the page number of the contact list to retrieve. If not provided, the default (1) behaviour will be followed.
HTTP Method: GET

Get Details on a Group-to-Contact Association- Get Group Contact Detail via REST API

Confirms whether a specific Group has a specific Contact listed (this function is a 1:1 match and is used for verification purposes).

You must use the appropriate 'ContactID' and 'GroupID'. You can find the ContactID and GroupID when creating entries or by using the List or Detail options.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/group/[GroupID]/contact/[ContactID]
HTTP Method:    GET

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
Group Code Test_Group Specifies the unique identifier of the group to retrieve.
ContactID 17f2b37e-4706-41c8-8dcb-de90e24c2447 Specifies the unique identifier of the contact to retrieve.
HTTP Method: POST

Create a Group-to-Contact Association - Create Group Contact via REST API

Adds a specific Contacts to a specific Group. This function is most useful when updating multiple Contacts at once.

You must use the appropriate 'ContactID' and 'GroupID'. You can find the ID when using the Create API or the List or Detail options.

You may only list one Contact per API call. Adding multiple Contacts to the Group requires multiple API calls.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/group/[GroupID]/contact
HTTP Method:    POST

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
GroupID 4000000b-f002-4007-b00a-c00000000002 Specifies the ID or Code of the group to which the contact relationship should be added.

Required Request body properties

Property Example Value Description
ContactID 17f2b37e-4706-41c8-8dcb-de90e24c2447 Specifies the unique identifier of the contact to create relationship.
HTTP Method: DELETE

Delete a Group-to-Contact Association - Delete Group Contact via REST API

Removes a specific Contact from specific Group. This function removes the Contact-to-Group association and does not delete any Contacts or any Groups.

You must use the appropriate 'ContactID' and 'GroupID'. You can find the ID when using the Create API or the List or Detail options.

 
API URL:        https://api.tnz.co.nz/api/v2.04/addressbook/group/[GroupID]/contact/[ContactID]
HTTP Method:    DELETE

    
Sample SUCCESS Response [HTTP Response Status: 200 OK]:
Sample FAILURE Response [HTTP Response Status: 400 Bad Request]:

Required HTTP Headers

Parameter Example Value Description
Content-Type application/json; encoding='utf-8' Sets the request data format. Set 'json' or 'xml' appropriately.
Accept application/json; encoding='utf-8' Sets the return data format. Set 'json' or 'xml' appropriately.
Authorization Basic eyJhbGciOiJI...adQssw5c Auth Token value set up (see Auth Token)

Required URL parameters

Parameter Example Value Description
GroupID 4000000b-f002-4007-b00a-c00000000002 Specifies the ID or Code of the group to be deleted.
ContactID 17f2b37e-4706-41c8-8dcb-de90e24c2447 Specifies the unique identifier of the contact to delete.

Versioning/Changelog

When a new version of the API is released, the APIVersion url parameter is incremented.
This allows you to use a different API version based on the API URL, limiting the testing you require should you wish to update one API URL to a later version of the API.

Want to upgrade to a new version for SMS but don't want to break and retest Email? Use the newer APIVersion for SMS while using the older APIVersion for Email.

For example, you may be using:
https://api.tnz.co.nz/api/v2.04/send/email
However, you may also simultaneously use:
https://api.tnz.co.nz/api/v2.02/send/email

As new versions of the API are released, this API reference guide will be updated to reflect the latest version and features supported:

 API Version ChangeLog


Frequently Asked Questions

Yes, full international delivery is supported.
The maximum request size supported is 20MB. This is our server side limitation. Your client side limitation may be smaller.
There is no limit to the number of Destinations (in either format), provided you do not breach the 20MB maximum REST request size.
There is a limit of 10 files specified in a single request. There is no file size limitation, provided you do not breach the 20MB maximum REST request size.
Yes, we support email security measures. Contact us for further information on setting up your own security measures for whitelabeled messages delivered with the API.
You can send a wide range of file types, including Microsoft Office® documents (doc, docx, ppt, pptx, xls, xlsx, etc), Openoffice/Libreoffice documents (odt, ods, etc), Adobe® documents (pdf, etc), image file types (jpg, gif, tif, bmp, etc) and more (txt, html, etc).
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.
Yes, we can provide a daily or monthly email report (as an attached CSV file) containing data on messages sent. This can be used for billing (contains costs) or for reporting (doesn’t contain costs).
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.
Some networks support customised SMS Caller IDs. This can be configured using your Web Dashboard.
Your Fax Caller ID can be configured using your Web Dashboard.
Your Voice and TextToSpeech Caller ID is specified on a per-message basis using the 'CallerID' parameter.
");