# Understand the following API Specification snippet in markdown format.
The API URL is: https://api.tnz.co.nz/api/v3.00
The module contains a path, for example: https://api.tnz.co.nz/api/v3.00/sms
POST requests require a Content-Type header (application/json) and an Authorization header (prefixed with 'Basic')
# TNZ REST API
- **OpenAPI Version:** `3.1.0`
- **API Version:** `3.00`
# Introduction
This API allows you to send messages via TNZ's platform, including SMS, Email, Voice (both pre-recorded and text-to-speech), Fax, WhatsApp, RCS and Workflow messages. You can also manage your TNZ Address Book and track the status of your messages.
**Sending/Receiving Messages**
- [Workflow](#tag/workflow)
- [SMS](#tag/sms)
- [Email](#tag/email)
- [Voice (pre-recorded audio)](#tag/voice)
- [Voice (text-to-speech)](#tag/tts)
- [Fax](#tag/fax)
- [WhatsApp](#tag/whatsapp)
- [RCS](#tag/rcs)
**Manage Your Account:**
- [Manage your TNZ Address Book](#tag/address-book)
- [Manage Opt-Outs](#tag/optout)
- [Manage users](#tag/partner-api) (restricted to Wholesale and Partner users)
# Authentication
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](https://my.tnz.co.nz)
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. Use the Auth Token in the Authorization Header when submitting an API call (remember to prefix with Bearer, e.g. "Bearer ey...0123")
**To refresh or invalidate your Auth Token:**
1. Login to the [TNZ Dashboard](https://my.tnz.co.nz)
2. Navigate to 'Users'
3. Click on your API user
4. Click on the 'API' tab
5. Click on the refresh/recycle button in the Auth Token section
6. Update your applications to use the new Auth Token
The TNZ API utilises JWT token Authentication. For OAuth2 authentication options, contact your TNZ representative.
# Change Log and Versioning
REST API changes are documented: [Change Log](https://www.tnz.co.nz/docs/restapi/contents/APIChangeLog.html)
When a new version of the API is released, the API Version in the URL is incremented. This gives you control over version updates.
# Libraries and Plugins
We have libraries for popular programming languages and platforms to help you get started quickly:
| Language | Documentation | Installation |
| -------- | -------------------------------------------------- | ----------------------------- |
| Node.JS | [NodeJSLib](https://www.tnz.co.nz/docs/NodeJSLib/) | npm i tnzapi |
| Python | [PythonLib](https://www.tnz.co.nz/docs/PythonLib/) | pip install tnzapi |
| .NET | [dotNETLib](https://www.tnz.co.nz/docs/dotNetLib/) | dotnet add package TNZAPI.NET |
## Servers
- **URL:** `https://api.tnz.co.nz/api/v3.00`
- **Description:** Base URL
- **URL:** `https://api.tnz.co.nz/api/v3.00/sms`
- **Description:** SMS URL
- **URL:** `https://api.tnz.co.nz/api/v3.00/email`
- **Description:** Email URL
- **URL:** `https://api.tnz.co.nz/api/v3.00/voice`
- **Description:** Voice URL
- **URL:** `https://api.tnz.co.nz/api/v3.00/tts`
- **Description:** TTS (Text-to-Speech) URL
- **URL:** `https://api.tnz.co.nz/api/v3.00/fax`
- **Description:** Fax URL
- **URL:** `https://api.tnz.co.nz/api/v3.00/whatsapp`
- **Description:** WhatsApp URL
- **URL:** `https://api.tnz.co.nz/api/v3.00/rcs`
- **Description:** RCS URL
- **URL:** `https://api.tnz.co.nz/api/v3.00/addressbook`
- **Description:** Address Book URL
- **URL:** `https://api.tnz.co.nz/api/v3.00/optout`
- **Description:** Opt-Out URL
## Operations
### Send Workflow
- **Method:** `POST`
- **Path:** `/workflow`
- **Tags:** Workflow
Send a message using a pre-configured workflow.
Use `WorkflowTemplateID` to specify the Workflow Template to send.
The `Destinations` parameter specifies the contacts to receive the message. Alternatively, you may use the `Destinations` array for multiple contacts, or use Address Book `ContactID` or `GroupID` values. If you specify a new contact, the API will automatically create an Address Book contact for you.
#### Request Body
##### Content-Type: application/json
- **`WorkflowTemplateID` (required)**
`string`, format: `uuid` — ID of the Workflow template. \[Find Your TemplateID]\(https\://www\.tnz.co.nz/help/how-to-find-your-templateid).
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Destination`**
`string` — A single destination to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
- **`Destinations`**
`array` — An array of one or more contacts to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
**Items:**
- **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
- **`Company`**
`string | null` — The contact's company name (used for personalising the message).
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
- **`Custom2`**
`string | null` — Additional custom variable.
- **`Custom3`**
`string | null` — Additional custom variable.
- **`Custom4`**
`string | null` — Additional custom variable.
- **`EmailAddress`**
`string`, format: `email` — The contact's email address.
- **`First Name`**
`string | null` — The contact's first name (used for personalising the message).
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`Last Name`**
`string | null` — The contact's last name (used for personalising the message).
- **`MainPhone`**
`string`, format: `phone` — The contact's voice telephone number. See \[Telephone Number Formatting]\(https\://www\.tnz.co.nz/help/telephone-number-formatting-for-voice-fax) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`MainPhone`**
`string`, format: `phone` — The contact's voice telephone number. See \[Telephone Number Formatting]\(https\://www\.tnz.co.nz/help/telephone-number-formatting-for-voice-fax) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`MessageID`**
`string | null` — 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.
- **`NotificationType`**
`string | null`, possible values: `"None", "Webhook", "Email"`, default: `""` — Specifies the notification method for delivery status updates and inbound replies for this message. Omit to use your User's default settings.
- **`Reference`**
`string | null` — A human readable message reference.
- **`SendTime`**
`string`, default: `null` — Delay sending until the specified specified time - {date}T{time} (in the user's 'Local' Timezone). Omit to send immediately.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`WebhookCallbackFormat`**
`string`, possible values: `"JSON", "XML", "POST", "GET"` — The format of the webhook body. Omit to use your User's default settings.
- **`WebhookCallbackURL`**
`string`, format: `uri` — The URL to receive the webhook. A full path including https\:// is required. Omit to use your User's default settings.
**Example:**
```json
{
"WorkflowTemplateID": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"Destinations": [
{
"ToNumber": "+6421000001",
"EmailAddress": "john.doe@example.com",
"MainPhone": "+6421000001",
"Attention": "John Doe",
"First Name": "John",
"Last Name": "Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group"
}
],
"Destination": "021-000001",
"ToNumber": "+6421000001",
"MainPhone": "+6421000001",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"Reference": "MyTest",
"NotificationType": "None",
"WebhookCallbackURL": "https://example.com/webhook",
"WebhookCallbackFormat": "JSON",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"SendTime": "2026-08-29T14:00",
"Timezone": "New Zealand"
}
```
#### Responses
##### Status: 200 OK \[successful submission]
###### Content-Type: application/json
- **`MessageID`**
`string` — Unique identifier for the API call.
**Example:**
```json
{
"MessageID": "1000000a-f002-4007-b00a-d00000000002"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Send SMS
- **Method:** `POST`
- **Path:** `/sms`
- **Tags:** SMS
Send an SMS message to one or more recipients.
The `Message` parameter specifies the SMS text. Alternatively, use `TemplateID` to send a pre-configured message template ([Find Your TemplateID](https://www.tnz.co.nz/help/how-to-find-your-templateid)).
The Message may include [Personalisation](https://www.tnz.co.nz/help/message-personalisation), use links from the [URL Shortener](https://www.tnz.co.nz/help/sms-url-shortener-and-short-links) and free [ReplyLink](https://www.tnz.co.nz/help/sms-reply-link-and-enhanced-sms-replies) pages.
The `Destination` parameter contains the mobile number to receive your message. Alternatively, you may use the `Destinations` array for multiple contacts, or use Address Book `ContactID` or `GroupID` values.
#### Request Body
##### Content-Type: application/json
- **`CharacterConversion`**
`boolean`, default: `false` — Convert multi-byte characters into normalised GSM character format - © to (C) - to save on message size. See \[Character Encoding]\(https\://www\.tnz.co.nz/help/sending-long-sms-messages-multi-part-slash-concatenation). Enabling this function will disable emojis, macrons and other special characters.
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Destination`**
`string` — A single destination to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
- **`Destinations`**
`array` — An array of one or more contacts to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
**Items:**
- **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
- **`Company`**
`string | null` — The contact's company name (used for personalising the message).
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
- **`Custom2`**
`string | null` — Additional custom variable.
- **`Custom3`**
`string | null` — Additional custom variable.
- **`Custom4`**
`string | null` — Additional custom variable.
- **`EmailAddress`**
`string`, format: `email` — The contact's email address.
- **`First Name`**
`string | null` — The contact's first name (used for personalising the message).
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`Last Name`**
`string | null` — The contact's last name (used for personalising the message).
- **`MainPhone`**
`string`, format: `phone` — The contact's voice telephone number. See \[Telephone Number Formatting]\(https\://www\.tnz.co.nz/help/telephone-number-formatting-for-voice-fax) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`FallbackMode`**
`string`, possible values: `"None", "Voice", "WhatsApp", "RCS"`, default: `"None"` — If the SMS delivery fails, try another method (in the order listed).
- **`Files`**
`array` — An array of file attachments.
**Items:**
- **`Data`**
`string`, format: `byte` — The base64-encoded file data. Download a sample PDF: \[base64-encoded-file-data]\(https\://www\.tnz.co.nz/docs/RESTAPI/samples/3.00/base64-Files.txt)
- **`Name`**
`string` — The name of the attached file including the file extension.
- **`FromNumber`**
`string` — Sets the Sender ID on your sent message (in E164 format without the leading +). Will be overridden for complex countries such as New Zealand.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`Message`**
`string` — The SMS text message to send. Alternatively, you may use the \`TemplateID\` parameter.
- **`MessageID`**
`string | null` — 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.
- **`Mode`**
`string | null`, default: `null` — Set to \`Test\` to have messages handled immediately as successful without sending a live message. Useful for end-to-end testing. Omit to use standard mode.
- **`NotificationType`**
`string | null`, possible values: `"None", "Webhook", "Email"`, default: `""` — Specifies the notification method for delivery status updates and inbound replies for this message. Omit to use your User's default settings.
- **`Reference`**
`string | null` — A human readable message reference.
- **`ReportTo`**
`string`, format: `email` — Email address to send a delivery report to once the message completes. Omit to use your User's default settings.
- **`SendTime`**
`string`, default: `null` — Delay sending until the specified specified time - {date}T{time} (in the user's 'Local' Timezone). Omit to send immediately.
- **`SMSCustomPageID`**
`string`, format: `uuid` — UUID of the \[\[CustomPage]] template to use. Edit a Custom Page template in the Dashboard to find the Template ID.
- **`SMSEmailReply`**
`string`, format: `email` — The email address to send SMS Reply notifications to. This may be ignored if a different Reply Notification rule is configured.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`TemplateID`**
`string`, format: `uuid` — UUID of the message template to use. Edit a template in the Dashboard to find the Template ID. If both \`TemplateID\` and a Message are specified, the message takes priority.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`WebhookCallbackFormat`**
`string`, possible values: `"JSON", "XML", "POST", "GET"` — The format of the webhook body. Omit to use your User's default settings.
- **`WebhookCallbackURL`**
`string`, format: `uri` — The URL to receive the webhook. A full path including https\:// is required. Omit to use your User's default settings.
**Example:**
```json
{
"Message": "Hello [[FirstName]], view the [[Custom1]] link at [[Link:https://www.example.com/path/to/page.html]] or reply at [[REPLY]]. Reply STOP to OptOut.",
"TemplateID": "123e4567-e89b-12d3-a456-426614174000",
"Destination": "021-000001",
"ToNumber": "+6421000001",
"Destinations": [
{
"ToNumber": "+6421000001",
"EmailAddress": "john.doe@example.com",
"MainPhone": "+6421000001",
"Attention": "John Doe",
"First Name": "John",
"Last Name": "Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group"
}
],
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"Reference": "MyTest",
"NotificationType": "None",
"WebhookCallbackURL": "https://example.com/webhook",
"WebhookCallbackFormat": "JSON",
"ReportTo": "reports@example.com",
"SendTime": "2026-08-29T14:00",
"Timezone": "New Zealand",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"FromNumber": "61408080909",
"SMSEmailReply": "reply@example.com",
"SMSCustomPageID": "123e4567-e89b-12d3-a456-426614174001",
"CharacterConversion": false,
"FallbackMode": "Voice",
"Files": [
{
"Name": "My Example.pdf",
"Data": "base64-encoded-file-data"
}
],
"Mode": "Test"
}
```
#### Responses
##### Status: 200 OK \[successful submission]
###### Content-Type: application/json
- **`MessageID`**
`string` — Unique identifier for the API call.
**Example:**
```json
{
"MessageID": "1000000a-f002-4007-b00a-d00000000002"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### SMS Details
- **Method:** `GET`
- **Path:** `/sms/{MessageID}`
- **Tags:** SMS
Poll for details of a sent SMS message.
The primary object details the message as a whole, while the `Recipients` array contains details of each recipient.
Under each recipient, an `SMSReplies` array will detail any received replies.
Timeout your polls after 6 hours with no result.
Limit your polls to 1 per second to avoid rate limits.
Consider the [Send Result Webhook](#tag/sms/webhook/POST/resultwebhook) for efficiency.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
**All of:**
- **`Account`**
`string` — Your account number.
- **`Complete`**
`integer` — Total Destinations that were successfully completed.
- **`Count`**
`integer` — Total Destinations specified in the message.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`DelayedTimeLocal`**
`string` — The time the entry was delayed until, in the local Timezone.
- **`DelayedTimeUTC`**
`string` — The time the entry was delayed until, in UTC.
- **`DelayedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was delayed until, in UTC (RFC3339 format).
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Failed`**
`integer` — Total Destinations that failed to deliver.
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`JobStatus`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
- **`MessageID`**
`string | null` — 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.
- **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
- **`Reference`**
`string | null` — A human readable message reference.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Success`**
`integer` — Total Destinations that were successfully delivered.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
* **`Page`**
`integer`
* **`PageCount`**
`integer`
* **`RecordsPerPage`**
`integer`
* **`TotalRecords`**
`integer`
- **`Recipients`**
`array` — List of recipients for the message.
**Items:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Destination`**
`string` — The destination address (e.g. phone number, email address). Telephone/mobile numbers are supplied in E.164 internationalised format.
- **`DestSeq`**
`string` — The ID of the destination in the list (increments per destination).
- **`MessageText`**
`string` — If the message has been submitted to the mobile (and not blocked prior to sending) this \`MessageText\` value contains the sent message. Otherwise, this parameter is missing.
- **`Result`**
`string` — The final delivery result. For a list of possible values, see \[SMS]\(https\://www\.tnz.co.nz/help/sms-delivery-result-codes) result codes.
- **`Status`**
`string`, possible values: `"Success", "Failed", "Pending"` — Current status of the message.
- **`Type`**
`string`, possible values: `"SMS", "Email", "Voice", "Fax"` — The type of message this data relates to.
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`Company`**
`string | null` — The contact's company name (used for personalising the message).
* **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
* **`Custom2`**
`string | null` — Additional custom variable.
* **`Custom3`**
`string | null` — Additional custom variable.
* **`Custom4`**
`string | null` — Additional custom variable.
* **`Custom5`**
`string | null` — Additional custom variable.
* **`Custom6`**
`string | null` — Additional custom variable.
* **`Custom7`**
`string | null` — Additional custom variable.
* **`Custom8`**
`string | null` — Additional custom variable.
* **`Custom9`**
`string | null` — Additional custom variable.
* **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
* **`RemoteID`**
`string | null` — For Voice, Text-to-Speech and Fax, dialled phone number. This may differ from 'Destination' if failover Alt Phones are used.
* **`SentTimeLocal`**
`string` — Time the message was sent in the users local Timezone (ISO 8601 format).
* **`SentTimeUTC`**
`string` — Time the message was sent in UTC (ISO 8601 format).
* **`SentTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was sent in UTC (RFC 3339 format).
- **`SMSReplies`**
`array` — A list of replies for this recipient.
**Items:**
- **`From`**
`string` — Sender of the SMS in E.164 internationalised format.
- **`MessageText`**
`string | null` — The received message.
- **`ReceivedID`**
`string`, format: `uuid` — A unique identifier (UUID).
- **`ReceivedTimeLocal`**
`string` — Time the message was received in the users local Timezone (ISO 8601 format).
- **`ReceivedTimeUTC`**
`string` — Time the message was received in UTC (ISO 8601 format).
- **`ReceivedTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was received in UTC (RFC 3339 format).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobStatus": "Pending",
"JobNum": "10AB20CE",
"Account": "101202",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"Reference": "MyTest",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"DelayedTimeLocal": "2025-05-29 05:11:03",
"DelayedTimeUTC": "2025-05-29 17:11:03",
"DelayedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand",
"Count": 1,
"Complete": 1,
"Success": 1,
"Failed": 0,
"Price": 0.1,
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Recipients": [
{
"Type": "SMS",
"DestSeq": "00000001",
"Destination": "+64212223333",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Status": "Success",
"Result": "Delivered",
"MessageText": "Hello, we sent you a test message.",
"SentTimeLocal": "2025-06-13T08:44:16.000Z",
"SentTimeUTC": "2025-06-12T20:44:16.000Z",
"SentTimeUTC_RFC3339": "2025-06-12T20:44:16.000Z",
"Attention": "John Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"Custom5": "",
"Custom6": "",
"Custom7": "",
"Custom8": "",
"Custom9": "",
"RemoteID": "+6495006000",
"Price": 0.1,
"SMSReplies": [
{
"ReceivedID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"ReceivedTimeLocal": "2025-09-01T14:02:03.000Z",
"ReceivedTimeUTC": "2025-09-01T02:02:03.000Z",
"ReceivedTimeUTC_RFC3339": "2025-09-01T02:02:03.000Z",
"Timezone": "New Zealand",
"From": "+6421000001",
"MessageText": "This is a received message from a mobile phone."
}
]
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Inbound SMS
- **Method:** `GET`
- **Path:** `/sms/received`
- **Tags:** SMS
Poll for a list of SMS received in a given timeframe.
You may search based on `timePeriod` (return results from the last *x* minutes) or by `dateFrom` to `dateTo` (return results within the specified timeframe).
If a received message can be matched as a reply, the `MessageID` parameter will contain the outbound message's `MessageID`.
Limit your polls to 1 per second to avoid rate limits.
Consider the [Inbound SMS Webhook](#tag/sms/webhook/POST/inboundsmswebhook) for efficiency.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
**All of:**
- **`Page`**
`integer`
- **`PageCount`**
`integer`
- **`RecordsPerPage`**
`integer`
- **`TotalRecords`**
`integer`
* **`Messages`**
`array` — List of messages found.
**Items:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`From`**
`string` — Sender of the SMS in E.164 internationalised format.
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string`, format: `uuid` — If a reply match has been found, this will be the MessageID parameter supplied when sending your original API call. If you did not supply one, the API generated one for you.
- **`MessageText`**
`string | null` — The received message.
- **`ReceivedID`**
`string`, format: `uuid` — A unique identifier (UUID).
- **`ReceivedTimeLocal`**
`string` — Time the message was received in the users local Timezone (ISO 8601 format).
- **`ReceivedTimeUTC`**
`string` — Time the message was received in UTC (ISO 8601 format).
- **`ReceivedTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was received in UTC (RFC 3339 format).
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`Version`**
`string` — The API version being used.
**Example:**
```json
{
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Messages": [
{
"ReceivedID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"MessageID": "7000000a-f002-4007-b00a-d00000000002",
"JobNum": "10AB20CE",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ReceivedTimeLocal": "2025-09-01T14:02:03.000Z",
"ReceivedTimeUTC": "2025-09-01T02:02:03.000Z",
"ReceivedTimeUTC_RFC3339": "2025-09-01T02:02:03.000Z",
"From": "+6421000001",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"MessageText": "This is a received message from a mobile phone.",
"Timezone": "New Zealand",
"Version": "v3.00"
}
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Reschedule
- **Method:** `PATCH`
- **Path:** `/sms/{MessageID}/reschedule`
- **Tags:** SMS
This endpoint allows you to reschedule a previously delayed message to be sent at a new time.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Reschedule"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Reschedule"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Abort
- **Method:** `PATCH`
- **Path:** `/sms/{MessageID}/abort`
- **Tags:** SMS
This endpoint allows you to abort a previously delayed message.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Abort"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Abort"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Send Email
- **Method:** `POST`
- **Path:** `/email`
- **Tags:** Email
Send an Email message to one or more recipients.
The `Message` parameter specifies the SMS text. Alternatively, use `TemplateID` to send a pre-configured message template ([Find Your TemplateID](https://www.tnz.co.nz/help/how-to-find-your-templateid)).
The `Destination` parameter contains the email address to receive your message. Alternatively, you may use the `Destinations` array for multiple contacts, or use Address Book `ContactID` or `GroupID` values.
#### Request Body
##### Content-Type: application/json
- **`BCCEmail`**
`string` — Adds an untracked BCC to the email (one per recipient, chargeable).
- **`CCEmail`**
`string` — Adds a tracked CC to the email (one per recipient, chargeable).
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Destination`**
`string` — A single destination to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
- **`Destinations`**
`array` — An array of one or more contacts to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
**Items:**
- **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
- **`Company`**
`string | null` — The contact's company name (used for personalising the message).
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
- **`Custom2`**
`string | null` — Additional custom variable.
- **`Custom3`**
`string | null` — Additional custom variable.
- **`Custom4`**
`string | null` — Additional custom variable.
- **`EmailAddress`**
`string`, format: `email` — The contact's email address.
- **`First Name`**
`string | null` — The contact's first name (used for personalising the message).
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`Last Name`**
`string | null` — The contact's last name (used for personalising the message).
- **`MainPhone`**
`string`, format: `phone` — The contact's voice telephone number. See \[Telephone Number Formatting]\(https\://www\.tnz.co.nz/help/telephone-number-formatting-for-voice-fax) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`EmailAddress`**
`string`, format: `email` — The contact's email address.
- **`EmailSubject`**
`string` — The Subject line used in the email.
- **`Files`**
`array` — An array of file attachments.
**Items:**
- **`Data`**
`string`, format: `byte` — The base64-encoded file data. Download a sample PDF: \[base64-encoded-file-data]\(https\://www\.tnz.co.nz/docs/RESTAPI/samples/3.00/base64-Files.txt)
- **`Name`**
`string` — The name of the attached file including the file extension.
- **`From`**
`string` — Sets the email sender's Friendly Name (seen by the email recipient)
- **`FromEmail`**
`string` — Sets the email sender's Email Address (uses the default email address for your API User if not specified).
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`MessageHTML`**
`string` — The HTML email body to send. You may use \`MessagePlain\` and/or \`MessageHTML\`, or you may specify a dashboard Template using \`TemplateID\`. This example uses \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation) and you can track links using the built-in \[URL Shortener]\(https\://www\.tnz.co.nz/help/email-url-shortener-and-short-links).
- **`MessageID`**
`string | null` — 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.
- **`MessagePlain`**
`string` — The plain-text email body to send. You may synonymously use \`MessagePlain\` or \`Message\`. You may use \`MessagePlain\` and/or \`MessageHTML\`, or you may specify a dashboard Template using \`TemplateID\`. This example uses \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation) and you can track links using the built-in \[URL Shortener]\(https\://www\.tnz.co.nz/help/email-url-shortener-and-short-links).
- **`Mode`**
`string | null`, default: `null` — Set to \`Test\` to have messages handled immediately as successful without sending a live message. Useful for end-to-end testing. Omit to use standard mode.
- **`NotificationType`**
`string | null`, possible values: `"None", "Webhook", "Email"`, default: `""` — Specifies the notification method for delivery status updates and inbound replies for this message. Omit to use your User's default settings.
- **`Reference`**
`string | null` — A human readable message reference.
- **`ReplyTo`**
`string` — Adds a Reply-To to the email (if the recipient replies, the Reply To will receive the reply).
- **`ReportTo`**
`string`, format: `email` — Email address to send a delivery report to once the message completes. Omit to use your User's default settings.
- **`SendTime`**
`string`, default: `null` — Delay sending until the specified specified time - {date}T{time} (in the user's 'Local' Timezone). Omit to send immediately.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`TemplateID`**
`string`, format: `uuid` — UUID of the message template to use. Edit a template in the Dashboard to find the Template ID. If both \`TemplateID\` and a Message are specified, the message takes priority.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`WebhookCallbackFormat`**
`string`, possible values: `"JSON", "XML", "POST", "GET"` — The format of the webhook body. Omit to use your User's default settings.
- **`WebhookCallbackURL`**
`string`, format: `uri` — The URL to receive the webhook. A full path including https\:// is required. Omit to use your User's default settings.
**Example:**
```json
{
"MessagePlain": "Hello [[FirstName]], view the [[Custom1]] link at [[Link:https://www.example.com/path/to/page.html]] or reply at [[REPLY]]. Reply STOP to OptOut.",
"MessageHTML": "Hello [[FirstName]], view the [[Custom1]] link at [[Link:https://www.example.com/path/to/page.html]] or reply at [[REPLY]]. Reply STOP to OptOut.",
"TemplateID": "123e4567-e89b-12d3-a456-426614174000",
"Destination": "021-000001",
"EmailAddress": "john.doe@example.com",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"Destinations": [
{
"ToNumber": "+6421000001",
"EmailAddress": "john.doe@example.com",
"MainPhone": "+6421000001",
"Attention": "John Doe",
"First Name": "John",
"Last Name": "Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group"
}
],
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"Reference": "MyTest",
"From": "Company One Ltd",
"FromEmail": "help@example.com",
"CCEmail": "notices@example.com",
"BCCEmail": "archive@example.com",
"ReplyTo": "replies@example.com",
"EmailSubject": "Your appointment is coming up!",
"NotificationType": "None",
"WebhookCallbackURL": "https://example.com/webhook",
"WebhookCallbackFormat": "JSON",
"ReportTo": "reports@example.com",
"SendTime": "2026-08-29T14:00",
"Timezone": "New Zealand",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"Files": [
{
"Name": "My Example.pdf",
"Data": "base64-encoded-file-data"
}
],
"Mode": "Test"
}
```
#### Responses
##### Status: 200 OK \[successful submission]
###### Content-Type: application/json
- **`MessageID`**
`string` — Unique identifier for the API call.
**Example:**
```json
{
"MessageID": "1000000a-f002-4007-b00a-d00000000002"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Email Details
- **Method:** `GET`
- **Path:** `/email/{MessageID}`
- **Tags:** Email
Poll for details of a sent Email message.
The primary object details the message as a whole, while the `Recipients` array contains details of each recipient.
Timeout your polls after 6 hours with no result.
Limit your polls to 1 per second to avoid rate limits.
Consider the [Send Result Webhook](#tag/email/webhook/POST/resultwebhook) for efficiency.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
**All of:**
- **`Account`**
`string` — Your account number.
- **`Complete`**
`integer` — Total Destinations that were successfully completed.
- **`Count`**
`integer` — Total Destinations specified in the message.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`DelayedTimeLocal`**
`string` — The time the entry was delayed until, in the local Timezone.
- **`DelayedTimeUTC`**
`string` — The time the entry was delayed until, in UTC.
- **`DelayedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was delayed until, in UTC (RFC3339 format).
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Failed`**
`integer` — Total Destinations that failed to deliver.
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`JobStatus`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
- **`MessageID`**
`string | null` — 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.
- **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
- **`Reference`**
`string | null` — A human readable message reference.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Success`**
`integer` — Total Destinations that were successfully delivered.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
* **`Page`**
`integer`
* **`PageCount`**
`integer`
* **`RecordsPerPage`**
`integer`
* **`TotalRecords`**
`integer`
- **`Recipients`**
`array` — List of recipients for the message.
**Items:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Destination`**
`string` — The destination address (e.g. phone number, email address).
- **`DestSeq`**
`string` — The ID of the destination in the list (increments per destination).
- **`Result`**
`string` — The final delivery result. For a list of possible values, see \[Email]\(https\://www\.tnz.co.nz/help/email-delivery-result-codes) result codes.
- **`Status`**
`string`, possible values: `"Success", "Failed", "Pending"` — Current status of the message.
- **`Type`**
`string`, possible values: `"SMS", "Email", "Voice", "Fax"` — The type of message this data relates to.
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`Company`**
`string | null` — The contact's company name (used for personalising the message).
* **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
* **`Custom2`**
`string | null` — Additional custom variable.
* **`Custom3`**
`string | null` — Additional custom variable.
* **`Custom4`**
`string | null` — Additional custom variable.
* **`Custom5`**
`string | null` — Additional custom variable.
* **`Custom6`**
`string | null` — Additional custom variable.
* **`Custom7`**
`string | null` — Additional custom variable.
* **`Custom8`**
`string | null` — Additional custom variable.
* **`Custom9`**
`string | null` — Additional custom variable.
* **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
* **`RemoteID`**
`string | null` — For Voice, Text-to-Speech and Fax, dialled phone number. This may differ from 'Destination' if failover Alt Phones are used.
* **`SentTimeLocal`**
`string` — Time the message was sent in the users local Timezone (ISO 8601 format).
* **`SentTimeUTC`**
`string` — Time the message was sent in UTC (ISO 8601 format).
* **`SentTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was sent in UTC (RFC 3339 format).
**Example:**
```json
{
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobStatus": "Pending",
"JobNum": "10AB20CE",
"Account": "101202",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"Reference": "MyTest",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"DelayedTimeLocal": "2025-05-29 05:11:03",
"DelayedTimeUTC": "2025-05-29 17:11:03",
"DelayedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand",
"Count": 1,
"Complete": 1,
"Success": 1,
"Failed": 0,
"Price": 0.1,
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Recipients": [
{
"Type": "Email",
"DestSeq": "00000001",
"Destination": "john.doe@example.com",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Status": "Success",
"Result": "250 OK",
"SentTimeLocal": "2025-06-13T08:44:16.000Z",
"SentTimeUTC": "2025-06-12T20:44:16.000Z",
"SentTimeUTC_RFC3339": "2025-06-12T20:44:16.000Z",
"Attention": "John Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"Custom5": "",
"Custom6": "",
"Custom7": "",
"Custom8": "",
"Custom9": "",
"RemoteID": "+6495006000",
"Price": 0.1
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Reschedule
- **Method:** `PATCH`
- **Path:** `/email/{MessageID}/reschedule`
- **Tags:** Email
This endpoint allows you to reschedule a previously delayed message to be sent at a new time.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Reschedule"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Reschedule"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Abort
- **Method:** `PATCH`
- **Path:** `/email/{MessageID}/abort`
- **Tags:** Email
This endpoint allows you to abort a previously delayed message.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Abort"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Abort"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Resubmit
- **Method:** `PATCH`
- **Path:** `/email/{MessageID}/resubmit`
- **Tags:** Email
This endpoint allows you to retry sending a previously failed message.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found].
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Resubmit"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Resubmit"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Send TTS
- **Method:** `POST`
- **Path:** `/tts`
- **Tags:** TTS
Send a Voice Call using Text-to-Speech to one or more recipients.
The `MessageToPeople` parameter specifies the message to send. Alternatively, use `TemplateID` to send a pre-configured message template ([Find Your TemplateID](https://www.tnz.co.nz/help/how-to-find-your-templateid)).
The `Destination` parameter contains the email address to receive your message. Alternatively, you may use the `Destinations` array for multiple contacts, or use Address Book `ContactID` or `GroupID` values.
#### Request Body
##### Content-Type: application/json
- **`AnswerPhoneMode`**
`string`, default: `"NDAS"` — Sets the action for when an Answering Machine is detected, such as playing a message or dropping the call ('NDAS','NDAF','DAS','DAF'). See \[Answer Phone Detection for Voice]\(https\://www\.tnz.co.nz/help/answer-phone-detection-for-voice).
- **`CallerID`**
`string`, format: `phone` — Sets the Caller ID used on the call (must be E.164 format and whitelisted under your account).
- **`CallRouteMessageOnWrongKey`**
`string` — 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.
- **`CallRouteMessageToOperators`**
`string` — Text-to-speech message played to the call centre representative answering the connected call.
- **`CallRouteMessageToPeople`**
`string` — Text-to-speech message played when a keypad option is pressed.
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Destination`**
`string` — A single destination to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
- **`Destinations`**
`array` — An array of one or more contacts to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
**Items:**
- **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
- **`Company`**
`string | null` — The contact's company name (used for personalising the message).
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
- **`Custom2`**
`string | null` — Additional custom variable.
- **`Custom3`**
`string | null` — Additional custom variable.
- **`Custom4`**
`string | null` — Additional custom variable.
- **`EmailAddress`**
`string`, format: `email` — The contact's email address.
- **`First Name`**
`string | null` — The contact's first name (used for personalising the message).
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`Last Name`**
`string | null` — The contact's last name (used for personalising the message).
- **`MainPhone`**
`string`, format: `phone` — The contact's voice telephone number. See \[Telephone Number Formatting]\(https\://www\.tnz.co.nz/help/telephone-number-formatting-for-voice-fax) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`KeypadOptionRequired`**
`boolean`, default: `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.
- **`Keypads`**
`array` — Detect if the recipient presses a keypad option and perform an action.
**Items:**
- **`Play`**
`string` — Message to play when the keypad button is pressed.
- **`PlaySection`**
`string` — If specified, the call will jump to this section. - Main = The main \`MessageToPeople\`. - AnswerPhone = Simulates an Answering Machine pickup and plays \`MessageToAnswerPhones\`. - WrongKey = Plays the \`CallRouteMessageOnWrongKey\` message.
- **`RouteNumber`**
`string`, format: `phone` — If specified, the call will be diverted to this number when the keypad button is pressed.
- **`Tone`**
`integer` — The keypad button.
- **`MessageID`**
`string | null` — 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.
- **`MessageToAnswerPhones`**
`string` — Enables Answering Machine/Voicemail detection. When an answering machine is detected, this message is played.
- **`MessageToPeople`**
`string` — The message to play when the call is answered by a person. You may synonymously use \`MessageToPeople\` or \`Message\`. You may use SSML commands to tweak the way words and phrases are spoken: \[SSML Commands]\(https\://www\.tnz.co.nz/help/text-to-speech-custom-commands). Alternatively, specify a template using \`TemplateID\`.
- **`Mode`**
`string | null`, default: `null` — Set to \`Test\` to have messages handled immediately as successful without sending a live message. Useful for end-to-end testing. Omit to use standard mode.
- **`NotificationType`**
`string | null`, possible values: `"None", "Webhook", "Email"`, default: `""` — Specifies the notification method for delivery status updates and inbound replies for this message. Omit to use your User's default settings.
- **`NumberOfOperators`**
`integer`, default: `99999` — When sending to multiple Destinations in a single message, you may use this parameter to limit the number of simultaneous calls to match the number of available operators. This is particularly useful when paired with a Keypad with a \`RouteNumber\`.
- **`Options`**
`string` — 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.
- **`Reference`**
`string | null` — A human readable message reference.
- **`ReportTo`**
`string`, format: `email` — Email address to send a delivery report to once the message completes. Omit to use your User's default settings.
- **`RetryAttempts`**
`integer` — Number of times to retry if the call fails (for example, the recipients line is busy or unavailable). RetryAttempts=0 means the call will not be retried. 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.
- **`RetryPeriod`**
`integer` — Minutes to wait between Retry Attempts.
- **`SendTime`**
`string`, default: `null` — Delay sending until the specified specified time - {date}T{time} (in the user's 'Local' Timezone). Omit to send immediately.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`TemplateID`**
`string`, format: `uuid` — UUID of the message template to use. Edit a template in the Dashboard to find the Template ID. If both \`TemplateID\` and a Message are specified, the message takes priority.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`Voice`**
`string`, default: `"Female1"` — Text-to-Speech voice to use (Male1, Female1, Nicole, Russell, Amy, Brian, Emma).
- **`WebhookCallbackFormat`**
`string`, possible values: `"JSON", "XML", "POST", "GET"` — The format of the webhook body. Omit to use your User's default settings.
- **`WebhookCallbackURL`**
`string`, format: `uri` — The URL to receive the webhook. A full path including https\:// is required. Omit to use your User's default settings.
**Example:**
```json
{
"MessageToPeople": "Hello, this is a call from Department01. This is relevant information. Press one to be connected to our call centre.",
"TemplateID": "123e4567-e89b-12d3-a456-426614174000",
"Destination": "021-000001",
"ToNumber": "+6421000001",
"Destinations": [
{
"ToNumber": "+6421000001",
"EmailAddress": "john.doe@example.com",
"MainPhone": "+6421000001",
"Attention": "John Doe",
"First Name": "John",
"Last Name": "Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group"
}
],
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"Reference": "MyTest",
"NotificationType": "None",
"WebhookCallbackURL": "https://example.com/webhook",
"WebhookCallbackFormat": "JSON",
"ReportTo": "reports@example.com",
"SendTime": "2026-08-29T14:00",
"Timezone": "New Zealand",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"MessageToAnswerPhones": "Hello, sorry we missed you. This is a call from Department 01. Please contact us on 0800 123123.",
"AnswerPhoneMode": "NDAS",
"Keypads": [
{
"Tone": 1,
"Play": "You pressed Keypad 1. We're connecting you now.",
"RouteNumber": "6421000001",
"PlaySection": "Main"
}
],
"KeypadOptionRequired": false,
"CallRouteMessageOnWrongKey": "Sorry, you have pressed an invalid key. Please try again.",
"CallRouteMessageToPeople": "Connecting you now.",
"CallRouteMessageToOperators": "Incoming Text To Speech call.",
"NumberOfOperators": 5,
"RetryAttempts": 1,
"RetryPeriod": 5,
"CallerID": 6495005000,
"Voice": "Female1",
"Options": "",
"Mode": "Test"
}
```
#### Responses
##### Status: 200 OK \[successful submission]
###### Content-Type: application/json
- **`MessageID`**
`string` — Unique identifier for the API call.
**Example:**
```json
{
"MessageID": "1000000a-f002-4007-b00a-d00000000002"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### TTS Details
- **Method:** `GET`
- **Path:** `/tts/{MessageID}`
- **Tags:** TTS
Poll for details of a sent TTS message.
The primary object details the message as a whole, while the `Recipients` array contains details of each recipient.
Timeout your polls after 6 hours with no result.
Limit your polls to 1 per second to avoid rate limits.
Consider the [Send Result Webhook](#tag/tts/webhook/POST/resultwebhook) for efficiency.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
**All of:**
- **`Account`**
`string` — Your account number.
- **`Complete`**
`integer` — Total Destinations that were successfully completed.
- **`Count`**
`integer` — Total Destinations specified in the message.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`DelayedTimeLocal`**
`string` — The time the entry was delayed until, in the local Timezone.
- **`DelayedTimeUTC`**
`string` — The time the entry was delayed until, in UTC.
- **`DelayedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was delayed until, in UTC (RFC3339 format).
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Failed`**
`integer` — Total Destinations that failed to deliver.
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`JobStatus`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
- **`MessageID`**
`string | null` — 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.
- **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
- **`Reference`**
`string | null` — A human readable message reference.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Success`**
`integer` — Total Destinations that were successfully delivered.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
* **`Page`**
`integer`
* **`PageCount`**
`integer`
* **`RecordsPerPage`**
`integer`
* **`TotalRecords`**
`integer`
- **`Recipients`**
`array` — List of recipients for the message.
**Items:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Destination`**
`string` — The destination address (e.g. phone number, email address).
- **`DestSeq`**
`string` — The ID of the destination in the list (increments per destination).
- **`Result`**
`string` — The final delivery result. For a list of possible values, see \[Voice]\(https\://www\.tnz.co.nz/help/voice-tts-delivery-result-codes) result codes.
- **`Status`**
`string`, possible values: `"Success", "Failed", "Pending"` — Current status of the message.
- **`Type`**
`string`, possible values: `"SMS", "Email", "Voice", "Fax"` — The type of message this data relates to.
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`Company`**
`string | null` — The contact's company name (used for personalising the message).
* **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
* **`Custom2`**
`string | null` — Additional custom variable.
* **`Custom3`**
`string | null` — Additional custom variable.
* **`Custom4`**
`string | null` — Additional custom variable.
* **`Custom5`**
`string | null` — Additional custom variable.
* **`Custom6`**
`string | null` — Additional custom variable.
* **`Custom7`**
`string | null` — Additional custom variable.
* **`Custom8`**
`string | null` — Additional custom variable.
* **`Custom9`**
`string | null` — Additional custom variable.
* **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
* **`RemoteID`**
`string | null` — For Voice, Text-to-Speech and Fax, dialled phone number. This may differ from 'Destination' if failover Alt Phones are used.
* **`SentTimeLocal`**
`string` — Time the message was sent in the users local Timezone (ISO 8601 format).
* **`SentTimeUTC`**
`string` — Time the message was sent in UTC (ISO 8601 format).
* **`SentTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was sent in UTC (RFC 3339 format).
**Example:**
```json
{
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobStatus": "Pending",
"JobNum": "10AB20CE",
"Account": "101202",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"Reference": "MyTest",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"DelayedTimeLocal": "2025-05-29 05:11:03",
"DelayedTimeUTC": "2025-05-29 17:11:03",
"DelayedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand",
"Count": 1,
"Complete": 1,
"Success": 1,
"Failed": 0,
"Price": 0.1,
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Recipients": [
{
"Type": "Voice",
"DestSeq": "00000001",
"Destination": "+6495006000",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Status": "Success",
"Result": "SentOK",
"SentTimeLocal": "2025-06-13T08:44:16.000Z",
"SentTimeUTC": "2025-06-12T20:44:16.000Z",
"SentTimeUTC_RFC3339": "2025-06-12T20:44:16.000Z",
"Attention": "John Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"Custom5": "",
"Custom6": "",
"Custom7": "",
"Custom8": "",
"Custom9": "",
"RemoteID": "+6495006000",
"Price": 0.1
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Reschedule
- **Method:** `PATCH`
- **Path:** `/tts/{MessageID}/reschedule`
- **Tags:** TTS
This endpoint allows you to reschedule a previously delayed message to be sent at a new time.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Reschedule"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Reschedule"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Abort
- **Method:** `PATCH`
- **Path:** `/tts/{MessageID}/abort`
- **Tags:** TTS
This endpoint allows you to abort a previously delayed message.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Abort"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Abort"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Resubmit
- **Method:** `PATCH`
- **Path:** `/tts/{MessageID}/resubmit`
- **Tags:** TTS
This endpoint allows you to retry sending a previously failed message.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Resubmit"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Resubmit"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Number Of Operators
- **Method:** `PATCH`
- **Path:** `/tts/{MessageID}/pacing`
- **Tags:** TTS
This endpoint allows you to adjust the `NumberOfOperators` configured for a pending message.
#### Request Body
##### Content-Type: application/json
- **`NumberOfOperators` (required)**
`integer`, default: `99999` — When sending to multiple Destinations in a single message, you may use this parameter to limit the number of simultaneous calls to match the number of available operators. This is particularly useful when paired with a Keypad with a \`RouteNumber\`.
**Example:**
```json
{
"NumberOfOperators": 5
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Pacing"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Pacing"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Send Voice
- **Method:** `POST`
- **Path:** `/voice`
- **Tags:** Voice
Send a Voice Call using Text-to-Speech to one or more recipients.
The `MessageToPeople` parameter specifies the message to send. Alternatively, use `TemplateID` to send a pre-configured message template ([Find Your TemplateID](https://www.tnz.co.nz/help/how-to-find-your-templateid)).
The `Destination` parameter contains the email address to receive your message. Alternatively, you may use the `Destinations` array for multiple contacts, or use Address Book `ContactID` or `GroupID` values.
#### Request Body
##### Content-Type: application/json
- **`AnswerPhoneMode`**
`string`, default: `"NDAS"` — Sets the action for when an Answering Machine is detected, such as playing a message or dropping the call ('NDAS','NDAF','DAS','DAF'). See \[Answer Phone Detection for Voice]\(https\://www\.tnz.co.nz/help/answer-phone-detection-for-voice).
- **`CallerID`**
`string`, format: `phone` — Sets the Caller ID used on the call (must be E.164 format and whitelisted under your account).
- **`CallRouteMessageOnWrongKey`**
`string` — 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".
- **`CallRouteMessageToOperators`**
`string` — Audio data played to the call centre representative answering the connected call (WAV format, 16-bit, 8000hz). E.g. "Incoming Text To Speech call."
- **`CallRouteMessageToPeople`**
`string` — Audio data played when a keypad option is pressed (WAV format, 16-bit, 8000hz). E.g. "Connecting you now."
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Destination`**
`string` — A single destination to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
- **`Destinations`**
`array` — An array of one or more contacts to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
**Items:**
- **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
- **`Company`**
`string | null` — The contact's company name (used for personalising the message).
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
- **`Custom2`**
`string | null` — Additional custom variable.
- **`Custom3`**
`string | null` — Additional custom variable.
- **`Custom4`**
`string | null` — Additional custom variable.
- **`EmailAddress`**
`string`, format: `email` — The contact's email address.
- **`First Name`**
`string | null` — The contact's first name (used for personalising the message).
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`Last Name`**
`string | null` — The contact's last name (used for personalising the message).
- **`MainPhone`**
`string`, format: `phone` — The contact's voice telephone number. See \[Telephone Number Formatting]\(https\://www\.tnz.co.nz/help/telephone-number-formatting-for-voice-fax) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`KeypadOptionRequired`**
`boolean`, default: `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.
- **`Keypads`**
`array` — Detect if the recipient presses a keypad option and perform an action.
**Items:**
- **`Play`**
`string` — Message to play when the keypad button is pressed.
- **`PlaySection`**
`string` — If specified, the call will jump to this section. - Main = The main \`MessageToPeople\`. - AnswerPhone = Simulates an Answering Machine pickup and plays \`MessageToAnswerPhones\`. - WrongKey = Plays the \`CallRouteMessageOnWrongKey\` message.
- **`RouteNumber`**
`string`, format: `phone` — If specified, the call will be diverted to this number when the keypad button is pressed.
- **`Tone`**
`integer` — The keypad button.
- **`MessageID`**
`string | null` — 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.
- **`MessageToAnswerPhones`**
`string` — 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.
- **`MessageToPeople`**
`string` — The audio data played if the call is answered by a human (WAV format, 16-bit, 8000hz). Download a sample WAV: \[base64-encoded-file-data]\(https\://www\.tnz.co.nz/docs/RESTAPI/samples/3.00/base64-MessageToPeople.txt) Alternatively, specify a template using \`TemplateID\`.
- **`Mode`**
`string | null`, default: `null` — Set to \`Test\` to have messages handled immediately as successful without sending a live message. Useful for end-to-end testing. Omit to use standard mode.
- **`NotificationType`**
`string | null`, possible values: `"None", "Webhook", "Email"`, default: `""` — Specifies the notification method for delivery status updates and inbound replies for this message. Omit to use your User's default settings.
- **`NumberOfOperators`**
`integer`, default: `99999` — When sending to multiple Destinations in a single message, you may use this parameter to limit the number of simultaneous calls to match the number of available operators. This is particularly useful when paired with a Keypad with a \`RouteNumber\`.
- **`Options`**
`string` — 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.
- **`Reference`**
`string | null` — A human readable message reference.
- **`ReportTo`**
`string`, format: `email` — Email address to send a delivery report to once the message completes. Omit to use your User's default settings.
- **`RetryAttempts`**
`integer` — Number of times to retry if the call fails (for example, the recipients line is busy or unavailable). RetryAttempts=0 means the call will not be retried. 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.
- **`RetryPeriod`**
`integer` — Minutes to wait between Retry Attempts.
- **`SendTime`**
`string`, default: `null` — Delay sending until the specified specified time - {date}T{time} (in the user's 'Local' Timezone). Omit to send immediately.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`TemplateID`**
`string`, format: `uuid` — UUID of the message template to use. Edit a template in the Dashboard to find the Template ID. If both \`TemplateID\` and a Message are specified, the message takes priority.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`WebhookCallbackFormat`**
`string`, possible values: `"JSON", "XML", "POST", "GET"` — The format of the webhook body. Omit to use your User's default settings.
- **`WebhookCallbackURL`**
`string`, format: `uri` — The URL to receive the webhook. A full path including https\:// is required. Omit to use your User's default settings.
**Example:**
```json
{
"MessageToPeople": "[Base64 encoded data]",
"TemplateID": "123e4567-e89b-12d3-a456-426614174000",
"Destination": "021-000001",
"ToNumber": "+6421000001",
"Destinations": [
{
"ToNumber": "+6421000001",
"EmailAddress": "john.doe@example.com",
"MainPhone": "+6421000001",
"Attention": "John Doe",
"First Name": "John",
"Last Name": "Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group"
}
],
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"Reference": "MyTest",
"NotificationType": "None",
"WebhookCallbackURL": "https://example.com/webhook",
"WebhookCallbackFormat": "JSON",
"ReportTo": "reports@example.com",
"SendTime": "2026-08-29T14:00",
"Timezone": "New Zealand",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"MessageToAnswerPhones": "[Base64 encoded data]",
"AnswerPhoneMode": "NDAS",
"Keypads": [
{
"Tone": 1,
"Play": [
"Base64 encoded data"
],
"RouteNumber": "6421000001",
"PlaySection": "Main"
}
],
"KeypadOptionRequired": false,
"CallRouteMessageOnWrongKey": [
"Base64 encoded data"
],
"CallRouteMessageToPeople": [
"Base64 encoded data"
],
"CallRouteMessageToOperators": [
"Base64 encoded data"
],
"NumberOfOperators": 5,
"RetryAttempts": 1,
"RetryPeriod": 5,
"CallerID": 6495005000,
"Options": "",
"Mode": "Test"
}
```
#### Responses
##### Status: 200 OK \[successful submission]
###### Content-Type: application/json
- **`MessageID`**
`string` — Unique identifier for the API call.
**Example:**
```json
{
"MessageID": "1000000a-f002-4007-b00a-d00000000002"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Voice Details
- **Method:** `GET`
- **Path:** `/voice/{MessageID}`
- **Tags:** Voice
Poll for details of a sent Voice message.
The primary object details the message as a whole, while the `Recipients` array contains details of each recipient.
Timeout your polls after 6 hours with no result.
Limit your polls to 1 per second to avoid rate limits.
Consider the [Send Result Webhook](#tag/voice/webhook/POST/resultwebhook) for efficiency.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
**All of:**
- **`Account`**
`string` — Your account number.
- **`Complete`**
`integer` — Total Destinations that were successfully completed.
- **`Count`**
`integer` — Total Destinations specified in the message.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`DelayedTimeLocal`**
`string` — The time the entry was delayed until, in the local Timezone.
- **`DelayedTimeUTC`**
`string` — The time the entry was delayed until, in UTC.
- **`DelayedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was delayed until, in UTC (RFC3339 format).
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Failed`**
`integer` — Total Destinations that failed to deliver.
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`JobStatus`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
- **`MessageID`**
`string | null` — 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.
- **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
- **`Reference`**
`string | null` — A human readable message reference.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Success`**
`integer` — Total Destinations that were successfully delivered.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
* **`Page`**
`integer`
* **`PageCount`**
`integer`
* **`RecordsPerPage`**
`integer`
* **`TotalRecords`**
`integer`
- **`Recipients`**
`array` — List of recipients for the message.
**Items:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Destination`**
`string` — The destination address (e.g. phone number, email address).
- **`DestSeq`**
`string` — The ID of the destination in the list (increments per destination).
- **`Result`**
`string` — The final delivery result. For a list of possible values, see \[Voice]\(https\://www\.tnz.co.nz/help/voice-tts-delivery-result-codes) result codes.
- **`Status`**
`string`, possible values: `"Success", "Failed", "Pending"` — Current status of the message.
- **`Type`**
`string`, possible values: `"SMS", "Email", "Voice", "Fax"` — The type of message this data relates to.
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`Company`**
`string | null` — The contact's company name (used for personalising the message).
* **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
* **`Custom2`**
`string | null` — Additional custom variable.
* **`Custom3`**
`string | null` — Additional custom variable.
* **`Custom4`**
`string | null` — Additional custom variable.
* **`Custom5`**
`string | null` — Additional custom variable.
* **`Custom6`**
`string | null` — Additional custom variable.
* **`Custom7`**
`string | null` — Additional custom variable.
* **`Custom8`**
`string | null` — Additional custom variable.
* **`Custom9`**
`string | null` — Additional custom variable.
* **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
* **`RemoteID`**
`string | null` — For Voice, Text-to-Speech and Fax, dialled phone number. This may differ from 'Destination' if failover Alt Phones are used.
* **`SentTimeLocal`**
`string` — Time the message was sent in the users local Timezone (ISO 8601 format).
* **`SentTimeUTC`**
`string` — Time the message was sent in UTC (ISO 8601 format).
* **`SentTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was sent in UTC (RFC 3339 format).
**Example:**
```json
{
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobStatus": "Pending",
"JobNum": "10AB20CE",
"Account": "101202",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"Reference": "MyTest",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"DelayedTimeLocal": "2025-05-29 05:11:03",
"DelayedTimeUTC": "2025-05-29 17:11:03",
"DelayedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand",
"Count": 1,
"Complete": 1,
"Success": 1,
"Failed": 0,
"Price": 0.1,
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Recipients": [
{
"Type": "Voice",
"DestSeq": "00000001",
"Destination": "+6495006000",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Status": "Success",
"Result": "SentOK",
"SentTimeLocal": "2025-06-13T08:44:16.000Z",
"SentTimeUTC": "2025-06-12T20:44:16.000Z",
"SentTimeUTC_RFC3339": "2025-06-12T20:44:16.000Z",
"Attention": "John Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"Custom5": "",
"Custom6": "",
"Custom7": "",
"Custom8": "",
"Custom9": "",
"RemoteID": "+6495006000",
"Price": 0.1
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Reschedule
- **Method:** `PATCH`
- **Path:** `/voice/{MessageID}/reschedule`
- **Tags:** Voice
This endpoint allows you to reschedule a previously delayed message to be sent at a new time.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Reschedule"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Reschedule"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Abort
- **Method:** `PATCH`
- **Path:** `/voice/{MessageID}/abort`
- **Tags:** Voice
This endpoint allows you to abort a previously delayed message.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Abort"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Abort"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Resubmit
- **Method:** `PATCH`
- **Path:** `/voice/{MessageID}/resubmit`
- **Tags:** Voice
This endpoint allows you to retry sending a previously failed message.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Resubmit"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Resubmit"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Number Of Operators
- **Method:** `PATCH`
- **Path:** `/voice/{MessageID}/pacing`
- **Tags:** Voice
This endpoint allows you to adjust the `NumberOfOperators` configured for a pending message.
#### Request Body
##### Content-Type: application/json
- **`NumberOfOperators` (required)**
`integer`, default: `99999` — When sending to multiple Destinations in a single message, you may use this parameter to limit the number of simultaneous calls to match the number of available operators. This is particularly useful when paired with a Keypad with a \`RouteNumber\`.
**Example:**
```json
{
"NumberOfOperators": 5
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Pacing"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Pacing"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Send Fax
- **Method:** `POST`
- **Path:** `/fax`
- **Tags:** Fax
Send a Fax to one or more recipients.
The `MessageToPeople` parameter specifies the message to send. Alternatively, use `TemplateID` to send a pre-configured message template ([Find Your TemplateID](https://www.tnz.co.nz/help/how-to-find-your-templateid)).
The `Destination` parameter contains the email address to receive your message. Alternatively, you may use the `Destinations` array for multiple contacts, or use Address Book `ContactID` or `GroupID` values.
#### Request Body
##### Content-Type: application/json
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`CSID`**
`string` — A human-readable Caller Sender ID (CSID) to be printed on the fax header.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Destination`**
`string` — A single destination to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
- **`Destinations`**
`array` — An array of one or more contacts to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
**Items:**
- **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
- **`Company`**
`string | null` — The contact's company name (used for personalising the message).
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
- **`Custom2`**
`string | null` — Additional custom variable.
- **`Custom3`**
`string | null` — Additional custom variable.
- **`Custom4`**
`string | null` — Additional custom variable.
- **`EmailAddress`**
`string`, format: `email` — The contact's email address.
- **`First Name`**
`string | null` — The contact's first name (used for personalising the message).
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`Last Name`**
`string | null` — The contact's last name (used for personalising the message).
- **`MainPhone`**
`string`, format: `phone` — The contact's voice telephone number. See \[Telephone Number Formatting]\(https\://www\.tnz.co.nz/help/telephone-number-formatting-for-voice-fax) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`Files`**
`array` — An array of file attachments.
**Items:**
- **`Data`**
`string`, format: `byte` — The base64-encoded file data. Download a sample PDF: \[base64-encoded-file-data]\(https\://www\.tnz.co.nz/docs/RESTAPI/samples/3.00/base64-Files.txt)
- **`Name`**
`string` — The name of the attached file including the file extension.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`MessageID`**
`string | null` — 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.
- **`Mode`**
`string | null`, default: `null` — Set to \`Test\` to have messages handled immediately as successful without sending a live message. Useful for end-to-end testing. Omit to use standard mode.
- **`NotificationType`**
`string | null`, possible values: `"None", "Webhook", "Email"`, default: `""` — Specifies the notification method for delivery status updates and inbound replies for this message. Omit to use your User's default settings.
- **`Reference`**
`string | null` — A human readable message reference.
- **`ReportTo`**
`string`, format: `email` — Email address to send a delivery report to once the message completes. Omit to use your User's default settings.
- **`Resolution`**
`string`, possible values: `"Low", "High"`, default: `"Low"` — Quality of the fax image. High for better quality, low for faster delivery speed.
- **`RetryAttempts`**
`integer` — Number of times to retry if the fax fails (for example, the line is busy or unavailable). RetryAttempts=0 means the fax will not be retried.
- **`RetryPeriod`**
`integer` — Minutes to wait between Retry Attempts.
- **`SendTime`**
`string`, default: `null` — Delay sending until the specified specified time - {date}T{time} (in the user's 'Local' Timezone). Omit to send immediately.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`TemplateID`**
`string`, format: `uuid` — UUID of the message template to use. Edit a template in the Dashboard to find the Template ID. If both \`TemplateID\` and a Message are specified, the message takes priority.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`WatermarkAllPages`**
`string` — Watermark file to apply to all pages.
- **`WatermarkFirstPage`**
`string` — Watermark file to apply to the first page only.
- **`WatermarkFolder`**
`string` — Location of Watermark file to use.
- **`WebhookCallbackFormat`**
`string`, possible values: `"JSON", "XML", "POST", "GET"` — The format of the webhook body. Omit to use your User's default settings.
- **`WebhookCallbackURL`**
`string`, format: `uri` — The URL to receive the webhook. A full path including https\:// is required. Omit to use your User's default settings.
**Example:**
```json
{
"Files": [
{
"Name": "My Example.pdf",
"Data": "base64-encoded-file-data"
}
],
"TemplateID": "123e4567-e89b-12d3-a456-426614174000",
"Destination": "021-000001",
"ToNumber": "+6421000001",
"Destinations": [
{
"ToNumber": "+6421000001",
"EmailAddress": "john.doe@example.com",
"MainPhone": "+6421000001",
"Attention": "John Doe",
"First Name": "John",
"Last Name": "Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group"
}
],
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"Reference": "MyTest",
"NotificationType": "None",
"WebhookCallbackURL": "https://example.com/webhook",
"WebhookCallbackFormat": "JSON",
"ReportTo": "reports@example.com",
"SendTime": "2026-08-29T14:00",
"Timezone": "New Zealand",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"CSID": "+64 9 500 6000",
"Resolution": "Low",
"WatermarkFolder": "Folder01",
"WatermarkFirstPage": "Watermark File Name.ps",
"WatermarkAllPages": "Watermark File Name.docx",
"RetryAttempts": 3,
"RetryPeriod": 1,
"Mode": "Test"
}
```
#### Responses
##### Status: 200 OK \[successful submission]
###### Content-Type: application/json
- **`MessageID`**
`string` — Unique identifier for the API call.
**Example:**
```json
{
"MessageID": "1000000a-f002-4007-b00a-d00000000002"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Fax Details
- **Method:** `GET`
- **Path:** `/fax/{MessageID}`
- **Tags:** Fax
Poll for details of a sent Fax message.
The primary object details the message as a whole, while the `Recipients` array contains details of each recipient.
Timeout your polls after 6 hours with no result.
Limit your polls to 1 per second to avoid rate limits.
Consider the [Send Result Webhook](#tag/fax/webhook/POST/resultwebhook) for efficiency.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
**All of:**
- **`Account`**
`string` — Your account number.
- **`Complete`**
`integer` — Total Destinations that were successfully completed.
- **`Count`**
`integer` — Total Destinations specified in the message.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`DelayedTimeLocal`**
`string` — The time the entry was delayed until, in the local Timezone.
- **`DelayedTimeUTC`**
`string` — The time the entry was delayed until, in UTC.
- **`DelayedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was delayed until, in UTC (RFC3339 format).
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Failed`**
`integer` — Total Destinations that failed to deliver.
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`JobStatus`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
- **`MessageID`**
`string | null` — 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.
- **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
- **`Reference`**
`string | null` — A human readable message reference.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Success`**
`integer` — Total Destinations that were successfully delivered.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
* **`Page`**
`integer`
* **`PageCount`**
`integer`
* **`RecordsPerPage`**
`integer`
* **`TotalRecords`**
`integer`
- **`Recipients`**
`array` — List of recipients for the message.
**Items:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Destination`**
`string` — The destination address (e.g. phone number, email address).
- **`DestSeq`**
`string` — The ID of the destination in the list (increments per destination).
- **`Result`**
`string` — The final delivery result. For a list of possible values, see \[Fax]\(https\://www\.tnz.co.nz/help/fax-delivery-result-codes) result codes.
- **`Status`**
`string`, possible values: `"Success", "Failed", "Pending"` — Current status of the message.
- **`Type`**
`string`, possible values: `"SMS", "Email", "Voice", "Fax"` — The type of message this data relates to.
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`Company`**
`string | null` — The contact's company name (used for personalising the message).
* **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
* **`Custom2`**
`string | null` — Additional custom variable.
* **`Custom3`**
`string | null` — Additional custom variable.
* **`Custom4`**
`string | null` — Additional custom variable.
* **`Custom5`**
`string | null` — Additional custom variable.
* **`Custom6`**
`string | null` — Additional custom variable.
* **`Custom7`**
`string | null` — Additional custom variable.
* **`Custom8`**
`string | null` — Additional custom variable.
* **`Custom9`**
`string | null` — Additional custom variable.
* **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
* **`RemoteID`**
`string | null` — For Voice, Text-to-Speech and Fax, dialled phone number. This may differ from 'Destination' if failover Alt Phones are used.
* **`SentTimeLocal`**
`string` — Time the message was sent in the users local Timezone (ISO 8601 format).
* **`SentTimeUTC`**
`string` — Time the message was sent in UTC (ISO 8601 format).
* **`SentTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was sent in UTC (RFC 3339 format).
**Example:**
```json
{
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobStatus": "Pending",
"JobNum": "10AB20CE",
"Account": "101202",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"Reference": "MyTest",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"DelayedTimeLocal": "2025-05-29 05:11:03",
"DelayedTimeUTC": "2025-05-29 17:11:03",
"DelayedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand",
"Count": 1,
"Complete": 1,
"Success": 1,
"Failed": 0,
"Price": 0.1,
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Recipients": [
{
"Type": "Fax",
"DestSeq": "00000001",
"Destination": "+6495006000",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Status": "Success",
"Result": "Sent OK",
"SentTimeLocal": "2025-06-13T08:44:16.000Z",
"SentTimeUTC": "2025-06-12T20:44:16.000Z",
"SentTimeUTC_RFC3339": "2025-06-12T20:44:16.000Z",
"Attention": "John Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"Custom5": "",
"Custom6": "",
"Custom7": "",
"Custom8": "",
"Custom9": "",
"RemoteID": "+6495006000",
"Price": 0.1
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Reschedule
- **Method:** `PATCH`
- **Path:** `/fax/{MessageID}/reschedule`
- **Tags:** Fax
This endpoint allows you to reschedule a previously delayed message to be sent at a new time.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Reschedule"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Reschedule"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Abort
- **Method:** `PATCH`
- **Path:** `/fax/{MessageID}/abort`
- **Tags:** Fax
This endpoint allows you to abort a previously delayed message.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Abort"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Abort"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Resubmit
- **Method:** `PATCH`
- **Path:** `/fax/{MessageID}/resubmit`
- **Tags:** Fax
This endpoint allows you to retry sending a previously failed message.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Resubmit"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Resubmit"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Send WhatsApp Message
- **Method:** `POST`
- **Path:** `/whatsapp`
- **Tags:** WhatsApp
Send a WhatsApp message to one or more recipients.
WhatsApp requires the use of a template to initiate contact with users. If the user responds within 24 hours, you may send freeform messages until the 24-hour window closes.
Each API request must include a `TemplateID` and `Message`. The API will dynamically handle the message selection.
#### Request Body
##### Content-Type: application/json
- **`FromNumber` (required)**
`string` — The WhatsApp Business phone number to send from.
- **`Message` (required)**
`string` — The WhatsApp text message to send within the 24-hour conversation window. If omitted, the Template will be used.
- **`TemplateID` (required)**
`string`, format: `uuid` — UUID of the message template to use. Edit a template in the Dashboard to find the Template ID. The \`TemplateID\` takes priority outside a 24-hour conversation window. The \`Message\` is used within the window.
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Destination`**
`string` — A single destination to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
- **`Destinations`**
`array` — An array of one or more contacts to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
**Items:**
- **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
- **`Company`**
`string | null` — The contact's company name (used for personalising the message).
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
- **`Custom2`**
`string | null` — Additional custom variable.
- **`Custom3`**
`string | null` — Additional custom variable.
- **`Custom4`**
`string | null` — Additional custom variable.
- **`EmailAddress`**
`string`, format: `email` — The contact's email address.
- **`First Name`**
`string | null` — The contact's first name (used for personalising the message).
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`Last Name`**
`string | null` — The contact's last name (used for personalising the message).
- **`MainPhone`**
`string`, format: `phone` — The contact's voice telephone number. See \[Telephone Number Formatting]\(https\://www\.tnz.co.nz/help/telephone-number-formatting-for-voice-fax) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`FallbackMode`**
`string`, possible values: `"None", "SMS", "Voice", "RCS"`, default: `"None"` — If WhatsApp delivery fails, try another method (in the order listed).
- **`Files`**
`array` — An array of file attachments.
**Items:**
- **`Data`**
`string`, format: `byte` — The base64-encoded file data. Download a sample PDF: \[base64-encoded-file-data]\(https\://www\.tnz.co.nz/docs/RESTAPI/samples/3.00/base64-Files.txt)
- **`Name`**
`string` — The name of the attached file including the file extension.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`MessageID`**
`string | null` — 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.
- **`Mode`**
`string | null`, default: `null` — Set to \`Test\` to have messages handled immediately as successful without sending a live message. Useful for end-to-end testing. Omit to use standard mode.
- **`NotificationType`**
`string | null`, possible values: `"None", "Webhook", "Email"`, default: `""` — Specifies the notification method for delivery status updates and inbound replies for this message. Omit to use your User's default settings.
- **`Reference`**
`string | null` — A human readable message reference.
- **`SendTime`**
`string`, default: `null` — Delay sending until the specified specified time - {date}T{time} (in the user's 'Local' Timezone). Omit to send immediately.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`WebhookCallbackFormat`**
`string`, possible values: `"JSON", "XML", "POST", "GET"` — The format of the webhook body. Omit to use your User's default settings.
- **`WebhookCallbackURL`**
`string`, format: `uri` — The URL to receive the webhook. A full path including https\:// is required. Omit to use your User's default settings.
**Example:**
```json
{
"TemplateID": "123e4567-e89b-12d3-a456-426614174000",
"Message": "Hello [[Custom1]], view the [[Custom2]] link at [[Link:https://www.example.com/path/to/page.html]] or reply at [[REPLY]]. Reply STOP to OptOut.",
"FallbackMode": "SMS, Voice",
"Files": [
{
"Name": "My Example.pdf",
"Data": "base64-encoded-file-data"
}
],
"FromNumber": "+6495006000",
"Destination": "021-000001",
"ToNumber": "+6421000001",
"Destinations": [
{
"ToNumber": "+6421000001",
"EmailAddress": "john.doe@example.com",
"MainPhone": "+6421000001",
"Attention": "John Doe",
"First Name": "John",
"Last Name": "Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group"
}
],
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"Reference": "MyTest",
"NotificationType": "None",
"WebhookCallbackURL": "https://example.com/webhook",
"WebhookCallbackFormat": "JSON",
"SendTime": "2026-08-29T14:00",
"Timezone": "New Zealand",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"Mode": "Test"
}
```
#### Responses
##### Status: 200 OK \[successful submission]
###### Content-Type: application/json
- **`MessageID`**
`string` — Unique identifier for the API call.
**Example:**
```json
{
"MessageID": "1000000a-f002-4007-b00a-d00000000002"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### WhatsApp Details
- **Method:** `GET`
- **Path:** `/whatsapp/{MessageID}`
- **Tags:** WhatsApp
Poll for details of a sent WhatsApp message.
The primary object details the message as a whole, while the `Recipients` array contains details of each recipient.
Under each recipient, an `SMSReplies` array will detail any received replies.
Timeout your polls after 6 hours with no result.
Limit your polls to 1 per second to avoid rate limits.
Consider the [Send Result Webhook](#tag/sms/webhook/POST/resultwebhook) for efficiency.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
**All of:**
- **`Account`**
`string` — Your account number.
- **`Complete`**
`integer` — Total Destinations that were successfully completed.
- **`Count`**
`integer` — Total Destinations specified in the message.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`DelayedTimeLocal`**
`string` — The time the entry was delayed until, in the local Timezone.
- **`DelayedTimeUTC`**
`string` — The time the entry was delayed until, in UTC.
- **`DelayedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was delayed until, in UTC (RFC3339 format).
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Failed`**
`integer` — Total Destinations that failed to deliver.
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`JobStatus`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
- **`MessageID`**
`string | null` — 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.
- **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
- **`Reference`**
`string | null` — A human readable message reference.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Success`**
`integer` — Total Destinations that were successfully delivered.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
* **`Page`**
`integer`
* **`PageCount`**
`integer`
* **`RecordsPerPage`**
`integer`
* **`TotalRecords`**
`integer`
- **`Recipients`**
`array` — List of recipients for the message.
**Items:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Destination`**
`string` — The destination address (e.g. phone number, email address). Telephone/mobile numbers are supplied in E.164 internationalised format.
- **`DestSeq`**
`string` — The ID of the destination in the list (increments per destination).
- **`Result`**
`string` — The final delivery result. For a list of possible values, see \[WhatsApp]\(https\://www\.tnz.co.nz/help/whatsapp-delivery-result-codes) result codes.
- **`Status`**
`string`, possible values: `"Success", "Failed", "Pending"` — Current status of the message.
- **`Type`**
`string`, possible values: `"WhatsApp", "SMS", "Email", "Voice", "Fax"` — The type of message this data relates to.
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`Company`**
`string | null` — The contact's company name (used for personalising the message).
* **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
* **`Custom2`**
`string | null` — Additional custom variable.
* **`Custom3`**
`string | null` — Additional custom variable.
* **`Custom4`**
`string | null` — Additional custom variable.
* **`Custom5`**
`string | null` — Additional custom variable.
* **`Custom6`**
`string | null` — Additional custom variable.
* **`Custom7`**
`string | null` — Additional custom variable.
* **`Custom8`**
`string | null` — Additional custom variable.
* **`Custom9`**
`string | null` — Additional custom variable.
* **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
* **`RemoteID`**
`string | null` — For Voice, Text-to-Speech and Fax, dialled phone number. This may differ from 'Destination' if failover Alt Phones are used.
* **`SentTimeLocal`**
`string` — Time the message was sent in the users local Timezone (ISO 8601 format).
* **`SentTimeUTC`**
`string` — Time the message was sent in UTC (ISO 8601 format).
* **`SentTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was sent in UTC (RFC 3339 format).
- **`SMSReplies`**
`array` — A list of replies for this recipient.
**Items:**
- **`From`**
`string` — Sender of the SMS in E.164 internationalised format.
- **`MessageText`**
`string | null` — The received message.
- **`ReceivedID`**
`string`, format: `uuid` — A unique identifier (UUID).
- **`ReceivedTimeLocal`**
`string` — Time the message was received in the users local Timezone (ISO 8601 format).
- **`ReceivedTimeUTC`**
`string` — Time the message was received in UTC (ISO 8601 format).
- **`ReceivedTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was received in UTC (RFC 3339 format).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobStatus": "Pending",
"JobNum": "10AB20CE",
"Account": "101202",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"Reference": "MyTest",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"DelayedTimeLocal": "2025-05-29 05:11:03",
"DelayedTimeUTC": "2025-05-29 17:11:03",
"DelayedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand",
"Count": 1,
"Complete": 1,
"Success": 1,
"Failed": 0,
"Price": 0.1,
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Recipients": [
{
"Type": "WhatsApp",
"DestSeq": "00000001",
"Destination": "+64212223333",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Status": "Success",
"Result": "Delivered",
"SentTimeLocal": "2025-06-13T08:44:16.000Z",
"SentTimeUTC": "2025-06-12T20:44:16.000Z",
"SentTimeUTC_RFC3339": "2025-06-12T20:44:16.000Z",
"Attention": "John Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"Custom5": "",
"Custom6": "",
"Custom7": "",
"Custom8": "",
"Custom9": "",
"RemoteID": "+6495006000",
"Price": 0.1,
"SMSReplies": [
{
"ReceivedID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"ReceivedTimeLocal": "2025-09-01T14:02:03.000Z",
"ReceivedTimeUTC": "2025-09-01T02:02:03.000Z",
"ReceivedTimeUTC_RFC3339": "2025-09-01T02:02:03.000Z",
"Timezone": "New Zealand",
"From": "+6421000001",
"MessageText": "This is a received message from a mobile phone."
}
]
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Inbound Messages
- **Method:** `GET`
- **Path:** `/whatsapp/received`
- **Tags:** WhatsApp
Poll for a list of text messages received in a given timeframe. This endpoint applies to SMS, WhatsApp and RCS messages.
You may search based on `timePeriod` (return results from the last *x* minutes) or by `dateFrom` to `dateTo` (return results within the specified timeframe).
If a received message can be matched as a reply, the `MessageID` parameter will contain the outbound message's `MessageID`.
Limit your polls to 1 per second to avoid rate limits.
Consider the [Inbound SMS Webhook](#tag/sms/webhook/POST/inboundsmswebhook) for efficiency.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
**All of:**
- **`Page`**
`integer`
- **`PageCount`**
`integer`
- **`RecordsPerPage`**
`integer`
- **`TotalRecords`**
`integer`
* **`Messages`**
`array` — List of messages found.
**Items:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`From`**
`string` — Sender of the SMS in E.164 internationalised format.
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string`, format: `uuid` — If a reply match has been found, this will be the MessageID parameter supplied when sending your original API call. If you did not supply one, the API generated one for you.
- **`MessageText`**
`string | null` — The received message.
- **`ReceivedID`**
`string`, format: `uuid` — A unique identifier (UUID).
- **`ReceivedTimeLocal`**
`string` — Time the message was received in the users local Timezone (ISO 8601 format).
- **`ReceivedTimeUTC`**
`string` — Time the message was received in UTC (ISO 8601 format).
- **`ReceivedTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was received in UTC (RFC 3339 format).
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`Version`**
`string` — The API version being used.
**Example:**
```json
{
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Messages": [
{
"ReceivedID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"MessageID": "7000000a-f002-4007-b00a-d00000000002",
"JobNum": "10AB20CE",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ReceivedTimeLocal": "2025-09-01T14:02:03.000Z",
"ReceivedTimeUTC": "2025-09-01T02:02:03.000Z",
"ReceivedTimeUTC_RFC3339": "2025-09-01T02:02:03.000Z",
"From": "+6421000001",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"MessageText": "This is a received message from a mobile phone.",
"Timezone": "New Zealand",
"Version": "v3.00"
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Reschedule
- **Method:** `PATCH`
- **Path:** `/whatsapp/{MessageID}/reschedule`
- **Tags:** WhatsApp
This endpoint allows you to reschedule a previously delayed message to be sent at a new time.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Reschedule"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Reschedule"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Abort
- **Method:** `PATCH`
- **Path:** `/whatsapp/{MessageID}/abort`
- **Tags:** WhatsApp
This endpoint allows you to abort a previously delayed message.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Abort"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Abort"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Send RCS Message
- **Method:** `POST`
- **Path:** `/rcs`
- **Tags:** RCS
Send an RCS message to one or more recipients.
#### Request Body
##### Content-Type: application/json
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Destination`**
`string` — A single destination to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
- **`Destinations`**
`array` — An array of one or more contacts to receive the message. You may use any of the \`Destination\` (string), \`ContactID\` (string), \`GroupID\` (string) or \`Destinations\` (array) parameters.
**Items:**
- **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
- **`Company`**
`string | null` — The contact's company name (used for personalising the message).
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
- **`Custom2`**
`string | null` — Additional custom variable.
- **`Custom3`**
`string | null` — Additional custom variable.
- **`Custom4`**
`string | null` — Additional custom variable.
- **`EmailAddress`**
`string`, format: `email` — The contact's email address.
- **`First Name`**
`string | null` — The contact's first name (used for personalising the message).
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`Last Name`**
`string | null` — The contact's last name (used for personalising the message).
- **`MainPhone`**
`string`, format: `phone` — The contact's voice telephone number. See \[Telephone Number Formatting]\(https\://www\.tnz.co.nz/help/telephone-number-formatting-for-voice-fax) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`FallbackMode`**
`string`, possible values: `"None", "SMS", "Voice", "WhatsApp"`, default: `"None"` — If the RCS delivery fails, try another method (in the order listed).
- **`Files`**
`array` — An array of file attachments.
**Items:**
- **`Data`**
`string`, format: `byte` — The base64-encoded file data. Download a sample PDF: \[base64-encoded-file-data]\(https\://www\.tnz.co.nz/docs/RESTAPI/samples/3.00/base64-Files.txt)
- **`Name`**
`string` — The name of the attached file including the file extension.
- **`FromNumber`**
`string` — Sets the Sender ID on your sent message (in E164 format without the leading +).
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
- **`Message`**
`string` — The text message to send. Alternatively, you may use the \`TemplateID\` parameter.
- **`MessageID`**
`string | null` — 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.
- **`Mode`**
`string | null`, default: `null` — Set to \`Test\` to have messages handled immediately as successful without sending a live message. Useful for end-to-end testing. Omit to use standard mode.
- **`NotificationType`**
`string | null`, possible values: `"None", "Webhook", "Email"`, default: `""` — Specifies the notification method for delivery status updates and inbound replies for this message. Omit to use your User's default settings.
- **`Reference`**
`string | null` — A human readable message reference.
- **`SendTime`**
`string`, default: `null` — Delay sending until the specified specified time - {date}T{time} (in the user's 'Local' Timezone). Omit to send immediately.
- **`SMSEmailReply`**
`string`, format: `email` — The email address to send SMS Reply notifications to. This may be ignored if a different Reply Notification rule is configured.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`TemplateID`**
`string`, format: `uuid` — UUID of the message template to use. Edit a template in the Dashboard to find the Template ID. If both \`TemplateID\` and a Message are specified, the message takes priority.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`ToNumber`**
`string`, format: `phone` — The contact's phone number. See \[Mobile Number Formatting]\(https\://www\.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent \[Toll Fraud]\(https\://www\.tnz.co.nz/help/Combatting-SMS-fraud).
- **`WebhookCallbackFormat`**
`string`, possible values: `"JSON", "XML", "POST", "GET"` — The format of the webhook body. Omit to use your User's default settings.
- **`WebhookCallbackURL`**
`string`, format: `uri` — The URL to receive the webhook. A full path including https\:// is required. Omit to use your User's default settings.
**Example:**
```json
{
"Message": "Hello [[FirstName]], view the [[Custom1]] link at [[Link:https://www.example.com/path/to/page.html]] or reply at [[REPLY]]. Reply STOP to OptOut.",
"TemplateID": "123e4567-e89b-12d3-a456-426614174000",
"Destination": "021-000001",
"ToNumber": "+6421000001",
"Destinations": [
{
"ToNumber": "+6421000001",
"EmailAddress": "john.doe@example.com",
"MainPhone": "+6421000001",
"Attention": "John Doe",
"First Name": "John",
"Last Name": "Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group"
}
],
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"Reference": "MyTest",
"NotificationType": "None",
"WebhookCallbackURL": "https://example.com/webhook",
"WebhookCallbackFormat": "JSON",
"SendTime": "2026-08-29T14:00",
"Timezone": "New Zealand",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"FromNumber": "61408080909",
"SMSEmailReply": "reply@example.com",
"Files": [
{
"Name": "My Example.pdf",
"Data": "base64-encoded-file-data"
}
],
"FallbackMode": "Voice",
"Mode": "Test"
}
```
#### Responses
##### Status: 200 OK \[successful submission]
###### Content-Type: application/json
- **`MessageID`**
`string` — Unique identifier for the API call.
**Example:**
```json
{
"MessageID": "1000000a-f002-4007-b00a-d00000000002"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### RCS Details
- **Method:** `GET`
- **Path:** `/rcs/{MessageID}`
- **Tags:** RCS
Poll for details of a sent RCS message.
The primary object details the message as a whole, while the `Recipients` array contains details of each recipient.
Under each recipient, an `SMSReplies` array will detail any received replies.
Timeout your polls after 6 hours with no result.
Limit your polls to 1 per second to avoid rate limits.
Consider the [Send Result Webhook](#tag/sms/webhook/POST/resultwebhook) for efficiency.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
**All of:**
- **`Account`**
`string` — Your account number.
- **`Complete`**
`integer` — Total Destinations that were successfully completed.
- **`Count`**
`integer` — Total Destinations specified in the message.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`DelayedTimeLocal`**
`string` — The time the entry was delayed until, in the local Timezone.
- **`DelayedTimeUTC`**
`string` — The time the entry was delayed until, in UTC.
- **`DelayedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was delayed until, in UTC (RFC3339 format).
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Failed`**
`integer` — Total Destinations that failed to deliver.
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`JobStatus`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
- **`MessageID`**
`string | null` — 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.
- **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
- **`Reference`**
`string | null` — A human readable message reference.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Success`**
`integer` — Total Destinations that were successfully delivered.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
* **`Page`**
`integer`
* **`PageCount`**
`integer`
* **`RecordsPerPage`**
`integer`
* **`TotalRecords`**
`integer`
- **`Recipients`**
`array` — List of recipients for the message.
**Items:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Destination`**
`string` — The destination address (e.g. phone number, email address). Telephone/mobile numbers are supplied in E.164 internationalised format.
- **`DestSeq`**
`string` — The ID of the destination in the list (increments per destination).
- **`Result`**
`string` — The final delivery result. For a list of possible values, see \[WhatsApp]\(https\://www\.tnz.co.nz/help/whatsapp-delivery-result-codes) result codes.
- **`Status`**
`string`, possible values: `"Success", "Failed", "Pending"` — Current status of the message.
- **`Type`**
`string`, possible values: `"RCS", "SMS", "Email", "Voice", "Fax"` — The type of message this data relates to.
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`Company`**
`string | null` — The contact's company name (used for personalising the message).
* **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
* **`Custom2`**
`string | null` — Additional custom variable.
* **`Custom3`**
`string | null` — Additional custom variable.
* **`Custom4`**
`string | null` — Additional custom variable.
* **`Custom5`**
`string | null` — Additional custom variable.
* **`Custom6`**
`string | null` — Additional custom variable.
* **`Custom7`**
`string | null` — Additional custom variable.
* **`Custom8`**
`string | null` — Additional custom variable.
* **`Custom9`**
`string | null` — Additional custom variable.
* **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
* **`RemoteID`**
`string | null` — For Voice, Text-to-Speech and Fax, dialled phone number. This may differ from 'Destination' if failover Alt Phones are used.
* **`SentTimeLocal`**
`string` — Time the message was sent in the users local Timezone (ISO 8601 format).
* **`SentTimeUTC`**
`string` — Time the message was sent in UTC (ISO 8601 format).
* **`SentTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was sent in UTC (RFC 3339 format).
- **`SMSReplies`**
`array` — A list of replies for this recipient.
**Items:**
- **`From`**
`string` — Sender of the SMS in E.164 internationalised format.
- **`MessageText`**
`string | null` — The received message.
- **`ReceivedID`**
`string`, format: `uuid` — A unique identifier (UUID).
- **`ReceivedTimeLocal`**
`string` — Time the message was received in the users local Timezone (ISO 8601 format).
- **`ReceivedTimeUTC`**
`string` — Time the message was received in UTC (ISO 8601 format).
- **`ReceivedTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was received in UTC (RFC 3339 format).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobStatus": "Pending",
"JobNum": "10AB20CE",
"Account": "101202",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"Reference": "MyTest",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"DelayedTimeLocal": "2025-05-29 05:11:03",
"DelayedTimeUTC": "2025-05-29 17:11:03",
"DelayedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand",
"Count": 1,
"Complete": 1,
"Success": 1,
"Failed": 0,
"Price": 0.1,
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Recipients": [
{
"Type": "RCS",
"DestSeq": "00000001",
"Destination": "+64212223333",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Status": "Success",
"Result": "Delivered",
"SentTimeLocal": "2025-06-13T08:44:16.000Z",
"SentTimeUTC": "2025-06-12T20:44:16.000Z",
"SentTimeUTC_RFC3339": "2025-06-12T20:44:16.000Z",
"Attention": "John Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"Custom5": "",
"Custom6": "",
"Custom7": "",
"Custom8": "",
"Custom9": "",
"RemoteID": "+6495006000",
"Price": 0.1,
"SMSReplies": [
{
"ReceivedID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"ReceivedTimeLocal": "2025-09-01T14:02:03.000Z",
"ReceivedTimeUTC": "2025-09-01T02:02:03.000Z",
"ReceivedTimeUTC_RFC3339": "2025-09-01T02:02:03.000Z",
"Timezone": "New Zealand",
"From": "+6421000001",
"MessageText": "This is a received message from a mobile phone."
}
]
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Inbound Messages
- **Method:** `GET`
- **Path:** `/rcs/received`
- **Tags:** RCS
Poll for a list of text messages received in a given timeframe. This endpoint applies to SMS, WhatsApp and RCS messages.
You may search based on `timePeriod` (return results from the last *x* minutes) or by `dateFrom` to `dateTo` (return results within the specified timeframe).
If a received message can be matched as a reply, the `MessageID` parameter will contain the outbound message's `MessageID`.
Limit your polls to 1 per second to avoid rate limits.
Consider the [Inbound SMS Webhook](#tag/sms/webhook/POST/inboundsmswebhook) for efficiency.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
**All of:**
- **`Page`**
`integer`
- **`PageCount`**
`integer`
- **`RecordsPerPage`**
`integer`
- **`TotalRecords`**
`integer`
* **`Messages`**
`array` — List of messages found.
**Items:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`From`**
`string` — Sender of the SMS in E.164 internationalised format.
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string`, format: `uuid` — If a reply match has been found, this will be the MessageID parameter supplied when sending your original API call. If you did not supply one, the API generated one for you.
- **`MessageText`**
`string | null` — The received message.
- **`ReceivedID`**
`string`, format: `uuid` — A unique identifier (UUID).
- **`ReceivedTimeLocal`**
`string` — Time the message was received in the users local Timezone (ISO 8601 format).
- **`ReceivedTimeUTC`**
`string` — Time the message was received in UTC (ISO 8601 format).
- **`ReceivedTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was received in UTC (RFC 3339 format).
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`Version`**
`string` — The API version being used.
**Example:**
```json
{
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Messages": [
{
"ReceivedID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"MessageID": "7000000a-f002-4007-b00a-d00000000002",
"JobNum": "10AB20CE",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ReceivedTimeLocal": "2025-09-01T14:02:03.000Z",
"ReceivedTimeUTC": "2025-09-01T02:02:03.000Z",
"ReceivedTimeUTC_RFC3339": "2025-09-01T02:02:03.000Z",
"From": "+6421000001",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"MessageText": "This is a received message from a mobile phone.",
"Timezone": "New Zealand",
"Version": "v3.00"
}
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Reschedule
- **Method:** `PATCH`
- **Path:** `/rcs/{MessageID}/reschedule`
- **Tags:** RCS
This endpoint allows you to reschedule a previously delayed message to be sent at a new time.
#### Request Body
##### Content-Type: application/json
- **`SendTime` (required)**
`string` — Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
```json
{
"SendTime": "2025-08-12T12:00:00.000Z"
}
```
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Reschedule"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Reschedule"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Abort
- **Method:** `PATCH`
- **Path:** `/rcs/{MessageID}/abort`
- **Tags:** RCS
This endpoint allows you to abort a previously delayed message.
#### Responses
##### Status: 200 OK \[message found]
###### Content-Type: application/json
- **`Action`**
`string`, possible values: `"Abort"` — The action this API call has performed.
- **`ActionResult`**
`string` — Result of the query (\*\*\*not\*\*\* the result of the message).
- **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
- **`MessageID`**
`string | null` — 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.
- **`Status`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
**Example:**
```json
{
"ActionResult": "Success",
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobNum": "10AB20CE",
"Status": "Pending",
"Action": "Abort"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[id is incorrect or still processing]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`MessageID`**
`string` — The MessageID queried.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "RecordNotFound",
"MessageID": "1000000a-f002-4007-b00a-d00000000002",
"ErrorMessage": [
"Unable to find entry."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Contact: Create
- **Method:** `POST`
- **Path:** `/addressbook/contact`
- **Tags:** Address Book
Create a new contact in the address book.
#### Request Body
##### Content-Type: application/json
- **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
- **`AltPhone1`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone2`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone3`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone4`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone5`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone6`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone7`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone8`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
- **`City`**
`string | null` — The contact's city.
- **`Company`**
`string | null` — The contact's company name (used for personalising messages and reporting).
- **`Country`**
`string | null` — The contact's country (no fixed format).
- **`Custom1`**
`string | null` — Custom field (used for personalising messages).
- **`Custom2`**
`string | null` — Custom field (used for personalising messages).
- **`Custom3`**
`string | null` — Custom field (used for personalising messages).
- **`Custom4`**
`string | null` — Custom field (used for personalising messages).
- **`EditBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The edit access rights.
- **`EmailAddress`**
`string`, format: `email` — The contact's email address (used for Email messages).
- **`ExID`**
`string` — An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID).
- **`ExType`**
`string` — An External ID Type can be used to categorise contacts (typically used by another system).
- **`FaxNumber`**
`string`, format: `phone` — The contact's fax number (used for Fax messages).
- **`FirstName`**
`string | null` — The contact's first name (used for personalising messages).
- **`LastName`**
`string | null` — The contact's last name (used for personalising messages).
- **`MainPhone`**
`string`, format: `phone` — The contact's main phone number (used for Voice and TTS calls).
- **`MobilePhone`**
`string`, format: `phone` — The contact's mobile phone number (used for SMS messages).
- **`Notes`**
`string | null` — Freeform notes.
- **`Position`**
`string | null` — The contact's position within their company.
- **`Postcode`**
`string | null` — The contact's postal code (no fixed format)
- **`RecipDepartment`**
`string | null` — The contact's department within their company.
- **`State`**
`string | null` — The contact's state or region.
- **`StreetAddress`**
`string | null` — The contact's street address.
- **`Suburb`**
`string | null` — The contact's suburb.
- **`Title`**
`string | null`, possible values: `"", "Mr", "Mrs", "Ms", "Miss", "Dr", "Prof", "Hon"` — The contact's title (for example, Mr, Ms, Dr).
- **`ViewBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The view access rights.
- **`WebAddress`**
`string`, format: `uri` — The contact's website address.
**Example:**
```json
{
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
```
#### Responses
##### Status: 200 OK \[contact created]
###### Content-Type: application/json
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`AltPhone1`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone2`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone3`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone4`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone5`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone6`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone7`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone8`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`City`**
`string | null` — The contact's city.
* **`Company`**
`string | null` — The contact's company name (used for personalising messages and reporting).
* **`Country`**
`string | null` — The contact's country (no fixed format).
* **`Custom1`**
`string | null` — Custom field (used for personalising messages).
* **`Custom2`**
`string | null` — Custom field (used for personalising messages).
* **`Custom3`**
`string | null` — Custom field (used for personalising messages).
* **`Custom4`**
`string | null` — Custom field (used for personalising messages).
* **`EditBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The edit access rights.
* **`EmailAddress`**
`string`, format: `email` — The contact's email address (used for Email messages).
* **`ExID`**
`string` — An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID).
* **`ExType`**
`string` — An External ID Type can be used to categorise contacts (typically used by another system).
* **`FaxNumber`**
`string`, format: `phone` — The contact's fax number (used for Fax messages).
* **`FirstName`**
`string | null` — The contact's first name (used for personalising messages).
* **`LastName`**
`string | null` — The contact's last name (used for personalising messages).
* **`MainPhone`**
`string`, format: `phone` — The contact's main phone number (used for Voice and TTS calls).
* **`MobilePhone`**
`string`, format: `phone` — The contact's mobile phone number (used for SMS messages).
* **`Notes`**
`string | null` — Freeform notes.
* **`Position`**
`string | null` — The contact's position within their company.
* **`Postcode`**
`string | null` — The contact's postal code (no fixed format)
* **`RecipDepartment`**
`string | null` — The contact's department within their company.
* **`State`**
`string | null` — The contact's state or region.
* **`StreetAddress`**
`string | null` — The contact's street address.
* **`Suburb`**
`string | null` — The contact's suburb.
* **`Title`**
`string | null`, possible values: `"", "Mr", "Mrs", "Ms", "Miss", "Dr", "Prof", "Hon"` — The contact's title (for example, Mr, Ms, Dr).
* **`ViewBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The view access rights.
* **`WebAddress`**
`string`, format: `uri` — The contact's website address.
**Example:**
```json
{
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand",
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Contact: Search
- **Method:** `GET`
- **Path:** `/addressbook/contact/search`
- **Tags:** Address Book
Search for contacts using various criteria. Partial matches are supported for most text fields.
#### Responses
##### Status: 200 OK
###### Content-Type: application/json
**All of:**
- **`Page`**
`integer`
- **`PageCount`**
`integer`
- **`RecordsPerPage`**
`integer`
- **`TotalRecords`**
`integer`
* **`Contacts`**
`array`
**Items:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`AltPhone1`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone2`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone3`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone4`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone5`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone6`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone7`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone8`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`City`**
`string | null` — The contact's city.
* **`Company`**
`string | null` — The contact's company name (used for personalising messages and reporting).
* **`Country`**
`string | null` — The contact's country (no fixed format).
* **`Custom1`**
`string | null` — Custom field (used for personalising messages).
* **`Custom2`**
`string | null` — Custom field (used for personalising messages).
* **`Custom3`**
`string | null` — Custom field (used for personalising messages).
* **`Custom4`**
`string | null` — Custom field (used for personalising messages).
* **`EditBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The edit access rights.
* **`EmailAddress`**
`string`, format: `email` — The contact's email address (used for Email messages).
* **`ExID`**
`string` — An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID).
* **`ExType`**
`string` — An External ID Type can be used to categorise contacts (typically used by another system).
* **`FaxNumber`**
`string`, format: `phone` — The contact's fax number (used for Fax messages).
* **`FirstName`**
`string | null` — The contact's first name (used for personalising messages).
* **`LastName`**
`string | null` — The contact's last name (used for personalising messages).
* **`MainPhone`**
`string`, format: `phone` — The contact's main phone number (used for Voice and TTS calls).
* **`MobilePhone`**
`string`, format: `phone` — The contact's mobile phone number (used for SMS messages).
* **`Notes`**
`string | null` — Freeform notes.
* **`Position`**
`string | null` — The contact's position within their company.
* **`Postcode`**
`string | null` — The contact's postal code (no fixed format)
* **`RecipDepartment`**
`string | null` — The contact's department within their company.
* **`State`**
`string | null` — The contact's state or region.
* **`StreetAddress`**
`string | null` — The contact's street address.
* **`Suburb`**
`string | null` — The contact's suburb.
* **`Title`**
`string | null`, possible values: `"", "Mr", "Mrs", "Ms", "Miss", "Dr", "Prof", "Hon"` — The contact's title (for example, Mr, Ms, Dr).
* **`ViewBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The view access rights.
* **`WebAddress`**
`string`, format: `uri` — The contact's website address.
**Example:**
```json
{
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Contacts": [
{
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand",
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Contact: List
- **Method:** `GET`
- **Path:** `/addressbook/contact/list`
- **Tags:** Address Book
Retrieve a list of all contacts in the address book.
#### Responses
##### Status: 200 OK
###### Content-Type: application/json
**All of:**
- **`Page`**
`integer`
- **`PageCount`**
`integer`
- **`RecordsPerPage`**
`integer`
- **`TotalRecords`**
`integer`
* **`Contacts`**
`array`
**Items:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`AltPhone1`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone2`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone3`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone4`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone5`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone6`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone7`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone8`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`City`**
`string | null` — The contact's city.
* **`Company`**
`string | null` — The contact's company name (used for personalising messages and reporting).
* **`Country`**
`string | null` — The contact's country (no fixed format).
* **`Custom1`**
`string | null` — Custom field (used for personalising messages).
* **`Custom2`**
`string | null` — Custom field (used for personalising messages).
* **`Custom3`**
`string | null` — Custom field (used for personalising messages).
* **`Custom4`**
`string | null` — Custom field (used for personalising messages).
* **`EditBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The edit access rights.
* **`EmailAddress`**
`string`, format: `email` — The contact's email address (used for Email messages).
* **`ExID`**
`string` — An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID).
* **`ExType`**
`string` — An External ID Type can be used to categorise contacts (typically used by another system).
* **`FaxNumber`**
`string`, format: `phone` — The contact's fax number (used for Fax messages).
* **`FirstName`**
`string | null` — The contact's first name (used for personalising messages).
* **`LastName`**
`string | null` — The contact's last name (used for personalising messages).
* **`MainPhone`**
`string`, format: `phone` — The contact's main phone number (used for Voice and TTS calls).
* **`MobilePhone`**
`string`, format: `phone` — The contact's mobile phone number (used for SMS messages).
* **`Notes`**
`string | null` — Freeform notes.
* **`Position`**
`string | null` — The contact's position within their company.
* **`Postcode`**
`string | null` — The contact's postal code (no fixed format)
* **`RecipDepartment`**
`string | null` — The contact's department within their company.
* **`State`**
`string | null` — The contact's state or region.
* **`StreetAddress`**
`string | null` — The contact's street address.
* **`Suburb`**
`string | null` — The contact's suburb.
* **`Title`**
`string | null`, possible values: `"", "Mr", "Mrs", "Ms", "Miss", "Dr", "Prof", "Hon"` — The contact's title (for example, Mr, Ms, Dr).
* **`ViewBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The view access rights.
* **`WebAddress`**
`string`, format: `uri` — The contact's website address.
**Example:**
```json
{
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Contacts": [
{
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand",
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Contact: List Groups
- **Method:** `GET`
- **Path:** `/addressbook/contact/{ContactID}/group/list`
- **Tags:** Address Book
Retrieve a list of groups that a specific contact belongs to.
#### Responses
##### Status: 200 OK
###### Content-Type: application/json
**All of:**
- **`Page`**
`integer`
- **`PageCount`**
`integer`
- **`RecordsPerPage`**
`integer`
- **`TotalRecords`**
`integer`
* **`Contact`**
`object`
* **`Groups`**
`array`
**Items:**
**All of:**
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`GroupName`**
`string` — The human-readable name of the Group.
* **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`ViewEditBy`**
`object`, possible values: `"Account", "SubAccount", "Department", "No"` — The view and edit access rights.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Contact": {
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand",
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
},
"Groups": [
{
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group",
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand"
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Contact: Details
- **Method:** `GET`
- **Path:** `/addressbook/contact/{ContactID}`
- **Tags:** Address Book
Retrieve the details of a specific contact by their ContactID.
#### Responses
##### Status: 200 OK
###### Content-Type: application/json
**All of:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`AltPhone1`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone2`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone3`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone4`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone5`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone6`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone7`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone8`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`City`**
`string | null` — The contact's city.
* **`Company`**
`string | null` — The contact's company name (used for personalising messages and reporting).
* **`Country`**
`string | null` — The contact's country (no fixed format).
* **`Custom1`**
`string | null` — Custom field (used for personalising messages).
* **`Custom2`**
`string | null` — Custom field (used for personalising messages).
* **`Custom3`**
`string | null` — Custom field (used for personalising messages).
* **`Custom4`**
`string | null` — Custom field (used for personalising messages).
* **`EditBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The edit access rights.
* **`EmailAddress`**
`string`, format: `email` — The contact's email address (used for Email messages).
* **`ExID`**
`string` — An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID).
* **`ExType`**
`string` — An External ID Type can be used to categorise contacts (typically used by another system).
* **`FaxNumber`**
`string`, format: `phone` — The contact's fax number (used for Fax messages).
* **`FirstName`**
`string | null` — The contact's first name (used for personalising messages).
* **`LastName`**
`string | null` — The contact's last name (used for personalising messages).
* **`MainPhone`**
`string`, format: `phone` — The contact's main phone number (used for Voice and TTS calls).
* **`MobilePhone`**
`string`, format: `phone` — The contact's mobile phone number (used for SMS messages).
* **`Notes`**
`string | null` — Freeform notes.
* **`Position`**
`string | null` — The contact's position within their company.
* **`Postcode`**
`string | null` — The contact's postal code (no fixed format)
* **`RecipDepartment`**
`string | null` — The contact's department within their company.
* **`State`**
`string | null` — The contact's state or region.
* **`StreetAddress`**
`string | null` — The contact's street address.
* **`Suburb`**
`string | null` — The contact's suburb.
* **`Title`**
`string | null`, possible values: `"", "Mr", "Mrs", "Ms", "Miss", "Dr", "Prof", "Hon"` — The contact's title (for example, Mr, Ms, Dr).
* **`ViewBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The view access rights.
* **`WebAddress`**
`string`, format: `uri` — The contact's website address.
- **`Groups`**
`array`
**Items:**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
**Example:**
```json
{
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand",
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API.",
"Groups": [
"223e4567-e89b-12d3-a456-426614175000"
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Contact: Update
- **Method:** `PATCH`
- **Path:** `/addressbook/contact/{ContactID}`
- **Tags:** Address Book
Update the details of an existing contact.
#### Request Body
##### Content-Type: application/json
- **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
- **`AltPhone1`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone2`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone3`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone4`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone5`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone6`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone7`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`AltPhone8`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
- **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
- **`City`**
`string | null` — The contact's city.
- **`Company`**
`string | null` — The contact's company name (used for personalising messages and reporting).
- **`Country`**
`string | null` — The contact's country (no fixed format).
- **`Custom1`**
`string | null` — Custom field (used for personalising messages).
- **`Custom2`**
`string | null` — Custom field (used for personalising messages).
- **`Custom3`**
`string | null` — Custom field (used for personalising messages).
- **`Custom4`**
`string | null` — Custom field (used for personalising messages).
- **`EditBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The edit access rights.
- **`EmailAddress`**
`string`, format: `email` — The contact's email address (used for Email messages).
- **`ExID`**
`string` — An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID).
- **`ExType`**
`string` — An External ID Type can be used to categorise contacts (typically used by another system).
- **`FaxNumber`**
`string`, format: `phone` — The contact's fax number (used for Fax messages).
- **`FirstName`**
`string | null` — The contact's first name (used for personalising messages).
- **`LastName`**
`string | null` — The contact's last name (used for personalising messages).
- **`MainPhone`**
`string`, format: `phone` — The contact's main phone number (used for Voice and TTS calls).
- **`MobilePhone`**
`string`, format: `phone` — The contact's mobile phone number (used for SMS messages).
- **`Notes`**
`string | null` — Freeform notes.
- **`Position`**
`string | null` — The contact's position within their company.
- **`Postcode`**
`string | null` — The contact's postal code (no fixed format)
- **`RecipDepartment`**
`string | null` — The contact's department within their company.
- **`State`**
`string | null` — The contact's state or region.
- **`StreetAddress`**
`string | null` — The contact's street address.
- **`Suburb`**
`string | null` — The contact's suburb.
- **`Title`**
`string | null`, possible values: `"", "Mr", "Mrs", "Ms", "Miss", "Dr", "Prof", "Hon"` — The contact's title (for example, Mr, Ms, Dr).
- **`ViewBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The view access rights.
- **`WebAddress`**
`string`, format: `uri` — The contact's website address.
**Example:**
```json
{
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
```
#### Responses
##### Status: 200 OK \[contact updated]
###### Content-Type: application/json
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`AltPhone1`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone2`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone3`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone4`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone5`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone6`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone7`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone8`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`City`**
`string | null` — The contact's city.
* **`Company`**
`string | null` — The contact's company name (used for personalising messages and reporting).
* **`Country`**
`string | null` — The contact's country (no fixed format).
* **`Custom1`**
`string | null` — Custom field (used for personalising messages).
* **`Custom2`**
`string | null` — Custom field (used for personalising messages).
* **`Custom3`**
`string | null` — Custom field (used for personalising messages).
* **`Custom4`**
`string | null` — Custom field (used for personalising messages).
* **`EditBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The edit access rights.
* **`EmailAddress`**
`string`, format: `email` — The contact's email address (used for Email messages).
* **`ExID`**
`string` — An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID).
* **`ExType`**
`string` — An External ID Type can be used to categorise contacts (typically used by another system).
* **`FaxNumber`**
`string`, format: `phone` — The contact's fax number (used for Fax messages).
* **`FirstName`**
`string | null` — The contact's first name (used for personalising messages).
* **`LastName`**
`string | null` — The contact's last name (used for personalising messages).
* **`MainPhone`**
`string`, format: `phone` — The contact's main phone number (used for Voice and TTS calls).
* **`MobilePhone`**
`string`, format: `phone` — The contact's mobile phone number (used for SMS messages).
* **`Notes`**
`string | null` — Freeform notes.
* **`Position`**
`string | null` — The contact's position within their company.
* **`Postcode`**
`string | null` — The contact's postal code (no fixed format)
* **`RecipDepartment`**
`string | null` — The contact's department within their company.
* **`State`**
`string | null` — The contact's state or region.
* **`StreetAddress`**
`string | null` — The contact's street address.
* **`Suburb`**
`string | null` — The contact's suburb.
* **`Title`**
`string | null`, possible values: `"", "Mr", "Mrs", "Ms", "Miss", "Dr", "Prof", "Hon"` — The contact's title (for example, Mr, Ms, Dr).
* **`ViewBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The view access rights.
* **`WebAddress`**
`string`, format: `uri` — The contact's website address.
**Example:**
```json
{
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand",
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Contact: Delete
- **Method:** `DELETE`
- **Path:** `/addressbook/contact/{ContactID}`
- **Tags:** Address Book
Delete a contact from the address book.
#### Responses
##### Status: 200 OK \[contact deleted]
###### Content-Type: application/json
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`AltPhone1`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone2`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone3`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone4`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone5`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone6`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone7`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone8`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`City`**
`string | null` — The contact's city.
* **`Company`**
`string | null` — The contact's company name (used for personalising messages and reporting).
* **`Country`**
`string | null` — The contact's country (no fixed format).
* **`Custom1`**
`string | null` — Custom field (used for personalising messages).
* **`Custom2`**
`string | null` — Custom field (used for personalising messages).
* **`Custom3`**
`string | null` — Custom field (used for personalising messages).
* **`Custom4`**
`string | null` — Custom field (used for personalising messages).
* **`EditBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The edit access rights.
* **`EmailAddress`**
`string`, format: `email` — The contact's email address (used for Email messages).
* **`ExID`**
`string` — An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID).
* **`ExType`**
`string` — An External ID Type can be used to categorise contacts (typically used by another system).
* **`FaxNumber`**
`string`, format: `phone` — The contact's fax number (used for Fax messages).
* **`FirstName`**
`string | null` — The contact's first name (used for personalising messages).
* **`LastName`**
`string | null` — The contact's last name (used for personalising messages).
* **`MainPhone`**
`string`, format: `phone` — The contact's main phone number (used for Voice and TTS calls).
* **`MobilePhone`**
`string`, format: `phone` — The contact's mobile phone number (used for SMS messages).
* **`Notes`**
`string | null` — Freeform notes.
* **`Position`**
`string | null` — The contact's position within their company.
* **`Postcode`**
`string | null` — The contact's postal code (no fixed format)
* **`RecipDepartment`**
`string | null` — The contact's department within their company.
* **`State`**
`string | null` — The contact's state or region.
* **`StreetAddress`**
`string | null` — The contact's street address.
* **`Suburb`**
`string | null` — The contact's suburb.
* **`Title`**
`string | null`, possible values: `"", "Mr", "Mrs", "Ms", "Miss", "Dr", "Prof", "Hon"` — The contact's title (for example, Mr, Ms, Dr).
* **`ViewBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The view access rights.
* **`WebAddress`**
`string`, format: `uri` — The contact's website address.
**Example:**
```json
{
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand",
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Group: Create
- **Method:** `POST`
- **Path:** `/addressbook/group`
- **Tags:** Address Book
Create a new group in the address book.
#### Request Body
##### Content-Type: application/json
- **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`GroupName`**
`string` — The human-readable name of the Group.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`ViewEditBy`**
`object`, possible values: `"Account", "SubAccount", "Department", "No"` — The view and edit access rights.
**Example:**
```json
{
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited"
}
```
#### Responses
##### Status: 200 OK \[group created]
###### Content-Type: application/json
**All of:**
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`GroupName`**
`string` — The human-readable name of the Group.
* **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`ViewEditBy`**
`object`, possible values: `"Account", "SubAccount", "Department", "No"` — The view and edit access rights.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group",
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Group: List
- **Method:** `GET`
- **Path:** `/addressbook/group/list`
- **Tags:** Address Book
Retrieve a list of all groups in the address book.
#### Responses
##### Status: 200 OK
###### Content-Type: application/json
**All of:**
- **`Page`**
`integer`
- **`PageCount`**
`integer`
- **`RecordsPerPage`**
`integer`
- **`TotalRecords`**
`integer`
* **`Groups`**
`array`
**Items:**
**All of:**
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`GroupName`**
`string` — The human-readable name of the Group.
* **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`ViewEditBy`**
`object`, possible values: `"Account", "SubAccount", "Department", "No"` — The view and edit access rights.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Groups": [
{
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group",
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand"
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Group: List Contacts
- **Method:** `GET`
- **Path:** `/addressbook/group/{GroupID}/contact/list`
- **Tags:** Address Book
Retrieve a list of contacts that belong to a specific group.
#### Responses
##### Status: 200 OK
###### Content-Type: application/json
**All of:**
- **`Page`**
`integer`
- **`PageCount`**
`integer`
- **`RecordsPerPage`**
`integer`
- **`TotalRecords`**
`integer`
* **`Contacts`**
`array`
**Items:**
**All of:**
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`AltPhone1`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone2`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone3`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone4`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone5`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone6`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone7`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone8`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`City`**
`string | null` — The contact's city.
* **`Company`**
`string | null` — The contact's company name (used for personalising messages and reporting).
* **`Country`**
`string | null` — The contact's country (no fixed format).
* **`Custom1`**
`string | null` — Custom field (used for personalising messages).
* **`Custom2`**
`string | null` — Custom field (used for personalising messages).
* **`Custom3`**
`string | null` — Custom field (used for personalising messages).
* **`Custom4`**
`string | null` — Custom field (used for personalising messages).
* **`EditBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The edit access rights.
* **`EmailAddress`**
`string`, format: `email` — The contact's email address (used for Email messages).
* **`ExID`**
`string` — An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID).
* **`ExType`**
`string` — An External ID Type can be used to categorise contacts (typically used by another system).
* **`FaxNumber`**
`string`, format: `phone` — The contact's fax number (used for Fax messages).
* **`FirstName`**
`string | null` — The contact's first name (used for personalising messages).
* **`LastName`**
`string | null` — The contact's last name (used for personalising messages).
* **`MainPhone`**
`string`, format: `phone` — The contact's main phone number (used for Voice and TTS calls).
* **`MobilePhone`**
`string`, format: `phone` — The contact's mobile phone number (used for SMS messages).
* **`Notes`**
`string | null` — Freeform notes.
* **`Position`**
`string | null` — The contact's position within their company.
* **`Postcode`**
`string | null` — The contact's postal code (no fixed format)
* **`RecipDepartment`**
`string | null` — The contact's department within their company.
* **`State`**
`string | null` — The contact's state or region.
* **`StreetAddress`**
`string | null` — The contact's street address.
* **`Suburb`**
`string | null` — The contact's suburb.
* **`Title`**
`string | null`, possible values: `"", "Mr", "Mrs", "Ms", "Miss", "Dr", "Prof", "Hon"` — The contact's title (for example, Mr, Ms, Dr).
* **`ViewBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The view access rights.
* **`WebAddress`**
`string`, format: `uri` — The contact's website address.
* **`Group`**
`object`
**Example:**
```json
{
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"Group": {
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group",
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand"
},
"Contacts": [
{
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand",
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
]
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Group: Details
- **Method:** `GET`
- **Path:** `/addressbook/group/{GroupID}`
- **Tags:** Address Book
Retrieve the details of a specific group by its GroupID.
#### Responses
##### Status: 200 OK
###### Content-Type: application/json
**All of:**
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`GroupName`**
`string` — The human-readable name of the Group.
* **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`ViewEditBy`**
`object`, possible values: `"Account", "SubAccount", "Department", "No"` — The view and edit access rights.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group",
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Group: Update
- **Method:** `PATCH`
- **Path:** `/addressbook/group/{GroupID}`
- **Tags:** Address Book
Update the details of an existing group.
#### Request Body
##### Content-Type: application/json
- **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
- **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`GroupName`**
`string` — The human-readable name of the Group.
- **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
- **`ViewEditBy`**
`object`, possible values: `"Account", "SubAccount", "Department", "No"` — The view and edit access rights.
**Example:**
```json
{
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited"
}
```
#### Responses
##### Status: 200 OK \[group updated]
###### Content-Type: application/json
**All of:**
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`GroupName`**
`string` — The human-readable name of the Group.
* **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`ViewEditBy`**
`object`, possible values: `"Account", "SubAccount", "Department", "No"` — The view and edit access rights.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group",
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Group: Delete
- **Method:** `DELETE`
- **Path:** `/addressbook/group/{GroupID}`
- **Tags:** Address Book
Delete a group from the address book.
#### Responses
##### Status: 200 OK \[group deleted]
###### Content-Type: application/json
**All of:**
- **`GroupCode`**
`string` — Human-readable unique identifier for the Address Book Group.
- **`GroupID`**
`string`, format: `uuid` — Unique group identifier that corresponds to an Address Book Group.
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`GroupName`**
`string` — The human-readable name of the Group.
* **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`ViewEditBy`**
`object`, possible values: `"Account", "SubAccount", "Department", "No"` — The view and edit access rights.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`Owner`**
`string` — The owner of the contact (typically the user who created it).
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group",
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Contact: Add to Group
- **Method:** `PATCH`
- **Path:** `/addressbook/contact/{ContactID}/group`
- **Tags:** Address Book
Add an existing contact to an existing group (add an association).
#### Request Body
##### Content-Type: application/json
- **`GroupID`**
`object` — Unique identifier for the Address Book Group.
**Example:**
```json
{
"GroupID": null
}
```
#### Responses
##### Status: 200 OK \[contact added to group]
###### Content-Type: application/json
- **`Contact`**
`object`
- **`Group`**
`object`
**Example:**
```json
{
"Group": {
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group",
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand"
},
"Contact": {
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand",
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Contact: Remove from Group
- **Method:** `DELETE`
- **Path:** `/addressbook/contact/{ContactID}/group/{GroupID}`
- **Tags:** Address Book
Remove an existing contact from an existing group (remove/delete an association).
#### Responses
##### Status: 200 OK \[contact removed from group]
###### Content-Type: application/json
- **`Contact`**
`object`
- **`Group`**
`object`
**Example:**
```json
{
"Group": {
"GroupID": "223e4567-e89b-12d3-a456-426614175000",
"GroupCode": "My_Test_Group",
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand"
},
"Contact": {
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"Owner": "COM\\DOMAIN\\APPLICATION",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand",
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 403 Forbidden \[access to this endpoint is disabled]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Access must be enabled for this API User in the Dashboard.
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Unauthorized access to Addressbook API!"
]
}
```
##### Status: 404 Not Found \[record not found]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
- **`Result`**
`string`
**Example:**
```json
{
"Result": "RecordNotFound",
"ErrorMessage": [
"Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### List OptOuts
- **Method:** `GET`
- **Path:** `/optout/list`
- **Tags:** OptOut
List all opt-out entries.
Limit your polls to 1 per second to avoid rate limits.
#### Responses
##### Status: 200 OK
###### Content-Type: application/json
**All of:**
- **`Page`**
`integer`
- **`PageCount`**
`integer`
- **`RecordsPerPage`**
`integer`
- **`TotalRecords`**
`integer`
* **`OptOuts`**
`array` — List of opt-out entries found.
**Items:**
**All of:**
- **`ID`**
`string`, format: `uuid` — A unique identifier (UUID).
* **`DestType` (required)**
`string` — The message type the entry applies to ('SMS', 'Email', 'Voice', 'Fax'). You may only specify one. For multi-channel opt-outs, see \`Create OptOuts (Batch)\`.
* **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
* **`Department`**
`string | null` — The Department the opt-out entry applies to. An empty value applies to all Departments.
* **`Destination`**
`string` — The destination opted-out. Telephone numbers are in E.164 format. You may use \`Destination\` or \`ContactID\` (not both).
* **`Notes`**
`string | null` — Free form notes.
* **`StopMessage`**
`string | null` — The Opt-Out message detected.
* **`SubAccount`**
`string | null` — The SubAccount the opt-out entry applies to. An empty value applies to all SubAccounts.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`OriginalMessage`**
`string` — The original message that triggered the opt-out.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
**Example:**
```json
{
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1,
"OptOuts": [
{
"ID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"DestType": "SMS",
"Destination": "+6421003004",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"SubAccount": "Business Unit One",
"Department": "Team Alpha",
"StopMessage": "Stop sending me these messages",
"Notes": "Entry edited using the API.",
"OriginalMessage": "Hello John, thanks for being a valued customer. Here's a free discount code for your next purchase - 10OFF. From My Company Ltd. Reply STOP to OptOut.",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand"
}
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### OptOut: Create
- **Method:** `POST`
- **Path:** `/optout`
- **Tags:** OptOut
Create a new entry in the OptOut List.
#### Request Body
##### Content-Type: application/json
- **`DestType` (required)**
`string` — The message type the entry applies to ('SMS', 'Email', 'Voice', 'Fax'). You may only specify one. For multi-channel opt-outs, see \`Create OptOuts (Batch)\`.
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The Department the opt-out entry applies to. An empty value applies to all Departments.
- **`Destination`**
`string` — The destination opted-out. Telephone numbers are in E.164 format. You may use \`Destination\` or \`ContactID\` (not both).
- **`Notes`**
`string | null` — Free form notes.
- **`StopMessage`**
`string | null` — The Opt-Out message detected.
- **`SubAccount`**
`string | null` — The SubAccount the opt-out entry applies to. An empty value applies to all SubAccounts.
**Example:**
```json
{
"DestType": "SMS",
"Destination": "+6421003004",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"SubAccount": "Business Unit One",
"Department": "Team Alpha",
"StopMessage": "Stop sending me these messages",
"Notes": "Entry edited using the API."
}
```
#### Responses
##### Status: 200 OK \[entry created]
###### Content-Type: application/json
**All of:**
- **`ID`**
`string`, format: `uuid` — A unique identifier (UUID).
* **`DestType` (required)**
`string` — The message type the entry applies to ('SMS', 'Email', 'Voice', 'Fax'). You may only specify one. For multi-channel opt-outs, see \`Create OptOuts (Batch)\`.
* **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
* **`Department`**
`string | null` — The Department the opt-out entry applies to. An empty value applies to all Departments.
* **`Destination`**
`string` — The destination opted-out. Telephone numbers are in E.164 format. You may use \`Destination\` or \`ContactID\` (not both).
* **`Notes`**
`string | null` — Free form notes.
* **`StopMessage`**
`string | null` — The Opt-Out message detected.
* **`SubAccount`**
`string | null` — The SubAccount the opt-out entry applies to. An empty value applies to all SubAccounts.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`OriginalMessage`**
`string` — The original message that triggered the opt-out.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
**Example:**
```json
{
"ID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"DestType": "SMS",
"Destination": "+6421003004",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"SubAccount": "Business Unit One",
"Department": "Team Alpha",
"StopMessage": "Stop sending me these messages",
"Notes": "Entry edited using the API.",
"OriginalMessage": "Hello John, thanks for being a valued customer. Here's a free discount code for your next purchase - 10OFF. From My Company Ltd. Reply STOP to OptOut.",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Create OptOuts (Batch)
- **Method:** `POST`
- **Path:** `/optout/batch`
- **Tags:** OptOut
Create multiple entries in the OptOut List.
You may list multiple `DestType` values, for example: "SMS, Email"
You may list `Destination`, `Destinations`, `ContactID` and `ContactIDs` in a single request.
#### Request Body
##### Content-Type: application/json
- **`DestType` (required)**
`string` — The type of message to block in this OptOut request ('SMS', 'Email', 'Voice', 'Fax'). You may specify multiple types, comma delimited.
- **`ContactID`**
`string` — A single Contact ID from your Address Book to be opted-out.
- **`ContactIDs`**
`array` — An array of ContactIDs to be opted-out.
**Items:**
`string` — An array of Contact IDs.
- **`Department`**
`string`, default: `""` — The Department the opt-out entry should apply to. Omit to apply the entry to all Departments.
- **`Destination`**
`string` — A single destination to be opted-out. Telephone numbers must be in E.164 format.
- **`Destinations`**
`array` — An array of destinations to be opted-out. Telephone numbers must be in E.164 format.
**Items:**
`string` — An array of contact numbers and emails.
- **`SubAccount`**
`string`, default: `""` — The SubAccount the opt-out entry should apply to. Omit to apply the entry to all SubAccounts.
**Example:**
```json
{
"DestType": "SMS",
"Destination": "+6421003004",
"Destinations": [
"+6421003004"
],
"ContactID": "6000000b-f002-4007-b00a-c00000000001",
"ContactIDs": [
"6000000b-f002-4007-b00a-c00000000001"
],
"SubAccount": "Business Unit One",
"Department": "Team Alpha"
}
```
#### Responses
##### Status: 200 OK \[entry created]
###### Content-Type: application/json
**All of:**
- **`ID`**
`string`, format: `uuid` — A unique identifier (UUID).
* **`DestType` (required)**
`string` — The message type the entry applies to ('SMS', 'Email', 'Voice', 'Fax'). You may only specify one. For multi-channel opt-outs, see \`Create OptOuts (Batch)\`.
* **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
* **`Department`**
`string | null` — The Department the opt-out entry applies to. An empty value applies to all Departments.
* **`Destination`**
`string` — The destination opted-out. Telephone numbers are in E.164 format. You may use \`Destination\` or \`ContactID\` (not both).
* **`Notes`**
`string | null` — Free form notes.
* **`StopMessage`**
`string | null` — The Opt-Out message detected.
* **`SubAccount`**
`string | null` — The SubAccount the opt-out entry applies to. An empty value applies to all SubAccounts.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`OriginalMessage`**
`string` — The original message that triggered the opt-out.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
**Example:**
```json
{
"ID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"DestType": "SMS",
"Destination": "+6421003004",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"SubAccount": "Business Unit One",
"Department": "Team Alpha",
"StopMessage": "Stop sending me these messages",
"Notes": "Entry edited using the API.",
"OriginalMessage": "Hello John, thanks for being a valued customer. Here's a free discount code for your next purchase - 10OFF. From My Company Ltd. Reply STOP to OptOut.",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### OptOut: Details
- **Method:** `GET`
- **Path:** `/optout/{OptOutID}`
- **Tags:** OptOut
Retrieve the details of a specific opt-out entry by its ID.
#### Responses
##### Status: 200 OK
###### Content-Type: application/json
**All of:**
- **`ID`**
`string`, format: `uuid` — A unique identifier (UUID).
* **`DestType` (required)**
`string` — The message type the entry applies to ('SMS', 'Email', 'Voice', 'Fax'). You may only specify one. For multi-channel opt-outs, see \`Create OptOuts (Batch)\`.
* **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
* **`Department`**
`string | null` — The Department the opt-out entry applies to. An empty value applies to all Departments.
* **`Destination`**
`string` — The destination opted-out. Telephone numbers are in E.164 format. You may use \`Destination\` or \`ContactID\` (not both).
* **`Notes`**
`string | null` — Free form notes.
* **`StopMessage`**
`string | null` — The Opt-Out message detected.
* **`SubAccount`**
`string | null` — The SubAccount the opt-out entry applies to. An empty value applies to all SubAccounts.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`OriginalMessage`**
`string` — The original message that triggered the opt-out.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
**Example:**
```json
{
"ID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"DestType": "SMS",
"Destination": "+6421003004",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"SubAccount": "Business Unit One",
"Department": "Team Alpha",
"StopMessage": "Stop sending me these messages",
"Notes": "Entry edited using the API.",
"OriginalMessage": "Hello John, thanks for being a valued customer. Here's a free discount code for your next purchase - 10OFF. From My Company Ltd. Reply STOP to OptOut.",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[invalid ID or resource not yet processed]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
**Example:**
```json
{
"ErrorMessage": [
"Unable to find or access the data you're looking for."
]
}
```
### Update OptOut
- **Method:** `PATCH`
- **Path:** `/optout/{OptOutID}`
- **Tags:** OptOut
Edit an existing OptOut entry.
#### Request Body
##### Content-Type: application/json
- **`DestType` (required)**
`string` — The message type the entry applies to ('SMS', 'Email', 'Voice', 'Fax'). You may only specify one. For multi-channel opt-outs, see \`Create OptOuts (Batch)\`.
- **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
- **`Department`**
`string | null` — The Department the opt-out entry applies to. An empty value applies to all Departments.
- **`Destination`**
`string` — The destination opted-out. Telephone numbers are in E.164 format. You may use \`Destination\` or \`ContactID\` (not both).
- **`Notes`**
`string | null` — Free form notes.
- **`StopMessage`**
`string | null` — The Opt-Out message detected.
- **`SubAccount`**
`string | null` — The SubAccount the opt-out entry applies to. An empty value applies to all SubAccounts.
**Example:**
```json
{
"DestType": "SMS",
"Destination": "+6421003004",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"SubAccount": "Business Unit One",
"Department": "Team Alpha",
"StopMessage": "Stop sending me these messages",
"Notes": "Entry edited using the API."
}
```
#### Responses
##### Status: 200 Entry updated.
###### Content-Type: application/json
**All of:**
- **`ID`**
`string`, format: `uuid` — A unique identifier (UUID).
* **`DestType` (required)**
`string` — The message type the entry applies to ('SMS', 'Email', 'Voice', 'Fax'). You may only specify one. For multi-channel opt-outs, see \`Create OptOuts (Batch)\`.
* **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
* **`Department`**
`string | null` — The Department the opt-out entry applies to. An empty value applies to all Departments.
* **`Destination`**
`string` — The destination opted-out. Telephone numbers are in E.164 format. You may use \`Destination\` or \`ContactID\` (not both).
* **`Notes`**
`string | null` — Free form notes.
* **`StopMessage`**
`string | null` — The Opt-Out message detected.
* **`SubAccount`**
`string | null` — The SubAccount the opt-out entry applies to. An empty value applies to all SubAccounts.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`OriginalMessage`**
`string` — The original message that triggered the opt-out.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
**Example:**
```json
{
"ID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"DestType": "SMS",
"Destination": "+6421003004",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"SubAccount": "Business Unit One",
"Department": "Team Alpha",
"StopMessage": "Stop sending me these messages",
"Notes": "Entry edited using the API.",
"OriginalMessage": "Hello John, thanks for being a valued customer. Here's a free discount code for your next purchase - 10OFF. From My Company Ltd. Reply STOP to OptOut.",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[invalid ID or resource not yet processed]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
**Example:**
```json
{
"ErrorMessage": [
"Unable to find or access the data you're looking for."
]
}
```
##### Status: 415 Unsupported Media Type \[the content-type header is incorrect]
###### Content-Type: application/json
- **`extend1`**
`string` — An error indicator.
- **`extend2`**
`string` — An error indicator.
- **`status`**
`integer` — The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid).
**Example:**
```json
{
"status": 415,
"extend1": "info1",
"extend2": "info2"
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
### Delete OptOut
- **Method:** `DELETE`
- **Path:** `/optout/{OptOutID}`
- **Tags:** OptOut
Delete an existing OptOut entry.
#### Responses
##### Status: 200 OK \[entry deleted]
###### Content-Type: application/json
**All of:**
- **`ID`**
`string`, format: `uuid` — A unique identifier (UUID).
* **`DestType` (required)**
`string` — The message type the entry applies to ('SMS', 'Email', 'Voice', 'Fax'). You may only specify one. For multi-channel opt-outs, see \`Create OptOuts (Batch)\`.
* **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
* **`Department`**
`string | null` — The Department the opt-out entry applies to. An empty value applies to all Departments.
* **`Destination`**
`string` — The destination opted-out. Telephone numbers are in E.164 format. You may use \`Destination\` or \`ContactID\` (not both).
* **`Notes`**
`string | null` — Free form notes.
* **`StopMessage`**
`string | null` — The Opt-Out message detected.
* **`SubAccount`**
`string | null` — The SubAccount the opt-out entry applies to. An empty value applies to all SubAccounts.
- **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
- **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
- **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
- **`OriginalMessage`**
`string` — The original message that triggered the opt-out.
- **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
- **`UpdatedTimeLocal`**
`string` — The time the entry was last updated, in the local Timezone.
- **`UpdatedTimeUTC`**
`string` — The time the entry was last updated, in UTC.
- **`UpdatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was last updated, in UTC (RFC3339 format).
**Example:**
```json
{
"ID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"DestType": "SMS",
"Destination": "+6421003004",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"SubAccount": "Business Unit One",
"Department": "Team Alpha",
"StopMessage": "Stop sending me these messages",
"Notes": "Entry edited using the API.",
"OriginalMessage": "Hello John, thanks for being a valued customer. Here's a free discount code for your next purchase - 10OFF. From My Company Ltd. Reply STOP to OptOut.",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"UpdatedTimeLocal": "0001-01-01 12:00:00",
"UpdatedTimeUTC": "0001-01-01 00:00:00",
"UpdatedTimeUTC_RFC3339": "0001-01-01T00:00:00.000Z",
"Timezone": "New Zealand"
}
```
##### Status: 400 Bad Request \[data incorrect]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"Missing or empty field"
]
}
```
##### Status: 401 Unauthorized \[auth token is invalid]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — A detailed description of the error.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Unauthorized",
"ErrorMessage": "[Access denied: Auth Token or credentials are incorrect or have expired.]"
}
```
##### Status: 404 Not Found \[invalid ID or resource not yet processed]
###### Content-Type: application/json
- **`ErrorMessage`**
`array`
**Items:**
`string`
**Example:**
```json
{
"ErrorMessage": [
"Unable to find or access the data you're looking for."
]
}
```
##### Status: 500 Server Error \[contact us]
###### Content-Type: application/json
- **`ErrorMessage`**
`array` — Your data contains errors.
- **`Result`**
`string` — Result of the API call.
**Example:**
```json
{
"Result": "Failed",
"ErrorMessage": [
"An unexpected error occurred while processing."
]
}
```
## Webhooks
### Webhook - Send Result
- **Method:**`POST`
- **Path:**`/webhooks/ResultWebhook`
- **Tags:** SMS, Email, Voice, TTS, Fax, Webhooks
This webhook is sent to your server when a message completes sending. It contains detailed information about the delivery Status, Result, and other metadata.
To set up this webhook, configure your Sender settings in the TNZ Dashboard (Users > API > Reporting).
### Webhook - Inbound SMS
- **Method:**`POST`
- **Path:**`/webhooks/InboundSMSWebhook`
- **Tags:** SMS, Webhooks
This webhook is sent to your server when an Inbound SMS message is received.
The MessageID parameter refers to a matched outbound message (if one is found).
To set up this webhook, configure your Sender settings in the TNZ Dashboard (Users > API > Reporting).
## Schemas
### MessageID
- **Type:**`[ "string", "null" ]`
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.
**Example:**
### Reference
- **Type:**`[ "string", "null" ]`
A human readable message reference.
**Example:**
### NotificationType
- **Type:**`[ "string", "null" ]`
Specifies the notification method for delivery status updates and inbound replies for this message. Omit to use your User's default settings.
**Example:**
### ReportTo
- **Type:**`string`
Email address to send a delivery report to once the message completes. Omit to use your User's default settings.
**Example:**
### WebhookCallbackURL
- **Type:**`string`
The URL to receive the webhook. A full path including https\:// is required. Omit to use your User's default settings.
**Example:**
### WebhookCallbackFormat
- **Type:**`string`
The format of the webhook body. Omit to use your User's default settings.
**Example:**
### SendTime
- **Type:**`string`
Delay sending until the specified specified time - {date}T{time} (in the user's 'Local' Timezone). Omit to send immediately.
**Example:**
### Timezone
- **Type:**`[ "string", "null" ]`
The 'Local' Timezone (based on Windows Timezones, [see a list](https://www.tnz.co.nz/help/setting-timezones)). Omit to use your User's default Timezone.
**Example:**
### Account
- **Type:**`string`
Your account number.
**Example:**
### SubAccount
- **Type:**`[ "string", "null" ]`
The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's [Cost Tracking & Rebilling](https://www.tnz.co.nz/help/tnz-api-structure) section.
**Example:**
### Department
- **Type:**`[ "string", "null" ]`
The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's [Cost Tracking & Rebilling](https://www.tnz.co.nz/help/tnz-api-structure) section.
**Example:**
### ContactID
- **Type:**`string`
Unique contact identifier that corresponds to an Address Book Contact.
**Example:**
### GroupID
- **Type:**`string`
Unique group identifier that corresponds to an Address Book Group.
**Example:**
### Destination
- **Type:**`string`
A single destination to receive the message. You may use any of the `Destination` (string), `ContactID` (string), `GroupID` (string) or `Destinations` (array) parameters.
**Example:**
### Destinations
- **Type:**`array`
An array of one or more contacts to receive the message. You may use any of the `Destination` (string), `ContactID` (string), `GroupID` (string) or `Destinations` (array) parameters.
**Example:**
### TemplateID
- **Type:**`string`
UUID of the message template to use. Edit a template in the Dashboard to find the Template ID.
If both `TemplateID` and a Message are specified, the message takes priority.
**Example:**
### Files
- **Type:**`array`
An array of file attachments.
**Example:**
### SMSCustomPageID
- **Type:**`string`
UUID of the \[\[CustomPage]] template to use. Edit a Custom Page template in the Dashboard to find the Template ID.
**Example:**
### NumberOfOperators
- **Type:**`integer`
When sending to multiple Destinations in a single message, you may use this parameter to limit the number of simultaneous calls to match the number of available operators. This is particularly useful when paired with a Keypad with a `RouteNumber`.
**Example:**
### GroupCode
- **Type:**`string`
Human-readable unique identifier for the Address Book Group.
**Example:**
### GroupName
- **Type:**`string`
The human-readable name of the Group.
**Example:**
### ViewBy
- **Type:**`string`
The view access rights.
**Example:**
### EditBy
- **Type:**`string`
The edit access rights.
**Example:**
### ViewEditBy
- **Type:**
The view and edit access rights.
**Example:**
### AccessControl
- **Type:**`string`
The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
**Example:**
### Owner
- **Type:**`string`
The owner of the contact (typically the user who created it).
**Example:**
### JobNumber
- **Type:**`string`
Alphanumeric tracking number (our internal Job Number).
**Example:**
### DestSeq
- **Type:**`string`
The ID of the destination in the list (increments per destination).
**Example:**
### JobStatus
- **Type:**`string`
Current state of the job.
**Example:**
### MessageStatus
- **Type:**`string`
Current status of the message.
**Example:**
### MessageResult
- **Type:**`string`
The final delivery result. For a list of possible values, see [SMS](https://www.tnz.co.nz/help/sms-delivery-result-codes), [Email](https://www.tnz.co.nz/help/email-delivery-result-codes), [Voice & TTS](https://www.tnz.co.nz/help/voice-tts-delivery-result-codes), and [Fax](https://www.tnz.co.nz/help/understanding-fax-delivery-result-codes) documentation.
**Example:**
### CreatedTimeLocal
- **Type:**`string`
The time the entry was created, in the local Timezone.
**Example:**
### CreatedTimeUTC
- **Type:**`string`
The time the entry was created, in UTC.
**Example:**
### CreatedTimeUTC\_RFC3339
- **Type:**`string`
The time the entry was created, in UTC (RFC3339 format).
**Example:**
### UpdatedTimeLocal
- **Type:**`string`
The time the entry was last updated, in the local Timezone.
**Example:**
### UpdatedTimeUTC
- **Type:**`string`
The time the entry was last updated, in UTC.
**Example:**
### UpdatedTimeUTC\_RFC3339
- **Type:**`string`
The time the entry was last updated, in UTC (RFC3339 format).
**Example:**
### DelayedTimeLocal
- **Type:**`string`
The time the entry was delayed until, in the local Timezone.
**Example:**
### DelayedTimeUTC
- **Type:**`string`
The time the entry was delayed until, in UTC.
**Example:**
### DelayedTimeUTC\_RFC3339
- **Type:**`string`
The time the entry was delayed until, in UTC (RFC3339 format).
**Example:**
### SentTimeLocal
- **Type:**`string`
Time the message was sent in the users local Timezone (ISO 8601 format).
**Example:**
### SentTimeUTC
- **Type:**`string`
Time the message was sent in UTC (ISO 8601 format).
**Example:**
### SentTimeUTC\_RFC3339
- **Type:**`string`
Time the message was sent in UTC (RFC 3339 format).
**Example:**
### ReceivedTimeLocal
- **Type:**`string`
Time the message was received in the users local Timezone (ISO 8601 format).
**Example:**
### ReceivedTimeUTC
- **Type:**`string`
Time the message was received in UTC (ISO 8601 format).
**Example:**
### ReceivedTimeUTC\_RFC3339
- **Type:**`string`
Time the message was received in UTC (RFC 3339 format).
**Example:**
### MobileNumber
- **Type:**`string`
The contact's phone number. Used for both SMS and Voice/TTS unless superseded by 'MobilePhone' or 'MainPhone'. See [Mobile Number Formatting](https://www.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent [Toll Fraud](https://www.tnz.co.nz/help/Combatting-SMS-fraud).
**Example:**
### ToNumber
- **Type:**`string`
The contact's phone number. See [Mobile Number Formatting](https://www.tnz.co.nz/help/mobile-number-formatting-for-sms) for guidelines. We recommend limiting the number prefix in your application to prevent [Toll Fraud](https://www.tnz.co.nz/help/Combatting-SMS-fraud).
**Example:**
### EmailAddress
- **Type:**`string`
The contact's email address.
**Example:**
### MainPhone
- **Type:**`string`
The contact's voice telephone number. See [Telephone Number Formatting](https://www.tnz.co.nz/help/telephone-number-formatting-for-voice-fax) for guidelines. We recommend limiting the number prefix in your application to prevent [Toll Fraud](https://www.tnz.co.nz/help/Combatting-SMS-fraud).
**Example:**
### Attention
- **Type:**`[ "string", "null" ]`
The contact's name (used for personalising the message and reporting).
**Example:**
### FirstName
- **Type:**`[ "string", "null" ]`
The contact's first name (used for personalising the message).
**Example:**
### LastName
- **Type:**`[ "string", "null" ]`
The contact's last name (used for personalising the message).
**Example:**
### Company
- **Type:**`[ "string", "null" ]`
The contact's company name (used for personalising the message).
**Example:**
### CustomVariable1
- **Type:**`[ "string", "null" ]`
A custom variable (used for reporting and [Personalisation](https://www.tnz.co.nz/help/message-personalisation)).
**Example:**
### CustomVariables
- **Type:**`[ "string", "null" ]`
Additional custom variable.
**Example:**
### RemoteID
- **Type:**`[ "string", "null" ]`
For Voice, Text-to-Speech and Fax, dialled phone number. This may differ from 'Destination' if failover Alt Phones are used.
**Example:**
### ReceivedMessage
- **Type:**`[ "string", "null" ]`
The received message.
**Example:**
### Price
- **Type:**`[ "string", "null" ]`
Cost of the message (before tax and plan credits). Null if no cost.
**Example:**
### Sender
- **Type:**`string`
Webhook sender authentication (can configure a unique Sender if required).
**Example:**
### APIKey
- **Type:**`[ "string", "null" ]`
Webhook token authentication (can configure a unique APIKey if required).
**Example:**
### URL
- **Type:**`string`
URL/URI for the request.
**Example:**
### Version
- **Type:**`string`
The API version being used.
**Example:**
### UniqueID
- **Type:**`string`
A unique identifier (UUID).
**Example:**
### QueryResult
- **Type:**`string`
Result of the query (***not*** the result of the message).
**Example:**
### UpdateSendTime
- **Type:**`string`
Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone.
**Example:**
### SMSFrom
- **Type:**`string`
Sender of the SMS in E.164 internationalised format.
**Example:**
### TestMode
- **Type:**`[ "string", "null" ]`
Set to `Test` to have messages handled immediately as successful without sending a live message. Useful for end-to-end testing. Omit to use standard mode.
**Example:**
### NullValue
- **Type:**
Null (unused).
**Example:**
### Message\_Detail
- **Type:**`object`
* **`Account`**
`string` — Your account number.
* **`Complete`**
`integer` — Total Destinations that were successfully completed.
* **`Count`**
`integer` — Total Destinations specified in the message.
* **`CreatedTimeLocal`**
`string` — The time the entry was created, in the local Timezone.
* **`CreatedTimeUTC`**
`string` — The time the entry was created, in UTC.
* **`CreatedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was created, in UTC (RFC3339 format).
* **`DelayedTimeLocal`**
`string` — The time the entry was delayed until, in the local Timezone.
* **`DelayedTimeUTC`**
`string` — The time the entry was delayed until, in UTC.
* **`DelayedTimeUTC_RFC3339`**
`string`, format: `date-time` — The time the entry was delayed until, in UTC (RFC3339 format).
* **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`Failed`**
`integer` — Total Destinations that failed to deliver.
* **`JobNum`**
`string` — Alphanumeric tracking number (our internal Job Number).
* **`JobStatus`**
`string`, possible values: `"Pending", "Delayed", "Completed", "CreditHold", "Unknown"` — Current state of the job.
* **`MessageID`**
`string | null` — 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.
* **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
* **`Reference`**
`string | null` — A human readable message reference.
* **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`Success`**
`integer` — Total Destinations that were successfully delivered.
* **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"MessageID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"JobStatus": "Pending",
"JobNum": "10AB20CE",
"Account": "101202",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"Reference": "MyTest",
"CreatedTimeLocal": "2025-05-29 05:11:03",
"CreatedTimeUTC": "2025-05-29 17:11:03",
"CreatedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"DelayedTimeLocal": "2025-05-29 05:11:03",
"DelayedTimeUTC": "2025-05-29 17:11:03",
"DelayedTimeUTC_RFC3339": "2025-05-29T17:11:03.000Z",
"Timezone": "New Zealand",
"Count": 1,
"Complete": 1,
"Success": 1,
"Failed": 0,
"Price": 0.1
}
```
### Recipients\_Detail
- **Type:**`object`
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`Company`**
`string | null` — The contact's company name (used for personalising the message).
* **`Custom1`**
`string | null` — A custom variable (used for reporting and \[Personalisation]\(https\://www\.tnz.co.nz/help/message-personalisation)).
* **`Custom2`**
`string | null` — Additional custom variable.
* **`Custom3`**
`string | null` — Additional custom variable.
* **`Custom4`**
`string | null` — Additional custom variable.
* **`Custom5`**
`string | null` — Additional custom variable.
* **`Custom6`**
`string | null` — Additional custom variable.
* **`Custom7`**
`string | null` — Additional custom variable.
* **`Custom8`**
`string | null` — Additional custom variable.
* **`Custom9`**
`string | null` — Additional custom variable.
* **`Price`**
`string | null` — Cost of the message (before tax and plan credits). Null if no cost.
* **`RemoteID`**
`string | null` — For Voice, Text-to-Speech and Fax, dialled phone number. This may differ from 'Destination' if failover Alt Phones are used.
* **`SentTimeLocal`**
`string` — Time the message was sent in the users local Timezone (ISO 8601 format).
* **`SentTimeUTC`**
`string` — Time the message was sent in UTC (ISO 8601 format).
* **`SentTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was sent in UTC (RFC 3339 format).
**Example:**
```json
{
"SentTimeLocal": "2025-06-13T08:44:16.000Z",
"SentTimeUTC": "2025-06-12T20:44:16.000Z",
"SentTimeUTC_RFC3339": "2025-06-12T20:44:16.000Z",
"Attention": "John Doe",
"Company": "Example Company Ltd",
"Custom1": "Appointment 4:00pm Friday",
"Custom2": "",
"Custom3": "",
"Custom4": "",
"Custom5": "",
"Custom6": "",
"Custom7": "",
"Custom8": "",
"Custom9": "",
"RemoteID": "+6495006000",
"Price": 0.1
}
```
### SMSReplies\_Detail
- **Type:**`object`
* **`From`**
`string` — Sender of the SMS in E.164 internationalised format.
* **`MessageText`**
`string | null` — The received message.
* **`ReceivedID`**
`string`, format: `uuid` — A unique identifier (UUID).
* **`ReceivedTimeLocal`**
`string` — Time the message was received in the users local Timezone (ISO 8601 format).
* **`ReceivedTimeUTC`**
`string` — Time the message was received in UTC (ISO 8601 format).
* **`ReceivedTimeUTC_RFC3339`**
`string`, format: `date-time` — Time the message was received in UTC (RFC 3339 format).
* **`Timezone`**
`string | null` — The 'Local' Timezone (based on Windows Timezones, \see a list\). Omit to use your User's default Timezone.
**Example:**
```json
{
"ReceivedID": "a1b2c3d4-e5f6-7890-1234-567890abcdee",
"ReceivedTimeLocal": "2025-09-01T14:02:03.000Z",
"ReceivedTimeUTC": "2025-09-01T02:02:03.000Z",
"ReceivedTimeUTC_RFC3339": "2025-09-01T02:02:03.000Z",
"Timezone": "New Zealand",
"From": "+6421000001",
"MessageText": "This is a received message from a mobile phone."
}
```
### Contact\_Detail
- **Type:**
**Example:**
### Contact\_Object
- **Type:**`object`
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`AltPhone1`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone2`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone3`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone4`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone5`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone6`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone7`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`AltPhone8`**
`string`, format: `phone` — An alternative phone number for the contact (used for Voice and TTS failover).
* **`Attention`**
`string | null` — The contact's name (used for personalising the message and reporting).
* **`City`**
`string | null` — The contact's city.
* **`Company`**
`string | null` — The contact's company name (used for personalising messages and reporting).
* **`Country`**
`string | null` — The contact's country (no fixed format).
* **`Custom1`**
`string | null` — Custom field (used for personalising messages).
* **`Custom2`**
`string | null` — Custom field (used for personalising messages).
* **`Custom3`**
`string | null` — Custom field (used for personalising messages).
* **`Custom4`**
`string | null` — Custom field (used for personalising messages).
* **`EditBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The edit access rights.
* **`EmailAddress`**
`string`, format: `email` — The contact's email address (used for Email messages).
* **`ExID`**
`string` — An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID).
* **`ExType`**
`string` — An External ID Type can be used to categorise contacts (typically used by another system).
* **`FaxNumber`**
`string`, format: `phone` — The contact's fax number (used for Fax messages).
* **`FirstName`**
`string | null` — The contact's first name (used for personalising messages).
* **`LastName`**
`string | null` — The contact's last name (used for personalising messages).
* **`MainPhone`**
`string`, format: `phone` — The contact's main phone number (used for Voice and TTS calls).
* **`MobilePhone`**
`string`, format: `phone` — The contact's mobile phone number (used for SMS messages).
* **`Notes`**
`string | null` — Freeform notes.
* **`Position`**
`string | null` — The contact's position within their company.
* **`Postcode`**
`string | null` — The contact's postal code (no fixed format)
* **`RecipDepartment`**
`string | null` — The contact's department within their company.
* **`State`**
`string | null` — The contact's state or region.
* **`StreetAddress`**
`string | null` — The contact's street address.
* **`Suburb`**
`string | null` — The contact's suburb.
* **`Title`**
`string | null`, possible values: `"", "Mr", "Mrs", "Ms", "Miss", "Dr", "Prof", "Hon"` — The contact's title (for example, Mr, Ms, Dr).
* **`ViewBy`**
`string`, possible values: `"Account", "SubAccount", "Department", "No"` — The view access rights.
* **`WebAddress`**
`string`, format: `uri` — The contact's website address.
**Example:**
```json
{
"ExType": "",
"ExID": "",
"ViewBy": "Account",
"EditBy": "Account",
"AccessControl": "Limited",
"Attention": "John Doe",
"Title": "Mr",
"Company": "Example Company",
"RecipDepartment": "Accounting",
"FirstName": "John",
"LastName": "Doe",
"Position": "Accountant",
"StreetAddress": "123 Queen Street",
"Suburb": "Auckland City",
"City": "Auckland",
"State": "",
"Country": "New Zealand",
"Postcode": "1010",
"MainPhone": "+6421002003",
"AltPhone1": "+6495006001",
"AltPhone2": "+6495006002",
"AltPhone3": "+6495006003",
"AltPhone4": "+6495006004",
"AltPhone5": "",
"AltPhone6": "",
"AltPhone7": "",
"AltPhone8": "",
"MobilePhone": "+6421002003",
"FaxNumber": "+64 9 500-5000",
"EmailAddress": "john.doe@example.com",
"WebAddress": "https://www.example.com",
"Custom1": "Custom Value 1",
"Custom2": "Custom Value 2",
"Custom3": "",
"Custom4": "",
"Notes": "This contact was created using the Address Book API."
}
```
### Group\_Detail
- **Type:**
**Example:**
### Group\_Object
- **Type:**`object`
* **`AccessControl`**
`string`, possible values: `"Limited", "Granted"` — The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No).
* **`Department`**
`string | null` — The applicable Department. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`GroupName`**
`string` — The human-readable name of the Group.
* **`SubAccount`**
`string | null` — The applicable SubAccount. Used for reporting, billing and Web Dashboard segmentation. See the TNZ API Structure guide's \[Cost Tracking & Rebilling]\(https\://www\.tnz.co.nz/help/tnz-api-structure) section.
* **`ViewEditBy`**
`object`, possible values: `"Account", "SubAccount", "Department", "No"` — The view and edit access rights.
**Example:**
```json
{
"GroupName": "My Test Group",
"SubAccount": "Business Unit One",
"Department": "Department Alpha",
"ViewEditBy": "Account",
"AccessControl": "Limited"
}
```
### OptOut\_Object
- **Type:**`object`
* **`DestType` (required)**
`string` — The message type the entry applies to ('SMS', 'Email', 'Voice', 'Fax'). You may only specify one. For multi-channel opt-outs, see \`Create OptOuts (Batch)\`.
* **`ContactID`**
`string`, format: `uuid` — Unique contact identifier that corresponds to an Address Book Contact.
* **`Department`**
`string | null` — The Department the opt-out entry applies to. An empty value applies to all Departments.
* **`Destination`**
`string` — The destination opted-out. Telephone numbers are in E.164 format. You may use \`Destination\` or \`ContactID\` (not both).
* **`Notes`**
`string | null` — Free form notes.
* **`StopMessage`**
`string | null` — The Opt-Out message detected.
* **`SubAccount`**
`string | null` — The SubAccount the opt-out entry applies to. An empty value applies to all SubAccounts.
**Example:**
```json
{
"DestType": "SMS",
"Destination": "+6421003004",
"ContactID": "123e4567-e89b-12d3-a456-426614174000",
"SubAccount": "Business Unit One",
"Department": "Team Alpha",
"StopMessage": "Stop sending me these messages",
"Notes": "Entry edited using the API."
}
```
### OptOut\_Detail
- **Type:**
**Example:**
### Pagination
- **Type:**`object`
* **`Page`**
`integer`
* **`PageCount`**
`integer`
* **`RecordsPerPage`**
`integer`
* **`TotalRecords`**
`integer`
**Example:**
```json
{
"TotalRecords": 1,
"RecordsPerPage": 20,
"PageCount": 1,
"Page": 1
}
```