### Start 'Info' Module ### openapi: 3.1.0 info: title: TNZ REST API summary: Flexible API for managing SMS, Email, Voice, Fax, Address Book Contacts and Opt-Out entries. version: '3.00' x-scalar-sdk-installation: - lang: Node description: We have a dedicated [Node.js npm package](https://www.tnz.co.nz/docs/NodeJSLib/) you are welcome to try! source: |- npm i tnzapi - lang: Python description: We have a dedicated [Python pip package](https://www.tnz.co.nz/docs/PythonLib/) you are welcome to try! source: |- pip install tnzapi - lang: csharp description: We have a dedicated [.NET NuGet package](https://www.tnz.co.nz/docs/dotNetLib/) you are welcome to try! source: |- dotnet add package TNZAPI.NET description: | # 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) ![REST API Features](https://www.tnz.co.nz/docs/restapi/assets/images/TNZApps[128x75].png) # 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. ![REST API Authentication](https://www.tnz.co.nz/docs/restapi/assets/images/TNZ[128x75].png) # 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 | contact: name: Support email: support@tnz.co.nz url: 'https://www.tnz.co.nz/about/contact/' termsOfService: 'https://www.tnz.co.nz/About/TermsAndConditions/' x-logo: url: 'https://www.tnz.co.nz/assets/img/logo2.png' altText: TNZ Logo 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 security: - bearerAuth: [] tags: - name: Workflow description: | **Turbocharge Your Messaging with Automated Workflows** The Workflow endpoint is your gateway to our most powerful messaging features, allowing you to execute complex, pre-configured strategies with a single API call. ![Workflow](https://www.tnz.co.nz/docs/restapi/assets/images/Workflow[128x75].png) Go beyond a simple "send" command and build sophisticated rules and automations. With Workflows, you can: * Create Multi-Channel Cascades: Start with an SMS, automatically failover to an Email if there's no reply, then trigger a Text-to-Speech call if the email isn't received. * Intelligent Failover: Define fallback channels to ensure your message always gets through, maximising reach and reliability. * Trigger Custom Webhooks: Integrate deeper into your own systems by firing off custom actions at any stage of the workflow. * No-Code Design: Use the Dashboard to design your Workflow rules using the drag-and-drop builder then trigger them using the API. It's a complete communication strategy without the overhead. - name: SMS description: | **Two Way SMS API Endpoint** Engage your audience directly with our SMS API. More than just a one-way notification system; it's a complete two-way messaging solution. Use the Send SMS endpoint to initiate conversations, from simple alerts to personalised campaigns. ![SMS](https://www.tnz.co.nz/docs/restapi/assets/images/SMS[128x75].png) You can then track delivery status in real-time and process inbound replies using either our efficient [Inbound SMS webhook](#tag/sms/webhook/POST/inboundsmswebhook) or the [SMS Details GET endpoint](#tag/sms/GET/sms/{MessageID}). To create a truly interactive experience, you can enhance your messages with powerful features: * URL Shortener: Track link engagement with our built-in URL shortener. * File Attachments: Send images, videos and documents by attaching files to your API request and using the `[[File1]]` command. * Templates: For sleek integration with the Dashboard, reference a pre-configured Dashboard `TemplateID` and let users self-manage their message templates. - name: Email description: | Go beyond plain text with our flexible Email API. Send beautifully crafted HTML emails using your own content or pre-configured templates. Or specify a `TemplateID` and let users manage their own HTML designs using the Dashboard's WYSIWYG editor. Track link clicks and attach files on the fly. Whether you're sending invoices, newsletters, or critical alerts, you can monitor delivery status every step of the way. ![Email](https://www.tnz.co.nz/docs/restapi/assets/images/Email[128x75].png) - name: TTS description: | Transform your written text into clear, natural-sounding voice calls with our Text-to-Speech (TTS) API. Ideal for automated alerts, appointment reminders, or customer surveys. Customize calls with different voices, SSML command support, and interactive keypad options that can route callers or capture responses. Answering machine detection ensures your message is delivered effectively, whether to a person or a voicemail. ![TTS](https://www.tnz.co.nz/docs/restapi/assets/images/TTS[128x75].png) - name: Voice description: | Deliver impactful messages by sending pre-recorded audio files as voice calls. Perfect for alerts where a human voice adds a personal touch or when conveying complex information. This endpoint allows you to manage calls to individuals or large groups, with powerful features like retry attempts for failed calls, answering machine detection, and interactive keypad responses. ![Voice](https://www.tnz.co.nz/docs/restapi/assets/images/Voice[128x75].png) - name: Fax description: | Bridge the gap between digital and traditional documentation with our reliable Fax API. Send documents directly from your application to any fax machine worldwide without needing any physical hardware. You can track the delivery status of each fax and receive detailed reports, ensuring your important documents arrive successfully. ![Fax](https://www.tnz.co.nz/docs/restapi/assets/images/Fax[128x75].png) - name: WhatsApp description: | Leverage the power of WhatsApp and send messages to WhatsApp users worldwide. Our WhatsApp API allows you to send text, files, templates and receive responses on the world's most popular messaging platform. ![WhatsApp](https://www.tnz.co.nz/docs/restapi/assets/images/WhatsApp[128x75].png) - name: RCS description: | Boost your text messages using Rich Communication Services (RCS). Our RCS API enables you to send media-rich messages that go beyond traditional SMS, providing a more engaging experience for your audience. RCS is unsupported in New Zealand and Australia. ![RCS](https://www.tnz.co.nz/docs/restapi/assets/images/RCS[128x75].png) - name: Webhooks description: | Get real-time updates without the need for constant polling. Our webhooks can notify your application instantly when a message completes sending or when you receive an inbound SMS. This efficient, event-driven approach ensures your system stays up-to-date with delivery receipts and customer replies, saving you resources and providing faster insights. ![Webhooks](https://www.tnz.co.nz/docs/restapi/assets/images/Developers[128x75].png) - name: Address Book description: | Centralise your Contacts using the Address Book API, your single source of truth. This simplifies your integration and unlocks powerful, data-rich personalisation across all messaging channels. > [!CAUTION] > To use this function, your API user must have the Address Book API enabled: > `Dashboard` > `Users` > `API User` > `API` > `Address Book API Access` With this set of endpoints, you can: * Programmatically create, retrieve, update, and delete contacts. Keep your data synchronised across systems without manual effort (CRMs, HR systems, Spreadsheets and more). * Organise contacts into groups. Send a message to thousands with a single API call by referencing a `GroupID`. * Store custom fields for each contact (e.g., `FirstName`, `Company`, `Custom1`) and use them as merge tags like `[[FirstName]]` to personalise messages across any channel. * Drastically reduce your payload size. Instead of sending a full array of recipient details every time, simply reference the unique `ContactID` or `GroupID`. * Use your contacts and groups with the TNZ Dashboard. ![Address Book](https://www.tnz.co.nz/docs/restapi/assets/images/AddressBook[128x75].png) - name: OptOut description: | The Opt-Out API allows you to programmatically manage contacts who have unsubscribed. Opt-Out API gives you the flexibility to manage unsubscribes on a SubAccount, Department and Message Type basis. This means a user can opt out of SMS marketing while still receiving important Email alerts. ![Opt-Outs](https://www.tnz.co.nz/docs/restapi/assets/images/Mobile1[128x75].png) When you attempt to send a message, the API will accept the request, but if the recipient is on the opt-out list for that channel, the delivery will be blocked and return a "Destination is blacklisted" result. This provides a clear audit trail and protects your brand from sending unwanted communications. Key features of this endpoint set include: * Add or remove individual contacts from your opt-out list in real-time. * Once added, a contact is automatically suppressed for the applicable message type. * Each message type is managed independently, giving you full control. * Retrieve a complete list of all opted-out contacts for auditing, reporting, or synchronizing with your own CRM. * Effortlessly manage unsubscribes to help meet your obligations under anti-spam regulations. - name: Partner API description: | Empower your wholesale and partner accounts with direct user management capabilities. This restricted set of endpoints is designed for partners to manage their sub-accounts and user details, providing an automated way to handle account administration. ![Partner API](https://www.tnz.co.nz/docs/restapi/assets/images/Integrations[128x75].png) paths: ### End 'Info' Module ### ### Start 'Workflow' Module ### # /workflow: post: tags: - Workflow summary: Send Workflow description: |- 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. operationId: client.messaging.workflow.sendmessage security: - bearerAuth: [] # The Accept header is optional #parameters: # - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ WorkflowTemplateID ] properties: WorkflowTemplateID: type: string format: uuid description: 'ID of the Workflow template. [Find Your TemplateID](https://www.tnz.co.nz/help/how-to-find-your-templateid).' example: a1b2c3d4-e5f6-7890-1234-567890abcdef Destinations: $ref: "#/components/schemas/Destinations" Destination: $ref: "#/components/schemas/Destination" ToNumber: $ref: "#/components/schemas/ToNumber" MainPhone: $ref: "#/components/schemas/MainPhone" ContactID: $ref: "#/components/schemas/ContactID" GroupID: $ref: "#/components/schemas/GroupID" MessageID: $ref: "#/components/schemas/MessageID" Reference: $ref: "#/components/schemas/Reference" NotificationType: $ref: "#/components/schemas/NotificationType" WebhookCallbackURL: $ref: "#/components/schemas/WebhookCallbackURL" WebhookCallbackFormat: $ref: "#/components/schemas/WebhookCallbackFormat" SubAccount: $ref: "#/components/schemas/SubAccount" Department: $ref: "#/components/schemas/Department" SendTime: $ref: "#/components/schemas/SendTime" Timezone: $ref: "#/components/schemas/Timezone" # Workflow examples examples: 'Send to an Address Book Contact': value: WorkflowTemplateID: a1b2c3d4-e5f6-7890-1234-567890abcdef ContactID: 6000000b-f002-4007-b00a-c00000000001 'Send to an Address Book Group': value: WorkflowTemplateID: a1b2c3d4-e5f6-7890-1234-567890abcdef GroupID: 4000000b-f002-4007-b00a-c00000000002 'Send to a new contact': value: 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 'Display all parameters': value: WorkflowTemplateID: a1b2c3d4-e5f6-7890-1234-567890abcdef Destinations: - ContactID: 4000000b-f002-4007-b00a-c00000000001 - GroupID: 6000000b-f002-4007-b00a-c00000000002 - ToNumber: '+6421000001' MainPhone: '+6495005000' EmailAddress: 'john.doe@example.com' FirstName: 'John' LastName: 'Doe' Company: 'Example Company' Custom1: 'Custom Value 1' Custom2: 'Custom Value 2' Custom3: 'Custom Value 3' Custom4: 'Custom Value 4' Destination: '+6421000001' ContactID: 4000000b-f002-4007-b00a-c00000000001 GroupID: 6000000b-f002-4007-b00a-c00000000002 Reference: An appointment reminder WebhookCallbackURL: https://www.example.com/webhook WebhookCallbackFormat: JSON MessageID: 1234-5678 SubAccount: Business Unit One Department: Team Alpha SendTime: 2025-08-01T09:00:00 Timezone: New Zealand # Workflow responses responses: '200': $ref: '#/components/responses/200OK' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' ### End 'Workflow' Module ### ### Start 'SMS' Module ### # /sms: # Send SMS post: tags: - SMS summary: Send SMS description: | 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. operationId: client.messaging.sms.sendmessage security: - bearerAuth: [] # The Accept header is optional #parameters: # - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object properties: Message: type: string maxLength: 1000 description: 'The SMS text message to send. Alternatively, you may use the `TemplateID` parameter.' example: '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: $ref: "#/components/schemas/TemplateID" Destination: $ref: "#/components/schemas/Destination" ToNumber: $ref: "#/components/schemas/ToNumber" Destinations: $ref: "#/components/schemas/Destinations" ContactID: $ref: "#/components/schemas/ContactID" GroupID: $ref: "#/components/schemas/GroupID" MessageID: $ref: "#/components/schemas/MessageID" Reference: $ref: "#/components/schemas/Reference" NotificationType: $ref: "#/components/schemas/NotificationType" WebhookCallbackURL: $ref: "#/components/schemas/WebhookCallbackURL" WebhookCallbackFormat: $ref: "#/components/schemas/WebhookCallbackFormat" ReportTo: $ref: "#/components/schemas/ReportTo" SendTime: $ref: "#/components/schemas/SendTime" Timezone: $ref: "#/components/schemas/Timezone" SubAccount: $ref: "#/components/schemas/SubAccount" Department: $ref: "#/components/schemas/Department" FromNumber: type: string description: Sets the Sender ID on your sent message (in E164 format without the leading +). Will be overridden for complex countries such as New Zealand. example: '61408080909' SMSEmailReply: type: string format: email description: The email address to send SMS Reply notifications to. This may be ignored if a different Reply Notification rule is configured. example: 'reply@example.com' SMSCustomPageID: $ref: "#/components/schemas/SMSCustomPageID" CharacterConversion: type: boolean description: '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.' example: false default: false FallbackMode: type: string description: If the SMS delivery fails, try another method (in the order listed). enum: [None, Voice, WhatsApp, RCS] default: 'None' example: 'Voice' Files: $ref: "#/components/schemas/Files" Mode: $ref: "#/components/schemas/TestMode" # Send SMS examples examples: 'Send a simple SMS message': value: Message: 'Hello, this is an SMS notification from Company One Ltd. Reply STOP to OptOut.' Destination: '021-000001' 'Send to an Address Book Contact': value: Message: 'Hello [[FirstName]], this is an SMS notification from Company One Ltd. Reply STOP to OptOut.' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Send to an Address Book Group': value: Message: 'Hello [[FirstName]], this is an SMS notification from Company One Ltd. Reply STOP to OptOut.' GroupID: 4000000b-f002-4007-b00a-c00000000002 'Send a Template to Multiple Contacts': value: TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destinations: - ToNumber: '+6421000001' - ToNumber: '+6421000002' - ContactID: 4000000b-f002-4007-b00a-c00000000001 'Display all parameters': value: Message: 'Hello [[FirstName]], this is an SMS notification from Company One Ltd. Reply STOP to OptOut.' TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: '+6421000001' Destinations: - ContactID: 4000000b-f002-4007-b00a-c00000000001 - GroupID: 6000000b-f002-4007-b00a-c00000000002 - ToNumber: '+6421000001' FirstName: 'John' LastName: 'Doe' Company: 'Example Company' Custom1: 'Custom Value 1' Custom2: 'Custom Value 2' Custom3: 'Custom Value 3' Custom4: 'Custom Value 4' ContactID: 4000000b-f002-4007-b00a-c00000000001 GroupID: 6000000b-f002-4007-b00a-c00000000002 MessageID: 1234-5678 Reference: An appointment reminder NotificationType: Webhook WebhookCallbackURL: https://www.example.com/webhook WebhookCallbackFormat: JSON SendTime: 2025-08-01T09:00:00 Timezone: New Zealand SubAccount: Business Unit One Department: Team Alpha FromNumber: 61410023004 SMSEmailReply: reply@example.com SMSCustomPageID: 987e6543-e21b-12d3-a456-426614174999 CharacterConversion: true FallbackMode: Voice Files: - Name: 'My Example.pdf' Data: '[base-64 data - see the field description for sample data]' # Send SMS responses responses: '200': description: OK [successful submission] content: application/json: schema: type: object properties: MessageID: type: string description: Unique identifier for the API call. example: 1000000a-f002-4007-b00a-d00000000002 example: MessageID: 1000000a-f002-4007-b00a-d00000000002 links: SMSStatus: operationId: client.messaging.sms.status parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to track the message. SMSReschedule: operationId: client.messaging.sms.reschedule parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. SMSAbort: operationId: client.messaging.sms.abort parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /sms/{MessageID}: get: # Get SMS Status tags: - SMS summary: SMS Details description: | 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. > [!TIP] > Timeout your polls after 6 hours with no result. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. > [!note] > Consider the [Send Result Webhook](#tag/sms/webhook/POST/resultwebhook) for efficiency. operationId: client.messaging.sms.status security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' # Get SMS Status responses responses: '200': description: OK [message found] content: application/json: schema: allOf: - $ref: '#/components/schemas/Message_Detail' - $ref: '#/components/schemas/Pagination' - type: object properties: Recipients: type: array description: List of recipients for the message. items: allOf: - type: object properties: Type: type: string description: The type of message this data relates to. enum: [SMS, Email, Voice, Fax] example: SMS DestSeq: $ref: '#/components/schemas/DestSeq' Destination: type: string description: The destination address (e.g. phone number, email address). Telephone/mobile numbers are supplied in E.164 internationalised format. example: '+64212223333' ContactID: $ref: '#/components/schemas/ContactID' Status: $ref: '#/components/schemas/MessageStatus' Result: type: string description: The final delivery result. For a list of possible values, see [SMS](https://www.tnz.co.nz/help/sms-delivery-result-codes) result codes. examples: - Delivered - Bad Number MessageText: type: string description: 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. example: 'Hello, we sent you a test message.' - $ref: '#/components/schemas/Recipients_Detail' - type: object properties: SMSReplies: type: array description: A list of replies for this recipient. items: $ref: '#/components/schemas/SMSReplies_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '500': $ref: '#/components/responses/500ServerError' '/sms/received': get: tags: - SMS summary: Inbound SMS description: | 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`. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. > [!note] > Consider the [Inbound SMS Webhook](#tag/sms/webhook/POST/inboundsmswebhook) for efficiency. operationId: client.messaging.sms.received security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - name: timePeriod in: query required: true description: Return results from the last _x_ minutes (e.g. last 5 minutes). example: 10 schema: type: integer minimum: 1 maximum: 1440 - name: dateFrom in: query required: false description: Return results from the specified date in the API User's local time. Maximum 7 days. example: 2025-08-01T00:00:00 schema: type: string - name: dateTo in: query required: false description: Return results to the specified date in the API User's local time. Maximum 7 days. example: 2025-08-01T12:00:00 schema: type: string - $ref: '#/components/parameters/RecordsPerPage' - $ref: '#/components/parameters/Page' responses: '200': description: OK [message found] content: application/json: schema: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: Messages: type: array description: List of messages found. items: type: object properties: ReceivedID: $ref: '#/components/schemas/UniqueID' MessageID: type: string format: uuid description: 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. example: 7000000a-f002-4007-b00a-d00000000002 JobNum: $ref: '#/components/schemas/JobNumber' SubAccount: $ref: '#/components/schemas/SubAccount' Department: $ref: '#/components/schemas/Department' ReceivedTimeLocal: $ref: '#/components/schemas/ReceivedTimeLocal' ReceivedTimeUTC: $ref: '#/components/schemas/ReceivedTimeUTC' ReceivedTimeUTC_RFC3339: $ref: '#/components/schemas/ReceivedTimeUTC_RFC3339' From: $ref: '#/components/schemas/SMSFrom' ContactID: $ref: '#/components/schemas/ContactID' MessageText: $ref: '#/components/schemas/ReceivedMessage' Timezone: $ref: '#/components/schemas/Timezone' Version: $ref: '#/components/schemas/Version' '401': $ref: '#/components/responses/401Unauthorized' '500': $ref: '#/components/responses/500ServerError' ### End 'SMS' Module ### '/sms/{MessageID}/reschedule': patch: tags: - SMS summary: Reschedule description: | This endpoint allows you to reschedule a previously delayed message to be sent at a new time. operationId: client.messaging.sms.reschedule security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Reschedule] example: Reschedule '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/sms/{MessageID}/abort': patch: tags: - SMS summary: Abort description: | This endpoint allows you to abort a previously delayed message. operationId: client.messaging.sms.abort security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Abort] example: Abort '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' ### Start 'Email' Module ### # /email: # Send Email post: tags: - Email summary: Send Email description: | 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. operationId: client.messaging.email.sendmessage security: - bearerAuth: [] # The Accept header is optional #parameters: # - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object properties: MessagePlain: type: string maxLength: 10000 description: | 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). example: '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: type: string maxLength: 10000 description: | 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). example: '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: $ref: "#/components/schemas/TemplateID" Destination: $ref: "#/components/schemas/Destination" EmailAddress: $ref: "#/components/schemas/EmailAddress" ContactID: $ref: "#/components/schemas/ContactID" GroupID: $ref: "#/components/schemas/GroupID" Destinations: $ref: "#/components/schemas/Destinations" MessageID: $ref: "#/components/schemas/MessageID" Reference: $ref: "#/components/schemas/Reference" From: type: string maxLength: 30 description: Sets the email sender's Friendly Name (seen by the email recipient) example: Company One Ltd FromEmail: type: string maxLength: 100 description: Sets the email sender's Email Address (uses the default email address for your API User if not specified). example: help@example.com CCEmail: type: string maxLength: 100 description: Adds a tracked CC to the email (one per recipient, chargeable). example: notices@example.com BCCEmail: type: string maxLength: 100 description: Adds an untracked BCC to the email (one per recipient, chargeable). example: archive@example.com ReplyTo: type: string maxLength: 100 description: Adds a Reply-To to the email (if the recipient replies, the Reply To will receive the reply). example: replies@example.com EmailSubject: type: string maxLength: 1024 description: The Subject line used in the email. examples: - Your appointment is coming up! - Your account is overdue. NotificationType: $ref: "#/components/schemas/NotificationType" WebhookCallbackURL: $ref: "#/components/schemas/WebhookCallbackURL" WebhookCallbackFormat: $ref: "#/components/schemas/WebhookCallbackFormat" ReportTo: $ref: "#/components/schemas/ReportTo" SendTime: $ref: "#/components/schemas/SendTime" Timezone: $ref: "#/components/schemas/Timezone" SubAccount: $ref: "#/components/schemas/SubAccount" Department: $ref: "#/components/schemas/Department" Files: $ref: "#/components/schemas/Files" Mode: $ref: "#/components/schemas/TestMode" # Send Email examples examples: 'Send a simple Email message': value: MessagePlain: 'Hello, this is an Email notification from Company One Ltd.' Destination: 'john.doe@example.com' 'Send an HTML Email to an Address Book Contact': value: MessageHTML: 'Hello [[FirstName]], this is an Email notification from Company One Ltd.' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Send an HTML Email to an Address Book Group': value: MessageHTML: 'Hello [[FirstName]], this is an Email notification from Company One Ltd.' GroupID: 4000000b-f002-4007-b00a-c00000000002 'Send a Template to Two Contacts': value: TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: 'john.doe@example.com' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Display all parameters': value: MessagePlain: 'Hello [[FirstName]], this is an Email notification from Company One Ltd.' MessageHTML: 'Hello [[FirstName]], this is an Email notification from Company One Ltd.' TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: 'john.doe@example.com' Destinations: - ContactID: 4000000b-f002-4007-b00a-c00000000001 - GroupID: 6000000b-f002-4007-b00a-c00000000002 - EmailAddress: 'john.doe@example.com' FirstName: 'John' LastName: 'Doe' Company: 'Example Company' Custom1: 'Custom Value 1' Custom2: 'Custom Value 2' Custom3: 'Custom Value 3' Custom4: 'Custom Value 4' ContactID: 4000000b-f002-4007-b00a-c00000000001 GroupID: 6000000b-f002-4007-b00a-c00000000002 MessageID: 1234-5678 Reference: An appointment reminder From: Company One Ltd FromEmail: help@example.com CCEmail: notices@example.com BCCEmail: archive@example.com ReplyTo: replies@example.com EmailSubject: A reminder of your appointment NotificationType: Webhook WebhookCallbackURL: https://www.example.com/webhook WebhookCallbackFormat: JSON SendTime: 2025-08-01T09:00:00 Timezone: New Zealand SubAccount: Business Unit One Department: Team Alpha Files: - Name: 'My Example.pdf' Data: '[base-64 data - see the field description for sample data]' # Send Email responses responses: '200': description: OK [successful submission] content: application/json: schema: type: object properties: MessageID: type: string description: Unique identifier for the API call. example: 1000000a-f002-4007-b00a-d00000000002 example: MessageID: 1000000a-f002-4007-b00a-d00000000002 links: EmailStatus: operationId: client.messaging.email.status parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to track the message. EmailReschedule: operationId: client.messaging.email.reschedule parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. EmailAbort: operationId: client.messaging.email.abort parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. EmailResubmit: operationId: client.messaging.email.resubmit parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to retry the message. '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /email/{MessageID}: get: # Get Email Status tags: - Email summary: Email Details description: | 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. > [!TIP] > Timeout your polls after 6 hours with no result. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. > [!note] > Consider the [Send Result Webhook](#tag/email/webhook/POST/resultwebhook) for efficiency. operationId: client.messaging.email.status security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' # Get Email Status responses responses: '200': description: OK [message found] content: application/json: schema: allOf: - $ref: '#/components/schemas/Message_Detail' - $ref: '#/components/schemas/Pagination' - type: object properties: Recipients: type: array description: List of recipients for the message. items: allOf: - type: object properties: Type: type: string description: The type of message this data relates to. enum: [SMS, Email, Voice, Fax] example: Email DestSeq: $ref: '#/components/schemas/DestSeq' Destination: type: string description: The destination address (e.g. phone number, email address). example: 'john.doe@example.com' ContactID: $ref: '#/components/schemas/ContactID' Status: $ref: '#/components/schemas/MessageStatus' Result: type: string description: The final delivery result. For a list of possible values, see [Email](https://www.tnz.co.nz/help/email-delivery-result-codes) result codes. examples: - 250 OK - 550 5.1.1 No such user - $ref: '#/components/schemas/Recipients_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '500': $ref: '#/components/responses/500ServerError' ### End 'Email' Module ### '/email/{MessageID}/reschedule': patch: tags: - Email summary: Reschedule description: | This endpoint allows you to reschedule a previously delayed message to be sent at a new time. operationId: client.messaging.email.reschedule security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Reschedule] example: Reschedule '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/email/{MessageID}/abort': patch: tags: - Email summary: Abort description: | This endpoint allows you to abort a previously delayed message. operationId: client.messaging.email.abort security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Abort] example: Abort '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/email/{MessageID}/resubmit': patch: tags: - Email summary: Resubmit description: | This endpoint allows you to retry sending a previously failed message. operationId: client.messaging.email.resubmit security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found]. content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Resubmit] example: Resubmit '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' ### Start 'TTS' Module ### # /tts: # Send TTS post: tags: - TTS summary: Send TTS description: | 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. operationId: client.messaging.tts.sendmessage security: - bearerAuth: [] # The Accept header is optional #parameters: # - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object properties: MessageToPeople: type: string maxLength: 5000 description: | 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`. example: 'Hello, this is a call from Department01. This is relevant information. Press one to be connected to our call centre.' TemplateID: $ref: "#/components/schemas/TemplateID" Destination: $ref: "#/components/schemas/Destination" ToNumber: $ref: "#/components/schemas/ToNumber" Destinations: $ref: "#/components/schemas/Destinations" ContactID: $ref: "#/components/schemas/ContactID" GroupID: $ref: "#/components/schemas/GroupID" MessageID: $ref: "#/components/schemas/MessageID" Reference: $ref: "#/components/schemas/Reference" NotificationType: $ref: "#/components/schemas/NotificationType" WebhookCallbackURL: $ref: "#/components/schemas/WebhookCallbackURL" WebhookCallbackFormat: $ref: "#/components/schemas/WebhookCallbackFormat" ReportTo: $ref: "#/components/schemas/ReportTo" SendTime: $ref: "#/components/schemas/SendTime" Timezone: $ref: "#/components/schemas/Timezone" SubAccount: $ref: "#/components/schemas/SubAccount" Department: $ref: "#/components/schemas/Department" MessageToAnswerPhones: type: string maxLength: 10000 description: | Enables Answering Machine/Voicemail detection. When an answering machine is detected, this message is played. example: 'Hello, sorry we missed you. This is a call from Department 01. Please contact us on 0800 123123.' AnswerPhoneMode: type: string default: NDAS description: 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). examples: - NDAS - DAS - NDAF - DAF Keypads: type: array description: Detect if the recipient presses a keypad option and perform an action. items: type: object properties: Tone: type: integer minimum: 0 maximum: 9 description: The keypad button. example: 1 Play: type: string description: Message to play when the keypad button is pressed. example: You pressed Keypad 1. We're connecting you now. RouteNumber: type: string format: phone description: If specified, the call will be diverted to this number when the keypad button is pressed. example: '6421000001' PlaySection: type: string description: | 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. examples: - Main - AnswerPhone - WrongKey KeypadOptionRequired: type: boolean default: false description: | 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. examples: - false - true CallRouteMessageOnWrongKey: type: string description: 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. example: Sorry, you have pressed an invalid key. Please try again. CallRouteMessageToPeople: type: string description: Text-to-speech message played when a keypad option is pressed. example: Connecting you now. CallRouteMessageToOperators: type: string description: Text-to-speech message played to the call centre representative answering the connected call. example: Incoming Text To Speech call. NumberOfOperators: $ref: '#/components/schemas/NumberOfOperators' RetryAttempts: type: integer minimum: 0 maximum: 5 description: | 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. example: 1 RetryPeriod: type: integer minimum: 0 maximum: 60 description: Minutes to wait between Retry Attempts. example: 5 CallerID: type: string format: phone description: Sets the Caller ID used on the call (must be E.164 format and whitelisted under your account). example: +6495005000 Voice: type: string default: Female1 description: Text-to-Speech voice to use (Male1, Female1, Nicole, Russell, Amy, Brian, Emma). examples: - Female1 - Male1 - Nicole - Russell - Amy - Brian - Emma Options: type: string description: 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. Mode: $ref: "#/components/schemas/TestMode" # Send TTS examples examples: 'Send a simple TTS message': value: MessageToPeople: 'Hello, this is an TTS notification from Company One Ltd.' Destination: '021-000001' 'Send to an Address Book Contact': value: MessageToPeople: 'Hello [[FirstName]], this is an TTS notification from Company One Ltd.' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Send to an Address Book Group': value: MessageToPeople: 'Hello [[FirstName]], this is an TTS notification from Company One Ltd.' GroupID: 4000000b-f002-4007-b00a-c00000000002 'Send a Template to Two Contacts': value: TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: '021-000001' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Display all parameters': value: MessageToPeople: 'Hello, this is a call from Department01. This is relevant information. Press one to be connected to our call centre or press two to hear this message again.' TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: '+6495005000' Destinations: - ContactID: 4000000b-f002-4007-b00a-c00000000001 - GroupID: 6000000b-f002-4007-b00a-c00000000002 - MainPhone: '+6495005000' FirstName: 'John' LastName: 'Doe' Company: 'Example Company' Custom1: 'Custom Value 1' Custom2: 'Custom Value 2' Custom3: 'Custom Value 3' Custom4: 'Custom Value 4' ContactID: 4000000b-f002-4007-b00a-c00000000001 GroupID: 6000000b-f002-4007-b00a-c00000000002 MessageID: 1234-5678 Reference: An appointment reminder NotificationType: Webhook WebhookCallbackURL: https://www.example.com/webhook WebhookCallbackFormat: JSON SendTime: 2025-08-01T09:00:00 Timezone: New Zealand SubAccount: Business Unit One Department: Team 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 RouteNumber: +64800123123 Play: Connecting you now. - Tone: 2 PlaySection: Main KeypadOptionRequired: true 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: '' # Send TTS responses responses: '200': description: OK [successful submission] content: application/json: schema: type: object properties: MessageID: type: string description: Unique identifier for the API call. example: 1000000a-f002-4007-b00a-d00000000002 example: MessageID: 1000000a-f002-4007-b00a-d00000000002 links: TTSStatus: operationId: client.messaging.tts.status parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to track the message. TTSReschedule: operationId: client.messaging.tts.reschedule parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. TTSAbort: operationId: client.messaging.tts.abort parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. TTSNumberOfOperators: operationId: client.messaging.tts.pacing parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. TTSResubmit: operationId: client.messaging.tts.resubmit parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to retry the message. '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /tts/{MessageID}: get: # Get TTS Status tags: - TTS summary: TTS Details description: | 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. > [!TIP] > Timeout your polls after 6 hours with no result. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. > [!note] > Consider the [Send Result Webhook](#tag/tts/webhook/POST/resultwebhook) for efficiency. operationId: client.messaging.tts.status security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' # Get TTS Status responses responses: '200': description: OK [message found] content: application/json: schema: allOf: - $ref: '#/components/schemas/Message_Detail' - $ref: '#/components/schemas/Pagination' - type: object properties: Recipients: type: array description: List of recipients for the message. items: allOf: - type: object properties: Type: type: string description: The type of message this data relates to. enum: [SMS, Email, Voice, Fax] example: Voice DestSeq: $ref: '#/components/schemas/DestSeq' Destination: type: string description: The destination address (e.g. phone number, email address). example: '+6495006000' ContactID: $ref: '#/components/schemas/ContactID' Status: $ref: '#/components/schemas/MessageStatus' Result: type: string description: 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. examples: - SentOK - Busy - $ref: '#/components/schemas/Recipients_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '500': $ref: '#/components/responses/500ServerError' ### End 'TTS' Module ### '/tts/{MessageID}/reschedule': patch: tags: - TTS summary: Reschedule description: | This endpoint allows you to reschedule a previously delayed message to be sent at a new time. operationId: client.messaging.tts.reschedule security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Reschedule] example: Reschedule '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/tts/{MessageID}/abort': patch: tags: - TTS summary: Abort description: | This endpoint allows you to abort a previously delayed message. operationId: client.messaging.tts.abort security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Abort] example: Abort '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/tts/{MessageID}/resubmit': patch: tags: - TTS summary: Resubmit description: | This endpoint allows you to retry sending a previously failed message. operationId: client.messaging.tts.resubmit security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Resubmit] example: Resubmit '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/tts/{MessageID}/pacing': patch: tags: - TTS summary: Number Of Operators description: | This endpoint allows you to adjust the `NumberOfOperators` configured for a pending message. operationId: client.messaging.tts.pacing security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ NumberOfOperators ] properties: NumberOfOperators: $ref: '#/components/schemas/NumberOfOperators' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Pacing] example: Pacing '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' ### Start 'Voice' Module ### # /voice: # Send Voice post: tags: - Voice summary: Send Voice description: | 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. operationId: client.messaging.voice.sendmessage security: - bearerAuth: [] # The Accept header is optional #parameters: # - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object properties: MessageToPeople: type: string maxLength: 5000 description: | 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`. example: '[Base64 encoded data]' TemplateID: $ref: "#/components/schemas/TemplateID" Destination: $ref: "#/components/schemas/Destination" ToNumber: $ref: "#/components/schemas/ToNumber" Destinations: $ref: "#/components/schemas/Destinations" ContactID: $ref: "#/components/schemas/ContactID" GroupID: $ref: "#/components/schemas/GroupID" MessageID: $ref: "#/components/schemas/MessageID" Reference: $ref: "#/components/schemas/Reference" NotificationType: $ref: "#/components/schemas/NotificationType" WebhookCallbackURL: $ref: "#/components/schemas/WebhookCallbackURL" WebhookCallbackFormat: $ref: "#/components/schemas/WebhookCallbackFormat" ReportTo: $ref: "#/components/schemas/ReportTo" SendTime: $ref: "#/components/schemas/SendTime" Timezone: $ref: "#/components/schemas/Timezone" SubAccount: $ref: "#/components/schemas/SubAccount" Department: $ref: "#/components/schemas/Department" MessageToAnswerPhones: type: string maxLength: 10000 description: | 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. example: '[Base64 encoded data]' AnswerPhoneMode: type: string default: NDAS description: 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). examples: - NDAS - DAS - NDAF - DAF Keypads: type: array description: Detect if the recipient presses a keypad option and perform an action. items: type: object properties: Tone: type: integer minimum: 0 maximum: 9 description: The keypad button. example: 1 Play: type: string description: Message to play when the keypad button is pressed. example: [Base64 encoded data] RouteNumber: type: string format: phone description: If specified, the call will be diverted to this number when the keypad button is pressed. example: '6421000001' PlaySection: type: string description: | 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. examples: - Main - AnswerPhone - WrongKey KeypadOptionRequired: type: boolean default: false description: | 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. examples: - false - true CallRouteMessageOnWrongKey: type: string description: 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". example: [Base64 encoded data] CallRouteMessageToPeople: type: string description: Audio data played when a keypad option is pressed (WAV format, 16-bit, 8000hz). E.g. "Connecting you now." example: [Base64 encoded data] CallRouteMessageToOperators: type: string description: Audio data played to the call centre representative answering the connected call (WAV format, 16-bit, 8000hz). E.g. "Incoming Text To Speech call." example: [Base64 encoded data] NumberOfOperators: $ref: '#/components/schemas/NumberOfOperators' RetryAttempts: type: integer minimum: 0 maximum: 5 description: | 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. example: 1 RetryPeriod: type: integer minimum: 0 maximum: 60 description: Minutes to wait between Retry Attempts. example: 5 CallerID: type: string format: phone description: Sets the Caller ID used on the call (must be E.164 format and whitelisted under your account). example: +6495005000 Options: type: string description: 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. Mode: $ref: "#/components/schemas/TestMode" # Send Voice examples examples: 'Send a simple Voice message': value: MessageToPeople: '[Base64 encoded data]' Destination: '021-000001' 'Send to an Address Book Contact': value: MessageToPeople: '[Base64 encoded data]' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Send to an Address Book Group': value: MessageToPeople: '[Base64 encoded data]' GroupID: 4000000b-f002-4007-b00a-c00000000002 'Send a Template to Two Contacts': value: TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: '021-000001' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Display all parameters': value: MessageToPeople: '[Base64 encoded data]' TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: '+6495005000' Destinations: - ContactID: 4000000b-f002-4007-b00a-c00000000001 - GroupID: 6000000b-f002-4007-b00a-c00000000002 - MainPhone: '+6495005000' FirstName: 'John' LastName: 'Doe' Company: 'Example Company' Custom1: 'Custom Value 1' Custom2: 'Custom Value 2' Custom3: 'Custom Value 3' Custom4: 'Custom Value 4' ContactID: 4000000b-f002-4007-b00a-c00000000001 GroupID: 6000000b-f002-4007-b00a-c00000000002 MessageID: 1234-5678 Reference: An appointment reminder NotificationType: Webhook WebhookCallbackURL: https://www.example.com/webhook WebhookCallbackFormat: JSON SendTime: 2025-08-01T09:00:00 Timezone: New Zealand SubAccount: Business Unit One Department: Team Alpha MessageToAnswerPhones: '[Base64 encoded data]' AnswerPhoneMode: NDAS Keypads: - Tone: 1 RouteNumber: +64800123123 Play: Connecting you now. - Tone: 2 PlaySection: Main KeypadOptionRequired: true CallRouteMessageOnWrongKey: [Base64 encoded data] CallRouteMessageToPeople: [Base64 encoded data] CallRouteMessageToOperators: [Base64 encoded data] NumberOfOperators: 5 RetryAttempts: 1 RetryPeriod: 5 CallerID: +6495005000 Options: '' # Send Voice responses responses: '200': description: OK [successful submission] content: application/json: schema: type: object properties: MessageID: type: string description: Unique identifier for the API call. example: 1000000a-f002-4007-b00a-d00000000002 example: MessageID: 1000000a-f002-4007-b00a-d00000000002 links: VoiceStatus: operationId: client.messaging.voice.status parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to track the message. VoiceReschedule: operationId: client.messaging.voice.reschedule parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. VoiceAbort: operationId: client.messaging.voice.abort parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. VoiceNumberOfOperators: operationId: client.messaging.voice.pacing parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. VoiceResubmit: operationId: client.messaging.voice.resubmit parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to retry the message. '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /voice/{MessageID}: get: # Get Voice Status tags: - Voice summary: Voice Details description: | 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. > [!TIP] > Timeout your polls after 6 hours with no result. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. > [!note] > Consider the [Send Result Webhook](#tag/voice/webhook/POST/resultwebhook) for efficiency. operationId: client.messaging.voice.status security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' # Get Voice Status responses responses: '200': description: OK [message found] content: application/json: schema: allOf: - $ref: '#/components/schemas/Message_Detail' - $ref: '#/components/schemas/Pagination' - type: object properties: Recipients: type: array description: List of recipients for the message. items: allOf: - type: object properties: Type: type: string description: The type of message this data relates to. enum: [SMS, Email, Voice, Fax] example: Voice DestSeq: $ref: '#/components/schemas/DestSeq' Destination: type: string description: The destination address (e.g. phone number, email address). example: '+6495006000' ContactID: $ref: '#/components/schemas/ContactID' Status: $ref: '#/components/schemas/MessageStatus' Result: type: string description: 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. examples: - SentOK - Busy - $ref: '#/components/schemas/Recipients_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '500': $ref: '#/components/responses/500ServerError' ### End 'Voice' Module ### '/voice/{MessageID}/reschedule': patch: tags: - Voice summary: Reschedule description: | This endpoint allows you to reschedule a previously delayed message to be sent at a new time. operationId: client.messaging.voice.reschedule security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Reschedule] example: Reschedule '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/voice/{MessageID}/abort': patch: tags: - Voice summary: Abort description: | This endpoint allows you to abort a previously delayed message. operationId: client.messaging.voice.abort security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Abort] example: Abort '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/voice/{MessageID}/resubmit': patch: tags: - Voice summary: Resubmit description: | This endpoint allows you to retry sending a previously failed message. operationId: client.messaging.voice.resubmit security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Resubmit] example: Resubmit '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/voice/{MessageID}/pacing': patch: tags: - Voice summary: Number Of Operators description: | This endpoint allows you to adjust the `NumberOfOperators` configured for a pending message. operationId: client.messaging.voice.pacing security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ NumberOfOperators ] properties: NumberOfOperators: $ref: '#/components/schemas/NumberOfOperators' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Pacing] example: Pacing '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' ### Start 'Fax' Module ### # /fax: # Send Fax post: tags: - Fax summary: Send Fax description: | 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. operationId: client.messaging.fax.sendmessage security: - bearerAuth: [] # The Accept header is optional #parameters: # - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object properties: Files: $ref: "#/components/schemas/Files" TemplateID: $ref: "#/components/schemas/TemplateID" Destination: $ref: "#/components/schemas/Destination" ToNumber: $ref: "#/components/schemas/ToNumber" Destinations: $ref: "#/components/schemas/Destinations" ContactID: $ref: "#/components/schemas/ContactID" GroupID: $ref: "#/components/schemas/GroupID" MessageID: $ref: "#/components/schemas/MessageID" Reference: $ref: "#/components/schemas/Reference" NotificationType: $ref: "#/components/schemas/NotificationType" WebhookCallbackURL: $ref: "#/components/schemas/WebhookCallbackURL" WebhookCallbackFormat: $ref: "#/components/schemas/WebhookCallbackFormat" ReportTo: $ref: "#/components/schemas/ReportTo" SendTime: $ref: "#/components/schemas/SendTime" Timezone: $ref: "#/components/schemas/Timezone" SubAccount: $ref: "#/components/schemas/SubAccount" Department: $ref: "#/components/schemas/Department" CSID: type: string maxLength: 30 description: A human-readable Caller Sender ID (CSID) to be printed on the fax header. examples: - +64 9 500 6000 - My HP Fax Machine Resolution: type: string description: Quality of the fax image. High for better quality, low for faster delivery speed. enum: [Low, High] default: Low examples: - Low - High WatermarkFolder: type: string description: Location of Watermark file to use. example: Folder01 WatermarkFirstPage: type: string description: Watermark file to apply to the first page only. example: Watermark File Name.ps WatermarkAllPages: type: string description: Watermark file to apply to all pages. example: Watermark File Name.docx RetryAttempts: type: integer minimum: 0 maximum: 5 description: 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. example: 3 RetryPeriod: type: integer minimum: 0 maximum: 60 description: Minutes to wait between Retry Attempts. example: 1 Mode: $ref: "#/components/schemas/TestMode" # Send Fax examples examples: 'Send a simple Fax message': value: Files: - Name: 'My Example.pdf' Data: '[base-64 data - see the field description for sample data]' Destination: '09 500 6000' 'Send to an Address Book Contact': value: Files: - Name: 'My Example.pdf' Data: '[base-64 data - see the field description for sample data]' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Send to an Address Book Group': value: Files: - Name: 'My Example.pdf' Data: '[base-64 data - see the field description for sample data]' GroupID: 4000000b-f002-4007-b00a-c00000000002 'Send a Template to Two Contacts': value: TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: '09 500 6000' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Display all parameters': value: Files: - Name: 'My Example.pdf' Data: '[base-64 data - see the field description for sample data]' TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: 'john.doe@example.com' Destinations: - ContactID: 4000000b-f002-4007-b00a-c00000000001 - GroupID: 6000000b-f002-4007-b00a-c00000000002 - MainPhone: 'john.doe@example.com' FirstName: 'John' LastName: 'Doe' Company: 'Example Company' Custom1: 'Custom Value 1' Custom2: 'Custom Value 2' Custom3: 'Custom Value 3' Custom4: 'Custom Value 4' ContactID: 4000000b-f002-4007-b00a-c00000000001 GroupID: 6000000b-f002-4007-b00a-c00000000002 MessageID: 1234-5678 Reference: A medical script NotificationType: Webhook WebhookCallbackURL: https://www.example.com/webhook WebhookCallbackFormat: JSON SendTime: 2025-08-01T09:00:00 Timezone: New Zealand SubAccount: Business Unit One Department: Team Alpha CSID: My HP Fax Machine Resolution: High WatermarkFolder: Folder01 WatermarkFirstPage: Watermark File Name.ps WatermarkAllPages: Watermark File Name.docx RetryAttempts: 3 RetryPeriod: 1 # Send Fax responses responses: '200': description: OK [successful submission] content: application/json: schema: type: object properties: MessageID: type: string description: Unique identifier for the API call. example: 1000000a-f002-4007-b00a-d00000000002 example: MessageID: 1000000a-f002-4007-b00a-d00000000002 links: FaxStatus: operationId: client.messaging.fax.status parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to track the message. FaxReschedule: operationId: client.messaging.fax.reschedule parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. FaxAbort: operationId: client.messaging.fax.abort parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. FaxResubmit: operationId: client.messaging.fax.resubmit parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to retry the message. '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /fax/{MessageID}: get: # Get Fax Status tags: - Fax summary: Fax Details description: | 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. > [!TIP] > Timeout your polls after 6 hours with no result. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. > [!note] > Consider the [Send Result Webhook](#tag/fax/webhook/POST/resultwebhook) for efficiency. operationId: client.messaging.fax.status security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' # Get Fax Status responses responses: '200': description: OK [message found] content: application/json: schema: allOf: - $ref: '#/components/schemas/Message_Detail' - $ref: '#/components/schemas/Pagination' - type: object properties: Recipients: type: array description: List of recipients for the message. items: allOf: - type: object properties: Type: type: string description: The type of message this data relates to. enum: [SMS, Email, Voice, Fax] example: Fax DestSeq: $ref: '#/components/schemas/DestSeq' Destination: type: string description: The destination address (e.g. phone number, email address). example: '+6495006000' ContactID: $ref: '#/components/schemas/ContactID' Status: $ref: '#/components/schemas/MessageStatus' Result: type: string description: The final delivery result. For a list of possible values, see [Fax](https://www.tnz.co.nz/help/fax-delivery-result-codes) result codes. examples: - Sent OK - No Answer - $ref: '#/components/schemas/Recipients_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '500': $ref: '#/components/responses/500ServerError' ### End 'Fax' Module ### '/fax/{MessageID}/reschedule': patch: tags: - Fax summary: Reschedule description: | This endpoint allows you to reschedule a previously delayed message to be sent at a new time. operationId: client.messaging.fax.reschedule security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Reschedule] example: Reschedule '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/fax/{MessageID}/abort': patch: tags: - Fax summary: Abort description: | This endpoint allows you to abort a previously delayed message. operationId: client.messaging.fax.abort security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Abort] example: Abort '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/fax/{MessageID}/resubmit': patch: tags: - Fax summary: Resubmit description: | This endpoint allows you to retry sending a previously failed message. operationId: client.messaging.fax.resubmit security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Resubmit] example: Resubmit '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' ### Start 'WhatsApp' Module ### # /whatsapp: # Send WhatsApp Message post: tags: - WhatsApp summary: Send WhatsApp Message description: | 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. operationId: client.messaging.whatsapp.sendmessage security: - bearerAuth: [] # The Accept header is optional #parameters: # - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object properties: TemplateID: type: string format: uuid description: | 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. example: 123e4567-e89b-12d3-a456-426614174000 Message: type: string maxLength: 1000 description: The WhatsApp text message to send within the 24-hour conversation window. If omitted, the Template will be used. example: '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: type: string description: If WhatsApp delivery fails, try another method (in the order listed). enum: [None, SMS, Voice, RCS] default: 'None' example: 'SMS, Voice' Files: $ref: "#/components/schemas/Files" FromNumber: type: string maxLength: 100 description: The WhatsApp Business phone number to send from. example: '+6495006000' Destination: $ref: "#/components/schemas/Destination" ToNumber: $ref: "#/components/schemas/ToNumber" Destinations: $ref: "#/components/schemas/Destinations" ContactID: $ref: "#/components/schemas/ContactID" GroupID: $ref: "#/components/schemas/GroupID" MessageID: $ref: "#/components/schemas/MessageID" Reference: $ref: "#/components/schemas/Reference" NotificationType: $ref: "#/components/schemas/NotificationType" WebhookCallbackURL: $ref: "#/components/schemas/WebhookCallbackURL" WebhookCallbackFormat: $ref: "#/components/schemas/WebhookCallbackFormat" SendTime: $ref: "#/components/schemas/SendTime" Timezone: $ref: "#/components/schemas/Timezone" SubAccount: $ref: "#/components/schemas/SubAccount" Department: $ref: "#/components/schemas/Department" Mode: $ref: "#/components/schemas/TestMode" required: - TemplateID - Message - FromNumber # Send WhatsApp examples examples: 'Send a simple WhatsApp message': value: TemplateID: 123e4567-e89b-12d3-a456-426614174000 Message: 'Hello [[Custom1]], this is a notification from [[Custom2]]. Your [[Custom3]] plan is due for renewal on [[Custom4]]. Reply STOP to OptOut.' FallbackMode: 'SMS' FromNumber: '+6495006000' Destinations: - ToNumber: '+6421000001' FirstName: 'John' LastName: 'Doe' Company: 'Company One Ltd.' Custom1: 'John' Custom2: 'Company One Ltd' Custom3: 'Premium' Custom4: '2026-12-31' 'Display all parameters': value: TemplateID: 123e4567-e89b-12d3-a456-426614174000 Message: 'Hello [[Custom1]], this is a notification from [[Custom2]]. Your [[Custom3]] plan is due for renewal on [[Custom4]]. View the renewal document at [[File1]]. Reply STOP to OptOut.' FallbackMode: 'SMS, Voice' FromNumber: '+6495006000' Destinations: - ContactID: 4000000b-f002-4007-b00a-c00000000001 - GroupID: 6000000b-f002-4007-b00a-c00000000002 - ToNumber: '+6421000001' FirstName: 'John' LastName: 'Doe' Company: 'Company One Ltd.' Custom1: 'John' Custom2: 'Company One Ltd' Custom3: 'Premium' Custom4: '2026-12-31' Custom5: '' Custom6: '' Custom7: '' Custom8: '' Custom9: '' ContactID: 4000000b-f002-4007-b00a-c00000000001 MessageID: 1234-5678 Reference: A plan renewal reminder NotificationType: Webhook WebhookCallbackURL: https://www.example.com/webhook WebhookCallbackFormat: JSON SendTime: 2025-08-01T09:00:00 Timezone: New Zealand SubAccount: Business Unit One Department: Team Alpha Files: - Name: 'My Example.pdf' Data: '[base-64 data - see the field description for sample data]' # Send WhatsApp responses responses: '200': description: OK [successful submission] content: application/json: schema: type: object properties: MessageID: type: string description: Unique identifier for the API call. example: 1000000a-f002-4007-b00a-d00000000002 example: MessageID: 1000000a-f002-4007-b00a-d00000000002 links: WhatsAppStatus: operationId: client.messaging.whatsapp.status parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to track the message. WhatsAppReschedule: operationId: client.messaging.whatsapp.reschedule parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. WhatsAppAbort: operationId: client.messaging.whatsapp.abort parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /whatsapp/{MessageID}: get: # Get WhatsApp Status tags: - WhatsApp summary: WhatsApp Details description: | 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. > [!TIP] > Timeout your polls after 6 hours with no result. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. > [!note] > Consider the [Send Result Webhook](#tag/sms/webhook/POST/resultwebhook) for efficiency. operationId: client.messaging.whatsapp.status security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' # Get WhatsApp Status responses responses: '200': description: OK [message found] content: application/json: schema: allOf: - $ref: '#/components/schemas/Message_Detail' - $ref: '#/components/schemas/Pagination' - type: object properties: Recipients: type: array description: List of recipients for the message. items: allOf: - type: object properties: Type: type: string description: The type of message this data relates to. enum: [WhatsApp, SMS, Email, Voice, Fax] example: WhatsApp DestSeq: $ref: '#/components/schemas/DestSeq' Destination: type: string description: The destination address (e.g. phone number, email address). Telephone/mobile numbers are supplied in E.164 internationalised format. example: '+64212223333' ContactID: $ref: '#/components/schemas/ContactID' Status: $ref: '#/components/schemas/MessageStatus' Result: type: string description: The final delivery result. For a list of possible values, see [WhatsApp](https://www.tnz.co.nz/help/whatsapp-delivery-result-codes) result codes. examples: - Delivered - Bad Number - $ref: '#/components/schemas/Recipients_Detail' - type: object properties: SMSReplies: type: array description: A list of replies for this recipient. items: $ref: '#/components/schemas/SMSReplies_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '500': $ref: '#/components/responses/500ServerError' '/whatsapp/received': get: tags: - WhatsApp summary: Inbound Messages description: | 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`. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. > [!note] > Consider the [Inbound SMS Webhook](#tag/sms/webhook/POST/inboundsmswebhook) for efficiency. operationId: client.messaging.whatsapp.received security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - name: timePeriod in: query required: true description: Return results from the last _x_ minutes (e.g. last 5 minutes). example: 10 schema: type: integer minimum: 1 maximum: 1440 - name: dateFrom in: query required: false description: Return results from the specified date in the API User's local time. Maximum 7 days. example: 2025-08-01T00:00:00 schema: type: string - name: dateTo in: query required: false description: Return results to the specified date in the API User's local time. Maximum 7 days. example: 2025-08-01T12:00:00 schema: type: string - $ref: '#/components/parameters/RecordsPerPage' - $ref: '#/components/parameters/Page' responses: '200': description: OK [message found] content: application/json: schema: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: Messages: type: array description: List of messages found. items: type: object properties: ReceivedID: $ref: '#/components/schemas/UniqueID' MessageID: type: string format: uuid description: 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. example: 7000000a-f002-4007-b00a-d00000000002 JobNum: $ref: '#/components/schemas/JobNumber' SubAccount: $ref: '#/components/schemas/SubAccount' Department: $ref: '#/components/schemas/Department' ReceivedTimeLocal: $ref: '#/components/schemas/ReceivedTimeLocal' ReceivedTimeUTC: $ref: '#/components/schemas/ReceivedTimeUTC' ReceivedTimeUTC_RFC3339: $ref: '#/components/schemas/ReceivedTimeUTC_RFC3339' From: $ref: '#/components/schemas/SMSFrom' ContactID: $ref: '#/components/schemas/ContactID' MessageText: $ref: '#/components/schemas/ReceivedMessage' Timezone: $ref: '#/components/schemas/Timezone' Version: $ref: '#/components/schemas/Version' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '500': $ref: '#/components/responses/500ServerError' ### End 'WhatsApp' Module ### '/whatsapp/{MessageID}/reschedule': patch: tags: - WhatsApp summary: Reschedule description: | This endpoint allows you to reschedule a previously delayed message to be sent at a new time. operationId: client.messaging.whatsapp.reschedule security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Reschedule] example: Reschedule '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/whatsapp/{MessageID}/abort': patch: tags: - WhatsApp summary: Abort description: | This endpoint allows you to abort a previously delayed message. operationId: client.messaging.whatsapp.abort security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Abort] example: Abort '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' ### Start 'RCS' Module ### # /rcs: # Send RCS Message post: tags: - RCS summary: Send RCS Message description: | Send an RCS message to one or more recipients. operationId: client.messaging.rcs.sendmessage security: - bearerAuth: [] # The Accept header is optional #parameters: # - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object properties: Message: type: string maxLength: 1000 description: 'The text message to send. Alternatively, you may use the `TemplateID` parameter.' example: '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: $ref: "#/components/schemas/TemplateID" Destination: $ref: "#/components/schemas/Destination" ToNumber: $ref: "#/components/schemas/ToNumber" Destinations: $ref: "#/components/schemas/Destinations" ContactID: $ref: "#/components/schemas/ContactID" GroupID: $ref: "#/components/schemas/GroupID" MessageID: $ref: "#/components/schemas/MessageID" Reference: $ref: "#/components/schemas/Reference" NotificationType: $ref: "#/components/schemas/NotificationType" WebhookCallbackURL: $ref: "#/components/schemas/WebhookCallbackURL" WebhookCallbackFormat: $ref: "#/components/schemas/WebhookCallbackFormat" SendTime: $ref: "#/components/schemas/SendTime" Timezone: $ref: "#/components/schemas/Timezone" SubAccount: $ref: "#/components/schemas/SubAccount" Department: $ref: "#/components/schemas/Department" FromNumber: type: string description: Sets the Sender ID on your sent message (in E164 format without the leading +). example: '61408080909' SMSEmailReply: type: string format: email description: The email address to send SMS Reply notifications to. This may be ignored if a different Reply Notification rule is configured. example: 'reply@example.com' Files: $ref: "#/components/schemas/Files" FallbackMode: type: string description: If the RCS delivery fails, try another method (in the order listed). enum: [None, SMS, Voice, WhatsApp] default: 'None' example: 'Voice' Mode: $ref: "#/components/schemas/TestMode" # Send RCS examples examples: 'Send a simple RCS message': value: Message: 'Hello, this is an RCS notification from Company One Ltd. Reply STOP to OptOut.' Destination: '021-000001' 'Send to an Address Book Contact': value: Message: 'Hello [[FirstName]], this is an RCS notification from Company One Ltd. Reply STOP to OptOut.' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Send to an Address Book Group': value: Message: 'Hello [[FirstName]], this is an RCS notification from Company One Ltd. Reply STOP to OptOut.' GroupID: 4000000b-f002-4007-b00a-c00000000002 'Send a Template to Two Contacts': value: TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: '021-000001' ContactID: 6000000b-f002-4007-b00a-c00000000001 'Display all parameters': value: Message: 'Hello [[FirstName]], this is an RCS notification from Company One Ltd. Reply STOP to OptOut.' TemplateID: 123e4567-e89b-12d3-a456-426614174000 Destination: '+6421000001' Destinations: - ContactID: 4000000b-f002-4007-b00a-c00000000001 - GroupID: 6000000b-f002-4007-b00a-c00000000002 - ToNumber: '+6421000001' FirstName: 'John' LastName: 'Doe' Company: 'Example Company' Custom1: 'Custom Value 1' Custom2: 'Custom Value 2' Custom3: 'Custom Value 3' Custom4: 'Custom Value 4' ContactID: 4000000b-f002-4007-b00a-c00000000001 GroupID: 6000000b-f002-4007-b00a-c00000000002 MessageID: 1234-5678 Reference: An appointment reminder NotificationType: Webhook WebhookCallbackURL: https://www.example.com/webhook WebhookCallbackFormat: JSON SendTime: 2025-08-01T09:00:00 Timezone: New Zealand SubAccount: Business Unit One Department: Team Alpha FromNumber: 61410023004 SMSEmailReply: reply@example.com CharacterConversion: true Files: - Name: 'My Example.pdf' Data: '[base-64 data - see the field description for sample data]' # Send RCS responses responses: '200': description: OK [successful submission] content: application/json: schema: type: object properties: MessageID: type: string description: Unique identifier for the API call. example: 1000000a-f002-4007-b00a-d00000000002 example: MessageID: 1000000a-f002-4007-b00a-d00000000002 links: RCSStatus: operationId: client.messaging.rcs.status parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to track the message. RCSReschedule: operationId: client.messaging.rcs.reschedule parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. RCSAbort: operationId: client.messaging.rcs.abort parameters: MessageID: "$response.body#/MessageID" description: > Use the `MessageID` to modify the message. '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /rcs/{MessageID}: get: # Get RCS Status tags: - RCS summary: RCS Details description: | 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. > [!TIP] > Timeout your polls after 6 hours with no result. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. > [!note] > Consider the [Send Result Webhook](#tag/sms/webhook/POST/resultwebhook) for efficiency. operationId: client.messaging.rcs.status security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' # Get RCS Status responses responses: '200': description: OK [message found] content: application/json: schema: allOf: - $ref: '#/components/schemas/Message_Detail' - $ref: '#/components/schemas/Pagination' - type: object properties: Recipients: type: array description: List of recipients for the message. items: allOf: - type: object properties: Type: type: string description: The type of message this data relates to. enum: [RCS, SMS, Email, Voice, Fax] example: RCS DestSeq: $ref: '#/components/schemas/DestSeq' Destination: type: string description: The destination address (e.g. phone number, email address). Telephone/mobile numbers are supplied in E.164 internationalised format. example: '+64212223333' ContactID: $ref: '#/components/schemas/ContactID' Status: $ref: '#/components/schemas/MessageStatus' Result: type: string description: The final delivery result. For a list of possible values, see [WhatsApp](https://www.tnz.co.nz/help/whatsapp-delivery-result-codes) result codes. examples: - Delivered - Bad Number - $ref: '#/components/schemas/Recipients_Detail' - type: object properties: SMSReplies: type: array description: A list of replies for this recipient. items: $ref: '#/components/schemas/SMSReplies_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '500': $ref: '#/components/responses/500ServerError' '/rcs/received': get: tags: - RCS summary: Inbound Messages description: | 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`. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. > [!note] > Consider the [Inbound SMS Webhook](#tag/sms/webhook/POST/inboundsmswebhook) for efficiency. operationId: client.messaging.rcs.received security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - name: timePeriod in: query required: true description: Return results from the last _x_ minutes (e.g. last 5 minutes). example: 10 schema: type: integer minimum: 1 maximum: 1440 - name: dateFrom in: query required: false description: Return results from the specified date in the API User's local time. Maximum 7 days. example: 2025-08-01T00:00:00 schema: type: string - name: dateTo in: query required: false description: Return results to the specified date in the API User's local time. Maximum 7 days. example: 2025-08-01T12:00:00 schema: type: string - $ref: '#/components/parameters/RecordsPerPage' - $ref: '#/components/parameters/Page' responses: '200': description: OK [message found] content: application/json: schema: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: Messages: type: array description: List of messages found. items: type: object properties: ReceivedID: $ref: '#/components/schemas/UniqueID' MessageID: type: string format: uuid description: 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. example: 7000000a-f002-4007-b00a-d00000000002 JobNum: $ref: '#/components/schemas/JobNumber' SubAccount: $ref: '#/components/schemas/SubAccount' Department: $ref: '#/components/schemas/Department' ReceivedTimeLocal: $ref: '#/components/schemas/ReceivedTimeLocal' ReceivedTimeUTC: $ref: '#/components/schemas/ReceivedTimeUTC' ReceivedTimeUTC_RFC3339: $ref: '#/components/schemas/ReceivedTimeUTC_RFC3339' From: $ref: '#/components/schemas/SMSFrom' ContactID: $ref: '#/components/schemas/ContactID' MessageText: $ref: '#/components/schemas/ReceivedMessage' Timezone: $ref: '#/components/schemas/Timezone' Version: $ref: '#/components/schemas/Version' '401': $ref: '#/components/responses/401Unauthorized' '500': $ref: '#/components/responses/500ServerError' ### End 'RCS' Module ### '/rcs/{MessageID}/reschedule': patch: tags: - RCS summary: Reschedule description: | This endpoint allows you to reschedule a previously delayed message to be sent at a new time. operationId: client.messaging.rcs.reschedule security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ SendTime ] properties: SendTime: $ref: '#/components/schemas/UpdateSendTime' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Reschedule] example: Reschedule '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/rcs/{MessageID}/abort': patch: tags: - RCS summary: Abort description: | This endpoint allows you to abort a previously delayed message. operationId: client.messaging.rcs.abort security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/MessageID' - $ref: '#/components/parameters/Accept' responses: '200': description: OK [message found] content: application/json: schema: type: object properties: ActionResult: $ref: '#/components/schemas/QueryResult' MessageID: $ref: '#/components/schemas/MessageID' JobNum: $ref: '#/components/schemas/JobNumber' Status: $ref: '#/components/schemas/JobStatus' Action: type: string description: The action this API call has performed. enum: [Abort] example: Abort '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404IDNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' ### Start 'Address Book' Module ### # '/addressbook/contact': # Create a new Address Book Contact post: tags: - Address Book summary: "Contact: Create" description: Create a new contact in the address book. operationId: client.addressbook.contact.create security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Contact_Object' responses: '200': description: OK [contact created] content: application/json: schema: $ref: '#/components/schemas/Contact_Detail' links: GetContactDetail: operationId: client.addressbook.contact.details parameters: ContactID: "$response.body#/ContactID" description: > The ContactID returned in the response is the unique `ContactID` for the entry. GetContactGroups: operationId: client.addressbook.contact.groups.list parameters: ContactID: "$response.body#/ContactID" description: > The ContactID returned in the response is the unique `ContactID` for the entry. PatchContact: operationId: client.addressbook.contact.update parameters: ContactID: "$response.body#/ContactID" description: > The ContactID returned in the response is the unique `ContactID` for the entry. DeleteContact: operationId: client.addressbook.contact.delete parameters: ContactID: "$response.body#/ContactID" description: > The ContactID returned in the response is the unique `ContactID` for the entry. DeleteContactFromGroup: operationId: client.addressbook.contact.groups.delete parameters: ContactID: "$response.body#/ContactID" description: > The ContactID returned in the response is the unique `ContactID` for the entry. '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' '/addressbook/contact/search': # Search for contacts using various criteria get: tags: - Address Book summary: "Contact: Search" description: Search for contacts using various criteria. Partial matches are supported for most text fields. operationId: client.addressbook.contact.search security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/RecordsPerPage' - name: EmailAddress in: query description: "Full match search by email address." schema: type: string format: email - name: MobilePhone in: query description: "Partial match search by mobile phone number." schema: type: string format: phone - name: MainPhone in: query description: "Partial match search by main phone number." schema: type: string - name: Attention in: query description: "Partial match search by attention field." schema: type: string - name: FirstName in: query description: "Partial match search by first name." schema: type: string - name: LastName in: query description: "Partial match search by last name." schema: type: string - name: Company in: query description: "Partial match search by company name." schema: type: string responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: Contacts: type: array items: $ref: '#/components/schemas/Contact_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '500': $ref: '#/components/responses/500ServerError' '/addressbook/contact/list': # Retrieve a list of all contacts in the address book get: tags: - Address Book summary: "Contact: List" description: Retrieve a list of all contacts in the address book. operationId: client.addressbook.contact.list security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/RecordsPerPage' responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: Contacts: type: array items: $ref: '#/components/schemas/Contact_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '500': $ref: '#/components/responses/500ServerError' /addressbook/contact/{ContactID}/group/list: # Retrieve a list of groups that a specific contact belongs to get: tags: - Address Book summary: "Contact: List Groups" description: Retrieve a list of groups that a specific contact belongs to. operationId: client.addressbook.contact.groups.list security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContactID' responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: Contact: $ref: '#/components/schemas/Contact_Detail' Groups: type: array items: $ref: '#/components/schemas/Group_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '404': $ref: '#/components/responses/404RecordNotFound' '500': $ref: '#/components/responses/500ServerError' '/addressbook/contact/{ContactID}': # Retrieve the details of a specific contact by their ContactID get: tags: - Address Book summary: "Contact: Details" description: Retrieve the details of a specific contact by their ContactID. operationId: client.addressbook.contact.details security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContactID' responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/Contact_Detail' - type: object properties: Groups: type: array items: $ref: '#/components/schemas/GroupID' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '404': $ref: '#/components/responses/404RecordNotFound' '500': $ref: '#/components/responses/500ServerError' patch: # Update the details of an existing contact tags: - Address Book summary: "Contact: Update" description: Update the details of an existing contact. operationId: client.addressbook.contact.update security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContactID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Contact_Object' responses: '200': description: OK [contact updated] content: application/json: schema: $ref: '#/components/schemas/Contact_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' delete: # Delete a contact from the address book tags: - Address Book summary: "Contact: Delete" description: Delete a contact from the address book. operationId: client.addressbook.contact.delete security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContactID' responses: '200': description: OK [contact deleted] content: application/json: schema: $ref: '#/components/schemas/Contact_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404RecordNotFound' '403': $ref: '#/components/responses/403Forbidden' '500': $ref: '#/components/responses/500ServerError' /addressbook/group: # Create a new group in the address book post: tags: - Address Book summary: "Group: Create" description: Create a new group in the address book. operationId: client.addressbook.group.create security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Group_Object' responses: '200': description: OK [group created] content: application/json: schema: $ref: '#/components/schemas/Group_Detail' links: GetGroupDetail: operationId: client.addressbook.group.details parameters: GroupID: "$response.body#/GroupID" description: > The GroupID returned in the response is the unique `GroupID` for the entry. GetGroupContacts: operationId: client.addressbook.group.contacts.list parameters: GroupID: "$response.body#/GroupID" description: > The GroupID returned in the response is the unique `GroupID` for the entry. PatchGroup: operationId: client.addressbook.group.update parameters: GroupID: "$response.body#/GroupID" description: > The GroupID returned in the response is the unique `GroupID` for the entry. DeleteGroup: operationId: client.addressbook.group.delete parameters: GroupID: "$response.body#/GroupID" description: > The GroupID returned in the response is the unique `GroupID` for the entry. DeleteContactFromGroup: operationId: client.addressbook.contact.groups.delete parameters: GroupID: "$response.body#/GroupID" description: > The GroupID returned in the response is the unique `GroupID` for the entry. '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /addressbook/group/list: # Retrieve a list of all groups in the address book get: tags: - Address Book summary: "Group: List" description: Retrieve a list of all groups in the address book. operationId: client.addressbook.group.list security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/RecordsPerPage' responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: Groups: type: array items: $ref: '#/components/schemas/Group_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '500': $ref: '#/components/responses/500ServerError' /addressbook/group/{GroupID}/contact/list: # Retrieve a list of contacts that belong to a specific group get: tags: - Address Book summary: "Group: List Contacts" description: Retrieve a list of contacts that belong to a specific group. operationId: client.addressbook.group.contacts.list security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/GroupID' responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: Group: $ref: '#/components/schemas/Group_Detail' Contacts: type: array items: $ref: '#/components/schemas/Contact_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '404': $ref: '#/components/responses/404RecordNotFound' '500': $ref: '#/components/responses/500ServerError' /addressbook/group/{GroupID}: # Retrieve the details of a specific group by its GroupID get: tags: - Address Book summary: "Group: Details" description: Retrieve the details of a specific group by its GroupID. operationId: client.addressbook.group.details security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/GroupID' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Group_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '404': $ref: '#/components/responses/404RecordNotFound' '500': $ref: '#/components/responses/500ServerError' patch: # Update the details of an existing group tags: - Address Book summary: "Group: Update" description: Update the details of an existing group. operationId: client.addressbook.group.update security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/GroupID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Group_Object' responses: '200': description: OK [group updated] content: application/json: schema: $ref: '#/components/schemas/Group_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' delete: # Delete a group from the address book tags: - Address Book summary: "Group: Delete" description: Delete a group from the address book. operationId: client.addressbook.group.delete security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/GroupID' responses: '200': description: OK [group deleted] content: application/json: schema: $ref: '#/components/schemas/Group_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '404': $ref: '#/components/responses/404RecordNotFound' '500': $ref: '#/components/responses/500ServerError' /addressbook/contact/{ContactID}/group: # Add an existing contact to an existing group patch: tags: - Address Book summary: "Contact: Add to Group" description: Add an existing contact to an existing group (add an association). operationId: client.addressbook.contact.groups.add security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContactID' requestBody: required: true content: application/json: schema: type: object properties: GroupID: $ref: '#/components/parameters/GroupID' responses: '200': description: OK [contact added to group] content: application/json: schema: type: object properties: Group: $ref: '#/components/schemas/Group_Detail' Contact: $ref: '#/components/schemas/Contact_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '404': $ref: '#/components/responses/404RecordNotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /addressbook/contact/{ContactID}/group/{GroupID}: # Remove an existing contact from an existing group delete: tags: - Address Book summary: "Contact: Remove from Group" description: Remove an existing contact from an existing group (remove/delete an association). operationId: client.addressbook.contact.groups.delete security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/ContactID' - $ref: '#/components/parameters/GroupID' responses: '200': description: OK [contact removed from group] content: application/json: schema: type: object properties: Group: $ref: '#/components/schemas/Group_Detail' Contact: $ref: '#/components/schemas/Contact_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '404': $ref: '#/components/responses/404RecordNotFound' '500': $ref: '#/components/responses/500ServerError' ### End 'Address Book' Module ### ### Start 'OptOut' Module ### # /optout/list: # Retrieve a list of all opt-out entries get: tags: - OptOut summary: List OptOuts description: |- List all opt-out entries. > [!CAUTION] > Limit your polls to 1 per second to avoid rate limits. operationId: client.configuration.optout.list security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - name: timePeriod in: query required: false description: Return results that were Created in the past _x_ days. example: 5 schema: type: integer - name: destType in: query required: false description: Return results matching the DestType. You may specify just one DestType. example: SMS schema: type: string - name: contactID in: query required: false description: Return results matching the given ContactID. schema: type: string - name: recordsPerPage in: query required: false description: Number of records to return per page (default is 100, maximum is 1000). example: 100 schema: type: integer minimum: 5 maximum: 1000 - name: page in: query required: false description: Page number to retrieve. default: 1 example: 1 schema: type: integer default: 1 responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/Pagination' - type: object properties: OptOuts: type: array description: List of opt-out entries found. items: $ref: '#/components/schemas/OptOut_Detail' '401': $ref: '#/components/responses/401Unauthorized' '500': $ref: '#/components/responses/500ServerError' /optout: post: # Create a new entry in the OptOut List tags: - OptOut summary: "OptOut: Create" description: Create a new entry in the OptOut List. operationId: client.configuration.optout.create security: - bearerAuth: [] # The Accept header is optional #parameters: # - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: required: [ DestType ] $ref: '#/components/schemas/OptOut_Object' responses: '200': description: OK [entry created] content: application/json: schema: description: The content of the new entry. $ref: '#/components/schemas/OptOut_Detail' links: GetOptOutDetail: operationId: client.configuration.optout.details parameters: OptOutID: "$response.body#/ID" description: > The ID returned in the response is the unique `OptOutID` for the entry. PatchOptOut: operationId: client.configuration.optout.update parameters: OptOutID: "$response.body#/ID" description: > The ID returned in the response is the unique `OptOutID` for the entry. DeleteOptOut: operationId: client.configuration.optout.delete parameters: OptOutID: "$response.body#/ID" description: > The ID returned in the response is the unique `OptOutID` for the entry. '400': $ref: '#/components/responses/400BadRequest' example: { "Result": "Failed", "ErrorMessage": "Unsupported DestType - Supported DestType: Fax / Text / SMS / Email / Speech / Voice." } '401': $ref: '#/components/responses/401Unauthorized' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /optout/batch: # Create multiple entries in the OptOut List post: tags: - OptOut summary: Create OptOuts (Batch) description: |- 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. operationId: client.configuration.optout.create security: - bearerAuth: [] # The Accept header is optional #parameters: # - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: type: object required: [ DestType ] properties: DestType: type: string description: The type of message to block in this OptOut request ('SMS', 'Email', 'Voice', 'Fax'). You may specify multiple types, comma delimited. examples: - SMS - Email - SMS,Voice - SMS,Email Destination: type: string description: A single destination to be opted-out. Telephone numbers must be in E.164 format. examples: - '+6421003004' - john.doe@example.com - '095006000' Destinations: type: array description: An array of destinations to be opted-out. Telephone numbers must be in E.164 format. items: type: string description: An array of contact numbers and emails. example: '+6421003004' ContactID: type: string description: A single Contact ID from your Address Book to be opted-out. example: 6000000b-f002-4007-b00a-c00000000001 ContactIDs: type: array description: An array of ContactIDs to be opted-out. items: type: string description: An array of Contact IDs. example: 6000000b-f002-4007-b00a-c00000000001 SubAccount: type: string default: "" description: The SubAccount the opt-out entry should apply to. Omit to apply the entry to all SubAccounts. example: Business Unit One Department: type: string default: "" description: The Department the opt-out entry should apply to. Omit to apply the entry to all Departments. example: Team Alpha responses: '200': description: OK [entry created] content: application/json: schema: description: The content of the new entry. $ref: '#/components/schemas/OptOut_Detail' links: GetOptOutDetail: operationId: client.configuration.optout.details parameters: OptOutID: "$response.body#/ID" description: > The ID returned in the response is the unique `OptOutID` for the entry. PatchOptOut: operationId: client.configuration.optout.update parameters: OptOutID: "$response.body#/ID" description: > The ID returned in the response is the unique `OptOutID` for the entry. DeleteOptOut: operationId: client.configuration.optout.delete parameters: OptOutID: "$response.body#/ID" description: > The ID returned in the response is the unique `OptOutID` for the entry. '400': $ref: '#/components/responses/400BadRequest' example: { "Result": "Failed", "ErrorMessage": "Unsupported DestType - Supported DestType: Fax / Text / SMS / Email / Speech / Voice." } '401': $ref: '#/components/responses/401Unauthorized' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' /optout/{OptOutID}: # Retrieve the details of a specific opt-out entry by its ID get: tags: - OptOut summary: "OptOut: Details" description: Retrieve the details of a specific opt-out entry by its ID. operationId: client.configuration.optout.details security: - bearerAuth: [] parameters: # - $ref: '#/components/parameters/Content-Type' - $ref: '#/components/parameters/Accept' - $ref: '#/components/parameters/OptOutID' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/OptOut_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404NotFound' patch: # Edit an existing OptOut entry tags: - OptOut summary: Update OptOut description: | Edit an existing OptOut entry. operationId: client.messaging.optout.update security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/OptOutID' - $ref: '#/components/parameters/Accept' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OptOut_Object' responses: '200': description: Entry updated. content: application/json: schema: $ref: '#/components/schemas/OptOut_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404NotFound' '415': $ref: '#/components/responses/415UnsupportedMediaType' '500': $ref: '#/components/responses/500ServerError' delete: tags: - OptOut summary: Delete OptOut description: | Delete an existing OptOut entry. operationId: client.messaging.optout.delete security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/OptOutID' - $ref: '#/components/parameters/Accept' responses: '200': description: OK [entry deleted] content: application/json: schema: $ref: '#/components/schemas/OptOut_Detail' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '404': $ref: '#/components/responses/404NotFound' '500': $ref: '#/components/responses/500ServerError' ### End 'OptOut' Module ### ### Start 'Webhook' Module ### # webhooks: ResultWebhook: post: tags: - SMS - Email - Voice - TTS - Fax - Webhooks summary: Webhook - Send Result description: | 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). parameters: - $ref: '#/components/parameters/X-Timestamp' - $ref: '#/components/parameters/X-Sender' - $ref: '#/components/parameters/Authorization' requestBody: content: application/json: schema: type: object properties: Version: $ref: '#/components/schemas/Version' Sender: $ref: '#/components/schemas/Sender' APIKey: $ref: '#/components/schemas/APIKey' Type: type: string description: | The type of message this webhook relates to - 'SMS', 'Email', 'Voice' (for Voice and TTS), 'Fax'. enum: [SMS, Email, Voice, Fax] examples: - SMS - Email - Voice - Fax Destination: type: string description: Destination that the webhook is for (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format). example: '+6421000001' ContactID: $ref: '#/components/schemas/ContactID' ReceivedID: $ref: '#/components/schemas/NullValue' MessageID: $ref: '#/components/schemas/MessageID' SubAccount: $ref: '#/components/schemas/SubAccount' Department: $ref: '#/components/schemas/Department' JobNumber: $ref: '#/components/schemas/JobNumber' SentTimeLocal: $ref: '#/components/schemas/SentTimeLocal' SendTimeUTC: $ref: '#/components/schemas/SentTimeUTC' SentTimeUTC_RFC3339: $ref: '#/components/schemas/SentTimeUTC_RFC3339' Status: $ref: '#/components/schemas/MessageStatus' Result: $ref: '#/components/schemas/MessageResult' Message: $ref: '#/components/schemas/NullValue' Price: $ref: '#/components/schemas/Price' Detail: type: string description: | Additional message details. * SMSParts: The quantity of SMS Parts. * EmailSize: The size of the email in bytes. * FaxPages: The quantity of Fax Pages. * VoiceRemoteID: The call recipient's phone number (this may differ from 'Destination' if failover Alt Phones are used). * VoiceSeconds: The call length in seconds. * VoiceTotalCallTime: The total call time including unbillable call set-up and ringing time. * Prompts: Defines the keypad options selected by the call recipient. example: 'SMSParts:2' URL: $ref: '#/components/schemas/URL' responses: '200': $ref: '#/components/responses/WebhookSuccess' '400': $ref: '#/components/responses/WebhookError' '500': $ref: '#/components/responses/WebhookError' InboundSMSWebhook: post: tags: - SMS - Webhooks summary: Webhook - Inbound SMS description: | 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). parameters: - $ref: '#/components/parameters/X-Timestamp' - $ref: '#/components/parameters/X-Sender' - $ref: '#/components/parameters/Authorization' requestBody: content: application/json: schema: type: object properties: Version: $ref: '#/components/schemas/Version' Sender: $ref: '#/components/schemas/Sender' APIKey: $ref: '#/components/schemas/APIKey' Type: type: string description: | If the received message can be matched as a reply, the type will be 'SMSReply'. Otherwise, the type will be 'SMSInbound'. enum: [SMSReply, SMSInbound] examples: - SMSReply - SMSInbound Destination: type: string description: Contact that sent the response message (alphanumeric field, where telephone/mobile numbers are supplied in E.164 internationalised format). example: '+6421000001' ContactID: $ref: '#/components/schemas/ContactID' ReceivedID: $ref: '#/components/schemas/UniqueID' MessageID: $ref: '#/components/schemas/MessageID' SubAccount: $ref: '#/components/schemas/SubAccount' Department: $ref: '#/components/schemas/Department' JobNumber: $ref: '#/components/schemas/JobNumber' SentTimeLocal: $ref: '#/components/schemas/SentTimeLocal' SendTimeUTC: $ref: '#/components/schemas/SentTimeUTC' SentTimeUTC_RFC3339: $ref: '#/components/schemas/SentTimeUTC_RFC3339' Status: type: string description: "Static value (SMS Received)" const: "RECEIVED" example: RECEIVED Result: type: string description: "Static value (SMS Received)" const: "RECEIVED" example: RECEIVED Message: $ref: '#/components/schemas/ReceivedMessage' Price: $ref: '#/components/schemas/Price' Detail: type: string description: | Additional message details. * InputToNumber: Displays the mobile number in the original sender's format (if applicable) example: 'InputToNumber:021-777909' URL: $ref: '#/components/schemas/URL' responses: '200': $ref: '#/components/responses/WebhookSuccess' '400': $ref: '#/components/responses/WebhookError' '500': $ref: '#/components/responses/WebhookError' ### End 'Webhook' Module ### ### Start 'Components' Module ### # components: # These go in the header parameters: Content-Type: name: Content-Type description: The media type of the resource. in: header required: true schema: type: string examples: - application/json; encoding="UTF-8" Accept: name: Accept description: The media type that is acceptable for the response. in: header required: true schema: type: string examples: - application/json; encoding="UTF-8" Authorization: name: Authorization description: The sender JWT Auth Token. in: header required: true schema: type: string format: password example: Basic ey...01 MessageID: name: MessageID description: The MessageID the API call is targeting. If you use common MessageID values across multiple calls, it will apply to the most recent message submitted. in: path required: true schema: type: string maxLength: 40 examples: - a1b2c3d4-e5f6-7890-1234-567890abcdee - ID1234567890 ContactID: name: ContactID description: Unique identifier for the Address Book Contact. in: path required: true schema: type: string format: uuid example: 8000000a-f002-4007-b00a-d00000000001 GroupID: name: GroupID description: Unique identifier for the Address Book Group. in: path required: true schema: type: string format: uuid example: 9000000a-f002-4007-b00a-d00000000001 OptOutID: name: OptOutID description: Unique identifier for the Opt Out entry. in: path required: true schema: type: string format: uuid example: 8000000a-f002-4007-b00a-d00000000001 Page: name: page in: query required: false description: Page number to retrieve. schema: type: [integer, "null"] default: 1 example: 1 RecordsPerPage: name: recordsPerPage in: query required: false description: Number of records to return per page. schema: type: [integer, "null"] minimum: 5 maximum: 100 example: 20 X-Sender: name: X-Sender in: header required: true description: The email address of the sender. schema: type: string format: email example: application@domain.com X-Timestamp: name: X-Timestamp in: header required: true description: The RFC3339 timestamp of the request. schema: type: string format: date-time example: 2025-06-03T21:16:55.000Z # These go in the header headers: Content-Type: description: The media type of the resource. schema: type: string example: application/json; encoding="UTF-8" Accept: description: The media type that is acceptable for the response. schema: type: string example: application/json; encoding="UTF-8" Authorization: description: The sender JWT Auth Token. schema: type: password example: Bearer ey...01 # These go in the body schemas: # Individual entries MessageID: type: [string, "null"] description: 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. maxLength: 40 examples: - a1b2c3d4-e5f6-7890-1234-567890abcdee - ID1234567890 Reference: type: [string, "null"] maxLength: 100 description: A human readable message reference. examples: - MyTest - An appointment reminder NotificationType: type: [string, "null"] description: | Specifies the notification method for delivery status updates and inbound replies for this message. Omit to use your User's default settings. enum: [None, Webhook, Email] default: '' examples: - None - Webhook - Email ReportTo: type: string format: email description: Email address to send a delivery report to once the message completes. Omit to use your User's default settings. example: reports@example.com WebhookCallbackURL: type: string format: uri maxLength: 500 description: The URL to receive the webhook. A full path including https:// is required. Omit to use your User's default settings. example: https://example.com/webhook WebhookCallbackFormat: type: string description: The format of the webhook body. Omit to use your User's default settings. enum: [JSON, XML, POST, GET] example: JSON SendTime: type: string default: null description: Delay sending until the specified specified time - {date}T{time} (in the user's 'Local' Timezone). Omit to send immediately. example: 2026-08-29T14:00 Timezone: type: [string, "null"] maxLength: 75 description: The 'Local' Timezone (based on Windows Timezones, see a list). Omit to use your User's default Timezone. examples: - New Zealand - AUS Eastern - E. Australia - W. Australia - Cen. Australia - Central Pacific Account: type: string description: Your account number. example: '101202' SubAccount: type: [string, "null"] maxLength: 40 description: 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: Business Unit One Department: type: [string, "null"] maxLength: 40 description: 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: Department Alpha ContactID: type: string format: uuid description: Unique contact identifier that corresponds to an Address Book Contact. example: 123e4567-e89b-12d3-a456-426614174000 GroupID: type: string format: uuid description: Unique group identifier that corresponds to an Address Book Group. example: 223e4567-e89b-12d3-a456-426614175000 Destination: type: string maxLength: 60 description: A single destination to receive the message. You may use any of the `Destination` (string), `ContactID` (string), `GroupID` (string) or `Destinations` (array) parameters. examples: - 021-000001 - '+642100002' - john.doe@example.com Destinations: type: array description: 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: type: object properties: ToNumber: $ref: '#/components/schemas/ToNumber' EmailAddress: $ref: '#/components/schemas/EmailAddress' MainPhone: $ref: '#/components/schemas/MainPhone' Attention: $ref: '#/components/schemas/Attention' First Name: $ref: '#/components/schemas/FirstName' Last Name: $ref: '#/components/schemas/LastName' Company: $ref: '#/components/schemas/Company' Custom1: $ref: '#/components/schemas/CustomVariable1' Custom2: $ref: '#/components/schemas/CustomVariables' Custom3: $ref: '#/components/schemas/CustomVariables' Custom4: $ref: '#/components/schemas/CustomVariables' ContactID: $ref: '#/components/schemas/ContactID' GroupID: $ref: '#/components/schemas/GroupID' GroupCode: $ref: '#/components/schemas/GroupCode' TemplateID: type: string format: uuid description: | 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: 123e4567-e89b-12d3-a456-426614174000 Files: type: array description: An array of file attachments. items: type: object properties: Name: type: string maxLength: 255 description: The name of the attached file including the file extension. examples: - 'My Example.pdf' - 'An Image.jpg' Data: type: string format: byte maxLength: 1398102 description: "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)" example: 'base64-encoded-file-data' SMSCustomPageID: type: string format: uuid description: | UUID of the [[CustomPage]] template to use. Edit a Custom Page template in the Dashboard to find the Template ID. example: 123e4567-e89b-12d3-a456-426614174001 NumberOfOperators: type: integer minimum: 1 maximum: 99999 default: 99999 description: 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: 5 GroupCode: description: Human-readable unique identifier for the Address Book Group. type: string maxLength: 100 example: My_Test_Group GroupName: type: string description: The human-readable name of the Group. maxLength: 100 example: "My Test Group" ViewBy: type: string description: The view access rights. enum: ["Account", "SubAccount", "Department", "No"] example: "Account" EditBy: type: string description: The edit access rights. enum: ["Account", "SubAccount", "Department", "No"] example: "Account" ViewEditBy: description: The view and edit access rights. enum: ["Account", "SubAccount", "Department", "No"] example: "Account" AccessControl: type: string description: The access control level for higher privilege users (setting 'Granted' means administrators can view/edit the contact even if the ViewBy=No). enum: ["Limited", "Granted"] examples: - "Limited" - "Granted" Owner: type: string maxLength: 100 description: The owner of the contact (typically the user who created it). example: "COM\\DOMAIN\\APPLICATION" JobNumber: type: string length: 8 description: Alphanumeric tracking number (our internal Job Number). example: 10AB20CE DestSeq: type: string length: 8 description: The ID of the destination in the list (increments per destination). example: '00000001' JobStatus: type: string maxLength: 100 description: Current state of the job. enum: [Pending, Delayed, Completed, CreditHold, Unknown] example: Pending MessageStatus: type: string maxLength: 100 description: Current status of the message. enum: [Success, Failed, Pending] example: Success MessageResult: type: string maxLength: 100 description: 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: delivered CreatedTimeLocal: type: string description: The time the entry was created, in the local Timezone. example: "2025-05-29 05:11:03" CreatedTimeUTC: type: string description: The time the entry was created, in UTC. example: "2025-05-29 17:11:03" CreatedTimeUTC_RFC3339: type: string format: date-time description: The time the entry was created, in UTC (RFC3339 format). example: "2025-05-29T17:11:03.000Z" UpdatedTimeLocal: type: string description: The time the entry was last updated, in the local Timezone. example: "0001-01-01 12:00:00" UpdatedTimeUTC: type: string description: The time the entry was last updated, in UTC. example: "0001-01-01 00:00:00" UpdatedTimeUTC_RFC3339: type: string format: date-time description: The time the entry was last updated, in UTC (RFC3339 format). example: "0001-01-01T00:00:00.000Z" DelayedTimeLocal: type: string description: The time the entry was delayed until, in the local Timezone. example: "2025-05-29 05:11:03" DelayedTimeUTC: type: string description: The time the entry was delayed until, in UTC. example: "2025-05-29 17:11:03" DelayedTimeUTC_RFC3339: type: string format: date-time description: The time the entry was delayed until, in UTC (RFC3339 format). example: "2025-05-29T17:11:03.000Z" SentTimeLocal: type: string description: Time the message was sent in the users local Timezone (ISO 8601 format). example: 2025-06-13 08:44:16 SentTimeUTC: type: string description: Time the message was sent in UTC (ISO 8601 format). example: 2025-06-12 20:44:16 SentTimeUTC_RFC3339: type: string format: date-time description: Time the message was sent in UTC (RFC 3339 format). example: 2025-06-12T20:44:16.000Z ReceivedTimeLocal: type: string description: Time the message was received in the users local Timezone (ISO 8601 format). example: 2025-09-01 14:02:03 ReceivedTimeUTC: type: string description: Time the message was received in UTC (ISO 8601 format). example: 2025-09-01 02:02:03 ReceivedTimeUTC_RFC3339: type: string format: date-time description: Time the message was received in UTC (RFC 3339 format). example: 2025-09-01T02:02:03.000Z MobileNumber: type: string format: phone maxLength: 20 description: 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). examples: - '+6421000001' - '021-000001' ToNumber: type: string format: phone description: 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). examples: - '+6421000001' - '021-000001' EmailAddress: type: string format: email maxLength: 60 description: The contact's email address. example: 'john.doe@example.com' MainPhone: type: string format: phone maxLength: 20 description: 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: '+6421000001' Attention: type: [string, "null"] maxLength: 200 description: The contact's name (used for personalising the message and reporting). example: John Doe FirstName: type: [string, "null"] maxLength: 60 description: The contact's first name (used for personalising the message). example: John LastName: type: [string, "null"] maxLength: 60 description: The contact's last name (used for personalising the message). example: Doe Company: type: [string, "null"] maxLength: 60 description: The contact's company name (used for personalising the message). example: Example Company Ltd CustomVariable1: type: [string, "null"] maxLength: 300 description: A custom variable (used for reporting and [Personalisation](https://www.tnz.co.nz/help/message-personalisation)). example: "Appointment 4:00pm Friday" CustomVariables: type: [string, "null"] maxLength: 300 description: Additional custom variable. example: "" RemoteID: type: [string, "null"] maxLength: 15 description: For Voice, Text-to-Speech and Fax, dialled phone number. This may differ from 'Destination' if failover Alt Phones are used. example: "+6495006000" ReceivedMessage: type: [string, "null"] maxLength: 1000 description: The received message. example: This is a received message from a mobile phone. Price: type: [string, "null"] maxLength: 10 description: Cost of the message (before tax and plan credits). Null if no cost. example: 0.10 Sender: type: string format: email maxLength: 100 description: Webhook sender authentication (can configure a unique Sender if required). example: application@domain.com APIKey: type: [string, "null"] maxLength: 255 description: Webhook token authentication (can configure a unique APIKey if required). example: ta8wr7ymd URL: type: string format: uri maxLength: 500 description: URL/URI for the request. example: https://www.example.com/data Version: type: string maxLength: 10 description: The API version being used. example: 'v3.00' UniqueID: type: string format: uuid description: A unique identifier (UUID). example: a1b2c3d4-e5f6-7890-1234-567890abcdee QueryResult: type: string description: Result of the query (***not*** the result of the message). example: Success UpdateSendTime: type: string description: Reschedule sending for the specified time - {date}T{time} - in the message's previously set Timezone. example: 2025-08-12T12:00:00 SMSFrom: type: string description: Sender of the SMS in E.164 internationalised format. example: '+6421000001' TestMode: type: [string, "null"] description: 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. default: null example: Test NullValue: type: null description: Null (unused). Message_Detail: type: object properties: MessageID: $ref: '#/components/schemas/MessageID' JobStatus: $ref: '#/components/schemas/JobStatus' JobNum: $ref: '#/components/schemas/JobNumber' Account: $ref: '#/components/schemas/Account' SubAccount: $ref: '#/components/schemas/SubAccount' Department: $ref: '#/components/schemas/Department' Reference: $ref: '#/components/schemas/Reference' CreatedTimeLocal: $ref: '#/components/schemas/CreatedTimeLocal' CreatedTimeUTC: $ref: '#/components/schemas/CreatedTimeUTC' CreatedTimeUTC_RFC3339: $ref: '#/components/schemas/CreatedTimeUTC_RFC3339' DelayedTimeLocal: $ref: '#/components/schemas/DelayedTimeLocal' DelayedTimeUTC: $ref: '#/components/schemas/DelayedTimeUTC' DelayedTimeUTC_RFC3339: $ref: '#/components/schemas/DelayedTimeUTC_RFC3339' Timezone: $ref: '#/components/schemas/Timezone' Count: type: integer description: Total Destinations specified in the message. example: 1 Complete: type: integer description: Total Destinations that were successfully completed. example: 1 Success: type: integer description: Total Destinations that were successfully delivered. example: 1 Failed: type: integer description: Total Destinations that failed to deliver. example: 0 Price: $ref: '#/components/schemas/Price' Recipients_Detail: type: object properties: SentTimeLocal: $ref: '#/components/schemas/SentTimeLocal' SentTimeUTC: $ref: '#/components/schemas/SentTimeUTC' SentTimeUTC_RFC3339: $ref: '#/components/schemas/SentTimeUTC_RFC3339' Attention: $ref: '#/components/schemas/Attention' Company: $ref: '#/components/schemas/Company' Custom1: $ref: '#/components/schemas/CustomVariable1' Custom2: $ref: '#/components/schemas/CustomVariables' Custom3: $ref: '#/components/schemas/CustomVariables' Custom4: $ref: '#/components/schemas/CustomVariables' Custom5: $ref: '#/components/schemas/CustomVariables' Custom6: $ref: '#/components/schemas/CustomVariables' Custom7: $ref: '#/components/schemas/CustomVariables' Custom8: $ref: '#/components/schemas/CustomVariables' Custom9: $ref: '#/components/schemas/CustomVariables' RemoteID: $ref: '#/components/schemas/RemoteID' Price: $ref: '#/components/schemas/Price' SMSReplies_Detail: type: object properties: ReceivedID: $ref: '#/components/schemas/UniqueID' ReceivedTimeLocal: $ref: '#/components/schemas/ReceivedTimeLocal' ReceivedTimeUTC: $ref: '#/components/schemas/ReceivedTimeUTC' ReceivedTimeUTC_RFC3339: $ref: '#/components/schemas/ReceivedTimeUTC_RFC3339' Timezone: $ref: '#/components/schemas/Timezone' From: $ref: '#/components/schemas/SMSFrom' MessageText: $ref: '#/components/schemas/ReceivedMessage' Contact_Detail: allOf: - type: object properties: ContactID: $ref: '#/components/schemas/ContactID' Owner: $ref: '#/components/schemas/Owner' CreatedTimeLocal: $ref: '#/components/schemas/CreatedTimeLocal' CreatedTimeUTC: $ref: '#/components/schemas/CreatedTimeUTC' CreatedTimeUTC_RFC3339: $ref: '#/components/schemas/CreatedTimeUTC_RFC3339' UpdatedTimeLocal: $ref: '#/components/schemas/UpdatedTimeLocal' UpdatedTimeUTC: $ref: '#/components/schemas/UpdatedTimeUTC' UpdatedTimeUTC_RFC3339: $ref: '#/components/schemas/UpdatedTimeUTC_RFC3339' Timezone: $ref: '#/components/schemas/Timezone' - $ref: '#/components/schemas/Contact_Object' Contact_Object: type: object properties: ExType: type: string maxLength: 20 description: An External ID Type can be used to categorise contacts (typically used by another system). example: "" ExID: type: string maxLength: 100 description: An External ID is an identifier used by another system to identify the contact (for example, your CRM's Contact ID). example: "" ViewBy: $ref: '#/components/schemas/ViewBy' EditBy: $ref: '#/components/schemas/EditBy' AccessControl: $ref: '#/components/schemas/AccessControl' Attention: $ref: '#/components/schemas/Attention' Title: type: [string, "null"] description: The contact's title (for example, Mr, Ms, Dr). enum: ['', Mr, Mrs, Ms, Miss, Dr, Prof, Hon] example: Mr Company: type: [string, "null"] description: The contact's company name (used for personalising messages and reporting). maxLength: 100 example: "Example Company" RecipDepartment: type: [string, "null"] description: The contact's department within their company. maxLength: 100 example: Accounting FirstName: type: [string, "null"] description: The contact's first name (used for personalising messages). maxLength: 100 example: "John" LastName: type: [string, "null"] description: The contact's last name (used for personalising messages). maxLength: 100 example: "Doe" Position: type: [string, "null"] description: The contact's position within their company. maxLength: 100 example: Accountant StreetAddress: type: [string, "null"] description: The contact's street address. maxLength: 100 example: "123 Queen Street" Suburb: type: [string, "null"] description: The contact's suburb. maxLength: 100 example: "Auckland City" City: type: [string, "null"] description: The contact's city. maxLength: 100 example: "Auckland" State: type: [string, "null"] description: The contact's state or region. maxLength: 100 example: "" Country: type: [string, "null"] description: The contact's country (no fixed format). maxLength: 100 example: "New Zealand" Postcode: type: [string, "null"] description: The contact's postal code (no fixed format) maxLength: 100 example: "1010" MainPhone: type: string format: phone description: The contact's main phone number (used for Voice and TTS calls). maxLength: 100 example: "+6421002003" AltPhone1: type: string format: phone description: An alternative phone number for the contact (used for Voice and TTS failover). maxLength: 100 example: "+6495006001" AltPhone2: type: string format: phone description: An alternative phone number for the contact (used for Voice and TTS failover). maxLength: 100 example: "+6495006002" AltPhone3: type: string format: phone description: An alternative phone number for the contact (used for Voice and TTS failover). maxLength: 100 example: "+6495006003" AltPhone4: type: string format: phone description: An alternative phone number for the contact (used for Voice and TTS failover). maxLength: 100 example: "+6495006004" AltPhone5: type: string format: phone description: An alternative phone number for the contact (used for Voice and TTS failover). maxLength: 100 example: "" AltPhone6: type: string format: phone description: An alternative phone number for the contact (used for Voice and TTS failover). maxLength: 100 example: "" AltPhone7: type: string format: phone description: An alternative phone number for the contact (used for Voice and TTS failover). maxLength: 100 example: "" AltPhone8: type: string format: phone description: An alternative phone number for the contact (used for Voice and TTS failover). maxLength: 100 example: "" MobilePhone: type: string format: phone description: The contact's mobile phone number (used for SMS messages). maxLength: 100 example: "+6421002003" FaxNumber: type: string format: phone description: The contact's fax number (used for Fax messages). maxLength: 100 example: "+64 9 500-5000" EmailAddress: type: string format: email description: The contact's email address (used for Email messages). maxLength: 100 example: "john.doe@example.com" WebAddress: type: string format: uri description: The contact's website address. maxLength: 100 example: "https://www.example.com" Custom1: type: [string, "null"] description: Custom field (used for personalising messages). maxLength: 100 example: "Custom Value 1" Custom2: type: [string, "null"] description: Custom field (used for personalising messages). maxLength: 100 example: "Custom Value 2" Custom3: type: [string, "null"] description: Custom field (used for personalising messages). maxLength: 100 example: "" Custom4: type: [string, "null"] description: Custom field (used for personalising messages). maxLength: 100 example: "" Notes: type: [string, "null"] description: Freeform notes. maxLength: 1000 example: "This contact was created using the Address Book API." Group_Detail: allOf: - type: object properties: GroupID: $ref: '#/components/schemas/GroupID' GroupCode: $ref: '#/components/schemas/GroupCode' - $ref: '#/components/schemas/Group_Object' - type: object properties: Owner: $ref: '#/components/schemas/Owner' CreatedTimeLocal: $ref: '#/components/schemas/CreatedTimeLocal' CreatedTimeUTC: $ref: '#/components/schemas/CreatedTimeUTC' CreatedTimeUTC_RFC3339: $ref: '#/components/schemas/CreatedTimeUTC_RFC3339' Timezone: $ref: '#/components/schemas/Timezone' Group_Object: type: object properties: GroupName: $ref: '#/components/schemas/GroupName' SubAccount: $ref: '#/components/schemas/SubAccount' Department: $ref: '#/components/schemas/Department' ViewEditBy: $ref: '#/components/schemas/ViewEditBy' AccessControl: $ref: '#/components/schemas/AccessControl' OptOut_Object: type: object properties: DestType: type: string description: 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)`. examples: - SMS - Email Destination: type: string maxLength: 60 description: | The destination opted-out. Telephone numbers are in E.164 format. You may use `Destination` or `ContactID` (not both). examples: - '+6421003004' - john.doe@example.com - '+6495006000' ContactID: $ref: '#/components/schemas/ContactID' SubAccount: type: [string, "null"] maxLength: 60 description: The SubAccount the opt-out entry applies to. An empty value applies to all SubAccounts. example: Business Unit One Department: type: [string, "null"] maxLength: 60 description: The Department the opt-out entry applies to. An empty value applies to all Departments. example: Team Alpha StopMessage: type: [string, "null"] maxLength: 1000 description: The Opt-Out message detected. example: Stop sending me these messages Notes: type: [string, "null"] maxLength: 1000 description: Free form notes. example: Entry edited using the API. required: - DestType OptOut_Detail: allOf: - type: object properties: ID: $ref: '#/components/schemas/UniqueID' - $ref: '#/components/schemas/OptOut_Object' - type: object properties: OriginalMessage: type: string description: The original message that triggered the opt-out. example: 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: $ref: '#/components/schemas/CreatedTimeLocal' CreatedTimeUTC: $ref: '#/components/schemas/CreatedTimeUTC' CreatedTimeUTC_RFC3339: $ref: '#/components/schemas/CreatedTimeUTC_RFC3339' UpdatedTimeLocal: $ref: '#/components/schemas/UpdatedTimeLocal' UpdatedTimeUTC: $ref: '#/components/schemas/UpdatedTimeUTC' UpdatedTimeUTC_RFC3339: $ref: '#/components/schemas/UpdatedTimeUTC_RFC3339' Timezone: $ref: '#/components/schemas/Timezone' Pagination: type: object properties: TotalRecords: type: integer example: 1 RecordsPerPage: type: integer example: 20 PageCount: type: integer example: 1 Page: type: integer example: 1 # The Security scheme used by API calls securitySchemes: # apiKeyHeader: # type: apiKey # in: header # name: Authorization # description: 'Authorization token containing a JWT. Enter the token with the "Basic" prefix, e.g. "Basic ey01aS1..."' bearerAuth: type: http scheme: bearer description: 'Authorization token containing a JWT. Enter the token with the "Bearer" prefix, e.g. "Bearer ey01aS1..."' # These are the response codes returned when submitting to the API. Refer to each sections $ref to home these responses. responses: 200OK: description: OK [successful submission] content: application/json: schema: type: object properties: MessageID: type: string description: Unique identifier for the API call. example: 1000000a-f002-4007-b00a-d00000000002 example: MessageID: 1000000a-f002-4007-b00a-d00000000002 400BadRequest: description: Bad Request [data incorrect] content: application/json: schema: type: object properties: Result: type: string description: Result of the API call. example: Failed ErrorMessage: type: array description: A detailed description of the error. example: [Missing or empty field] example: Result: Failed ErrorMessage: Missing or empty field 401Unauthorized: description: Unauthorized [auth token is invalid] content: application/json: schema: type: object properties: Result: type: string description: Result of the API call. example: Unauthorized ErrorMessage: type: array description: A detailed description of the error. example: "[Access denied: Auth Token or credentials are incorrect or have expired.]" example: Result: Unauthorized ErrorMessage: "Access denied: Auth Token or credentials are incorrect or have expired." 403Forbidden: description: Forbidden [access to this endpoint is disabled] content: application/json: schema: type: object properties: Result: type: string example: "Failed" ErrorMessage: type: array description: Access must be enabled for this API User in the Dashboard. items: type: string example: "Unauthorized access to Addressbook API!" 404NotFound: description: Not Found [invalid ID or resource not yet processed] content: application/json: schema: type: object properties: ErrorMessage: type: array items: type: string example: "Unable to find or access the data you're looking for." 404IDNotFound: description: Not Found [id is incorrect or still processing] content: application/json: schema: type: object properties: Result: type: string description: Result of the API call. example: RecordNotFound MessageID: type: string description: The MessageID queried. example: 1000000a-f002-4007-b00a-d00000000002 ErrorMessage: type: array description: A detailed description of the error. example: [Unable to find entry.] 404RecordNotFound: description: Not Found [record not found] content: application/json: schema: type: object properties: Result: type: string example: "RecordNotFound" ErrorMessage: type: array items: type: string example: "Unable to find or access record with id '0eee9801-098e-fc70-86b3-ae5a4s550992d'." 415UnsupportedMediaType: description: Unsupported Media Type [the content-type header is incorrect] content: application/json: schema: type: object properties: status: type: integer description: The HTTP error code for Unsupported Media Type (Content-Type or Accept header is likely invalid). example: 415 extend1: type: string description: An error indicator. example: info1 extend2: type: string description: An error indicator. example: info2 example: status: 415 extend1: info1 extend2: info2 500ServerError: description: Server Error [contact us] content: application/json: schema: type: object properties: Result: type: string description: Result of the API call. example: Failed ErrorMessage: type: array description: Your data contains errors. example: ["An unexpected error occurred while processing."] WebhookSuccess: description: Success [your server acknowledged the webhook] WebhookError: description: Failed [your server rejected the webhook (retried every 5 min for 24 hours)] ### End 'Components' Module ###