openapi: 3.2.0 info: version: 2.1.0 title: Sinch Engage termsOfService: https://www.sinch.com/legal/terms-and-conditions/ contact: name: Sinch Engage Support email: support@app.sinch.com url: https://support.app.sinch.com/hc/en-us/categories/10516535548943-Sinch-Engage-Developer-Guides license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html x-logo: url: ./logo.png description: | # Introduction The Sinch APIs provide powerful business messaging capabilities across sending, receiving, and processing SMS, MMS, and rich messaging. All requests to the Sinch REST API must be authenticated, this can either be done using Basic Authentication or by signing with a HMAC signature. # Base URI The API uses the following base URI For EU instance please use https://eu.app.api.sinch.com For APAC instance, use https://au.app.api.sinch.com # Credentials To access the API, an API key and secret are required. [Sign up for a developer account here to get access](https://support.app.sinch.com/hc/en-us/categories/10516535548943-Sinch-Engage-Developer-Guides) # Features ### De-Duplication De-Duplication helps you avoid having to undertake data cleansing before commencing send outs. It automatically detects and withholds messages deemed to be duplicates through the use of a 24-hour window – if a message is sent to the same number with the same content within a 24hr period, the subsequent message(s) will be withheld and rejected. To enable this, you don't need to make any changes to your application, just an account configuration change by Sinch's support team. ### Social Sending Social Sending permits messages to be sent only during sociable hours - i.e. 8am to 6pm (based on your accounts local time zone - not local time). Messages sent outside of these hours are scheduled to be released during the next social time period. This feature helps businesses avoid send-outs during a time that would be deemed unsuitable by the customer. To enable this, you don't need to make any changes to your application, just an account configuration change by Sinch's support team. ### Familiar Sender Familiar Sender ensures all communication sent to a customer are from the same phone number. This allows businesses to build trust and familiarity with their customers and not confuse them by changing outgoing numbers. To enable this, you don't need to make any changes to your application, just an account configuration change by Sinch's support team. ### Character Converter Characters in a message may not always fall within the GSM-7 supported character set, and when this occurs all outbound messages will be encoded using UCS-2 leading to the customer being double-charged for the SMS. Character Converter can help you avoid being double-charged for your SMS by converting all characters into the GSM-7 format ensuring you always get the maximum characters into an SMS. Bear in mind, this will downgrade all your unicode characters so for instance, your emojis will be translated into a string of unknown characters (eg: �). To enable this, you don't need to make any changes to your application, just an account configuration change by Sinch's support team. servers: - url: https://eu.app.api.sinch.com/ description: EU instance name: EU - url: https://au.app.api.sinch.com/ description: APAC instance name: APAC tags: - name: Basic Authentication kind: nav description: |- Every request requires an `Authorization` header in the following format: ```plain Authorization: Basic Base64(api_key:api_secret) ``` Where the header consists of the Basic keyword followed by your Basic Authentication `api_key` and `api_secret` that you have been supplied by support, separated with a colon (:) which is then Base64 encoded. ### Example request with Basic Authentication ```plain POST /v1/messages HTTP/1.1 Host: eu.app.api.sinch.com Accept: application/json Content-Type: application/json Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp { "messages": [ { "content": "Hello World", "destination_number": "+61491570156", "format": "SMS" } ] } ``` _Note: spaces are used as indentation in the body of the above request._ - name: HMAC Authentication kind: nav description: |- Every request requires an `Authorization` header in the following formats: For a request with a request body: ```plain Authorization: hmac username="", algorithm="hmac-sha256", headers ="Date Content-MD5 request-line", signature="" ``` For a request _without_ a request body: ```plain Authorization: hmac username="", algorithm="hmac-sha256", headers="Date request-line", signature="" ``` ### To create this header #### Step 1 Add a `Date` header to the request using the current date time in [RFC7231 Section 7.1.1.2](http://tools.ietf.org/html/rfc7231#section-7.1.1.2) format #### Step 2 If the request has a body, add a header called `Content-MD5` where the value of this header is an MD5 hash of the request body, otherwise this header is not required #### Step 3 Create a signing string by concatenating the `Date` header, the `Content-MD5` header (if set) and the request line with line breaks: ```plain Date: Sat, 30 Jul 2016 05:13:23 GMT\nContent-MD5: 10fd4feab20d38432480c07301e49616\nPOST /v1/messages HTTP/1.1 ``` or ```plain Date: Sat, 30 Jul 2016 05:13:23 GMT\nGET /v1/messages/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1 ``` #### Step 4 Create a SHA256 HMAC hash using the signing string and the secret key (both converted to bytes using UTF-8) ```HMAC-SHA256(signing string, secret)``` #### Step 5 Base64 encode the HMAC hash and include it as the signature in the ```Authorization``` header ### Example request with body ```plain POST /v1/messages HTTP/1.1 Host: eu.app.api.sinch.com Accept: application/json Content-Type: application/json Date: Sat, 30 Jul 2016 05:18:52 GMT Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha256", headers="Date Content-MD5 request-line", signature="Ia4G5lkhH/3NDYpix+8ZHUnp6bA=" Content-MD5: 5407644fa83bec240dede971307e0cad Content-Length: 133 { "messages": [ { "content": "Hello World", "destination_number": "+61491570156", "format": "SMS" } ] } ``` _Note: spaces are used as indentation in the body of the above request._ ### Example request without body ```plain GET /v1/messages/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1 Host: eu.app.api.sinch.com Accept: application/json Date: Sat, 30 Jul 2016 05:18:52 GMT Authorization: hmac username="uCXUdoogNfCsehEClbO2", algorithm="hmac-sha256", headers="Date request-line", signature="NTUwMjUwNTVmZGYzZTIxODMyYjc1ZmM3M2EwZWQ1NzA3NzA4ZTZjNw==" ``` - name: Sub-accounts kind: nav description: | ## Performing actions on behalf of sub-accounts Using API keys at the parent account level, you can perform actions on behalf of a sub-account. This feature is supported by the Messages, Replies, Delivery Reports and Webhooks APIs. To do this include a header key ```Account``` with the sub-account ID as the value. For example: ```Account: mySubAccount``` **Example request with Sending from sub-accounts** ```plain POST /v1/messages HTTP/1.1 Host: eu.app.api.sinch.com Accept: application/json Content-Type: application/json Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp Account: SubAccount { "messages": [ { "content": "Hello World", "destination_number": "+61491570156", "delivery_report": true } ] } ``` - name: Messages description: |- The Sinch Messages API provides a number of endpoints for building powerful two-way messaging applications. The Messages API provides access to three main resources: * Messages - Messages delivered from an application to a handset. * Delivery Reports - Real time reports on the delivery status of a message. As a message is processed, it's status may change several times before it is finally delivered to a handset. * Replies - Messages sent from a handset to an application. These messages are typically a reply to a previously sent message. ![Message Flow](./message-flow.png) - name: Source Address description: | The source address API provides several endpoints for you to request an SMS sender ID and track its approval status. **What is Trusted Sender ID?** Simply put, a sender ID is whatever you send a text message from. This is typically either a phone number, or a string of alphanumeric characters (commonly referred to as an "Alpha Tag"). With regulations surrounding SMS becoming much stricter all over the world in an effect to combat scam SMS messages, Sinch is working on "Trusted Sender ID" a concept that allows customers to request a Sender ID and have it verified. Currently, Trusted Sender ID supports two types of Sender ID: Alpha Tags and Personal ("Own") Numbers. It will likely be extended to support additional number types, such as TFN and 10DLC where additional registration, (external) verification, and overall account allowlist of numbers will be required. ### Alpha Tag Sending messages from your brand name is particularly ideal for SMS marketing and two-factor authentication, as it increases recognition and trust. There are, however, a few considerations to be aware of. Alpha tags are made up of 3-11 letters and/or numbers. Alpha tags must be registered and approved before sending and must have clear relevancy to your business and/or use case. Alpha Tags appear as the "From" number when you receive messages. A good alpha tag meets at least one of the following valid use cases: * Business names * Trademark names * Product or service name * an acronym, initialism, or contraction of your entity In addition to the requirements around clearly relating to the business, we typically advise the following for alpha tags to ensure maximum compatibility with the various carriers: * 6-11 characters long * Only contains characters from the following sets: * A-Z * a-z * 0-9 * _ (underscore) * \- (hyphen) Alpha Tags can currently be registered through the Source Address API for the following countries: ```AD```, ```AI```, ```AL```, ```AS```, ```AT```, ```AU```, ```AW```, ```BA```, ```BB```, ```BH```, ```BW```, ```CD```, ```CH```, ```CK```, ```CY```, ```DE```, ```DJ```, ```DK```, ```DM```, ```EE```, ```ES```, ```FI```, ```FJ```, ```FM```, ```FO```, ```FR```, ```GB```, ```GD```, ```GG```, ```GI```, ```GL```, ```GM```, ```GQ```, ```GR```, ```GY```, ```IL```, ```IM```, ```IS```, ```JE```, ```JM```, ```JP```, ```KI```, ```KY```, ```LA```, ```LI```, ```LS```, ```LT```, ```LU```, ```LV```, ```MC```, ```ME```, ```MH```, ```MO```, ```MR```, ```MS```, ```MT```, ```MV```, ```NC```, ```NF```, ```NL```, ```NO```, ```NR```, ```NU```, ```PF```, ```PM```, ```PT```, ```SB```, ```SC```, ```SE```, ```SH```, ```SL```, ```SM```, ```ST```, ```TC```, ```TD```, ```TO```, ```VC```, ```VG``` and ```WS``` To register an Alpha Tag as a sender ID you must: 1. Make a request to the **Request a Sender Address** endpoint 2. Wait for the alpha tag to be approved. The status of the alpha tag can be monitored using the **Get status of a sender address request** endpoint Once the alpha tag has been approved, you can begin using it as a Sender ID for SMS messages. ### Personal Number A personal number, or "My Own Number", is a number that you own rather than one provided to you by Sinch. Typically, this is your personal mobile phone number. You may wish to register this number for use with our service so that you can easily send messages from a number already associated with your organisation. Before you can send messages using your own number, you need to verify that you have a right to use that number. Ensuring you have a right to use a phone number is an important regulatory requirement, aiming to prevent scam, spam, and misuse of messaging services. Personal numbers can currently be registered through the Source Address API for the following countries: ```AT```, ```AU```, ```CH```, ```CY```, ```DE```, ```DK```, ```EE```, ```ES```, ```FI```, ```GB```, ```HR```, ```IE```, ```IT```, ```LT```, ```LU```, ```LV```, ```MT```, ```NL```, ```NO```, ```PT```, ```SE```, and ```SI``` To register a personal number as a Sender ID you must: 1. Make a request to the **Request a Sender Address** endpoint 2. A unique verification code will be sent to the requested number 3. Make a request to the **Submitting a Verification Code** endpoint, using the verification code that was sent in the previous step. A 200 OK response will indicate the number has been verified and is ready for use. ⚠️ Own numbers need to be re-verified every 12 months. You will be notified by email that verification of your number is about to expire. ### Requesting a Source Address on behalf of a sub-account By default, all requests made through the API are made on behalf of the account that the API keys used to authorize the request were made on. API keys created on a parent account can request a source address on behalf of a sub-account. To do this, include a header key ```Account``` with the sub-account ID as the value. For example: ```Account: mySubAccount``` **Example request with Request a Sender Address from a sub-account** ```plain POST /v1/messaging/numbers/sender_address/requests HTTP/1.1 Host: eu.app.api.sinch.com Accept: application/json Content-Type: application/json Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp Account: mySubAccount { "sender_address": "+61341234131", "sender_address_type": "INTERNATIONAL", "usage_type": "OWN_NUMBER", "destination_countries": [ "AU" ], "reason": "I confirm that my business has a valid use case", "label": "my number sample" } ``` *Note: The use of the Account header key applies to all Source Address endpoints.* - name: Delivery Reports description: | If a callback URL is specified in the submit message request, then changes to the message status, replies received in response to the message or delivery reports received for the message will be pushed via a HTTP POST request. An alternative to delivery reports via a callback URL is custom webhooks using the webhooks management API. All notifications are JSON encoded and the request expects to receive a response in the HTTP 200 range. If a valid response isn't received the request will be retried in an exponentially backing off fashion. Delivery Reports may carry an additional charge. For pricing, please contact your Account Manager or Support Team (). To include billing units in your delivery receipts via Webhooks, ensure that the switch "Enable billing units in Delivery Reports and Callbacks" is enabled in the API settings of your account. For delivery reports or changes in the status of a message, the POST request to the specified URL will be as follows: _Note, multiple delivery report notifications will be received for a single message._ ```javascript { "callback_url":"http://mockbin.org/bin/ac52ebd4-eca1-4c86-bf38-4dce79633906", "delivery_report_id":"693e87f2-a553-4281-9ffe-ddf04cbc4bf3", "source_number":"+61491570156", "date_received":"2016-11-03T11:49:02.807Z", "status":"delivered", "delay":0, "billing_units":1, "submitted_date":"2016-11-03T11:49:01.551Z", "original_text":"Hello world!", "message_id":"389dc1a8-62a4-4110-ba61-af94806c006f", "vendor_account_id":{ "vendor_id":"SinchEU", "account_id":"MyAccount" }, "error_code":"220", "metadata":{ "key":"value" } } ``` The properties included in the notification are as follows: * **Callback URL**: The URL specified as the callback URL in the original submit message request. * **Delivery Report ID**: A unique ID for the delivery report that this notification represents. * **Source Number**: The destination address of the original message. * **Date Received**: The date and time at which this notification was generated in UTC. * **Status**: The status of the message as indicated by this delivery report. The status field can be one of the following values: * `enroute`: Message has been received by the gateway and is being processed (or waiting to be processed). * `submitted`: Message has been submitted to a provider/carrier for delivery. * `delivered`: Message delivery has been confirmed by the provider, including to the handset (where possible). * `expired`: The message has expired. * `rejected`: The message will not be delivered - permanent failure. Reasons may include usage limit exceeded, insufficient credit, number blocked, or content filtered * `failed`: The message has failed. Reasons may include no active routes to destination or undeliverable by downstream provider. * **Delay**: _Deprecated, no longer in use_ * **Billing Units**: The number of billing units charged for the message. * **Submitted Date**: Date time status of the message changed in UTC. For a delivered DR this may indicate the time at which the message was received on the handset. * **Original Text**: Text of the original message. * **Message ID**: ID of the original message. * **Vendor Account ID**: The account used to submit the original message. The vendor will always be `SinchEU` * **Error Code**: A status code which provides additional information about the message status: * `101`: Message being processed by the gateway. * `102`: Message is being rerouted to a different provider after failing via the first provider. * `151`: Message held for screening. * `200`: Message submitted to downstream provider for delivery. * `210`: Message accepted by downstream provider. * `211`: Message is enroute for delivery by provider. * `212`: Message submitted. Delivery pending. * `213`: Message scheduled for delivery by downstream provider. * `220`: Message delivered. * `221`: Message delivered to the handset. * `320`: Message validity period has expired (prior to submission). * `401`: Message validity period has expired (before delivery). * `301`: Usage threshold reached. Message discarded. * `302`: Destination address blocked. Message discarded. * `303`: Source address blocked. Message discarded. * `304`: Message dropped. Contact support. * `305`: Message discarded due to duplicate detection. * `402`: Message rejected by downstream provider. * `403`: Message skipped by downstream provider. * `410`: Invalid source address. * `411`: Invalid destination address. * `412`: Destination address blocked. * `413`: SMS service unavailable on destination. * `414`: Destination unreachable. * `330`: Gateway failure. * `331`: Message discarded. * `332`: No available route to destination. * `333`: Source address unsupported for this destination. * `400`: Message failed; undeliverable. * `405`: Message cancelled or deleted by provider. - name: Replies description: Endpoints for checking and confirming inbound message replies (MO) received by your account. - name: Number Authorisation description: |- The number authorisation API allows you to manage your blacklists. Sinch automatically adds numbers to your blacklist if people send one of the opt-out keywords in response to one of your messages. This is a legal requirement. If you decide to handle the legal compliance yourself, calls to this endpoint will not affect your messages. - name: Dedicated Numbers description: "The Numbers API allows your to purchase, provision and configure the dedicated numbers assigned to your Sinch account. \n\nTo learn more about the benefits of dedicated numbers, and their use cases,\_visit our [feature page](https://support.app.sinch.com/hc/en-us/articles/10526389880207-Dedicated-numbers).\n\nThis is a paid feature and must be enabled on your account. Please contact [support@app.sinch.com](mailto:support@app.sinch.com) or your account manager.\n\n## Concepts\n\nThis API allows you to purchase and assign to your account a number from a pool of dedicated numbers. Dedicated numbers are priced differently according to their classification.\n\nThe following is the system by which we classify dedicated numbers. \n\n| Pattern Type | Gold| Silver |\n|---|---|---|\n| Same Number | Six of same (e.g. 999999) | Five of same (e.g. 999991 or 199999) | \n| Sequence | Six in sequence (e.g. 234567, or 765432) | Five in sequence (e.g. 245678, 456782, or 287654) |\n| Triplets | Two identical (e.g. 123123) or two double (e.g. 444666) | Identical pairs within triplets (e.g. 004008, or 400800), one identical and one in sequence (e.g. 444789, or 345777), or mirror image (e.g. 468864)| \n|Pair|Three identical (e.g. 454545)|Three non-identical (e.g. 447700) or three in sequence (e.g. 232425, or 090807)|\n\nAny numbers that do not meet the criteria for Gold or Silver are classified as Bronze.\n\nFor pricing on dedicated numbers please refer to the Numbers page in our Hub web portal, or speak with your Sinch Account Manager.\n" - name: Messaging Reports description: | The Sinch Reports API provides a number of endpoints for running reports of messages sent and received through a Sinch Account. The API allows two kinds of reports, _Detailed Reports_ and _Summary Reports_. Detailed reports list all messages and the details of each message sent or received in a specified time period. Summary reports allow inbound and outbound message data to be aggregated on a number of dimensions. - name: Short Trackable Links Reports description: | Short Trackable Links is a feature available to [Messaging API](https://support.app.sinch.com/hc/en-us/categories/10516535548943-Sinch-Engage-Developer-Guides) users whereby it automatically and seamlessly shortens any URL to just 22 characters. Every shortened URL is unique to each recipient. The reporting API has endpoints specific to this feature, allowing users to obtain details regarding the number of click-throughs on each URL. To enable this feature on your account, contact your account manager or contact support on [support@app.sinch.com](mailto:support@app.sinch.com). To learn more about the benefits of the Short Trackable Links feature, [visit our feature page](https://support.app.sinch.com/hc/en-us/articles/10525004171919-Short-Trackable-Links-URL-shortener). - name: Webhooks Management description: Webhooks Management API allows you to manage your webhooks configuration. You can subscribe to one or several events, retrieve the webhooks, update them or even delete them if needed. - name: Signature Key Management description: | As a Sinch customer, you want to be able to ensure that webhooks are coming from Sinch and not from a 3rd party. Since these are calls to your own system, you should be provided with an extra level of security when calling your resources. The Sinch Signature Key API provides a number of endpoints for managing key used to sign each unique request to ensure security and the requests can't (easily) be spoofed. This is similar to using HMAC in your outbound messaging (rather than HTTP Basic). The Signature Key API provides seven main endpoints: - ```Create signature key``` Create a new signature key for signature verification in webhooks. - ```Get signature key detail``` Retrieve the current detail of a signature key using the key_id returned in the ```create signature key``` endpoint. - ```Delete signature key``` Delete a signature key using the key_id returned in the ```create signature key``` endpoint. - ```Get signature key list``` Retrieve the paginated list of signature keys. - ```Enable signature key``` Enable a signature key using the key_id returned in the ```create signature key``` endpoint. - ```Get enabled signature key``` Retrieve the current enabled signature key. - ```Disable an enabled signature key``` Disable the current enabled signature key. - name: Mobile Landing Pages (beta) description: | The mobile landing pages (MLP) API provides the facilities to create mobile landing pages and sends them to recipients. This API is currently in beta. *Note: This API is only available in the APAC region.* ## Concepts The approach to creating mobile landing pages involves creating a _Campaign_ and sending them to one or more _Recipients_. A campaign consists of the baseline configuration of a mobile landing page and message that will be generated and sent to each recipient. ## Parameters Campaign and Recipients can contain parameters. These parameters are used to customise the generated landing page and the message that is to be sent to each user. Campaign and Recipient parameters are merged to form a complete set when processing a recipient. When resolving parameters sets, Recipient parameters override Campaign parameters with the same name. Parameter names used within the template have an associated type, which will be validated when creating the Campaign or sending it to Recipients. You are free to define additional parameters for your own uses, such as when specifying the message. The SMS message that is to be sent to each user is defined at the Campaign level. The message itself can consist of parameter references surrounded in `${...}`, for example: ```Hello ${firstName} ${lastName}, this is your message.``` ## Sending Mobile Landing Pages From end to end, sending a Mobile Landing Pages involves the following steps: ### Step 1: Create a campaign Choose a template from the template catalogue, and work out what you are going to specify for the required parameters for that template. You will then use the `Create new campaign` endpoint to create the campaign. The following example specifies the desired parameters for the template_id and sets up a message template: ``` { "template_id": "ac895f01-3149-4bf8-a8fe-01d3b8a9ba97", "parameters": { "pageTitle": "The page title", "pageText": "The body text", "imageUrl": "https://example.com/image.jpg", "secondaryImageUrl": "https://www.example.com/optional_secondary_image.jpg", "buttonLink": "https://example.com/", "buttonText": "Call to Action Button Text", "secondaryButtonLink": "https://example.com/optional_secondary_button", "secondaryButtonText": "Secondary Call to Action Button" }, "message": { "content": "Hello ${firstName} ${lastName}, this is the SMS message body", "metadata": { "key": "value" } } } ``` Inside the message content the `{}` curly braces indicate template placeholders. These are the names of the parameters you will need to specify for the message when you send to your recipients. ### Step 2: Send to recipients Using the `Send campaign to recipients` endpoint, you can specify the id of your campaign in the path and a array of recipients as the payload. Each recipient will include an E.164 formatted (international) phone number, an optional scheduled time, and values of any recipient scoped template parameters you may have created. In the following example the recipients have been scoped with the template parameters above: ``` { "recipients": [ { "number": "+6140000000", "parameters": { "firstName":"Joe", "lastName","Bloe" } }, { "number": "+6141111111", "parameters": { "firstName":"Jane", "lastName","Doe" } } ] } ``` ## Landing Page Store The Landing Page Store is used by the Hub portal to store landing page templates that have been configured using the visual interface. This means that you can optionally use this data store to programatically send landing pages that have been designed and configured in the hub. If you have made a landing page in the hub, use the `Get landing pages` endpoint to find the landing pages you have made, along with the template and parameters that have been configured. You will then need to copy those template and parameters into a campaign. ## Template Parameters Each template will have different required parameters, shown in the Templates section. The following is a description of the requirements of each parameter when included in a template. | Parameter | Required | Tyep|Description | |------------------|-------------|-----------|-----------| | imageBackgroundUrl | Optional - depends on MLP template. |image| Width: 750 pixels, height: 1624 pixels, size: less than 300 kB, type: png, gif, or jpg| | barcodeValue | Optional - depends on MLP template. |text| Alphanumeric string. We will use CODE-128 format 1-D barcode. | | barcodeDisplayValue | Optional - defaults to true. Otherwise, use false |text| Indicates whether the barcode value is shown below the barcode image| | barcodeHeight| Optional| text|| | barcodeMargin| Optional| text|| | barcodeWidth| Optional| text|| | barcodeLineColor|Optional - each template has it's own default value| text| Indicate the color of bar code. Use a color name(eg. 'red', 'green'), or a hex value(eg. '#F0F8FF') | | pageText | |html| For personalisation, use the following format: "Hi ${firstName}, thanks for visiting…"| | pageTextColor|Optional - each template has it's own default value| text| Indicate the color of page text. Use a color name(eg. 'red', 'green'), or a hex value(eg. '#F0F8FF') | | imageHeaderUrl | Optional - depends on MLP template |image| Width: 750 pixels, height: 375 pixels, size: less than 300 kB, type: png, gif, or jpg.| | headline | |text| For personalisation, use the following format: "Hi ${firstName}, thanks for visiting…". Specifications: 60 characters or less recommended| | headlineColor|Optional - each template has it's own default value| text| Indicate the color of headline. Use a color name(eg. 'red', 'green'), or a hex value(eg. '#F0F8FF') | | pageTitle | |text| HTML page title shown on browser tab. Specifications: 60 characters or less recommended.| | imageLogoUrl |Optional |image| Specifications: width: 300 pixels, height: 120 pixels, size: less than 300 kB, type: png, gif, or jpg| | logoLink | Optional|url| For personalisation, use the following format: "https://example.com/?cid=${customerId}"| | primaryButtonLink | |url| For personalisation, use the following format: "https://example.com/?cid=${customerId}"| | primaryButtonText | |text| For personalisation, use the following format: "${firstName}, shop now". Specifications: 36 characters or less recommended | | primaryButtonTextColor|Optional - each template has it's own default value| text| Indicate the color of primary button text. Use a color name(eg. 'red', 'green'), or a hex value(eg. '#F0F8FF') | | primaryButtonBackgroundColor|Optional - each template has it's own default value| text| Indicate the background color of primary button. Use a color name(eg. 'red', 'green'), or a hex value(eg. '#F0F8FF') | | secondaryButtonLink | Optional - depends on MLP template |url| For personalisation, use the following format: "https://example.com/?cid=${customerId}"| | secondaryButtonText | Optional - depends on MLP template |text| For personalisation, use the following format: "Hi ${firstName}, thanks for visiting…". Specifications: 36 characters or less recommended | | secondaryButtonTextColor|Optional - each template has it's own default value| text| Indicate the color of the secondary button text. Use a color name(eg. 'red', 'green'), or a hex value(eg. '#F0F8FF') | | secondaryButtonBackgroundColor|Optional - each template has it's own default value| text| Indicate the background color of secondary button. Use a color name(eg. 'red', 'green'), or a hex value(eg. '#F0F8FF') | | fontFamilyURL1 | Optional - each template has it's own default value|url| Indicate the url of font family, those font family can be used in other property(eg. `headlineFontFamily`)| | fontFamilyURL2 | Optional - each template has it's own default value|url| Indicate the url of font family, those font family can be used in other property(eg. `headlineFontFamily`)| | fontFamilyURL3 | Optional - each template has it's own default value|url| Indicate the url of font family, those font family can be used in other property(eg. `headlineFontFamily`)| | pageTextFontFamily | |text| Specify the font family of page text | | headlineFontFamily | |text| Specify the font family of headline text | | buttonFontFamily | |text| Specify the font family of button text | ## Template Catalogue | Name and preview | Template ID | |-------------------|-------------| | ![](https://developers.sinch.com/wp-content/templates/Template1.png) | 7614456e-844f-4d83-bdfe-20c17ce0f97c | | ![](https://developers.sinch.com/wp-content/templates/Template2.png) | f56b5806-f732-4693-b87a-90b66a7d7bfc | |![](https://developers.sinch.com/wp-content/templates/template3.png) | c9d7ce1d-20c4-4228-9ba1-6da2a3b4e5e0 | - name: Contacts description: | The API provides access to two main resources: * **Contacts**: Data associated with the individuals you need to contact. * **Lists**: Groups of contacts created for specific purposes. * **Custom Fields**: Additional fields that can be tailored to complement the basic contact fields. paths: /v2-preview/reporting/messages/metakeys: post: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Metadata Keys description: Returns a list of metadata keys. operationId: PostMetadataKeys parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/metakeyrequest" responses: "200": description: A list of metadata keys. headers: {} content: application/json: schema: $ref: "#/components/schemas/metakeyresponse" "400": description: Bad Request. Check the json response for more details on what went wrong. "401": $ref: "#/components/responses/Unauthorized" /v2-preview/reporting/messages/detail: post: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Post detail report description: Generates a report listing all sent and/or received messages within a specified time period. operationId: PostDetailReport requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/detailrequest" responses: "200": description: A list of all messages received in the specified time window headers: {} content: application/json: schema: $ref: "#/components/schemas/detailresponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/messages/insights: post: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Post insight report description: Create report summary containing total number of sent, received and billing units, using pre-calculated data to improve performance. operationId: PostInsightReport requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/insightsrequest" responses: "200": description: A list of all messages received in the specified time window headers: {} content: application/json: schema: $ref: "#/components/schemas/insightsresponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/messages/async/detail: post: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Post async detail report description: Generates an asynchronous report listing all sent and/or received messages within a specified time period. operationId: PostAsyncDetailReport parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/asyncsentmessagesdetailrequest" required: true responses: "202": description: A list of all messages received in the specified time window headers: {} content: application/json: schema: $ref: "#/components/schemas/asyncreportresponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/messages/async/summary: post: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Post async summary report description: Creates an asynchronous report summary containing total number of sent, received and billing units. operationId: PostAsyncSummaryReport parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/asyncsummaryrequest" responses: "202": description: A list of all messages received in the specified time window headers: {} content: application/json: schema: $ref: "#/components/schemas/asyncreportresponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/messages/async/status: get: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Get async detail report status description: Retrieves the status of a detail report. operationId: GetAsyncDetailStatus parameters: - name: report_id in: query description: The ID of the detail report to retrieve. required: true style: form explode: true schema: type: string example: abc responses: "200": description: The status of the requested detail report. headers: {} content: application/json: schema: $ref: "#/components/schemas/reportstatusresponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/messages/async/detail/fields: post: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Get async detail fields description: Can be used for async detail report to select the fields to export csv files operationId: GetAsyncDetailFields parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/metakeyrequest" example: page: 1 page_size: 50 start_date: "2020-05-28T10:27:46.259Z" end_date: "2020-06-28T10:27:46.259Z" responses: "200": description: A list of selected fields to export csv files. headers: {} content: application/json: schema: $ref: "#/components/schemas/fieldsresponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/messages/async/reports: get: security: - basic_auth: [] - hmac_auth: [] - bearer_auth: [] tags: - Messaging Reports summary: Get async report history description: Returns a list of asynchronous reports that have been requested by the current account. operationId: GetAsyncReportHistory parameters: - name: page_size in: query description: The number of items to return per page. required: false style: form explode: true schema: type: integer example: 10 - name: page_token in: query description: A pagination token returned from a previous call. Pass this to retrieve the next page of results. required: false style: form explode: true schema: type: string example: eyJyZXBvcnRJZCI6IjUxZjAwOTdmLTkwYjItNGE1OS1hZDg4LWEwZmQ5M2FiYWE4MiJ9 - name: report_name in: query description: Filter results by report name. required: false style: form explode: true schema: type: string example: My Detail Report - name: status in: query description: Filter results by report status. Multiple statuses can be specified. required: false style: form explode: true schema: type: array items: type: string enum: - REQUESTED - RUNNING - FAILED - CANCELLED - DONE - name: start_date in: query description: Filter reports requested on or after this date (ISO 8601). required: false style: form explode: true schema: type: string format: date-time example: "2020-05-28T10:27:46.259Z" - name: end_date in: query description: Filter reports requested on or before this date (ISO 8601). required: false style: form explode: true schema: type: string format: date-time example: "2020-06-28T10:27:46.259Z" - name: sort_direction in: query description: Sort direction for the results. required: false style: form explode: true schema: type: string enum: - ASCENDING - DESCENDING example: DESCENDING responses: "200": description: A list of async reports for the current account. headers: {} content: application/json: schema: $ref: "#/components/schemas/reporthistoryresponses" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/messages/async/reports/{reportId}/download-url: get: security: - basic_auth: [] - hmac_auth: [] - bearer_auth: [] tags: - Messaging Reports summary: Get async report download URL description: Returns a temporary pre-signed URL for downloading the generated report. The URL allows customers to securely download the report file directly using the provided reportId. operationId: GetAsyncReportDownloadUrl parameters: - name: reportId in: path description: The ID of the report to download. required: true style: simple schema: type: string format: uuid example: 51f0097f-90b2-4a59-ad88-a0fd93abaa82 responses: "200": description: A pre-signed URL for downloading the report. headers: {} content: application/json: schema: $ref: "#/components/schemas/presignedurlresponse" "401": $ref: "#/components/responses/Unauthorized" "404": description: Report not found. /v2-preview/reporting/detail/scheduled: post: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Scheduled detail report description: Create scheduled report in detail containing total number of sent, received and billing units. operationId: detailscheduledreport parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/scheduleddetailreport" required: true responses: "201": description: A scheduled detail report received using the specified parameters. content: application/json: schema: $ref: "#/components/schemas/scheduledreportresponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/detail/scheduled/{scheduled_id}: put: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Update a scheduled detail report description: Updates a selected scheduled report in detail, which contains a total number of sent, received and billing units. operationId: updatedetailscheduledreport parameters: - name: scheduled_id in: path required: true schema: type: string description: The ID of the scheduled report to update. example: e6fb8282-c7c3-4367-8590-6c77ddb11c3e requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/updatescheduleddetailreport" required: true responses: "200": description: The updated scheduled detail report. content: application/json: schema: $ref: "#/components/schemas/scheduleddetailreportresponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/summary/scheduled: post: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Scheduled summary report description: Create scheduled report summary containing total number of sent, received and billing units. operationId: summaryscheduledreport parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/scheduledsummaryreport" required: true responses: "201": description: A scheduled summary report received using the specified parameters. content: application/json: schema: $ref: "#/components/schemas/scheduledreportresponse" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/summary/scheduled/{scheduled_id}: put: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Update a scheduled summary report description: Updates a selected scheduled report summary, which contains a total number of sent, received and billing units. operationId: updatesummaryscheduledreport parameters: - name: scheduled_id in: path required: true schema: type: string description: The ID of the scheduled report to update. example: e6fb8282-c7c3-4367-8590-6c77ddb11c3e requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/updatescheduledsummaryreport" required: true responses: "200": description: The updated scheduled summary report. content: application/json: schema: $ref: "#/components/schemas/scheduledsummaryreportresposne" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v2-preview/reporting/scheduled: get: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Get active reports description: Retrieves all ACTIVE scheduled reports of a provided account. operationId: GetActiveReport parameters: - name: page_size in: query description: Number of results to return in a page for paginated result sets. style: form explode: true schema: type: number example: 20 minimum: 1 maximum: 100 - name: page_token in: query description: Returned by Chronos service schema: type: string example: eyJwYWdlIjoyfQ responses: "200": description: A list of all messages received in the specified time window headers: {} content: application/json: schema: $ref: "#/components/schemas/chronosscheduleresponse" "401": $ref: "#/components/responses/Unauthorized" "404": description: Scheduled report not found. /v2-preview/reporting/scheduled/{scheduled_id}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Get scheduled report by id description: Retrieves a scheduled report by providing its id. operationId: GetScheduledReport parameters: - name: scheduled_id in: path required: true schema: type: string description: The ID of the scheduled report to retrieve. example: e6fb8282-c7c3-4367-8590-6c77ddb11c3e responses: "200": description: The scheduled report matching the provided ID. headers: {} content: application/json: schema: $ref: "#/components/schemas/scheduledreport" "401": $ref: "#/components/responses/Unauthorized" "404": description: Scheduled report not found. delete: security: - basic_auth: [] - hmac_auth: [] tags: - Messaging Reports summary: Delete scheduled report by id description: Deletes a scheduled report by providing its id. operationId: DeleteScheduledReport parameters: - name: scheduled_id in: path required: true schema: type: string description: The ID of the scheduled report to delete. example: e6fb8282-c7c3-4367-8590-6c77ddb11c3e responses: "202": description: An empty response indicating the report has been deleted. "401": $ref: "#/components/responses/Unauthorized" "404": description: Scheduled report not found. /v1/messages/{messageId}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Messages summary: Get message status description: | Retrieve the current status of a message using the message ID returned in the send messages endpoint. A successful request to the get message status endpoint will return a response body as follows: ```javascript { "format": "SMS", "content": "My first message!", "metadata": { "key1": "value1", "key2": "value2" }, "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7", "callback_url": "https://my.callback.url.com", "delivery_report": true, "destination_number": "+61401760575", "scheduled": "2016-11-03T11:49:02.807Z", "source_number": "+61491570157", "source_number_type": "INTERNATIONAL", "message_expiry_timestamp": "2016-11-03T11:49:02.807Z", "status": "enroute" } ``` The status property of the response indicates the current status of the message. See the Delivery Reports section of this documentation for more information on message statuses. The expiry date for getting an entity is 45 days. *Note: If an invalid or nonexistent message ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned* operationId: GetMessageStatus parameters: - name: messageId in: path description: 36 character UUID. required: true style: simple schema: type: string example: 389dc1a8-62a4-4110-ba61-af94806c006f responses: "200": description: The submitted message including the status of the message headers: {} content: application/json: schema: $ref: "#/components/schemas/Getmessagestatusresponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" x-codeSamples: - lang: C# label: C# source: |- string messageId = "messageId2"; try { GetMessageStatusResponse result = messages.GetMessageStatusAsync(messageId).Result; } catch (APIException e){}; - lang: Java label: Java source: |- String messageId = "messageId2"; messagesController.getMessageStatusAsync(messageId, new APICallBack() { public void onSuccess(HttpContext context, GetMessageStatusResponse response) { // TODO success callback handler } public void onFailure(HttpContext context, Throwable error) { // TODO failure callback handler } }); - lang: JavaScript label: JavaScript source: |- let messageId = 'messageId2'; const promise = controller.getMessageStatus(messageId); promise.then((response) => { // this block will be executed on successful endpoint call // `response` will be of type 'GetMessageStatusResponse' }, (err) => { // this block will be executed on endpoint call failure // `err` is an 'object' containing more information about the error }); - lang: PHP label: PHP source: |- $messageId = 'messageId2'; $result = $messagesController->getMessageStatus($messageId); - lang: Python label: Python source: |- message_id = 'messageId2' result = messages_controller.get_message_status(message_id) put: security: - basic_auth: [] - hmac_auth: [] tags: - Messages summary: Cancel scheduled message description: | Cancel a scheduled message that has not yet been delivered. A scheduled message can be cancelled by updating the status of a message from ```scheduled``` to ```cancelled```. This is done by submitting a PUT request to the messages endpoint using the message ID as a parameter (the same endpoint used above to retrieve the status of a message). The expiry date for getting an entity is 45 days. The body of the request simply needs to contain a ```status``` property with the value set to ```cancelled```. ```javascript { "status": "cancelled" } ``` *Note: Only messages with a status of scheduled can be cancelled. If an invalid or nonexistent message ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned* operationId: CancelScheduledMessage parameters: - name: messageId in: path description: 36 character UUID. required: true style: simple schema: type: string example: 389dc1a8-62a4-4110-ba61-af94806c006f requestBody: description: Parameters of a message to change. content: application/json: schema: $ref: "#/components/schemas/Cancelscheduledmessagerequest" example: status: cancelled required: true responses: "200": description: Message status updated successfully "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" x-codeSamples: - lang: C# label: C# source: |- string messageId = "messageId2"; CancelScheduledMessageRequest body = new CancelScheduledMessageRequest(); body.Status = "cancelled"; try { dynamic result = messages.CancelScheduledMessageAsync(messageId, body).Result; } catch (APIException e){}; - lang: Java label: Java source: |- String messageId = "messageId2"; CancelScheduledMessageRequest body = new CancelScheduledMessageRequest(); body.setStatus("cancelled"); messagesController.cancelScheduledMessageAsync(messageId, body, new APICallBack() { public void onSuccess(HttpContext context, DynamicResponse response) { // TODO success callback handler } public void onFailure(HttpContext context, Throwable error) { // TODO failure callback handler } }); - lang: JavaScript label: JavaScript source: |- let messageId = 'messageId2'; let body = new lib.CancelScheduledMessageRequest(); body.status = 'cancelled'; const promise = controller.cancelScheduledMessage(messageId, body); promise.then((response) => { // this block will be executed on successful endpoint call // `response` will be of type 'mixed' }, (err) => { // this block will be executed on endpoint call failure // `err` is an 'object' containing more information about the error }); - lang: PHP label: PHP source: |- $messageId = 'messageId2'; $body = new Models\CancelScheduledMessageRequest; $body->status = 'cancelled'; $result = $messagesController->cancelScheduledMessage($messageId, $body); - lang: Python label: Python source: |- message_id = 'messageId2' body = CancelScheduledMessageRequest() body.status = 'cancelled' result = messages_controller.cancel_scheduled_message(message_id, body) /v1/messages: post: security: - basic_auth: [] - hmac_auth: [] tags: - Messages summary: Send messages description: | Submit one or more (up to 100 per request) SMS, MMS or text to voice messages for delivery. The most basic message has the following structure: ```javascript { "messages": [ { "content": "My first message!", "destination_number": "+61491570156" } ] } ``` More advanced delivery features can be specified by setting the following properties in a message: - ```callback_url``` A URL can be included with each message to which Webhooks will be pushed to via a HTTP POST request. Webhooks will be sent if and when the status of the message changes as it is processed (if the delivery report property of the request is set to ```true```) and when replies are received. Specifying a callback URL is optional. - ```content``` The content of the message. This can be a Unicode string, up to 5,000 characters long. Message content is required. - ```delivery_report``` Delivery reports can be requested with each message. If delivery reports are requested, a webhook will be submitted to the ```callback_url``` property specified for the message (or to the webhooks) specified for the account every time the status of the message changes as it is processed. The current status of the message can also be retrieved via the Delivery Reports endpoint of the Messages API. Delivery reports are optional and by default will not be requested. - ```destination_number``` The destination number the message should be delivered to. This should be specified in E.164 international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. A destination number is required. ⚠️ IMDA TLS Compliance Notice: From 1 April 2026, all requests sending messages to Singapore (+65) numbers must use TLS 1.3 or higher. Requests using an older TLS version will be rejected with HTTP 422 Unprocessable Entity. - ```format``` The format specifies which format the message will be sent as, ```SMS``` (text message), ```MMS``` (multimedia message) or ```TTS``` (text to speech). With ```TTS``` format, we will call the destination number and read out the message using a computer generated voice. Specifying a format is optional, by default ```SMS``` will be used. - ```source_number_type``` If a source number is specified, the type of source number may also be specified. This is recommended when using a source address type that is not an internationally formatted number, available options are ```INTERNATIONAL```, ```ALPHANUMERIC``` or ```SHORTCODE```. Specifying a source number type is only valid when the ```source_number``` parameter is specified and is optional. If a source number is specified and no source number type is specified, the source number type will be inferred from the source number, however this may be inaccurate. - ```source_number```[optional] Specify a source number to be used. Refer to the section below for more information on source numbers. ⚠️ The number or sender ID must be registered to your account (from 1-Mar-2024). #### Source number (sender ID) There are several options for the number or sender ID that will show as the source of an outbound message. Some things to note: - If you do not specify a source number, the message will be sent with the default number for your account. - The default may be a number you have purchased from us - such as a dedicated number, a 10-digit longcode or toll-free number (US/CA), or a shortcode. Log into the web portal to manage your numbers. - If your account has multiple numbers, you can specify which source number to use in the request. - If your account does not have a number, your message may be sent using our shared number pool (in certain countries only) - `Alpha tag:` In some countries (AU, GB, some others), you may be able to send using an alpha tag - text that represents your brand of business. Before using an alpha tag, you must register it in the Numbers section of the web portal. - `Other numbers:` You may use numbers that you own as the source number, but you must register them in the Numbers section of the web portal to confirm you have a right to use the number. If you need to register a large number of source numbers/sender IDs, consider using our [Source Address API](#tag/Source-Address) ⚠️ If you specify a source_number that is not registered to your account, the message may fail to send, or may be sent with an alternative number. - ```media``` The media is used to specify a list of URLs of the media file(s) that you are trying to send. Supported file formats include png, jpeg and gif. ```format``` parameter must be set to ```MMS``` for this to work. - ```subject``` The subject field is used to denote subject of the MMS message and has a maximum size of 64 characters long. Specifying a subject is optional. - ```scheduled``` A message can be scheduled for delivery in the future by setting the scheduled property. The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be provided in UTC and is optional. If no scheduled property is set, the message will be delivered immediately. - ```message_expiry_timestamp``` A message expiry timestamp can be provided to specify the latest time at which the message should be delivered. If the message cannot be delivered before the specified message expiry timestamp elapses, the message will be discarded. Specifying a message expiry timestamp is optional. - ```metadata``` Metadata can be included with the message which will then be included with any delivery reports or replies matched to the message. This can be used to create powerful two-way messaging applications without having to store persistent data in the application. Up to 10 key / value metadata data pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to 256 characters long. Specifying metadata for a message is optional. The response body of a successful POST request to the messages endpoint will include a ```messages``` property which contains a list of all messages submitted. The list of messages submitted will reflect the list of messages included in the request, but each message will also contain two new properties, ```message_id``` and ```status```. The returned message ID will be a 36 character UUID which can be used to check the status of the message via the Get Message Status endpoint. The status of the message which reflect the status of the message at submission time which will always be ```queued```. See the Delivery Reports section of this documentation for more information on message statuses. *Note: when sending multiple messages in a request, all messages must be valid for the request to be successful. If any messages in the request are invalid, no messages will be sent.* operationId: SendMessages parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/Sendmessagesrequest" example: messages: - callback_url: https://my.callback.url.com content: My first message destination_number: "+61491570156" delivery_report: true format: SMS message_expiry_timestamp: "2016-11-03T11:49:02.807Z" metadata: key1: value1 key2: value2 scheduled: "2016-11-03T11:49:02.807Z" source_number: "+61491570157" source_number_type: INTERNATIONAL - callback_url: https://my.callback.url.com content: My second message destination_number: "+61491570158" delivery_report: true format: MMS subject: This is an MMS message media: - https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg message_expiry_timestamp: "2016-11-03T11:49:02.807Z" metadata: key1: value1 key2: value2 scheduled: "2016-11-03T11:49:02.807Z" source_number: "+61491570159" source_number_type: INTERNATIONAL required: true responses: "202": description: Messages were accepted for processing headers: {} content: application/json: schema: $ref: "#/components/schemas/Sendmessagesresponse" "400": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/400response" example: message: Something went wrong. Please try again later. "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" x-codeSamples: - lang: C# label: C# source: |- SendMessagesRequest body = new SendMessagesRequest(); body.Messages = new List(); Message body_messages_0 = new Message(); body_messages_0.CallbackUrl = "https://my.callback.url.com"; body_messages_0.Content = "My first message"; body_messages_0.DestinationNumber = "+61491570156"; body_messages_0.DeliveryReport = true; body_messages_0.Format = Format.SMS; body_messages_0.MessageExpiryTimestamp = DateTime.Parse("2016-11-03T11:49:02.807Z"); body_messages_0.Metadata = APIHelper.JsonDeserialize("{\"key1\":\"value1\",\"key2\":\"value2\"}"); body_messages_0.Scheduled = DateTime.Parse("2016-11-03T11:49:02.807Z"); body_messages_0.SourceNumber = "+61491570157"; body_messages_0.SourceNumberType = SourceNumberType.INTERNATIONAL; body.Messages.Add(body_messages_0); Message body_messages_1 = new Message(); body_messages_1.CallbackUrl = "https://my.callback.url.com"; body_messages_1.Content = "My second message"; body_messages_1.DestinationNumber = "+61491570158"; body_messages_1.DeliveryReport = true; body_messages_1.Format = Format.MMS; body_messages_1.MessageExpiryTimestamp = DateTime.Parse("2016-11-03T11:49:02.807Z"); body_messages_1.Metadata = APIHelper.JsonDeserialize("{\"key1\":\"value1\",\"key2\":\"value2\"}"); body_messages_1.Scheduled = DateTime.Parse("2016-11-03T11:49:02.807Z"); body_messages_1.SourceNumber = "+61491570159"; body_messages_1.SourceNumberType = SourceNumberType.INTERNATIONAL; body_messages_1.Media = new List(); body_messages_1.Media.Add("https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg"); body_messages_1.Subject = "This is an MMS message"; body.Messages.Add(body_messages_1); try { SendMessagesResponse result = messages.SendMessagesAsync(body).Result; } catch (APIException e){}; - lang: Java label: Java source: | SendMessagesRequest body = new SendMessagesRequest(); body.setMessages(new LinkedList()); Message body_messages_0 = new Message(); body_messages_0.setCallbackUrl("https://my.callback.url.com"); body_messages_0.setContent("My first message"); body_messages_0.setDestinationNumber("+61491570156"); body_messages_0.setDeliveryReport(true); body_messages_0.setFormat(FormatEnum.SMS); body_messages_0.setMessageExpiryTimestamp(new DateTime("2016-11-03T11:49:02.807Z", DateTimeZone.UTC)); body_messages_0.setMetadata(com.messagemedia.messages.APIHelper.deserialize("{\"key1\":\"value1\",\"key2\":\"value2\"}")); body_messages_0.setScheduled(new DateTime("2016-11-03T11:49:02.807Z", DateTimeZone.UTC)); body_messages_0.setSourceNumber("+61491570157"); body_messages_0.setSourceNumberType(SourceNumberTypeEnum.INTERNATIONAL); body.getMessages().add(body_messages_0); Message body_messages_1 = new Message(); body_messages_1.setCallbackUrl("https://my.callback.url.com"); body_messages_1.setContent("My second message"); body_messages_1.setDestinationNumber("+61491570158"); body_messages_1.setDeliveryReport(true); body_messages_1.setFormat(FormatEnum.MMS); body_messages_1.setMessageExpiryTimestamp(new DateTime("2016-11-03T11:49:02.807Z", DateTimeZone.UTC)); body_messages_1.setMetadata(com.messagemedia.messages.APIHelper.deserialize("{\"key1\":\"value1\",\"key2\":\"value2\"}")); body_messages_1.setScheduled(new DateTime("2016-11-03T11:49:02.807Z", DateTimeZone.UTC)); body_messages_1.setSourceNumber("+61491570159"); body_messages_1.setSourceNumberType(SourceNumberTypeEnum.INTERNATIONAL); body_messages_1.setMedia(new LinkedList()); body_messages_1.getMedia().add("https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg"); body_messages_1.setSubject("This is an MMS message"); body.getMessages().add(body_messages_1); messagesController.sendMessagesAsync(body, new APICallBack() { public void onSuccess(HttpContext context, SendMessagesResponse response) { // TODO success callback handler } public void onFailure(HttpContext context, Throwable error) { // TODO failure callback handler } }); - lang: JavaScript label: JavaScript source: |- let body = new lib.SendMessagesRequest(); body.messages = []; body.messages[0] = new lib.Message(); body.messages[0].callbackUrl = 'https://my.callback.url.com'; body.messages[0].content = 'My first message'; body.messages[0].destinationNumber = '+61491570156'; body.messages[0].deliveryReport = true; body.messages[0].format = lib.FormatEnum.SMS; body.messages[0].messageExpiryTimestamp = moment('2016-11-03T11:49:02.807Z').parseZone('2016-11-03T11:49:02.807Z'); body.messages[0].metadata = JSON.parse('{"key1":"value1","key2":"value2"}'); body.messages[0].scheduled = moment('2016-11-03T11:49:02.807Z').parseZone('2016-11-03T11:49:02.807Z'); body.messages[0].sourceNumber = '+61491570157'; body.messages[0].sourceNumberType = lib.SourceNumberTypeEnum.INTERNATIONAL; body.messages[1] = new lib.Message(); body.messages[1].callbackUrl = 'https://my.callback.url.com'; body.messages[1].content = 'My second message'; body.messages[1].destinationNumber = '+61491570158'; body.messages[1].deliveryReport = true; body.messages[1].format = lib.FormatEnum.MMS; body.messages[1].messageExpiryTimestamp = moment('2016-11-03T11:49:02.807Z').parseZone('2016-11-03T11:49:02.807Z'); body.messages[1].metadata = JSON.parse('{"key1":"value1","key2":"value2"}'); body.messages[1].scheduled = moment('2016-11-03T11:49:02.807Z').parseZone('2016-11-03T11:49:02.807Z'); body.messages[1].sourceNumber = '+61491570159'; body.messages[1].sourceNumberType = lib.SourceNumberTypeEnum.INTERNATIONAL; body.messages[1].media = ['https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg']; body.messages[1].subject = 'This is an MMS message'; const promise = controller.sendMessages(body); promise.then((response) => { // this block will be executed on successful endpoint call // `response` will be of type 'SendMessagesResponse' }, (err) => { // this block will be executed on endpoint call failure // `err` is an 'object' containing more information about the error }); - lang: PHP label: PHP source: |- $body = new Models\SendMessagesRequest; $body->messages = array(); $body->messages[0] = new Models\Message; $body->messages[0]->callbackUrl = 'https://my.callback.url.com'; $body->messages[0]->content = 'My first message'; $body->messages[0]->destinationNumber = '+61491570156'; $body->messages[0]->deliveryReport = true; $body->messages[0]->format = Models\FormatEnum::SMS; $body->messages[0]->messageExpiryTimestamp = DateTimeHelper::fromRfc3339DateTime('2016-11-03T11:49:02.807Z'); $body->messages[0]->metadata = MessageMediaMessagesLib\APIHelper::deserialize('{"key1":"value1","key2":"value2"}'); $body->messages[0]->scheduled = DateTimeHelper::fromRfc3339DateTime('2016-11-03T11:49:02.807Z'); $body->messages[0]->sourceNumber = '+61491570157'; $body->messages[0]->sourceNumberType = Models\SourceNumberTypeEnum::INTERNATIONAL; $body->messages[1] = new Models\Message; $body->messages[1]->callbackUrl = 'https://my.callback.url.com'; $body->messages[1]->content = 'My second message'; $body->messages[1]->destinationNumber = '+61491570158'; $body->messages[1]->deliveryReport = true; $body->messages[1]->format = Models\FormatEnum::MMS; $body->messages[1]->messageExpiryTimestamp = DateTimeHelper::fromRfc3339DateTime('2016-11-03T11:49:02.807Z'); $body->messages[1]->metadata = MessageMediaMessagesLib\APIHelper::deserialize('{"key1":"value1","key2":"value2"}'); $body->messages[1]->scheduled = DateTimeHelper::fromRfc3339DateTime('2016-11-03T11:49:02.807Z'); $body->messages[1]->sourceNumber = '+61491570159'; $body->messages[1]->sourceNumberType = Models\SourceNumberTypeEnum::INTERNATIONAL; $body->messages[1]->media = array('https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg'); $body->messages[1]->subject = 'This is an MMS message'; $result = $messagesController->sendMessages($body); - lang: Python label: Python source: |- body = SendMessagesRequest() body.messages = [] body.messages.append(Message()) body.messages[0].callback_url = 'https://my.callback.url.com' body.messages[0].content = 'My first message' body.messages[0].destination_number = '+61491570156' body.messages[0].delivery_report = True body.messages[0].format = FormatEnum.SMS body.messages[0].message_expiry_timestamp = dateutil.parser.parse('2016-11-03T11:49:02.807Z') body.messages[0].metadata = jsonpickle.decode('{"key1":"value1","key2":"value2"}') body.messages[0].scheduled = dateutil.parser.parse('2016-11-03T11:49:02.807Z') body.messages[0].source_number = '+61491570157' body.messages[0].source_number_type = SourceNumberTypeEnum.INTERNATIONAL body.messages.append(Message()) body.messages[1].callback_url = 'https://my.callback.url.com' body.messages[1].content = 'My second message' body.messages[1].destination_number = '+61491570158' body.messages[1].delivery_report = True body.messages[1].format = FormatEnum.MMS body.messages[1].message_expiry_timestamp = dateutil.parser.parse('2016-11-03T11:49:02.807Z') body.messages[1].metadata = jsonpickle.decode('{"key1":"value1","key2":"value2"}') body.messages[1].scheduled = dateutil.parser.parse('2016-11-03T11:49:02.807Z') body.messages[1].source_number = '+61491570159' body.messages[1].source_number_type = SourceNumberTypeEnum.INTERNATIONAL body.messages[1].media = ['https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg'] body.messages[1].subject = 'This is an MMS message' result = messages_controller.send_messages(body) /v1/messaging/numbers/sender_address/requests: post: security: - basic_auth: [] - hmac_auth: [] tags: - Source Address summary: Request a Sender Address description: | Submit a request to register a new Sender ID. When making a request to this endpoint, you will always need to specify ```sender_address_type``` and ```usage_type``` parameters. The following table shows the acceptable values and combinations for these parameters: | Sender ID | sender_address_type | usage_type | |--- |--- |--- | | Alpha tag | `ALPHANUMERIC` | `ALPHANUMERIC` | | Personal number | `INTERNATIONAL` | `OWN_NUMBER` | The other parameters required for your request will depend on the type of Sender ID you are registering. ### Sender ID is an Alpha Tag The following parameters are used when registering an alpha tag as a Sender ID: - ```sender_address:``` **(Required)**. The alphanumeric string that you wish register as an alpha tag. This parameter is case insensitive. If this alpha tag already exists on your account, you will receive a conflict error message. - ```destination_countries:``` **(Required)**. The countries that you wish to register the alpha tag for use in, in two-character ISO 3166 format. Currently AD, AI, AL, AS, AT, AW, BA, BB, BH, BW, CD, CH, CK, CY, DE, DJ, DK, DM, EE, ES, FI, FJ, FM, FO, FR, GB, GD, GG, GI, GL, GM, GQ, GR, GY, IL, IM, IS, JE, JM, JP, KI, KY, LA, LI, LS, LT, LU, LV, MC, ME, MH, MO, MR, MS, MT, MV, NC, NF, NL, NO, NR, NU, PF, PM, PT, SB, SC, SE, SH, SL, SM, ST, TC, TD, TO, VC, VG and WS are supported. - ```sender_address_type:``` **(Required)**. For alpha tags this is always ALPHANUMERIC - ```usage_type:``` **(Required)**. For alpha tags this is always ALPHANUMERIC - ```label:``` **(Optional)**. A reference name for the sender ID to allow you to easily track it. - ```reason:``` **(Required)**. This is a specifically formatted string made up of the following sub-items (all of which are required): - `useCase:` one of the following: - `SOLE_TRADER_NAME` - `COMPANY_NAME` - `PARTNERSHIP_NAME` - `REGISTERED_TRUST_NAME` - `CO_OPERATIVE_NAME` - `INDIGENOUS_CORPORATION_NAME` - `REGISTERED_ORGANISATION_NAME` - `PERSONAL_NAME` - `AUSTRALIAN_TRADEMARK` - `INTERNATIONAL_TRADEMARK` - `AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY` - `FOREIGN_GOVERNMENT_AGENCY_OR_ENTITY` - `PRODUCT_OR_SERVICE_NAME` - `ACRONYM_INITIALISM` - `CONTRACTION_OF_NAME` - `OTHER` - `description:` A description used if OTHER was selected as the use case. Limited to 200 characters. - `email:` The preferred contact email for our approval team when additional details are required. - `australianGovernmentAgencyOrEntityName:` The name of your organisation. - `abn:` Your organisation’s Australian Business Number - `statement:` A legal declaration - If applying for your own business: "We are authorized to use the Sender ID with a valid use case." - If applying on behalf of a third-party entity: "We are authorized to use the Sender ID on behalf of [full entity name of sender] with a valid use case." The reason parameter must contain all the above items. A well formatted reason looks like the following: - "reason": "{\n  \\"useCase\\":\\"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY\\",\n  \\"description\\":\\"bal bla\\",\n  \\"email\\":\\"example@email.com\\",\n  \\"australianGovernmentAgencyOrEntityName\\":\\"bla bla\\",\n  \\"statement\\":\\"We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case.\\"\n}\n" ### Sender ID is a Personal Number The following parameters are used when registering a personal mobile phone number as a Sender ID: - ```sender_address:``` **(Required)**. The phone number that you wish register as a personal number. This number must be in E.164. If this number is already registered to an account, you will receive a conflict error message. - ```destination_countries:``` **(Required)**. The country of the number that you wish to register, in two-character ISO 3166 format. Refer to the **Types of Sender ID** section for a list of currently supported countries. - ```sender_address_type:``` **(Required)**. For personal numbers this is always INTERNATIONAL - ```usage_type:``` **(Required)**. For personal numbers this is always OWN_NUMBER - ```label:``` **(Optional)**. A reference name for the sender ID to allow you to easily track it. - ```Reason:``` **(Required)**. A string describing why you wish to register the number as a Sender ID. Limited to 200 characters. operationId: requestSenderAddressUsingPOST parameters: [] requestBody: description: Request body. content: application/json: schema: oneOf: - $ref: "#/components/schemas/RequestAlphaTag" - $ref: "#/components/schemas/RequestVerificationCode" examples: example1: summary: Example for RequestAlphaTag value: sender_address: EXAMPLE sender_address_type: ALPHANUMERIC usage_type: ALPHANUMERIC destination_countries: - AU reason: | { "useCase":"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY", "description":"bal bla", "email":"xample@email.com", "australianGovernmentAgencyOrEntityName":"bla bla", "statement":"We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case." } label: label example2: summary: Example for RequestVerificationCode value: sender_address: "+61401234567" sender_address_type: INTERNATIONAL usage_type: OWN_NUMBER destination_countries: - AU reason: my personal number label: label required: true responses: "201": description: Created headers: {} content: application/json: schema: oneOf: - $ref: "#/components/schemas/AlphaTagRequestItem" - $ref: "#/components/schemas/VerificationCodeRequestItem" examples: example1: summary: Example for AlphaTagRequest value: id: 6f79a12e-14f1-4776-adc0-5c5e48a999b7 sender_address: EXAMPLE sender_address_type: ALPHANUMERIC usage_type: ALPHANUMERIC destination_countries: - AU reason: | { "useCase":"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY", "description":"bal bla", "email":"xample@email.com", "australianGovernmentAgencyOrEntityName":"bla bla", "statement":"We are authorised to use the Sender ID on behalf of [full entity name of sender] with a valid use case." } label: label status: OPEN account_id: XYZ_ExampleAccount created_date: "2023-10-25T14:15:22Z" last_modified_date: "2023-10-25T14:15:22Z" example2: summary: Example for VerificationCodeRequest value: id: 6f79a12e-14f1-4776-adc0-5c5e48a999b8 sender_address: "+61401234567" sender_address_type: INTERNATIONAL usage_type: OWN_NUMBER destination_countries: - AU reason: my personal number label: label status: PENDING account_id: XYZ_ExampleAccount created_date: "2023-10-24T14:15:22Z" last_modified_date: "2023-10-24T14:15:22Z" "400": description: Bad Request "401": description: Unauthorized "403": description: Forbidden "409": description: Conflict /v1/messaging/numbers/sender_address/requests/{id}/verify: post: security: - basic_auth: [] - hmac_auth: [] tags: - Source Address summary: Submitting a verification code description: | Complete the 2FA verification process required to register a Personal Number as a Sender ID. The following parameters are required for this request: - ```id:``` The UUID received in the API response of your request to the **Request a Sender Address** endpoint. - ```verification_code:``` The six-digit code received via SMS to the phone number that you are attempting to register operationId: SubmittingVerificationCodePost parameters: - name: id in: path description: 36 character UUID. required: true style: simple schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 requestBody: description: Verification code to be verified content: application/json: schema: $ref: "#/components/schemas/PostVerificationCode" required: true responses: "201": description: Created headers: {} content: application/json: schema: $ref: "#/components/schemas/VerificationCodeRequestItem" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" /v1/messaging/numbers/sender_address/addresses/{id}/reverify: post: tags: - Source Address summary: Re-verify Sender Address description: | The below table defines the allowed combination of `sender_address_type` and `usage_type` values | Description | sender_address_type | usage_type | | ---------------- | ------------------- | ------------ | | Own Number | INTERNATIONAL | OWN_NUMBER | OWN_NUMBER Sender Addresses require reverification every 12 months to allow continued use. The reverification process is quite similar to the original verification process for the Sender Address, and requires a fresh 2FA check. To reverify an OWN_NUMBER Sender Address: 1. Retrieve the UUID for the OWN_NUMBER using the **Get all approved sender addresses** endpoint 2. Make a request to this endpoint to trigger the 2FA check 3. Make a POST request to the **Submit verification code endpoint**, providing the new 2FA code in the body of the request operationId: reVerifySenderAddressUsingPOST security: - basic_auth: [] - hmac_auth: [] parameters: - name: id in: path description: Sender Address ID required: true style: simple schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 responses: "200": description: OK headers: {} content: application/json: schema: $ref: "#/components/schemas/ReVerifySenderAddressRequestItem" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" /v1/messaging/numbers/sender_address/requests/{id}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Source Address summary: Get status of a sender address request description: | Retrieve the current status of a sender address request using the request ID returned in the sender address request endpoint. A successful request to the get message status endpoint will return a response body as follows: ```javascript { "id": "365dd65f-7101-46cd-8e79-e49c5620eb15", "sender_address": "sample", "sender_address_type": "ALPHANUMERIC", "usage_type": "ALPHANUMERIC", "destination_countries": [ "AU" ], "reason": "This is my approval reason", "label": "label" "status": "APPROVED", "account_id": "sample", "created_date": "2023-09-07T05:48:26.741Z", "last_modified_date": "2023-09-07T05:49:20.888Z" } ``` operationId: GetStatusOfSenderAddressRequest parameters: - name: id in: path description: 36 character UUID. required: true style: simple schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 responses: "200": description: Get the status of Sender Address Request headers: {} content: application/json: schema: $ref: "#/components/schemas/AlphaTagRequestItem" "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" /v1/messaging/numbers/sender_address/addresses/: get: security: - basic_auth: [] - hmac_auth: [] tags: - Source Address summary: Get all approved sender addresses operationId: GetAllApprovedSenderAddresses description: | Retrieve all sender addresses currently registered to your account. parameters: - name: sender_address in: query schema: type: string description: A string containing some or all of a specific Sender ID example: EXAMPLE - name: sender_address_type in: query schema: type: string enum: - ALPHANUMERIC - INTERNATIONAL description: The type of Sender ID. This will be either ALPHANUMERIC or INTERNATIONAL example: ALPHANUMERIC - name: usage_type in: query schema: type: string enum: - ALPHANUMERIC - OWN_NUMBER - DEDICATED description: The usage type of the Sender ID. This will be ALPHANUMERIC, OWN_NUMBER, or DEDICATED example: ALPHANUMERIC - name: include_related_accounts in: query description: | When true, include Sender IDs that belong to related accounts in addition to those on the authenticated account. schema: type: boolean example: true - name: expiry_status in: query schema: type: string enum: - EXPIRED - EXPIRING description: | Filter the results by OWN_NUMBER Sender IDs that are already expired, or will expire soon. Acceptable values are EXPIRED and EXPIRING. This parameter requires both the sender_address_type and usage_type parameters to be present. example: EXPIRED - name: page_size in: query schema: type: integer default: 20 example: 20 description: The number of results per page. Default is 20. - name: token in: query description: In paginated data, the original request will return with a "next_token" attribute. This token must be entered into subsequent call in the "token" query parameter to obtain the next set of records. schema: type: string example: eyJwYWdlIjoyfQ responses: "200": description: A list of approved sender addresses for your account only headers: {} content: application/json: schema: $ref: "#/components/schemas/GetAllApprovedSenderAddresses" example: data: - id: 7927d9eb-4e74-4021-836e-6cae071f84e7 sender_address: EXAMPLE1 sender_address_type: ALPHANUMERIC usage_type: ALPHANUMERIC destination_countries: - AU reason: This is my reason 1 label: This is my label 1 account_id: my_account, created_date: 2023-08-04T04:21:55.958Z, last_modified_date: 2023-08-04T04:21:55.958Z, - id: 365dd65f-7101-46cd-8e79-e49c5620eb15 sender_address: EXAMPLE2 sender_address_type: ALPHANUMERIC usage_type: ALPHANUMERIC destination_countries: - AU reason: This is my reason 2 label: This is my label 2 account_id: my_account, created_date: 2023-08-14T04:21:55.958Z, last_modified_date: 2023-08-14T04:21:55.958Z, - id: 4a9cb0f4-f383-40b5-84dc-bbb6a3b210dd sender_address: 61491570156 sender_address_type: INTERNATIONAL usage_type: OWN_NUMBER destination_countries: - AU reason: This is my reason 3 label: This is my label 3 account_id: my_account, created_date: 2023-08-24T04:21:55.958Z, last_modified_date: 2023-08-24T04:21:55.958Z, expiry: "2024-08-03T04:21:55.958Z" display_status: APPROVED pagination: page_size: 20 next_token: UWFTeXNBZGRyMSN8JEAsdmVuZG9ySWRUZXN0MSN8JEAsYWNjb3VudElkVGVzdDI= "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/403response" /v1/messaging/numbers/sender_address/addresses/{id}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Source Address summary: Get sender address by id operationId: GetSenderAddressById description: | Retrieve a sender address currently registered to your account by Id parameters: - name: id in: path description: The UUID of the sender address required: true schema: type: string format: uuid example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 responses: "200": description: A sender address for your account only headers: {} content: application/json: schema: $ref: "#/components/schemas/GetSenderAddress" "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/403response" delete: security: - basic_auth: [] - hmac_auth: [] tags: - Source Address summary: Delete Sender Address description: | Remove any registered sender addresses that are no longer required from your account. operationId: deleteSenderAddressUsingDELETE parameters: - name: id in: path description: The UUID of the sender address required: true schema: type: string format: uuid example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 - name: reason in: query description: A string detailing why the sender address is being removed required: true schema: type: string example: I%20want%20do%20delete%20this%20number. responses: "202": description: Accepted "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" patch: security: - basic_auth: [] - hmac_auth: [] tags: - Source Address summary: Update My Own Number Label description: | Update label for my own number only. operationId: updateSenderAddressUsingPATCH parameters: - name: id in: path description: The UUID of the sender address required: true schema: type: string format: uuid example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 requestBody: description: Input the label need to update content: application/json: schema: $ref: "#/components/schemas/PatchLabelMyOwnNumber" example: label: ExampleLabel required: true responses: "200": description: OK headers: {} content: application/json: schema: $ref: "#/components/schemas/GetSenderAddress" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized "403": description: Forbidden content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" /v1/delivery_reports: get: security: - basic_auth: [] - hmac_auth: [] tags: - Delivery Reports summary: Check delivery reports description: |- Check for any delivery reports that have been received. Delivery reports are a notification of the change in status of a message as it is being processed. Each request to the check delivery reports endpoint will return any delivery reports received that have not yet been confirmed using the confirm delivery reports endpoint. A response from the check delivery reports endpoint will have the following structure: ```javascript { "delivery_reports": [ { "callback_url": "https://my.callback.url.com", "delivery_report_id": "01e1fa0a-6e27-4945-9cdb-18644b4de043", "source_number": "+61491570157", "date_received": "2017-05-20T06:30:37.642Z", "status": "enroute", "delay": 0, "billing_units": 1, "submitted_date": "2017-05-20T06:30:37.639Z", "original_text": "My first message!", "message_id": "d781dcab-d9d8-4fb2-9e03-872f07ae94ba", "vendor_account_id": { "vendor_id": "SinchEU", "account_id": "MyAccount" }, "metadata": { "key1": "value1", "key2": "value2" } }, { "callback_url": "https://my.callback.url.com", "delivery_report_id": "0edf9022-7ccc-43e6-acab-480e93e98c1b", "source_number": "+61491570158", "date_received": "2017-05-21T01:46:42.579Z", "status": "enroute", "delay": 0, "billing_units": 1, "submitted_date": "2017-05-21T01:46:42.574Z", "original_text": "My second message!", "message_id": "fbb3b3f5-b702-4d8b-ab44-65b2ee39a281", "vendor_account_id": { "vendor_id": "SinchEU", "account_id": "MyAccount" }, "metadata": { "key1": "value1", "key2": "value2" } } ] } ``` Each delivery report will contain details about the message, including any metadata specified and the new status of the message (as each delivery report indicates a change in status of a message) and the timestamp at which the status changed. Every delivery report will have a unique delivery report ID for use with the confirm delivery reports endpoint. *Note: The source number and destination number properties in a delivery report are the inverse of those specified in the message that the delivery report relates to. The source number of the delivery report is the destination number of the original message.* Subsequent requests to the check delivery reports endpoint will return the same delivery reports and a maximum of 100 delivery reports will be returned in each request. Applications should use the confirm delivery reports endpoint in the following pattern so that delivery reports that have been processed are no longer returned in subsequent check delivery reports requests. The expiry date for getting an entity is 45 days. 1. Call check delivery reports endpoint 2. Process each delivery report 3. Confirm all processed delivery reports using the confirm delivery reports endpoint *Note: It is recommended to use the Webhooks feature to receive reply messages rather than polling the check delivery reports endpoint.* operationId: CheckDeliveryReports parameters: [] responses: "200": description: Unconfirmed reports headers: {} content: application/json: schema: $ref: "#/components/schemas/Checkdeliveryreportsresponse" example: delivery_reports: - callback_url: https://my.callback.url.com delivery_report_id: 01e1fa0a-6e27-4945-9cdb-18644b4de043 source_number: "+61491570157" date_received: "2017-05-20T06:30:37.642Z" status: enroute delay: 0 submitted_date: "2017-05-20T06:30:37.639Z" original_text: My first message! message_id: d781dcab-d9d8-4fb2-9e03-872f07ae94ba vendor_account_id: vendor_id: SinchEU account_id: MyAccount metadata: key1: value1 key2: value2 - callback_url: https://my.callback.url.com delivery_report_id: 0edf9022-7ccc-43e6-acab-480e93e98c1b source_number: "+61491570158" date_received: "2017-05-21T01:46:42.579Z" status: submitted delay: 0 submitted_date: "2017-05-21T01:46:42.574Z" original_text: My second message! message_id: fbb3b3f5-b702-4d8b-ab44-65b2ee39a281 vendor_account_id: vendor_id: SinchEU account_id: MyAccount metadata: key1: value1 key2: value2 "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" x-codeSamples: - lang: Java label: Java source: |- deliveryReportsController.checkDeliveryReportsAsync(new APICallBack() { public void onSuccess(HttpContext context, CheckDeliveryReportsResponse response) { // TODO success callback handler } public void onFailure(HttpContext context, Throwable error) { // TODO failure callback handler } }); - lang: JavaScript label: JavaScript source: |- const promise = controller.checkDeliveryReports(); promise.then((response) => { // this block will be executed on successful endpoint call // `response` will be of type 'CheckDeliveryReportsResponse' }, (err) => { // this block will be executed on endpoint call failure // `err` is an 'object' containing more information about the error }); - lang: PHP label: PHP source: $result = $deliveryReportsController->checkDeliveryReports(); - lang: Python label: Python source: | result = delivery_reports_controller.check_delivery_reports() /v1/delivery_reports/confirmed: post: security: - basic_auth: [] - hmac_auth: [] tags: - Delivery Reports summary: Confirm delivery reports as received description: |- Mark a delivery report as confirmed so it is no longer return in check delivery reports requests. The confirm delivery reports endpoint is intended to be used in conjunction with the check delivery reports endpoint to allow for robust processing of delivery reports. Once one or more delivery reports have been processed, they can then be confirmed using the confirm delivery reports endpoint so they are no longer returned in subsequent check delivery reports requests. The confirm delivery reports endpoint takes a list of delivery report IDs as follows: ```javascript { "delivery_report_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2d1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ] } ``` The expiry date for getting an entity is 45 days. Up to 100 delivery reports can be confirmed in a single confirm delivery reports request. operationId: ConfirmDeliveryReportsAsReceived parameters: [] requestBody: description: Delivery reports to confirm as received. content: application/json: schema: $ref: "#/components/schemas/Confirmdeliveryreportsasreceivedrequest" example: delivery_report_ids: - 011dcead-6988-4ad6-a1c7-6b6c68ea628d - 3487b3fa-6586-4979-a233-2d1b095c7718 - ba28e94b-c83d-4759-98e7-ff9c7edb87a1 required: true responses: "202": description: Requested delivery reports will be marked as confirmed headers: {} content: text/plain: schema: type: object description: Requested delivery reports will be marked as confirmed "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" x-codeSamples: - lang: Java label: Java source: |- ConfirmDeliveryReportsAsReceivedRequest body = new ConfirmDeliveryReportsAsReceivedRequest(); body.setDeliveryReportIds(new LinkedList()); body.getDeliveryReportIds().add("011dcead-6988-4ad6-a1c7-6b6c68ea628d"); body.getDeliveryReportIds().add("3487b3fa-6586-4979-a233-2d1b095c7718"); body.getDeliveryReportIds().add("ba28e94b-c83d-4759-98e7-ff9c7edb87a1"); deliveryReportsController.confirmDeliveryReportsAsReceivedAsync(body, new APICallBack() { public void onSuccess(HttpContext context, DynamicResponse response) { // TODO success callback handler } public void onFailure(HttpContext context, Throwable error) { // TODO failure callback handler } }); - lang: JavaScript label: JavaScript source: |- let body = new lib.ConfirmDeliveryReportsAsReceivedRequest(); body.deliveryReportIds = ['011dcead-6988-4ad6-a1c7-6b6c68ea628d', '3487b3fa-6586-4979-a233-2d1b095c7718', 'ba28e94b-c83d-4759-98e7-ff9c7edb87a1']; const promise = controller.confirmDeliveryReportsAsReceived(body); promise.then((response) => { // this block will be executed on successful endpoint call // `response` will be of type 'mixed' }, (err) => { // this block will be executed on endpoint call failure // `err` is an 'object' containing more information about the error }); - lang: PHP label: PHP source: |- $body = new Models\ConfirmDeliveryReportsAsReceivedRequest; $body->deliveryReportIds = array('011dcead-6988-4ad6-a1c7-6b6c68ea628d', '3487b3fa-6586-4979-a233-2d1b095c7718', 'ba28e94b-c83d-4759-98e7-ff9c7edb87a1'); $result = $deliveryReportsController->confirmDeliveryReportsAsReceived($body); - lang: Python label: Python source: |- body = ConfirmDeliveryReportsAsReceivedRequest() body.delivery_report_ids = ['011dcead-6988-4ad6-a1c7-6b6c68ea628d', '3487b3fa-6586-4979-a233-2d1b095c7718', 'ba28e94b-c83d-4759-98e7-ff9c7edb87a1'] result = delivery_reports_controller.confirm_delivery_reports_as_received(body) /v1/replies: get: security: - basic_auth: [] - hmac_auth: [] tags: - Replies summary: Check replies description: |- Check for any replies that have been received. Replies are messages that have been sent from a handset in response to a message sent by an application or messages that have been sent from a handset to a inbound number associated with an account, known as a dedicated inbound number (contact for more information on dedicated inbound numbers). Each request to the check replies endpoint will return any replies received that have not yet been confirmed using the confirm replies endpoint. A response from the check replies endpoint will have the following structure: ```javascript { "replies": [ { "metadata": { "key1": "value1", "key2": "value2" }, "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7", "reply_id": "a175e797-2b54-468b-9850-41a3eab32f74", "date_received": "2016-12-07T08:43:00.850Z", "callback_url": "https://my.callback.url.com", "destination_number": "+61491570156", "source_number": "+61491570157", "vendor_account_id": { "vendor_id": "SinchEU", "account_id": "MyAccount" }, "content": "My first reply!" }, { "metadata": { "key1": "value1", "key2": "value2" }, "message_id": "8f2f5927-2e16-4f1c-bd43-47dbe2a77ae4", "reply_id": "3d8d53d8-01d3-45dd-8cfa-4dfc81600f7f", "date_received": "2016-12-07T08:43:00.850Z", "callback_url": "https://my.callback.url.com", "destination_number": "+61491570157", "source_number": "+61491570158", "vendor_account_id": { "vendor_id": "SinchEU", "account_id": "MyAccount" }, "content": "My second reply!" } ] } ``` Each reply will contain details about the reply message, as well as details of the message the reply was sent in response to, including any metadata specified. Every reply will have a reply ID to be used with the confirm replies endpoint. *Note: The source number and destination number properties in a reply are the inverse of those specified in the message the reply is in response to. The source number of the reply message is the same as the destination number of the original message, and the destination number of the reply message is the same as the source number of the original message. If a source number wasn't specified in the original message, then the destination number property will not be present in the reply message.* Subsequent requests to the check replies endpoint will return the same reply messages and a maximum of 100 replies will be returned in each request. Applications should use the confirm replies endpoint in the following pattern so that replies that have been processed are no longer returned in subsequent check replies requests. The expiry date for getting an entity is 45 days. 1. Call check replies endpoint 2. Process each reply message 3. Confirm all processed reply messages using the confirm replies endpoint *Note: It is recommended to use the Webhooks feature to receive reply messages rather than polling the check replies endpoint.* operationId: CheckReplies parameters: [] responses: "200": description: Unconfirmed replies headers: {} content: application/json: schema: $ref: "#/components/schemas/Checkrepliesresponse" example: replies: - metadata: key1: value1 key2: value2 message_id: 877c19ef-fa2e-4cec-827a-e1df9b5509f7 reply_id: a175e797-2b54-468b-9850-41a3eab32f74 date_received: "2016-12-07T08:43:00.850Z" callback_url: https://my.callback.url.com destination_number: "+61491570156" source_number: "+61491570157" vendor_account_id: vendor_id: SinchEU account_id: MyAccount content: My first reply! - metadata: key1: value1 key2: value2 message_id: 8f2f5927-2e16-4f1c-bd43-47dbe2a77ae4 reply_id: 3d8d53d8-01d3-45dd-8cfa-4dfc81600f7f date_received: "2016-12-07T08:43:00.850Z" callback_url: https://my.callback.url.com destination_number: "+61491570157" source_number: "+61491570158" vendor_account_id: vendor_id: SinchEU account_id: MyAccount content: My second reply! "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" x-codeSamples: - lang: Java label: Java source: |- repliesController.checkRepliesAsync(new APICallBack() { public void onSuccess(HttpContext context, CheckRepliesResponse response) { // TODO success callback handler } public void onFailure(HttpContext context, Throwable error) { // TODO failure callback handler } }); - lang: JavaScript label: JavaScript source: |- const promise = controller.checkReplies(); promise.then((response) => { // this block will be executed on successful endpoint call // `response` will be of type 'CheckRepliesResponse' }, (err) => { // this block will be executed on endpoint call failure // `err` is an 'object' containing more information about the error }); - lang: PHP label: PHP source: $result = $repliesController->checkReplies(); /v1/replies/confirmed: post: security: - basic_auth: [] - hmac_auth: [] tags: - Replies summary: Confirm replies as received description: |- Mark a reply message as confirmed so it is no longer returned in check replies requests. The confirm replies endpoint is intended to be used in conjunction with the check replies endpoint to allow for robust processing of reply messages. Once one or more reply messages have been processed they can then be confirmed using the confirm replies endpoint so they are no longer returned in subsequent check replies requests. The confirm replies endpoint takes a list of reply IDs as follows: ```javascript { "reply_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2d1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ] } ``` The expiry date for getting an entity is 45 days. Up to 100 replies can be confirmed in a single confirm replies request. operationId: ConfirmRepliesAsReceived parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/Confirmrepliesasreceivedrequest" example: reply_ids: - 011dcead-6988-4ad6-a1c7-6b6c68ea628d - 3487b3fa-6586-4979-a233-2d1b095c7718 - ba28e94b-c83d-4759-98e7-ff9c7edb87a1 required: true responses: "202": description: Requested replies will be marked as confirmed headers: {} content: text/plain: schema: type: object description: Requested replies will be marked as confirmed "400": description: Bad request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" "404": description: Resource not found content: application/json: schema: $ref: "#/components/schemas/404response" x-codeSamples: - lang: Java label: Java source: |- ConfirmRepliesAsReceivedRequest body = new ConfirmRepliesAsReceivedRequest(); body.setReplyIds(new LinkedList()); body.getReplyIds().add("011dcead-6988-4ad6-a1c7-6b6c68ea628d"); body.getReplyIds().add("3487b3fa-6586-4979-a233-2d1b095c7718"); body.getReplyIds().add("ba28e94b-c83d-4759-98e7-ff9c7edb87a1"); repliesController.confirmRepliesAsReceivedAsync(body, new APICallBack() { public void onSuccess(HttpContext context, DynamicResponse response) { // TODO success callback handler } public void onFailure(HttpContext context, Throwable error) { // TODO failure callback handler } }); - lang: JavaScript label: JavaScript source: |- let body = new lib.ConfirmRepliesAsReceivedRequest(); body.replyIds = ['011dcead-6988-4ad6-a1c7-6b6c68ea628d', '3487b3fa-6586-4979-a233-2d1b095c7718', 'ba28e94b-c83d-4759-98e7-ff9c7edb87a1']; const promise = controller.confirmRepliesAsReceived(body); promise.then((response) => { // this block will be executed on successful endpoint call // `response` will be of type 'mixed' }, (err) => { // this block will be executed on endpoint call failure // `err` is an 'object' containing more information about the error }); - lang: PHP label: PHP source: |- $body = new Models\ConfirmRepliesAsReceivedRequest; $body->replyIds = array('011dcead-6988-4ad6-a1c7-6b6c68ea628d', '3487b3fa-6586-4979-a233-2d1b095c7718', 'ba28e94b-c83d-4759-98e7-ff9c7edb87a1'); $result = $repliesController->confirmRepliesAsReceived($body); /v1/number_authorisation/mt/blacklist: get: security: - basic_auth: [] - hmac_auth: [] tags: - Number Authorisation summary: List all blocked numbers description: |- This endpoint returns a list of 100 numbers that are on the blacklist. There is a pagination token to retrieve the next 100 numbers In the example response the numbers `+61491570156` and `+61491570157` are on the blacklist and therefore will never receive any messages from you. operationId: ListAllBlockedNumbers parameters: - name: token in: query description: | Opaque pagination token from a previous response. Omit on the first request. Pass the returned token to retrieve the next page of up to 100 numbers. required: false schema: type: string example: eyJwYWdlIjoyfQ responses: "200": description: Number authorisation blacklist was returned successfully. content: application/json: schema: $ref: "#/components/schemas/Getnumberauthorisationblacklistresponse" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" post: security: - basic_auth: [] - hmac_auth: [] tags: - Number Authorisation summary: Add one or more numbers to your blacklist description: |- This endpoint allows you to add one or more numbers to your blacklist. You can add up to 10 numbers in one request. NOTE: numbers need to be in international format and therefore start with a + operationId: AddOneOrMoreNumbersToYourBlacklist parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/Addoneormorenumberstoyourblacklistrequest" example: numbers: - "61491570156" - "61491570157" required: true responses: "201": description: If all the numbers are already on the blacklist, then a 200 is returned. headers: {} content: application/json: schema: $ref: "#/components/schemas/Addoneormorenumberstoyourblacklistresponse" example: uri: /v1/number_authorisation/mt/blacklist numbers: - "61491570156" - "61491570157" "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v1/number_authorisation/mt/blacklist/{number}: delete: security: - basic_auth: [] - hmac_auth: [] tags: - Number Authorisation summary: Remove a number from the blacklist description: |- This endpoint allows you to remove a number from the blacklist. Only one number can be deleted per request. In the example +61491570157 will be removed from the blacklist. NOTE: numbers need to be in international format and therefore start with a + operationId: RemoveANumberFromTheBlacklist parameters: - in: path name: number required: true schema: type: string example: "+61491570156" description: a number in international format e.g. ```+61491570156``` example: "+61491570156" responses: "200": description: The number has been successfully deleted. headers: {} content: text/plain: schema: type: string description: The number has been successfully deleted. format: binary "401": $ref: "#/components/responses/Unauthorized" "404": description: Not found. /v1/number_authorisation/is_authorised/{numbers}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Number Authorisation summary: Check if one or several numbers are currently blacklisted description: |- This endpoint lists for each requested number if you are authorised (which means the number is not blacklisted) to send to this number. In the example given +61491570157 is on the blacklist. NOTE: We do this call for you internally no matter what. Use this endpoint only if you want to have some indication upfront. If you send a message which is on the blacklist, we issue a delivery receipt with the appropriate status code. operationId: CheckIfOneOrSeveralNumbersAreCurrentlyBlacklisted parameters: - in: path name: numbers required: true schema: type: array minimum: 1 items: type: string example: - "+61491570156" - "+61491570157" description: one or more numbers in international format separated by a comma, e.g. ```+61491570156,+61491570157``` example: - "+61491570156" - "+61491570157" responses: "200": description: Successful response. headers: {} content: application/json: schema: $ref: "#/components/schemas/Checkifoneorseveralnumbersarecurrentlyblacklistedresponse" example: uri: /v1/number_authorisation/is_authorised/+61491570156,+61491570157 numbers: - number: 61491570156 authorised: true - number: 61491570157 authorised: false "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /v1/messaging/numbers/dedicated/: get: security: - basic_auth: [] - hmac_auth: [] tags: - Dedicated Numbers summary: Get numbers description: Get a list of available dedicated numbers, filtered by requirements. operationId: GetNumbers parameters: - name: country in: query description: ISO_3166 country code, 2 character code to filter available numbers by country style: form explode: true schema: type: string example: AU - name: matching in: query description: filters results by a pattern of digits contained within the number style: form explode: true schema: type: string example: 223344 - name: page_size in: query description: number of results returned per page, default 50 style: form explode: true schema: type: integer format: int32 example: 20 - name: service_types in: query description: filter results to include numbers with certain capabilities style: form explode: true schema: $ref: "#/components/schemas/service_types" - name: token in: query description: In paginated data the original request will return with a "next_token" attribute. This token must be entered into subsequent call in the "token" query parameter to obtain the next set of records. style: form explode: true schema: type: string example: eyJwYWdlIjoyfQ responses: "200": description: OK headers: {} content: application/json;charset=UTF-8: schema: $ref: "#/components/schemas/NumbersListResponse" example: pagination: next_token: 0428d673-0f75-4063-9493-e89d75f13438 page_size: 5 data: - id: 03cf54ad-a4a3-4cd1-afd5-e0ca2cf158a3 phone_number: 61436489205 country: AU type: MOBILE classification: BRONZE available_after: "2019-08-06T23:56:15.633Z" capabilities: - SMS "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/403response" example: message: Invalid authentication credentials /v1/messaging/numbers/dedicated/{id}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Dedicated Numbers summary: Get number by ID description: Get details about a specific dedicated number. operationId: GetNumberById parameters: - name: id in: path description: unique identifier required: true style: simple explode: true schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 - name: Accept in: header description: Requested response media type. required: true style: simple schema: type: string example: application/json;charset=UTF-8 responses: "200": description: OK headers: {} content: application/json;charset=UTF-8: schema: $ref: "#/components/schemas/Number" example: id: be3cb602-7c00-4c87-ae4b-b8defc04f179 phone_number: 614111111111 country: AU type: MOBILE classification: SILVER available_after: "2019-06-21T04:04:31.707Z" capabilities: - SMS - MMS "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/403response" example: message: Invalid authentication credentials "404": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/404response" example: message: Not found /v1/messaging/numbers/dedicated/{numberId}/assignment: get: security: - basic_auth: [] - hmac_auth: [] tags: - Dedicated Numbers summary: Get assignment description: Use this endpoint to view details of the assignment including the label and metadata. operationId: GetAssignment parameters: - name: numberId in: path description: unique identifier required: true style: simple schema: type: string example: b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985 - name: Accept in: header description: Requested response media type. required: true style: simple schema: type: string example: application/json;charset=UTF-8 responses: "200": description: OK headers: {} content: application/json;charset=UTF-8: schema: $ref: "#/components/schemas/Assignment" example: metadata: key1: value1 label: LabelTest0 id: be3cb602-7c00-4c87-ae4b-b8defc04f179 number_id: b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985 "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/403response" example: message: Invalid authentication credentials "404": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/404response" example: message: Not found post: security: - basic_auth: [] - hmac_auth: [] tags: - Dedicated Numbers summary: Create assignment description: |- Assign the specified number to the authenticated account. Use the body of the request to specify a label or metadata for this number assignment. If you receive a *conflict* error then the number that you have selected is unavailable for assignment. This means that the number is either already assigned to another account, or has an available_after date in the future. Should this occur, perform another search and select a different number. operationId: CreateAssignment parameters: - name: numberId in: path description: unique identifier required: true style: simple schema: type: string example: b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985 - name: Accept in: header description: Requested response media type. required: true style: simple schema: type: string example: application/json;charset=UTF-8 requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/createAssignmentrequest" example: label: ExampleLabel metadata: Key1: value1 Key2: value2 required: true responses: "201": description: Created headers: {} content: application/json;charset=UTF-8: schema: $ref: "#/components/schemas/Assignment" example: label: cillum irure number_id: et pariatur "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/403response" example: message: Invalid authentication credentials "404": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/404response" example: message: Not found delete: security: - basic_auth: [] - hmac_auth: [] tags: - Dedicated Numbers summary: Delete assignment description: Release the dedicated number from your account. operationId: DeleteAssignment parameters: - name: numberId in: path description: unique identifier required: true style: simple schema: type: string example: b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985 - name: Accept in: header description: Requested response media type. required: true style: simple schema: type: string example: application/json;charset=UTF-8 responses: "204": description: No Content headers: {} content: application/json;charset=UTF-8: schema: type: string description: No Content format: binary "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/403response" example: message: Invalid authentication credentials patch: security: - basic_auth: [] - hmac_auth: [] tags: - Dedicated Numbers summary: Update assignment description: Retain the dedicated number assignment, and edit or add additional metadata or title information. You can exclude any data from the body of this request that you do not want updated. operationId: UpdateAssignment parameters: - name: numberId in: path description: unique identifier required: true style: simple schema: type: string example: b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985 - name: Accept in: header description: Requested response media type. required: true style: simple schema: type: string example: application/json;charset=UTF-8 requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/updateAssignmentrequest" example: label: ExampleLabel metadata: Key1: value1 Key2: value2 required: true responses: "204": description: OK headers: {} content: application/json;charset=UTF-8: schema: $ref: "#/components/schemas/Assignment" example: id: b06387c0-f4d9-4333-8657-c819bede79c3 number_id: 073fb6bd-f054-4644-aada-8fb204145d77 "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/403response" example: message: Invalid authentication credentials /v1/messaging/numbers/dedicated/assignments: get: security: - basic_auth: [] - hmac_auth: [] tags: - Dedicated Numbers summary: Get assigned numbers description: Retrieves the list of assigned dedicated numbers. operationId: GetAssignedNumbers parameters: - name: page_size in: query description: Number of results returned per page, default 50 style: form explode: true schema: type: integer format: int32 example: 20 - name: token in: query description: In paginated data the original request will return with a "next_token" attribute. This token must be entered into subsequent call in the "token" query parameter to obtain the next set of records. style: form explode: true schema: type: string example: eyJwYWdlIjoyfQ - name: number_id in: query description: Unique identifier of a specific number style: form explode: true schema: type: string example: examples - name: matching in: query description: Filters results by a pattern of digits contained within the number style: form explode: true schema: type: string example: 223344 - name: country in: query description: Filter results by ISO_3166 country code, 2 character code to filter available numbers by country style: form explode: true schema: type: string example: AU - name: type in: query description: Filter results by Number type. When both `type` and `types` are provided, `types` will take precedence, and `type` will be ignored. style: form explode: true schema: $ref: "#/components/schemas/Type" - name: types in: query description: Filter results by Number Types style: form explode: true schema: $ref: "#/components/schemas/Types" - name: classification in: query description: Filter results by Number Classification style: form explode: true schema: $ref: "#/components/schemas/Classification" - name: service_types in: query description: Filter results by capabilities style: form explode: true schema: $ref: "#/components/schemas/service_types" - name: label in: query description: Filter results by a matching label style: form explode: true schema: type: string example: examples - name: sort_by in: query description: Sort results by property style: form explode: true schema: $ref: "#/components/schemas/sort_by" example: TIMESTAMP - name: sort_direction in: query description: Sort direction style: form explode: true schema: $ref: "#/components/schemas/sort_direction" example: ASCENDING - name: Accept in: header description: Requested response media type. required: true style: simple schema: type: string example: application/json;charset=UTF-8 responses: "200": description: OK headers: {} content: application/json;charset=UTF-8: schema: $ref: "#/components/schemas/AssignedNumberListResponse" example: pagination: next_token: 0428d673-0f75-4063-9493-e89d75f13438 page_size: 5 data: - assignment: metadata: Key1: value1 Key2: value2 label: LabelTest0 id: be3cb602-7c00-4c87-ae4b-b8defc04f179 number_id: b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985 number: id: 03cf54ad-a4a3-4cd1-afd5-e0ca2cf158a3 phone_number: 61436489205 country: AU type: MOBILE classification: BRONZE available_after: "2019-08-06T23:56:15.633Z" capabilities: - SMS "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" example: message: Invalid authentication credentials /v1/reporting/links/summary: get: security: - basic_auth: [] - hmac_auth: [] tags: - Short Trackable Links Reports summary: Log summary description: Clicks summary report for metadata key value pair, long url and short url. operationId: LogSummary parameters: - name: key in: query description: Metadata key used to filter results. style: form explode: true schema: type: string - name: value in: query description: Metadata value used to filter results. style: form explode: true schema: type: string - name: url in: query description: URL used to filter results. style: form explode: true schema: type: string - name: recipient in: query description: Recipient address used to filter results. style: form explode: true schema: type: string - name: page in: query description: Page number for pagination (1-based). style: form explode: true schema: type: number format: double example: 1 - name: pageSize in: query description: Number of results per page. style: form explode: true schema: type: number format: double example: 20 responses: "200": description: OK headers: {} content: application/json: schema: $ref: "#/components/schemas/LogSummaryResult" example: total_clicks: 3 unique_clicks: 1 total_views: 2 unique_views: 1 short_urls_generated: 1 short_urls: - click_count: 3 view_count: 2 message_id: 00000000-0000-0000-0000-000000000000 long_url: https://developers.sinch.com short_url: https://nxt.to/abc1234 destination_number: 61491570157 pagination: page: 1 page_size: 100 page_count: 3 "400": description: Bad Request. Invalid data provided "401": $ref: "#/components/responses/Unauthorized" "404": description: Data cannot be found "500": description: System Error /v1/reporting/links/detail: get: security: - basic_auth: [] - hmac_auth: [] tags: - Short Trackable Links Reports summary: Log detail description: Detailed clicks report for a hashcode. operationId: LogDetail parameters: - name: hash in: query description: Short URL hash code to retrieve click detail for. required: true style: form explode: true schema: type: string - name: page in: query description: Page number for pagination (1-based). style: form explode: true schema: type: number format: double example: 1 - name: pageSize in: query description: Number of results per page. style: form explode: true schema: type: number format: double example: 20 responses: "200": description: OK headers: {} content: application/json: schema: $ref: "#/components/schemas/LogsDetailResult" example: message_id: 00000000-0000-0000-0000-000000000000 long_url: https://developers.sinch.com short_url: https://nxt.to/abc1234 destination_number: 61491570157 click_count: 3 view_count: 2 clicks: - dt: "2018-09-18T01:22:17.071493" user_agent: Mozilla/5.0 (Windows NT... ip: 127.0.0.1 views: - dt: "2018-09-18T01:22:17.071493" user_agent: Mozilla/5.0 (Windows NT... ip: 127.0.0.1 pagination: page: 1 page_size: 100 page_count: 3 "400": description: Bad Request. Invalid data provided "401": $ref: "#/components/responses/Unauthorized" "404": description: Data cannot be found "500": description: System Error /v1/webhooks/messages: get: security: - basic_auth: [] - hmac_auth: [] tags: - Webhooks Management summary: Retrieve webhook description: |- Retrieve all the webhooks created for the connected account. A successful request to the retrieve webhook endpoint will return a response body as follows: ``` { "page": 0, "pageSize": 100, "pageData": [ { "id": "76fa7010-8c1f-4a24-917a-4d62a54e744d", "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "headers": {}, "events": [ "ENROUTE_DR", "DELIVERED_DR" ], "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}", "read_timeout": 5000, "retries": 3, "retry_delay": 30 } ] } ``` *Note: Response 400 is returned when the `page` query parameter is not valid or the `pageSize` query parameter is not valid.* operationId: RetrieveWebhook parameters: - name: page in: query description: Page number for pagination (0-based). style: form explode: true schema: type: integer format: int32 example: 0 example: 0 - name: page_size in: query description: Number of results per page. style: form explode: true schema: type: integer format: int32 example: 20 example: 20 responses: "200": description: Successful response. headers: {} content: application/json: schema: $ref: "#/components/schemas/RetrieveWebhookresponse" "400": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/UpdateWebhook400response" example: message: Something went wrong. Please try again later. "401": $ref: "#/components/responses/Unauthorized" post: security: - basic_auth: [] - hmac_auth: [] tags: - Webhooks Management summary: Create webhook description: | Create a webhook for one or more of the specified events. A webhook would typically have the following structure: ``` { "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "headers": {}, "events": [ "ENROUTE_DR", "DELIVERED_DR" ], "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}", "read_timeout": 5000, "retries": 3, "retry_delay": 30 } ``` A valid webhook must consist of the following properties: - ```url``` The configured URL which will trigger the webhook when a selected event occurs. - ```method``` The methods to map CRUD (create, retrieve, update, delete) operations to HTTP requests. - ```encoding``` Webhooks can be delivered using different content types. You can choose from ```JSON```, ```FORM_ENCODED``` or ```XML```. This will automatically add the Content-Type header for you so you don't have to add it again in the `headers` property. - ```headers``` HTTP header fields which provide required information about the request or response, or about the object sent in the message body. This should NOT include the `Content-Type` header. - ```events``` Event or events that will trigger the webhook. At least one event should be present. - ```template``` The structure of the payload that will be returned. You can format this in JSON or XML. - ```read_timeout``` (Optional) The read timeout for the call to the Webhook in milliseconds. Set to 20000 by default, max 60000. - ```retries``` (Optional) The read timeout for the call to the Webhook in milliseconds. Set to 20000 by default, max 60000. - ```retry_delay``` (Optional) The delay period between retries in seconds. Minimum of 5, max 60. #### Types of Events You can select all of the events (listed below) or combine them in whatever way you like but at least one event must be used. Otherwise, the webhook won't be created. A webhook will be triggered when any one or more of the events occur: + **SMS** + `RECEIVED_SMS` Receive an SMS + `OPT_OUT_SMS` Opt-out occurred + **MMS** + `RECEIVED_MMS` Receive an MMS + **DR (Delivery Reports)** + `ENROUTE_DR` Message is enroute + `EXPIRED_DR` Message has expired + `REJECTED_DR` Message is rejected + `FAILED_DR` Message has failed + `DELIVERED_DR` Message is delivered + `SUBMITTED_DR` Message is submitted #### Template Parameters You can choose what to include in the data that will be sent as the payload via the Webhook. It's up to you to choose what format you would like the payload to be returned. You can choose between JSON or XML. Keep in mind, if you've chosen JSON as the format, you must escape the JSON in the template value (see example above). The table illustrates a list of all the parameters that can be included in the template and which event types it can be applied to. | Data | Parameter Name | Example | Event Type | |:--|--|--|--:| | **Service Type** | $format, $type *- `$type` will be deprecated in the future; use `$format` instead*| `SMS` | `DR` `MO` `MO MMS` | | **Message ID** | $mtId, $messageId| `877c19ef-fa2e-4cec-827a-e1df9b5509f7` | `DR` `MO` `MO MMS`| | **Delivery Report ID** |$drId, $reportId| `01e1fa0a-6e27-4945-9cdb-18644b4de043` | `DR` | | **Reply ID**| $moId, $replyId| `a175e797-2b54-468b-9850-41a3eab32f74` | `MO` `MO MMS` | | **Account ID** | $accountId| `DeveloperPortal7000` | `DR` `MO` `MO MMS` | | **Message Timestamp** | $submittedTimestamp| `2016-12-07T08:43:00.850Z` | `DR` `MO` `MO MMS` | | **Provider Timestamp** | $receivedTimestamp| `2016-12-07T08:44:00.850Z` | `DR` `MO` `MO MMS` | | **Message Status** | $status| `enroute` | `DR` |\n| **Status Code** | $statusCode| `200` | `DR` | | **External Metadata** | $metadata.get('key')| `name` | `DR` `MO` `MO MMS` | | **Source Address**| $sourceAddress| `+61491570156` | `DR` `MO` `MO MMS` | | **Destination Address**| $destinationAddress| `+61491593156` | `MO` `MO MMS` | | **Message Content**| $mtContent, $messageContent, $esc.json($!mtContent) *- when used in `JSON` encoded `template`*| `Hi Derp` | `DR` `MO` `MO MMS` | | **Reply Content**| $moContent, $replyContent, $esc.json($!moContent) *- when used in `JSON` encoded `template`*| `Hello Derpina` | `MO` `MO MMS` | | **Retry Count**| $retryCount| `1` | `DR` `MO` `MO MMS` | | **Billing Unit**| $billingUnits| `1` | `DR` | | **Attachments**| $attachments, refer to example below on how to use in `JSON` encoded `template`| [
{
"content_type": "image/png",
"content": "...",
"original_name": "file.png"
}
] | `MO MMS` | #### Example Webhook Request with Templates ##### MO / MO MMS ``` { "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "events": ["RECEIVED_MMS"], "template": "{ \"account_id\": \"$accountId\", \"reply_id\": \"$replyId\", \"destination_number\": \"$destinationAddress\", \"source_number\": \"$sourceAddress\", \"date_received\": \"$receivedTimestamp\", \"message_id\": \"$messageId\", #if ($attachments) \"attachments\": [ #foreach ($entry in $attachments) { \"content_type\": \"$entry.contentType\", \"content\": \"$entry.base64\", \"original_name\": \"$entry.originalName\" }#if( $foreach.hasNext ),#end #end ], #else \"content\": \"$esc.json($moContent)\", #end \"metadata\": { #foreach ($entry in $metadata.entrySet()) \"$entry.key\": \"$entry.value\"#if( $foreach.hasNext ),#end #end }}" } ``` ##### DR (Delivery Report) ``` { "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "events": ["DELIVERED_DR"], "template": "{ \"delivery_report_id\": \"$drId\", \"source_number\": \"$sourceAddress\", \"date_received\": \"$receivedTimestamp\", \"status\": \"$status\", \"delay\": \"0\", \"submitted_date\": \"$submittedTimestamp\", \"message_id\": \"$messageId\", \"original_text\": \"$esc.json($!mtContent)\", \"vendor_account_id\": { \"vendor_id\": \"$vendorId\", \"account_id\": \"$accountId\" }, \"error_code\": \"$statusCode\", \"metadata\": { #foreach($key in $metadata.keySet()) \"$key\": \"$esc.json($metadata.get($key))\"#if( $velocityHasNext ),#end #end }}" } ``` #### Message Statuses Delivery Reports indicate message status. A message can have one of the following statuses: * `enroute`: Message has been received by the gateway and is being processed (or waiting to be processed). * `submitted`: Message has been submitted to a provider/carrier for delivery. * `delivered`: Message delivery has been confirmed by the provider, including to the handset (where possible). * `expired`: The message has expired. * `rejected`: The message will not be delivered - permanent failure. Reasons may include usage limit exceeded, insufficient credit, number blocked, or content filtered * `failed`: The message has failed. Reasons may include no active routes to destination or undeliverable by downstream provider. #### Message Status Codes Status codes provide more granular insight into a message's status. A message can have one of the following status codes: * `101`: Message being processed by the gateway. * `102`: Message is being rerouted to a different provider after failing via the first provider. * `151`: Message held for screening. * `200`: Message submitted to downstream provider for delivery. * `210`: Message accepted by downstream provider. * `211`: Message is enroute for delivery by provider. * `212`: Message submitted. Delivery pending. * `213`: Message scheduled for delivery by downstream provider. * `220`: Message delivered. * `221`: Message delivered to the handset. * `320`: Message validity period has expired (prior to submission). * `401`: Message validity period has expired (before delivery). * `301`: Usage threshold reached. Message discarded. * `302`: Destination address blocked. Message discarded. * `303`: Source address blocked. Message discarded. * `304`: Message dropped. Contact support. * `305`: Message discarded due to duplicate detection. * `402`: Message rejected by downstream provider. * `403`: Message skipped by downstream provider. * `410`: Invalid source address. * `411`: Invalid destination address. * `412`: Destination address blocked. * `413`: SMS service unavailable on destination. * `414`: Destination unreachable. * `330`: Gateway failure. * `331`: Message discarded. * `332`: No available route to destination. * `333`: Source address unsupported for this destination. * `400`: Message failed; undeliverable. * `405`: Message cancelled or deleted by provider. *Note: A 400 response will be returned if the `url` is invalid, the `events`, `encoding` or `method` is null or the `headers` has a Content-Type attribute.* operationId: CreateWebhook parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/CreateWebhookrequest" example: url: http://webhook.com method: POST encoding: JSON headers: {} events: - ENROUTE_DR - DELIVERED_DR template: "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}" read_timeout: 5000 retries: 3 retry_delay: 30 required: true responses: "201": description: Webhook successfully created headers: {} content: application/json: schema: $ref: "#/components/schemas/CreateWebhookresponse" example: id: 76fa7010-8c1f-4a24-917a-4d62a54e744d url: http://webhook.com method: POST encoding: JSON headers: {} events: - ENROUTE_DR - DELIVERED_DR template: "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}" read_timeout: 5000 retries: 3 retry_delay: 30 "400": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/UpdateWebhook400response" example: message: Something went wrong. Please try again later. "401": $ref: "#/components/responses/Unauthorized" "409": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/UpdateWebhook400response" example: message: A webhook with the given url and method already exists. /v1/webhooks/messages/{webhookId}: delete: security: - basic_auth: [] - hmac_auth: [] tags: - Webhooks Management summary: Delete webhook description: |- Delete a webhook that was previously created for the connected account. A webhook can be cancelled by appending the UUID of the webhook to the endpoint and submitting a DELETE request to the /webhooks/messages endpoint. A successful request to the retrieve webhook endpoint will return a null response. *Note: Only pre-created webhooks can be deleted. If an invalid or non existent webhook ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned.* operationId: DeleteWebhook parameters: - name: webhookId in: path description: Unique identifier of the webhook. required: true style: simple schema: type: string format: uuid example: a7f11bb0-f299-4861-a5ca-9b29d04bc5ad example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 responses: "204": description: Webhook deleted successfully headers: {} "401": $ref: "#/components/responses/Unauthorized" "404": description: Not found. patch: security: - basic_auth: [] - hmac_auth: [] tags: - Webhooks Management summary: Update webhook description: |- Update a webhook. You can update individual attributes or all of them by submitting a PATCH request to the /webhooks/messages endpoint (the same endpoint used above to delete a webhook). All fields in the request body are optional, but at least one must be provided. An empty body or a body with all null fields will be rejected. A successful request to the update webhook endpoint will return a response body as follows: ``` { "id": "76fa7010-8c1f-4a24-917a-4d62a54e744d", "url": "http://webhook.com", "method": "POST", "encoding": "JSON", "headers": {}, "events": [ "ENROUTE_DR", "DELIVERED_DR" ], "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}", "read_timeout": 5000, "retries": 3, "retry_delay": 30 } ``` *Note: Only pre-created webhooks can be deleted. If an invalid or non existent webhook ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned.* operationId: UpdateWebhook parameters: - name: webhookId in: path description: Unique identifier of the webhook. required: true style: simple schema: type: string format: uuid example: a7f11bb0-f299-4861-a5ca-9b29d04bc5ad example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/UpdateWebhookrequest" example: url: http://webhook.com method: POST encoding: JSON headers: {} events: - ENROUTE_DR - DELIVERED_DR template: "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}" required: true responses: "200": description: Webhook updated successfully headers: {} content: application/json: schema: $ref: "#/components/schemas/CreateWebhookresponse" "400": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/UpdateWebhook400response" example: message: Something went wrong. Please try again later. "401": $ref: "#/components/responses/Unauthorized" "404": description: Not found. /v1/iam/signature_keys: get: security: - basic_auth: [] - hmac_auth: [] tags: - Signature Key Management summary: Get signature key list description: |- Retrieve the paginated list of signature keys. A successful request for the ```get signature key list``` endpoint will return a response body as follows: ```javascript [ { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31", "cipher": "RSA", "digest": "SHA224", "created": "2018-01-18T10:16:12.364Z", "enabled": false } ] ``` operationId: GetSignatureKeyList parameters: - name: page in: query description: Page number for pagination (1-based). required: true schema: type: string example: "1" - name: page_size in: query description: Number of results per page. required: true schema: type: string example: "20" responses: "200": description: The list of signature keys. headers: {} content: application/json: schema: type: array items: $ref: "#/components/schemas/Getsignaturekeylistresponse" description: The list of signature keys. example: - key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: RSA digest: SHA224 created: "2018-01-18T10:16:12.364Z" enabled: true - key_id: 6a0108cf-3659-435e-800e-004beb910fd1 cipher: RSA digest: SHA224 created: "2018-01-18T10:15:31.035Z" enabled: false "400": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Enablesignaturekey400response" example: message: Bad Request details: - page property value is invalid "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: This feature has not been enabled in your account. post: security: - basic_auth: [] - hmac_auth: [] tags: - Signature Key Management summary: Create signature key description: |- This will create a key pair: - The ```private key``` stored in Sinch is used to create the signature. - The ```public key``` is returned and stored at your side to verify the signature in webhooks. You need to enable your signature key after creating. The most basic body has the following structure: ```javascript { "digest": "SHA224", "cipher": "RSA" } ``` - ```digest``` is used to hash the message. The valid values for digest type are: SHA224, SHA256, SHA512 - ```cipher``` is used to encrypt the hashed message. The valid value for cipher type is: RSA A successful request for the ```create signature key``` endpoint will return a response body as follows: ```javascript { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31", "public_key": "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCTIxtRyT5CuOD74r7UCT+AKzWNxvaAP9myjAqR7+vBnJKEvoPnmbKTnm6uLlxutnMbjKrnCCWnQ9vtBVnnd+ElhwLDPADfMcJoOqwi7mTcxucckeEbBsfsgYRfdacxgSZL8hVD1hLViQr3xwjEIkJcx1w3x8npvwMuTY0uW8+PjwIDAQAB", "cipher": "RSA", "digest": "SHA224", "created": "2018-01-18T10:16:12.364Z", "enabled": false } ``` The response body of a successful POST request to the ```create signature key``` endpoint will contain six properties: - ```key_id``` will be a 36 character UUID which can be used to enable, delete or get the details. - ```public_key``` is used to decrypt the signature. - ```cipher``` same as cipher in request body. - ```digest``` same as digest in request body. - ```created``` is the created date. - ```enabled``` is false for the new signature key. You can use the ```enable signature key``` endpoint to set this field to true. operationId: CreateSignatureKey parameters: - name: Accept in: header description: Requested response media type. required: true style: simple schema: type: string example: application/json requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/Createsignaturekeyrequest" example: digest: SHA224 cipher: RSA required: true responses: "201": description: The new signature key has been created. headers: {} content: application/json: schema: $ref: "#/components/schemas/Createsignaturekeyresponse" example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 public_key: MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCTIxtRyT5CuOD74r7UCT+AKzWNxvaAP9myjAqR7+vBnJKEvoPnmbKTnm6uLlxutnMbjKrnCCWnQ9vtBVnnd+ElhwLDPADfMcJoOqwi7mTcxucckeEbBsfsgYRfdacxgSZL8hVD1hLViQr3xwjEIkJcx1w3x8npvwMuTY0uW8+PjwIDAQAB cipher: RSA digest: SHA224 created: "2018-01-18T10:16:12.364Z" enabled: false "400": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Enablesignaturekey400response" example: message: Bad Request details: - "/cipher: [RA] is invalid" "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: This feature has not been enabled in your account. /v1/iam/signature_keys/{key_id}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Signature Key Management summary: Get signature key detail description: |- Retrieve the current detail of a signature key using the key_id returned in the ```create signature key``` endpoint. A successful request for the ```get signature key detail``` endpoint will return a response body as follows: ```javascript { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31", "cipher": "RSA", "digest": "SHA224", "created": "2018-01-18T10:16:12.364Z", "enabled": false } ``` *Note: If an invalid or non-existent key_id parameter is specified in the request, then an HTTP 404 Not Found response will be returned* operationId: GetSignatureKeyDetail parameters: - name: key_id in: path description: Unique identifier of the signature key. required: true style: simple schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 responses: "200": description: The detail of signature key. headers: {} content: application/json: schema: $ref: "#/components/schemas/Getsignaturekeydetailresponse" example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: RSA digest: SHA224 created: "2018-01-18T10:16:12.364Z" enabled: false "400": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Enablesignaturekey400response" example: message: Bad Request details: - key_id property value is invalid "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: This feature has not been enabled in your account. "404": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: Entity not found delete: security: - basic_auth: [] - hmac_auth: [] tags: - Signature Key Management summary: Delete signature key description: |- Delete a signature key using the key_id returned in the ```create signature key``` endpoint. A successful request for the ```delete signature key``` endpoint will return an empty response body. *Note: If an invalid or non-existent key_id parameter is specified in the request, then an HTTP 404 Not Found response will be returned* operationId: DeleteSignatureKey parameters: - name: key_id in: path description: Unique identifier of the signature key. required: true style: simple schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 responses: "200": description: The signature key has been deleted. headers: {} "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: This feature has not been enabled in your account. "404": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: Entity not found /v1/iam/signature_keys/enabled: patch: security: - basic_auth: [] - hmac_auth: [] tags: - Signature Key Management summary: Enable signature key description: |- Enable a signature key using the key_id returned in the ```create signature key``` endpoint. There is only one signature key is enabled at the one moment in time. So if you enable the new signature key, the old one will be disabled. The most basic body has the following structure: ```javascript { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31" } ``` The response body of a successful PATCH request to ```enable signature key``` endpoint will contain the ```enabled``` properties with the value is true as follows: ```javascript { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31", "cipher": "RSA", "digest": "SHA224", "created": "2018-01-18T10:16:12.364Z", "enabled": true } ``` *Note: If an invalid or non-existent key_id parameter is specified in the request, then an HTTP 404 Not Found response will be returned* operationId: EnableSignatureKey parameters: - name: Accept in: header description: Requested response media type. required: true style: simple schema: type: string example: application/json requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/Enablesignaturekeyrequest" example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 required: true responses: "200": description: The enabled signature key. headers: {} content: application/json: schema: $ref: "#/components/schemas/Enablesignaturekeyresponse" example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: RSA digest: SHA224 created: "2018-01-18T10:16:12.364Z" enabled: true "400": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Enablesignaturekey400response" example: message: Bad Request details: - "/key_id: Key id cannot be null" "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: This feature has not been enabled in your account. "404": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: Entity not found get: security: - basic_auth: [] - hmac_auth: [] tags: - Signature Key Management summary: Get enabled signature key description: |- Retrieve the currently enabled signature key. A successful request for the ```get enabled signature key``` endpoint will return a response body as follows: ```javascript { "key_id": "7ca628a8-08b0-4e42-aeb8-960b37049c31", "cipher": "RSA", "digest": "SHA224", "created": "2018-01-18T10:16:12.364Z", "enabled": true } ``` *Note: If there is no enabled signature key, then an HTTP 404 Not Found response will be returned* operationId: GetEnabledSignatureKey responses: "200": description: The detail of signature key. headers: {} content: application/json: schema: $ref: "#/components/schemas/Getenabledsignaturekeyresponse" example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: RSA digest: SHA224 created: "2018-01-18T10:16:12.364Z" enabled: true "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: This feature has not been enabled in your account. "404": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: Currently no key is enabled delete: security: - basic_auth: [] - hmac_auth: [] tags: - Signature Key Management summary: Disable the current enabled signature key description: |- Disable the current enabled signature key. A successful request for the ```disable the current enabled signature key``` endpoint will return no content when successful. If there is an enabled key, it will be disabled; and the 204 status code is returned. If there is no key or no enabled key, the 204 status code is also returned. operationId: DisableTheCurrentEnabledSignatureKey responses: "204": description: No content. headers: {} "401": $ref: "#/components/responses/Unauthorized" "403": description: Unexpected error in API call. See HTTP response body for details. content: application/json: schema: $ref: "#/components/schemas/Disablethecurrentenabledsignaturekey.403response" example: message: This feature has not been enabled in your account. /beta/smsplus/campaigns: post: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Create New Campaign description: Mobile Landing Pages Campaigns belonging to the user.Create a new campaign. operationId: CreateNewCampaign parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/Campaign" example: template_id: ac895f01-3149-4bf8-a8fe-01d3b8a9ba97 parameters: pageTitle: The page title pageText: The body text imageUrl: https://example.com/image.jpg secondaryImageUrl: https://www.example.com/optional_secondary_image.jpg buttonLink: https://example.com/ buttonText: Call to Action Button Text secondaryButtonLink: https://example.com/optional_secondary_button secondaryButtonText: Secondary Call to Action Button message: content: Hello ${firstName} ${lastName}, this is the SMS message body metadata: key: value required: true x-send-file-in-body: false responses: "201": description: Campaign was successfully created. headers: {} content: application/json: schema: $ref: "#/components/schemas/CreateNewCampaignresponse" example: id: a94041bb-704b-48fa-ba0b-6f1538fc502f template_id: ac895f01-3149-4bf8-a8fe-01d3b8a9ba97 parameters: title: This is a title bodyText: This is some body text callToAction: http://www.example.com/ message: content: This is the message. destination_number: "+61491570156" metadata: key: value "400": description: Bad request. "401": $ref: "#/components/responses/Unauthorized" "402": description: Payment required. /beta/smsplus/campaigns/{id}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Get Campaign description: A single campaign, identified by a unique identifier.Returns the details of a single campaign. operationId: GetCampaign parameters: - name: id in: path description: Unique identifier of the campaign. required: true style: simple schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 responses: "200": description: Successful response. headers: {} content: application/json: schema: $ref: "#/components/schemas/GetCampaignresponse" example: id: a94041bb-704b-48fa-ba0b-6f1538fc502f template_id: ac895f01-3149-4bf8-a8fe-01d3b8a9ba97 parameters: title: This is a title bodyText: This is some body text callToAction: http://www.example.com/ message: content: This is the message. destination_number: "+61491570156" metadata: key: value "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /beta/smsplus/campaigns/{id}/recipients: post: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Send Campaign To Recipients description: Sends a campaign message to a group of recipients. operationId: SendCampaignToRecipients parameters: - name: id in: path description: Unique identifier of the campaign. required: true style: simple schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/SendCampaignToRecipientsrequest" required: true x-send-file-in-body: false responses: "202": description: The message recipients have successfully been queued for delivery. headers: {} content: application/json: schema: $ref: "#/components/schemas/SendCampaignToRecipientsresponse" example: recipients: - id: 05f81030-95fb-4c17-8736-ac73948e8b82 number: 61491570156 parameters: firstName: John lastName: English - id: 01261663-9428-4a1d-9798-e8a1877cc29d number: 61491570158 parameters: firstName: Mary lastName: Example "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /beta/smsplus/landing_pages: post: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Create a Landing Page description: The Landing Page datastore makes it easier to create Campaigns based on the saved data.Create a Landing Page. operationId: CreateaLandingPage parameters: [] requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/CreateLandingPage" example: name: " My Landing Page" template_id: ac895f01-3149-4bf8-a8fe-01d3b8a9ba97 parameters: pageTitle: The page title pageText: The body text imageUrl: https://example.com/image.jpg fields: title: type: TEXT bodyText: type: TEXT ctaUrl: type: URL required: true x-send-file-in-body: false responses: "201": description: Landing Page was successfully created. headers: {} content: application/json: schema: $ref: "#/components/schemas/CreateaLandingPageresponse" example: id: a94041bb-704b-48fa-ba0b-6f1538fc502f name: " My Landing Page" template_id: ac895f01-3149-4bf8-a8fe-01d3b8a9ba97 parameters: title: This is a ${title} bodyText: This is some ${bodyText} callToAction: ${ctaUrl} fields: title: type: TEXT bodyText: type: TEXT ctaUrl: type: URL created_timestamp: "2019-11-03T11:49:02.807Z" modified_timestamp: "2019-11-03T11:49:02.807Z" "400": description: Bad request. "401": $ref: "#/components/responses/Unauthorized" "402": description: Payment required. get: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Get Landing Pages description: The Landing Page datastore makes it easier to create Campaigns based on the saved data.Returns a paginated list of Landing Pages for your account. ```sort_by``` and ```sort_direction``` must both be specified or neither at all (the default sort options are ```DESCENDING``` ```MODIFIED_TIMESTAMP```). operationId: GetLandingPages parameters: - name: page_size in: query description: Page size between 5 and 100 (default 20) style: form explode: true schema: type: string example: "20" - name: page_token in: query description: Token to fetch the next page style: form explode: true schema: type: string example: eyJwYWdlIjoyfQ - name: sort_by in: query description: Can be `CREATED_TIMESTAMP` or `UPDATED_TIMESTAMP` style: form explode: true schema: type: string - name: sort_direction in: query description: Can be `ASCENDING` or `DESCENDING` style: form explode: true schema: type: string responses: "200": description: Successful response. headers: {} content: application/json: schema: type: object "401": $ref: "#/components/responses/Unauthorized" "402": description: Payment required. /beta/smsplus/landing_pages/{id}: patch: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Update a Landing Page description: The Landing Page datastore makes it easier to create Campaigns based on the saved data.Update a Landing Page. operationId: UpdateaLandingPage parameters: - name: id in: path description: Unique identifier of the landing page. required: true style: simple schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 requestBody: description: Request body. content: application/json: schema: $ref: "#/components/schemas/UpdateLandingPage" example: parameters: pageTitle: The new page title pageText: The new body text imageUrl: https://example.com/image.jpg required: true x-send-file-in-body: false responses: "202": description: Landing Page was successfully updated. headers: {} content: application/json: schema: $ref: "#/components/schemas/UpdateaLandingPageresponse" example: id: a94041bb-704b-48fa-ba0b-6f1538fc502f name: " My Landing Page" template_id: ac895f01-3149-4bf8-a8fe-01d3b8a9ba97 parameters: pageTitle: The new page title pageText: The new body text callToAction: ${ctaUrl} fields: title: type: TEXT bodyText: type: TEXT ctaUrl: type: URL created_timestamp: "2019-11-03T11:49:02.807Z" modified_timestamp: "2019-11-04T11:49:02.807Z" "400": description: Bad request. "401": $ref: "#/components/responses/Unauthorized" "402": description: Payment required. delete: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Delete a Landing Page description: The Landing Page datastore makes it easier to create Campaigns based on the saved data.Delete a Landing Page. operationId: DeleteaLandingPage parameters: - name: id in: path description: Unique identifier of the landing page. required: true style: simple schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 responses: "204": description: Landing Page deleted. headers: {} "401": $ref: "#/components/responses/Unauthorized" "402": description: Payment required. /beta/smsplus/reporting/{campaign_id}/summary: get: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Get Campaign Summary description: |- The reporting endpoint provides access to the reporting analytics. ### Events Types The campaign report consists of a series of events, that were generated by recipients when interacting with the generated mobile landing page. The set of events that are currently supported are as follows: | Event Type | Event Source | Description | |:------------------|:-------------|:-----------------------------------------------| | `PAGE_OPEN` | n/a | The page was opened in a browser. | | `BUTTON_CLICKED` | Button label | One of the Call to Action buttons was clicked. | | `FORM_SUBMITTED` | n/a | A form has been submitted with the captured data stored in the 'data' field. |Returns the breakdown of events and recipients of a particular campaign. This will contain the following bits of information: - The total number of events recorded for the particular campaign. - The number of unique engagements. This is the number of recipients for which there exists at least one recorded event. - A breakdown of the number of the total number of events grouped by the event type and event source The event breakdown will return the following information for each event and source type: - The total number of recorded events of that type and source - The number of unique recipients for which that event and source was recorded for at least once For example, if a recipient opened the landing page three times, the number of recorded events will be 3 but the number of unique recipients will be 1. operationId: GetCampaignSummary parameters: - name: campaign_id in: path description: The campaign ID required: true style: simple schema: type: string example: f56b5806-f732-4693-b87a-90b66a7d7bfc responses: "200": description: Successful response. headers: {} content: application/json: schema: $ref: "#/components/schemas/CampaignSummary" example: total_events: 24 unique_engagements: 9 event_summary: - event: PAGE_OPEN total_events: 8 unique_recipients: 6 - event: BUTTON_CLICK source: OK total_events: 12 unique_recipients: 8 - event: BUTTON_CLICK source: Cancel total_events: 4 unique_recipients: 1 "400": description: Bad Request content: application/json: schema: $ref: "#/components/schemas/400response" "401": description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/403response" /beta/smsplus/reporting/{campaign_id}/events: get: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Get Campaign Events description: |- The reporting endpoint provides access to the reporting analytics. ### Events Types The campaign report consists of a series of events, that were generated by recipients when interacting with the generated mobile landing page. The set of events that are currently supported are as follows: | Event Type | Event Source | Description | |:------------------|:-------------|:-----------------------------------------------| | `PAGE_OPEN` | n/a | The page was opened in a browser. | | `BUTTON_CLICKED` | Button label | One of the Call to Action buttons was clicked. | | `FORM_SUBMITTED` | n/a | A form has been submitted with the captured data stored in the 'data' field. |Returns a list of events that have occurred for a particular campaign. At this stage, the events are returned in reverse chronological order. operationId: GetCampaignEvents parameters: - name: campaign_id in: path description: The campaign ID required: true style: simple schema: type: string example: f56b5806-f732-4693-b87a-90b66a7d7bfc - name: page in: query description: The page of results to retrieve. If unspecified, defaults to 0. style: form explode: true schema: type: number format: double example: 1 - name: page_size in: query description: The size of each page. Must be between 5 and 100. Defaults to 25. style: form explode: true schema: type: number format: double example: 20 responses: "200": description: Successful response. headers: {} content: application/json: schema: $ref: "#/components/schemas/ListCampaignEventPage" "401": $ref: "#/components/responses/Unauthorized" "402": description: Payment required. "404": description: Not found. /beta/smsplus/reporting/{campaign_id}/events/async: get: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Export Campaign Events Async description: |- The reporting endpoint provides access to the reporting analytics. ### Events Types The campaign report consists of a series of events, that were generated by recipients when interacting with the generated mobile landing page. The set of events that are currently supported are as follows: | Event Type | Event Source | Description | |:------------------|:-------------|:-----------------------------------------------| | `PAGE_OPEN` | n/a | The page was opened in a browser. | | `BUTTON_CLICKED` | Button label | One of the Call to Action buttons was clicked. | | `FORM_SUBMITTED` | n/a | A form has been submitted with the captured data stored in the 'data' field. |Produces an unpaginated CSV file of events that have occurred for a particular campaign and emails them to the specified address(es). At this stage, the events are returned in reverse chronological order. operationId: ExportCampaignEventsAsync parameters: - name: campaign_id in: path description: The campaign ID required: true style: simple schema: type: string example: f56b5806-f732-4693-b87a-90b66a7d7bfc responses: "202": description: Accepted for processing. headers: {} "401": $ref: "#/components/responses/Unauthorized" "402": description: Payment required. "404": description: Not found. /beta/smsplus/templates: get: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Get Templates description: Returns a paginated list of Template. operationId: GetTemplates parameters: - name: page_size in: query description: Page size between 5 and 100 (default 20) style: form explode: true schema: type: string example: "20" - name: page_token in: query description: Token to fetch the next page style: form explode: true schema: type: string example: eyJwYWdlIjoyfQ responses: "200": description: Successful response. headers: {} content: application/json: schema: $ref: "#/components/schemas/GetTemplatesresponse" example: templates: - id: c9d7ce1d-20c4-4228-9ba1-6da2a3b4e5e0 name: Header image and 1 or 2 CTA - id: f56b5806-f732-4693-b87a-90b66a7d7bfc name: Header Image and 1 CTA - id: 7614456e-844f-4d83-bdfe-20c17ce0f97c name: Background image and 0 or 1 CTA pagination: next_page_token: qwerty123 page_size: 5 "401": $ref: "#/components/responses/Unauthorized" "402": description: Payment required. /beta/smsplus/templates/{id}/fields: get: security: - basic_auth: [] - hmac_auth: [] tags: - Mobile Landing Pages (beta) summary: Get Templates Fields Definition description: Returns a list of Template Field Definition. operationId: GetTemplatesFieldsDefinition parameters: - name: id in: path description: Template Id required: true style: simple schema: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 responses: "200": description: The list of template parameters required in this template headers: {} content: application/json: schema: $ref: "#/components/schemas/GetTemplatesFieldsDefinitionresponse" example: fields: fontFamilyURL1: type: TEXT secondaryButtonTextColor: type: TEXT fontFamilyURL3: type: TEXT pageTitle: type: TEXT fontFamilyURL2: type: TEXT pageTextColor: type: TEXT barcodeHeight: type: TEXT imageHeaderUrl: type: IMAGE barcodeMargin: type: TEXT logoLink: type: TEXT primaryButtonLink: type: TEXT primaryButtonBackgroundColor: type: TEXT secondaryButtonLink: type: TEXT barcodeWidth: type: TEXT primaryButtonText: type: TEXT headline: type: TEXT headlineColor: type: TEXT pageText: type: TEXT secondaryButtonBackgroundColor: type: TEXT imageLinkPreviewUrl: type: TEXT pageTextFontFamily: type: TEXT secondaryButtonText: type: TEXT headlineFontFamily: type: TEXT barcodeLineColor: type: TEXT barcodeValue: type: TEXT primaryButtonTextColor: type: TEXT imageLogoUrl: type: TEXT barcodeDisplayValue: type: TEXT buttonFontFamily: type: TEXT "401": $ref: "#/components/responses/Unauthorized" "402": description: Account is not postpaid, or does not have Mobile Landing Pages Enabled. /api/v1/contacts/contacts: post: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Create a contact description: Creates a new contact in the account. operationId: createContact requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateContactRequest" required: true responses: "201": description: Contact is created content: "*/*": schema: $ref: "#/components/schemas/ContactData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" get: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Get contacts page description: Retrieves a paginated list of contacts. operationId: getContactsPage parameters: - name: request in: query required: true description: | Pagination and filter options for the contacts page (page tokens, page size, list/contact/channel filters). schema: $ref: "#/components/schemas/GetContactsRequest" responses: "200": description: Returns a contacts page content: "*/*": schema: $ref: "#/components/schemas/PageTokenDtoContactData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /api/v1/contacts/contacts/{contactId}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Get a single contact description: Retrieves details for a single contact by ID. operationId: getContactById parameters: - name: contactId in: path description: Contact id in UUID format required: true schema: type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 responses: "200": description: Returns a single contact content: "*/*": schema: $ref: "#/components/schemas/ContactData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" delete: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Delete a contact description: Deletes a contact from the account. operationId: deleteContactById parameters: - name: contactId in: path description: Contact id in UUID format required: true schema: type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 responses: "204": description: Contact is deleted "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" patch: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Update a contact description: Updates an existing contact. operationId: updateContact parameters: - name: contactId in: path description: Contact id in UUID format required: true schema: type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateContactRequest" required: true responses: "200": description: Contact is updated content: "*/*": schema: $ref: "#/components/schemas/ContactData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /api/v1/contacts/lists: post: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Create a contact list description: Creates a new contact list. operationId: createContactList requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateListRequest" required: true responses: "201": description: Contact list is created content: "*/*": schema: $ref: "#/components/schemas/ListData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" get: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Get contact lists page description: Retrieves a paginated list of contact lists. operationId: getContactListsPage parameters: - name: request in: query required: true description: | Pagination and filter options for the contact lists page (page tokens, page size, and related filters). schema: $ref: "#/components/schemas/GetListsRequest" responses: "200": description: Returns a contact lists page content: "*/*": schema: $ref: "#/components/schemas/PageTokenDtoListData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /api/v1/contacts/lists/{listId}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Get a single contact list description: Retrieves details for a single contact list by ID. operationId: getContactListById parameters: - name: listId in: path description: Contact list id in UUID format required: true schema: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee responses: "200": description: Returns a single contact list content: "*/*": schema: $ref: "#/components/schemas/ListData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" delete: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Delete a contact list description: Deletes a contact list. operationId: deleteContactListById parameters: - name: listId in: path description: Contact list id in UUID format required: true schema: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee responses: "204": description: Contact list is deleted "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" patch: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Update a contact list description: Updates an existing contact list. operationId: updateContactList parameters: - name: listId in: path description: Contact list id in UUID format required: true schema: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateListRequest" required: true responses: "200": description: List is updated content: "*/*": schema: $ref: "#/components/schemas/ListData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /api/v1/contacts/lists/{listId}/contacts: patch: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Add or remove multiple contacts to/from a list description: Adds or removes multiple contacts to or from a contact list. operationId: modifyContactsInContactList parameters: - name: listId in: path description: Contact list id in UUID format required: true schema: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateContactsListRequest" required: true responses: "200": description: Contacts added/removed to/from list content: "*/*": schema: $ref: "#/components/schemas/ListData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /api/v1/contacts/lists/{listId}/contacts/{contactId}: post: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Add contact to a list description: Adds a contact to a contact list. operationId: addContactToContactList parameters: - name: listId in: path description: Contact list id in UUID format required: true schema: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee - name: contactId in: path description: Contact id to remove in UUID format required: true schema: type: string format: uuid example: 4a03d2d8-1f85-463f-bdb4-2891c17258a7 responses: "200": description: Contacts have been added content: "*/*": schema: $ref: "#/components/schemas/ListData" "201": description: Created content: "*/*": schema: $ref: "#/components/schemas/ListData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" delete: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Remove contact from the contact list description: Removes a contact from a contact list. operationId: removeContactFromContactList parameters: - name: listId in: path description: Contact list id in UUID format required: true schema: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee - name: contactId in: path description: Contact id to add in UUID format required: true schema: type: string format: uuid example: 4a03d2d8-1f85-463f-bdb4-2891c17258a7 responses: "204": description: No Content "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /api/v1/contacts/custom-fields: post: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Create a custom field description: Creates a new custom field for contacts. operationId: createCustomField requestBody: content: application/json: schema: $ref: "#/components/schemas/CustomFieldCreateRequest" required: true responses: "201": description: Custom field is created content: "*/*": schema: $ref: "#/components/schemas/CustomFieldData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" get: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Get custom fields page description: Retrieves a paginated list of custom fields. operationId: getCustomFieldsPage parameters: - name: request in: query required: true description: | Pagination and filter options for the custom fields page (page tokens, page size, and related filters). schema: $ref: "#/components/schemas/GetCustomFieldsRequest" responses: "200": description: Returns a custom fields page content: "*/*": schema: $ref: "#/components/schemas/PageTokenDtoCustomFieldData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" /api/v1/contacts/custom-fields/{customFieldId}: get: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Get a single custom field description: Retrieves details for a single custom field by ID. operationId: getCustomFieldById parameters: - name: customFieldId in: path description: Custom field id in UUID format required: true schema: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee responses: "200": description: Returns a single custom field content: "*/*": schema: $ref: "#/components/schemas/CustomFieldData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" delete: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Delete a custom field description: Deletes a custom field. operationId: deleteCustomFieldById parameters: - name: customFieldId in: path description: Custom field id in UUID format required: true schema: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee responses: "204": description: Custom field is deleted "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" patch: security: - basic_auth: [] - hmac_auth: [] tags: - Contacts summary: Update a custom field description: Updates an existing custom field. operationId: updateCustomField parameters: - name: customFieldId in: path description: Custom field id in UUID format required: true schema: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateCustomFieldRequest" required: true responses: "200": description: Custom field is updated content: "*/*": schema: $ref: "#/components/schemas/CustomFieldData" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "500": $ref: "#/components/responses/InternalServerError" "501": $ref: "#/components/responses/RequestNotRecognised" "502": $ref: "#/components/responses/BadGateway" "503": $ref: "#/components/responses/ServerUnavailable" "504": $ref: "#/components/responses/GatewayTimeout" components: schemas: Format: title: Format enum: - SMS - TTS - MMS type: string description: Filter results by message format, using enumerable MessageType. example: SMS format: title: MessageType type: array items: type: string enum: - MMS - SMS - TTS - RCS - CHANNEL description: Format of message type. example: - MMS - TTS MessageMLP: title: MessageMLP required: - content - metadata type: object properties: content: type: string metadata: $ref: "#/components/schemas/Metadata" example: content: This is the message. metadata: key: value MetadataMLP: title: Metadata required: - key type: object properties: key: type: string example: key: value PaginationMLP: title: PaginationMLP required: - next_page_token - page_size type: object properties: next_page_token: type: string page_size: type: integer format: int32 example: next_page_token: qwerty123 page_size: 5 ApiError: required: - detail - title - type - uuid type: object properties: uuid: type: string description: Error id in UUID format format: uuid type: type: string description: Error type enum: - validation - not_found - method_not_allowed - conflict - payload_too_large - unsupported_media_type - message_not_readable - internal_server_error - request_not_recognised - forbidden - bad_gateway - payment_required - unauthorized - unknown title: type: string description: Error title detail: type: string description: Error additional details description: Api error data InvalidInputApiError: required: - detail - invalidFields - title - type - uuid type: object properties: uuid: type: string description: Error id in UUID format format: uuid type: type: string description: Error type enum: - validation - not_found - method_not_allowed - conflict - payload_too_large - unsupported_media_type - message_not_readable - internal_server_error - request_not_recognised - forbidden - bad_gateway - payment_required - unauthorized - unknown title: type: string description: Error title detail: type: string description: Error additional details invalidFields: type: array description: List of invalid fields items: $ref: "#/components/schemas/InvalidInputField" description: Invalid input error data InvalidInputField: required: - code - name - reason type: object properties: name: type: string description: Invalid input field name channelType: type: string description: Invalid channel type enum: - PHONE - WHATSAPP - GBM - INSTAGRAM - FACEBOOK - EMAIL code: type: string description: Invalid input value code enum: - must_not_be_empty - must_be_empty - must_not_be_null - invalid_length - duplicated_value - invalid_format - type_mismatch - missing_parameter - invalid_reference - incorrect_operation - no_such_pattern - constraint_violation reason: type: string description: Error message invalidIds: type: array items: type: string description: Invalid input field MessageDirection: title: MessageDirection type: string enum: - inbound - outbound - all example: all description: The type of messages to include in the report. metakeyrequest: title: metakeyrequest type: object required: - start_date - end_date properties: page: type: number description: Page number for paging through paginated result sets. example: 2 page_size: type: number description: Number of results to return in a page for paginated result sets. example: 15 start_date: type: string description: Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. example: 2022-12-12T00:00:00.000z end_date: type: string description: End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. example: 2022-12-14T00:00:00.000z direction: $ref: "#/components/schemas/MessageDirection" accounts: type: array items: type: string description: Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. example: - Account1 - Account2 metakeyresponse: title: metakeyresponse properties: keys: type: array items: type: string example: - meta1 - meta2 - meta3 MessageStatus: title: MessageStatus type: string enum: - UNDEFINED - QUEUED - PROCESSING - PROCESSED - FAILED - SCHEDULED - CANCELLED - DELIVERED - EXPIRED - ENROUTE - HELD - SUBMITTED - REJECTED - READ example: DELIVERED description: An enumerable list of potential message statuses. detailrequest: title: detailrequest required: - start_date - end_date type: object properties: start_date: description: Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. type: string example: 2022-12-12T00:00:00.000z end_date: description: End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date. type: string example: 2022-12-14T00:00:00.000z direction: $ref: "#/components/schemas/MessageDirection" timezone: description: The timezone of the messages to include, using the name of the region. type: string example: Australia/Sydney source: description: Filter results by source address. type: string example: "+61555555555" sources: description: Filter results by multiple source addresses. This property overrides the `source` parameter. type: array items: type: string example: - "+61555555555" - "+614987654321" destination: description: Filter results by destination address. type: string example: "+61555555555" destinations: description: Filter results by multiple destination addresses. This property overrides the `destination` parameter. type: array items: type: string example: - "+61555555555" - "+614987654321" metadata_key: description: Filter results for messages that include a metadata key. type: string example: broadcastId metadata_value: description: Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. type: string example: ABC metadata_values: description: Filter results for messages that include a metadata key containing these values. This parameter overrides the metadata_value property. If this parameter is provided, the metadata_key parameter must also be provided. type: array items: type: string example: - meta1 - meta2 accounts: description: Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. type: array items: type: string example: - Account1 - Account2 status: description: An array of message statuses type: array items: $ref: "#/components/schemas/MessageStatus" opt_out: description: Filter the report to only include messages that triggered an opt-out type: string example: "true" mms_media: description: Filter results by mms media. type: string example: "true" message_format: $ref: "#/components/schemas/format" channels: description: Filter the report by one or more message channels. type: array items: type: string enum: - SMS - MMS - TTS - RCS - WHATSAPP - CHANNEL example: - SMS - WHATSAPP page: description: Page number for paging through paginated result sets. type: number example: 0 page_size: description: Number of results to return in a page for paginated result sets. type: number example: 20 Status: title: Status enum: - enroute - submitted - delivered - expired - rejected - undeliverable - queued - processed - cancelled - scheduled - failed type: string description: The status of the message example: enroute RichMessageType: title: RichMessageType type: string description: The type of rich message. Supported from 09/Sep/2025, and this data is available only for reports starting from this date. enum: - TEXT_MESSAGE - MEDIA_MESSAGE - LOCATION_MESSAGE - CHOICE_RESPONSE_MESSAGE - MEDIA_CARD_MESSAGE - CARD_MESSAGE - CAROUSEL_MESSAGE - CHOICE_MESSAGE example: TEXT_MESSAGE DetailReportMessageRecord: title: Message type: object properties: message_id: type: string description: Unique ID of this message format: uuid format: $ref: "#/components/schemas/Format" timestamp: type: string description: Timestamp of this message example: "2017-02-10T16:30:00" delivered_timestamp: type: string description: Time that this message was delivered example: "2017-02-10T16:30:00" last_status_update: type: string description: Last time this message's status was updated example: "2017-02-10T16:30:00" direction: $ref: "#/components/schemas/MessageDirection" status: $ref: "#/components/schemas/Status" status_code: type: number description: The response code of the status example: 220 status_description: type: string description: The status of the message example: Message delivered source_address: type: string example: "+61490246135" destination_address: maxLength: 15 minLength: 1 type: string description: Destination number of the message example: "+6149123654" destination_address_country: type: string description: Country of the destination address example: AU content: maxLength: 5000 minLength: 1 type: string description: Content of the message example: Hello world! account_id: type: string description: The ID of the account example: account_1 units: type: number description: The amount of messages received example: 1 billing_category: type: string description: The billing category applied to this RCS message (e.g. RCS_BASIC, RCS_SINGLE, RCS_RICH, RCS_RICH_MEDIA). Supported from 5/Feb/2026. This field is only available for RCS messages and only for messages sent on or after this date. example: RCS_BASIC message_type: $ref: "#/components/schemas/RichMessageType" metadata: type: object description: |- Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long ``` { "myKey": "myValue", "anotherKey": "anotherValue" } ``` example: - myKey: myValue - anotherKey: anotherValue Paginate: title: Pagination type: object properties: page: type: number example: 0 page_size: type: number example: 20 has_next: type: boolean example: false detailresponse: title: detailresponse type: object properties: messages: type: array items: $ref: "#/components/schemas/DetailReportMessageRecord" pagination: $ref: "#/components/schemas/Paginate" 400response: title: Bad request required: - message - details type: object properties: message: type: string details: type: array items: type: string description: Additional error detail messages. example: message: Request failed to parse correctly. Please ensure input is valid and try again. details: - Failed to parse message body. 403response: title: 403 response required: - message type: object properties: message: type: string example: message: Invalid authentication credentials GroupByInsightField: title: GroupByInsightField enum: - ACCOUNT - DAY - WEEK - MONTH - YEAR - METADATA_KEY - METADATA_VALUE - STATUS - COUNTRY - CHANNEL - POSTBACK_DATA type: string example: DAY insightsrequest: title: insightsrequest required: - start_date - end_date - timezone type: object properties: start_date: description: Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format and may include precise time values (e.g., milliseconds). type: string example: 2022-12-12T01:01:01.001z end_date: description: End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format, and after the requested start_date and may include precise time values (e.g., milliseconds). type: string example: 2022-12-14T01:01:01.001z timezone: description: The timezone of the messages to include, using the name of the region. type: string example: Australia/Sydney direction: $ref: "#/components/schemas/MessageDirection" source: description: Filter results by source address. type: string example: "+61555555555" sources: description: Filter results by multiple source addresses. This property overrides the `source` parameter. type: array items: type: string example: - "+61555555555" - "+614987654321" destination: description: Filter results by destination address. type: string example: "+61555555555" destinations: description: Filter results by multiple destination addresses. This property overrides the `destination` parameter. type: array items: type: string example: - "+61555555555" - "+614987654321" metadata_key: description: Filter results for messages that include a metadata key. Can be used independently for searching. type: string example: broadcastId metadata_value: description: Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. Cannot be used together with metadata_values. type: string example: ABC metadata_values: description: Filter results for messages that include a metadata key containing these values. Must be used together with metadata_key. Cannot be used together with metadata_value. type: array items: type: string example: - meta1 - meta2 accounts: description: Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. type: array items: type: string example: - account1 - account2 status: description: An array of message statuses. type: array items: $ref: "#/components/schemas/MessageStatus" example: - DELIVERED - ENROUTE opt_out: description: Filter the report to only include messages that triggered an opt-out type: string example: "true" channels: description: Filter the report by one or more message channels. Supported from 14/Aug/2025, and filtering by channels is available only for reports starting from this date. type: array items: type: string enum: - SMS - MMS - TTS - RCS - WHATSAPP - CHANNEL example: - SMS - WHATSAPP group_by: description: Defines available fields for grouping insights reports. COUNTRY and CHANNEL are supported from 14/Aug/2025, and POSTBACK_DATA is supported from 16/Sep/2025, with data available only from those dates onward. type: array items: $ref: "#/components/schemas/GroupByInsightField" example: - WEEK - ACCOUNT insightssubitemresponse: title: insightsubitemresponse type: object properties: date: type: string description: One or more dates separated by a comma, e.g. 2022-05-18,2022-05-19 example: "2020-11-01" group: type: string example: "2020-11-01" total_sent: type: number example: 20 total_received: type: number example: 0 total_billing_units: type: number example: 20 total_opt_out: type: number example: 0 insightsitemresponse: title: insightsitemresponse type: object properties: group: type: string example: Account1 total_sent: type: number example: 60 total_received: type: number example: 30 total_billing_units: type: number example: 90 total_opt_out: type: number example: 7 sub_group: type: array items: $ref: "#/components/schemas/insightssubitemresponse" insightsresponse: title: insightsresponse type: object properties: summaries: type: array items: $ref: "#/components/schemas/insightsitemresponse" total_sent: type: number example: 100 total_received: type: number example: 50 total_billing_units: type: number example: 150 total_opt_out: type: number example: 10 asyncfieldsrequest: title: asyncfieldsrequest type: object required: - name - display_name properties: name: type: string example: id description: The `async/detail/fields` value from API. display_name: type: string example: id description: Any string that you want to see in the CSV file header. deliveryOptionsBody: title: deliveryOptionsBody type: object properties: delivery_type: type: string description: How to deliver the report. example: EMAIL delivery_addresses: type: array items: type: string example: - email@example.com - test@example.com description: A list of email addresses to use as the recipient of the email. Only works for EMAIL delivery type delivery_format: type: string description: Format of the report. example: CSV description: A delivery option asyncsentmessagesdetailrequest: title: asyncsentmessagesdetailrequest required: - end_date - start_date type: object properties: start_date: description: Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. type: string example: 2022-12-12T00:00:00.000z end_date: description: End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. type: string example: 2022-12-14T00:00:00.000z timezone: description: The timezone of the messages to include, using the name of the region. type: string example: Australia/Sydney direction: $ref: "#/components/schemas/MessageDirection" source: description: Filter results by source address. type: string example: "+61555555555" sources: description: Filter results by multiple source addresses. This property overrides the `source` parameter. type: array items: type: string example: - "+61555555555" - "+614987654321" destination: description: Filter results by destination address. type: string example: "+61555555555" destinations: description: Filter results by multiple destination addresses. This property overrides the `destination` parameter. type: array items: type: string example: - "+61555555555" - "+614987654321" addresses: description: Filter messages where source OR destination matches one of the provided values. This parameter can only be set when "direction" is "all" and cannot be used in the same request as the "source", "destination", "sources", or "destinations" parameters. type: array items: type: string example: - "+61400000001" - "+61400000002" metadata_key: description: Filter results for messages that include a metadata key. Can be used independently for searching. type: string example: broadcastId metadata_value: description: Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. Cannot be used together with metadata_values. type: string example: ABC metadata_values: description: Filter results for messages that include a metadata key containing these values. Must be used together with metadata_key. Cannot be used together with metadata_value. type: array items: type: string example: - meta1 - meta2 accounts: description: Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. type: array items: type: string example: - Account1 - Account2 status: type: array items: $ref: "#/components/schemas/MessageStatus" opt_out: description: Filter the report to only include messages that triggered an opt-out type: string example: "true" message_format: $ref: "#/components/schemas/format" fields: description: Can be used for async detail report to select the fields to export csv files type: array items: $ref: "#/components/schemas/asyncfieldsrequest" delivery_options: description: A list of options to configure the delivery of the report. type: array items: $ref: "#/components/schemas/deliveryOptionsBody" asyncreportresponse: title: asyncreportresponse type: object properties: report_id: type: string example: 51f0097f-90b2-4a59-ad88-a0fd93abaa82 description: The ID of the returned report. GroupByField: title: GroupByField enum: - ACCOUNT - DAY - WEEK - MONTH - YEAR - METADATA_KEY - METADATA_VALUE - STATUS type: string example: DAY asyncsummaryrequest: title: asyncsummaryrequest required: - start_date - end_date type: object properties: start_date: description: Start date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. type: string example: 2022-12-12T00:00:00.000z end_date: description: End date time for report window. By default, the timezone for this parameter will be taken from the account settings for the account associated with the credentials used to make the request, or the account included in the Account parameter. This can be overridden using the timezone parameter per request. The date must be in ISO8601 format. type: string example: 2022-12-14T00:00:00.000z timezone: description: The timezone of the messages to include, using the name of the region. type: string example: Australia/Sydney direction: $ref: "#/components/schemas/MessageDirection" source: description: Filter results by source address. type: string example: "+61555555555" sources: description: Filter results by multiple source addresses. This property overrides the `source` parameter. type: array items: type: string example: - "+61555555555" - "+614987654321" destination: description: Filter results by destination address. type: string example: "+61555555555" destinations: description: Filter results by multiple destination addresses. This property overrides the `destination` parameter. type: array items: type: string example: - "+61555555555" - "+614987654321" metadata_key: description: Filter results for messages that include a metadata key. Can be used independently for searching. type: string example: broadcastId metadata_value: description: Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. Cannot be used together with metadata_values. type: string example: ABC metadata_values: description: Filter results for messages that include a metadata key containing these values. Must be used together with metadata_key. Cannot be used together with metadata_value. type: array items: type: string example: - meta1 - meta2 accounts: description: Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. type: array items: type: string example: - Account1 - Account2 status: type: array items: $ref: "#/components/schemas/MessageStatus" description: A list of message statuses to filter the report by. opt_out: description: Filter the report to only include messages that triggered an opt-out type: string example: "false" group_by: description: Group results by a list of values, from the enumerable table above. type: array items: $ref: "#/components/schemas/GroupByField" example: - WEEK - ACCOUNT delivery_options: description: A list of options to configure the delivery of the report. type: array items: $ref: "#/components/schemas/deliveryOptionsBody" reportstatusresponse: title: reportstatusresponse type: object properties: report_status: type: string enum: - REQUESTED - RUNNING - FAILED - CANCELLED - DONE example: DONE fieldsresponse: title: fieldsresponse type: object properties: fields: type: array items: type: string example: - id - content - meta1 description: An array of fields to be retrieved. reporthistoryresponse: title: reporthistoryresponse type: object properties: report_id: type: string format: uuid description: Unique identifier for the report. example: 51f0097f-90b2-4a59-ad88-a0fd93abaa82 report_name: type: string description: The name of the report. example: My Detail Report report_type: type: string description: The type of the report. enum: - DETAIL - SUMMARY example: DETAIL direction: type: string description: The message direction the report covers. enum: - INBOUND - OUTBOUND - ALL example: OUTBOUND requested_by: type: string description: The UUID of the user who requested the report. example: MyAccount requested_at: type: string format: date-time description: The date and time when the report was requested (ISO 8601). example: "2020-06-01T10:00:00.000Z" updated_at: type: string format: date-time description: The date and time when the report was last updated (ISO 8601). example: "2020-06-01T10:05:00.000Z" status: type: string description: The current status of the report. enum: - REQUESTED - RUNNING - FAILED - CANCELLED - DONE example: DONE account_id: type: string description: The account ID associated with the report. example: MyAccount vendor_id: type: string description: The vendor ID associated with the report. example: sinchonline s3_file_size: type: integer format: int64 description: The size of the report file in bytes. example: 204800 reporthistoryresponses: title: reporthistoryresponses type: object properties: items: type: array items: $ref: "#/components/schemas/reporthistoryresponse" description: A list of report history items. next_page_token: type: string description: A token to retrieve the next page of results. Absent if there are no more pages. example: eyJyZXBvcnRJZCI6IjUxZjAwOTdmLTkwYjItNGE1OS1hZDg4LWEwZmQ5M2FiYWE4MiJ9 presignedurlresponse: title: presignedurlresponse type: object properties: download_url: type: string description: The pre-signed URL for downloading the report file. example: https://s3.amazonaws.com/reports/51f0097f.csv?AWSAccessKeyId=EXAMPLE file_name: type: string description: The filename of the report CSV. example: report-51f0097f-90b2-4a59-ad88-a0fd93abaa82.csv file_size: type: integer format: int64 description: The size of the report file in bytes. example: 204800 expires_in_seconds: type: integer description: The number of seconds until the pre-signed URL expires. example: 3600 expires_at: type: integer format: int64 description: Unix timestamp (seconds) when the pre-signed URL expires. example: 1622555046 schedule: title: schedule type: object description: The time schedule of a scheduled report required: - timezone - cron_expression - type properties: timezone: type: string example: UTC description: The timezone of the report. cron_expression: type: string example: 0 0 * * * ? * description: A string consisting of six or seven subexpressions that describe individual details of the schedule. type: type: string example: cron ReportPeriod: title: ReportPeriod enum: - TODAY - YESTERDAY - THIS_WEEK - LAST_WEEK - THIS_MONTH - LAST_MONTH - LAST_30_DAYS - LAST_7_DAYS - THIS_WEEKDAYS - LAST_WEEKDAYS type: string description: Automatically set a date range based on the period value. Can't be combined with start_date and end_date. example: THIS_WEEK scheduleddetailrequest: title: scheduleddetailrequest type: object description: A scheduled detail report request required: - period properties: period: $ref: "#/components/schemas/ReportPeriod" timezone: type: string example: Australia/Sydney description: The standard timezone name direction: $ref: "#/components/schemas/MessageDirection" source: type: string example: "+61555555555" description: The source phone number. destination: type: string example: "+61555555555" description: The destination phone number. metadata_key: type: string example: broadcastId description: Filter results for messages that include a metadata key. metadata_value: type: string example: ABC description: Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. accounts: type: array items: type: string example: - Account1 - Account2 description: Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. status: type: array items: $ref: "#/components/schemas/MessageStatus" description: An array of message statuses. opt_out: type: string example: "true" description: Filter the report to only include messages that triggered an opt-out delivery_options: type: array items: $ref: "#/components/schemas/deliveryOptionsBody" description: A list of options to configure the delivery of the report. scheduleddetailreport: title: scheduleddetailreport type: object required: - label - schedule - report properties: label: type: string example: Weekly Report description: The label of the report schedule schedule: $ref: "#/components/schemas/schedule" report: $ref: "#/components/schemas/scheduleddetailrequest" metadata: type: object description: |- Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long ``` { "myKey": "myValue", "anotherKey": "anotherValue" } ``` example: - myKey: myValue - anotherKey: anotherValue scheduledreportresponse: title: scheduledreportresponse type: object properties: scheduled_report_id: type: string example: 51f0097f-90b2-4a59-ad88-a0fd93abaa82 description: The ID of the scheduled report. updatescheduleddetailreport: title: updatescheduleddetailreport type: object required: - label - schedule - report properties: label: type: string example: Weekly Report description: The label of the report schedule schedule: $ref: "#/components/schemas/schedule" report: $ref: "#/components/schemas/scheduleddetailrequest" scheduleddetailreportresponse: title: scheduleddetailreportresponse type: object properties: label: type: string example: Weekly Report description: The label of the report schedule schedule: $ref: "#/components/schemas/schedule" report: $ref: "#/components/schemas/scheduleddetailrequest" scheduled_report_id: type: string example: 43928f76-c381-4943-8619-f10460005898 description: The ID of the scheduled report. message_type: $ref: "#/components/schemas/MessageDirection" report_type: type: string example: detail metadata: type: object description: |- Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long ``` { "myKey": "myValue", "anotherKey": "anotherValue" } ``` example: - myKey: myValue - anotherKey: anotherValue scheduledsummaryrequest: title: scheduledsummaryrequest type: object description: A scheduled summary report request required: - period - timezone properties: period: $ref: "#/components/schemas/ReportPeriod" timezone: type: string example: Australia/Sydney description: The standard timezone name direction: $ref: "#/components/schemas/MessageDirection" source: type: string example: "+61555555555" description: The source phone number. destination: type: string example: "+61555555555" description: The destination phone number. metadata_key: type: string example: broadcastId description: Filter results for messages that include a metadata key. metadata_value: type: string example: ABC description: Filter results for messages that include a metadata key containing this value. If this parameter is provided, the metadata_key parameter must also be provided. accounts: type: array items: type: string example: - Account1 - Account2 description: Filter results by a specific account. By default results will be returned for the account associated with the authentication credentials and all sub-accounts. status: type: array items: $ref: "#/components/schemas/MessageStatus" example: - DELIVERED - ENROUTE description: An array of message statuses. opt_out: type: string example: "true" description: Filter the report to only include messages that triggered an opt-out. group_by: type: array items: $ref: "#/components/schemas/GroupByField" example: - DAY - WEEK description: Group results by a list of values, from the enumerable table above. delivery_options: type: array items: $ref: "#/components/schemas/deliveryOptionsBody" description: A list of options to configure the delivery of the report. scheduledsummaryreport: title: scheduledsummaryreport type: object required: - label - schedule - report properties: label: type: string example: Weekly Report description: The label of the report schedule schedule: $ref: "#/components/schemas/schedule" report: $ref: "#/components/schemas/scheduledsummaryrequest" metadata: type: object description: |- Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long ``` { "myKey": "myValue", "anotherKey": "anotherValue" } ``` example: - myKey: myValue - anotherKey: anotherValue updatescheduledsummaryreport: title: updatescheduledsummaryreport type: object required: - label - schedule - report properties: label: type: string example: Weekly Report description: The label of the report schedule schedule: $ref: "#/components/schemas/schedule" report: $ref: "#/components/schemas/scheduledsummaryrequest" scheduledsummaryreportresposne: title: scheduledsummaryreportresposne type: object properties: label: type: string example: Weekly Report description: The label of the report schedule schedule: $ref: "#/components/schemas/schedule" report: $ref: "#/components/schemas/scheduledsummaryrequest" scheduled_report_id: type: string example: 43928f76-c381-4943-8619-f10460005898 description: The ID of the scheduled report. message_type: $ref: "#/components/schemas/MessageDirection" report_type: type: string example: detail metadata: type: object description: |- Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long ``` { "myKey": "myValue", "anotherKey": "anotherValue" } ``` example: - myKey: myValue - anotherKey: anotherValue scheduledreport: title: scheduledreport type: object properties: label: type: string example: Weekly Report description: The label of the report schedule report: $ref: "#/components/schemas/scheduledsummaryrequest" schedule: $ref: "#/components/schemas/schedule" scheduled_report_id: type: string example: 43928f76-c381-4943-8619-f10460005898 description: The ID of the scheduled report. message_type: $ref: "#/components/schemas/MessageDirection" report_type: type: string example: detail chronosscheduleresponse: title: chronosscheduleresponse type: object properties: page_token: type: string example: abc123 page_size: type: number example: 20 description: Number of results to return in a page for paginated result sets. data: type: array items: $ref: "#/components/schemas/scheduledreport" SourceNumberType: title: SourceNumberType enum: - INTERNATIONAL - ALPHANUMERIC - SHORTCODE type: string description: Type of source address specified, this can be INTERNATIONAL, ALPHANUMERIC or SHORTCODE example: INTERNATIONAL Getmessagestatusresponse: title: Getmessagestatusresponse type: object properties: callback_url: type: string description: URL replies and delivery reports to this message will be pushed to example: https://my.url.com content: maxLength: 5000 minLength: 1 type: string description: Content of the message example: Hello world! destination_number: maxLength: 15 minLength: 1 type: string description: Destination number of the message example: "+61491570156" delivery_report: type: boolean description: Request a delivery report for this message example: false format: $ref: "#/components/schemas/Format" message_expiry_timestamp: type: string description: Date time after which the message expires and will not be sent format: date-time example: 11/3/2016 11:49:02 AM metadata: type: object description: |- Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long ``` { "myKey": "myValue", "anotherKey": "anotherValue" } ``` scheduled: type: string description: Scheduled delivery date time of the message format: date-time example: 11/3/2016 11:49:02 AM source_number: type: string example: "+61491570156" source_number_type: $ref: "#/components/schemas/SourceNumberType" message_id: type: string description: Unique ID of this message format: uuid status: $ref: "#/components/schemas/Status" 404response: title: Resource not found required: - message type: object properties: message: type: string example: message: Resource not found. Cancelscheduledmessagerequest: title: Cancelscheduledmessagerequest required: - status type: object properties: status: type: string example: cancelled description: Must be set to ```cancelled```. example: status: cancelled Message: title: Message required: - content - destination_number type: object properties: callback_url: type: string description: URL replies and delivery reports to this message will be pushed to example: https://my.url.com content: maxLength: 5000 minLength: 1 type: string description: Content of the message example: Hello world! destination_number: maxLength: 15 minLength: 1 type: string description: Destination number of the message example: "+61491570156" delivery_report: type: boolean description: Request a delivery report for this message example: false format: $ref: "#/components/schemas/Format" message_expiry_timestamp: type: string description: Date time after which the message expires and will not be sent format: date-time example: 11/3/2016 11:49:02 AM metadata: type: object description: |- Metadata for the message specified as a set of key value pairs, each key can be up to 100 characters long and each value can be up to 256 characters long ``` { "myKey": "myValue", "anotherKey": "anotherValue" } ``` example: - myKey: myValue - anotherKey: anotherValue scheduled: type: string description: Scheduled delivery date time of the message format: date-time example: 11/3/2016 11:49:02 AM source_number: type: string example: "+61491570156" source_number_type: $ref: "#/components/schemas/SourceNumberType" message_id: type: string description: Unique ID of this message format: uuid status: $ref: "#/components/schemas/Status" media: type: array items: type: string description: The media is used to specify a list of URLs of the media file(s) that you are trying to send. Supported file formats include png, jpeg and gif. format parameter must be set to MMS for this to work. example: - https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg subject: type: string description: The subject field is used to denote subject of the MMS message and has a maximum size of 64 characters long example: New Products Sendmessagesrequest: title: Sendmessagesrequest required: - messages type: object properties: messages: type: array items: $ref: "#/components/schemas/Message" description: List of messages. example: messages: - callback_url: https://my.callback.url.com content: My first message destination_number: "+61491570156" delivery_report: true format: SMS message_expiry_timestamp: "2016-11-03T11:49:02.807Z" metadata: key1: value1 key2: value2 scheduled: "2016-11-03T11:49:02.807Z" source_number: "+61491570157" source_number_type: INTERNATIONAL - callback_url: https://my.callback.url.com content: My second message destination_number: "+61491570158" delivery_report: true format: MMS subject: This is an MMS message media: - https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg message_expiry_timestamp: "2016-11-03T11:49:02.807Z" metadata: key1: value1 key2: value2 scheduled: "2016-11-03T11:49:02.807Z" source_number: "+61491570159" source_number_type: INTERNATIONAL Sendmessagesresponse: title: Sendmessagesresponse type: object properties: messages: maxItems: 100 type: array items: $ref: "#/components/schemas/Message" description: List of messages. RequestAlphaTag: title: RequestAlphaTag type: object required: - sender_address - sender_address_type - usage_type - destination_countries - reason properties: sender_address: type: string description: The Sender Address to be requested sender_address_type: type: string enum: - ALPHANUMERIC usage_type: type: string enum: - ALPHANUMERIC destination_countries: type: array description: list of 2-character ISO country codes items: type: string reason: type: string label: type: string RequestVerificationCode: title: RequestVerificationCode type: object required: - sender_address - sender_address_type - usage_type - destination_countries - reason properties: sender_address: type: string description: The Own Number to be verified sender_address_type: type: string enum: - INTERNATIONAL usage_type: type: string enum: - OWN_NUMBER destination_countries: type: array description: list of 2-character ISO country codes items: type: string reason: type: string label: type: string AlphaTagRequestItem: title: AlphaTagRequestItem type: object properties: id: type: string format: uuid description: Primary ID of the record example: 6f79a12e-14f1-4776-adc0-5c5e48a999b7 sender_address: type: string description: The Alpha tag to be requested example: EXAMPLE sender_address_type: type: string description: The Sender Address Type enum: - ALPHANUMERIC usage_type: type: string description: The Sender Address Usage Type enum: - ALPHANUMERIC destination_countries: type: array description: list of 2-character ISO country codes this sender address applies to items: type: string example: - AU reason: type: string example: This is my reason label: type: string example: label status: type: string enum: - OPEN - PENDING - REJECTED - APPROVED account_id: type: string example: XYZ_ExampleAccount created_date: type: string format: date-time last_modified_date: type: string format: date-time VerificationCodeRequestItem: title: VerificationCodeRequestItem type: object properties: id: type: string format: uuid description: Primary ID of the record example: 6f79a12e-14f1-4776-adc0-5c5e48a999b8 sender_address: type: string description: The Own Number to be requested example: "+61401234567" sender_address_type: type: string description: The Sender Address Type enum: - INTERNATIONAL usage_type: type: string description: The Sender Address Usage Type enum: - OWN_NUMBER destination_countries: type: array description: list of 2-character ISO country codes this sender address applies to items: type: string example: - AU reason: type: string example: my personal number label: type: string example: label status: type: string enum: - PENDING - REJECTED - APPROVED account_id: type: string example: XYZ_ExampleAccount created_date: type: string format: date-time last_modified_date: type: string format: date-time PostVerificationCode: type: object title: PostVerificationCode required: - verification_code properties: verification_code: type: string description: Verify Sender Address Request example: "123456" ReVerifySenderAddressRequestItem: title: ReVerifySenderAddressRequestItem type: object properties: id: type: string format: uuid description: Primary ID of the record example: 6f79a12e-14f1-4776-adc0-5c5e48a999b7 sender_address: type: string description: The Sender Address to be requested example: "+61450999999" sender_address_type: type: string description: The Sender Address Type enum: - INTERNATIONAL usage_type: type: string description: The Sender Address Usage Type enum: - OWN_NUMBER destination_countries: type: array description: list of 2-character ISO country codes this sender address applies to items: type: string example: - AU - NZ - US reason: type: string example: my company is example.com label: type: string example: Example Address status: type: string enum: - PENDING account_id: type: string example: XYZ_ExampleAccount created_date: type: string format: date-time last_modified_date: type: string format: date-time GetAllApprovedSenderAddresses: title: GetAllApprovedSenderAddresses type: object properties: data: type: array items: type: object properties: id: type: string format: uuid description: Primary ID of the record sender_address: type: string description: The Sender Address to be requested sender_address_type: type: string description: The Sender Address Type enum: - ALPHANUMERIC usage_type: type: string description: The Sender Address Usage Type enum: - ALPHANUMERIC destination_countries: type: array description: list of 2-character ISO country codes this sender address applies to items: type: string reason: type: string label: type: string created_date: type: string format: date-time last_modified_date: type: string format: date-time expiry: type: string format: date-time description: The Sender Address expiration time (apply for sender_address_type = OWN_NUMBER) display_status: type: string description: The Sender Address status (apply for sender_address_type = OWN_NUMBER) enum: - APPROVED - EXPIRING - EXPIRED pagination: type: object properties: page_size: type: number next_token: type: string description: The pagination token of the next set of results. GetSenderAddress: title: GetSenderAddress type: object properties: id: type: string format: uuid description: Primary ID of the record example: 6f79a12e-14f1-4776-adc0-5c5e48a999b8 sender_address: type: string description: The Own Number to be requested example: "+61401234567" sender_address_type: type: string description: The Sender Address Type enum: - INTERNATIONAL usage_type: type: string description: The Sender Address Usage Type enum: - OWN_NUMBER destination_countries: type: array description: list of 2-character ISO country codes this sender address applies to items: type: string example: - AU reason: type: string example: my personal number label: type: string example: ABC account_id: type: string example: XYZ_ExampleAccount created_date: type: string format: date-time last_modified_date: type: string format: date-time expiry: type: string format: date-time description: The Sender Address expiration time (apply for sender_address_type = OWN_NUMBER) display_status: type: string enum: - APPROVED - EXPIRED - EXPIRING PatchLabelMyOwnNumber: type: object title: PatchLabelMyOwnNumber required: - label properties: label: type: string maxLength: 100 description: Label need to be updated example: My Number VendorAccountId: title: VendorAccountId type: object properties: vendor_id: type: string example: SinchEU account_id: type: string description: The account used to submit the original message. example: MyAccount001 DeliveryReport: title: DeliveryReport type: object properties: callback_url: type: string description: The URL specified as the callback URL in the original submit message request example: https://my.url.com date_received: type: string description: The date and time at which this delivery report was generated in UTC. format: date-time example: 11/3/2016 11:49:02 AM delay: type: integer deprecated: true description: Deprecated, no longer in use format: int32 example: 0 billing_units: type: integer description: The billing units of this report format: int32 example: 1 delivery_report_id: type: string description: Unique ID for this delivery report format: uuid message_id: type: string description: Unique ID of the original message format: uuid metadata: type: object description: Any metadata that was included in the original submit message request original_text: type: string description: Text of the original message. example: Hello back source_number: maxLength: 15 minLength: 1 type: string description: Address from which this delivery report was received example: "+61491570156" status: $ref: "#/components/schemas/Status" submitted_date: type: string description: The date and time when the message status changed in UTC. For a delivered DR this may indicate the time at which the message was received on the handset. format: date-time example: 11/3/2016 11:49:02 AM vendor_account_id: $ref: "#/components/schemas/VendorAccountId" Checkdeliveryreportsresponse: title: Checkdeliveryreportsresponse type: object properties: delivery_reports: maxItems: 100 minItems: 0 type: array items: $ref: "#/components/schemas/DeliveryReport" description: The oldest 100 unconfirmed delivery reports example: delivery_reports: - callback_url: https://my.callback.url.com delivery_report_id: 01e1fa0a-6e27-4945-9cdb-18644b4de043 source_number: "+61491570157" date_received: "2017-05-20T06:30:37.642Z" status: enroute delay: 0 billing_units: 1 submitted_date: "2017-05-20T06:30:37.639Z" original_text: My first message! message_id: d781dcab-d9d8-4fb2-9e03-872f07ae94ba vendor_account_id: vendor_id: SinchEU account_id: MyAccount metadata: key1: value1 key2: value2 - callback_url: https://my.callback.url.com delivery_report_id: 0edf9022-7ccc-43e6-acab-480e93e98c1b source_number: "+61491570158" date_received: "2017-05-21T01:46:42.579Z" status: submitted delay: 0 billing_units: 1 submitted_date: "2017-05-21T01:46:42.574Z" original_text: My second message! message_id: fbb3b3f5-b702-4d8b-ab44-65b2ee39a281 vendor_account_id: vendor_id: SinchEU account_id: MyAccount metadata: key1: value1 key2: value2 Confirmdeliveryreportsasreceivedrequest: title: Confirmeliveryreportsasreceivedrequest required: - delivery_report_ids type: object properties: delivery_report_ids: maxItems: 100 type: array items: type: string format: uuid description: Array of unique IDs for the delivery report that this notification represents example: delivery_report_ids: - 011dcead-6988-4ad6-a1c7-6b6c68ea628d - 3487b3fa-6586-4979-a233-2d1b095c7718 - ba28e94b-c83d-4759-98e7-ff9c7edb87a1 Reply: title: Reply type: object properties: callback_url: type: string description: The URL specified as the callback URL in the original submit message request example: https://my.url.com content: maxLength: 5000 minLength: 1 type: string description: Content of the reply example: Hello back date_received: type: string description: Date time when the reply was received format: date-time example: 11/3/2016 11:49:02 AM destination_number: maxLength: 15 minLength: 1 type: string description: Address from which this reply was sent to example: "+61491570156" message_id: type: string description: Unique ID of the original message format: uuid metadata: type: object description: Any metadata that was included in the original submit message request reply_id: type: string description: Unique ID of this reply format: uuid source_number: maxLength: 15 minLength: 1 type: string description: Address from which this reply was received from example: "+61491570156" vendor_account_id: $ref: "#/components/schemas/VendorAccountId" Checkrepliesresponse: title: Checkrepliesresponse type: object properties: replies: maxItems: 100 minItems: 0 type: array items: $ref: "#/components/schemas/Reply" description: The oldest 100 unconfirmed replies example: replies: - metadata: key1: value1 key2: value2 message_id: 877c19ef-fa2e-4cec-827a-e1df9b5509f7 reply_id: a175e797-2b54-468b-9850-41a3eab32f74 date_received: "2016-12-07T08:43:00.850Z" callback_url: https://my.callback.url.com destination_number: "+61491570156" source_number: "+61491570157" vendor_account_id: vendor_id: SinchEU account_id: MyAccount content: My first reply! - metadata: key1: value1 key2: value2 message_id: 8f2f5927-2e16-4f1c-bd43-47dbe2a77ae4 reply_id: 3d8d53d8-01d3-45dd-8cfa-4dfc81600f7f date_received: "2016-12-07T08:43:00.850Z" callback_url: https://my.callback.url.com destination_number: "+61491570157" source_number: "+61491570158" vendor_account_id: vendor_id: SinchEU account_id: MyAccount content: My second reply! Confirmrepliesasreceivedrequest: title: Confirmrepliesasreceivedrequest required: - reply_ids type: object properties: reply_ids: maxItems: 100 type: array items: type: string format: uuid description: "The UUID of the *reply* to be confirmed (note: not the UUID of the message it is in response to)" example: reply_ids: - 011dcead-6988-4ad6-a1c7-6b6c68ea628d - 3487b3fa-6586-4979-a233-2d1b095c7718 - ba28e94b-c83d-4759-98e7-ff9c7edb87a1 PaginationNumberAuth: title: Pagination type: object properties: page: type: string description: The pagination token of the next set of results. example: "0" next_uri: type: string description: The uri pointing to the next set of results. example: /v1/number_authorisation/mt/blacklist?token=0 Getnumberauthorisationblacklistresponse: title: Getnumberauthorisationblacklistresponse type: object properties: uri: type: string description: URL of the current API call, used to show the current pagination token for calls subsequent to the first one in the case of paginated data. example: /v1/number_authorisation/mt/blacklist" numbers: type: array description: List of numbers belonging to the blacklist. items: type: string example: - "+61491570156" - "+61491570157" pagination: $ref: "#/components/schemas/PaginationNumberAuth" Addoneormorenumberstoyourblacklistrequest: title: Addoneormorenumberstoyourblacklistrequest required: - numbers type: object properties: numbers: type: array items: type: string description: Array of numbers to be added to the blacklist. These should be specified in E.164 international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. example: numbers: - "61491570156" - "61491570157" Addoneormorenumberstoyourblacklistresponse: title: Addoneormorenumberstoyourblacklistresponse required: - uri - numbers type: object properties: uri: type: string numbers: type: array items: type: string description: List of phone numbers. example: uri: /v1/number_authorisation/mt/blacklist numbers: - "61491570156" - "61491570157" Number: title: Number required: - number - authorised type: object properties: number: type: string authorised: type: boolean example: number: 61491570156 authorised: true Checkifoneorseveralnumbersarecurrentlyblacklistedresponse: title: Checkifoneorseveralnumbersarecurrentlyblacklistedresponse required: - uri - numbers type: object properties: uri: type: string numbers: type: array items: $ref: "#/components/schemas/Number" description: List of phone numbers. example: uri: /v1/number_authorisation/is_authorised/+61491570156,+61491570157 numbers: - number: 61491570156 authorised: true - number: 61491570157 authorised: false service_types: title: service_types enum: - SMS - TTS - MMS type: string example: SMS Capability: title: Capability enum: - SMS - TTS - MMS type: string example: SMS Classification: title: Classification enum: - BRONZE - SILVER - GOLD type: string example: BRONZE Type: title: Type enum: - MOBILE - LANDLINE - TOLL_FREE - SHORT_CODE type: string example: MOBILE DedicatedNumber: title: Number type: object properties: available_after: type: string format: date-time capabilities: type: array items: $ref: "#/components/schemas/Capability" description: Capabilities supported by this number. classification: $ref: "#/components/schemas/Classification" country: type: string id: type: string phone_number: type: string type: $ref: "#/components/schemas/Type" example: id: be3cb602-7c00-4c87-ae4b-b8defc04f179 phone_number: 614111111111 country: AU type: MOBILE classification: SILVER available_after: "2019-06-21T04:04:31.707Z" capabilities: - SMS - MMS Pagination: title: Pagination type: object properties: page: type: number description: The current page of results example: 3 page_size: type: number description: The amount of results returned per page example: 50 total_count: type: number description: The total number of results in the results set example: 80 page_count: type: number description: The total number of pages in the results set example: 5 next_uri: type: string description: Link to the next page of results example: example.url previous_uri: type: string description: Link to the previous page of results example: example.url NumbersListResponse: title: NumbersListResponse type: object properties: data: type: array items: $ref: "#/components/schemas/DedicatedNumber" description: List of result items. pagination: $ref: "#/components/schemas/Pagination" example: pagination: next_token: 0428d673-0f75-4063-9493-e89d75f13438 page_size: 5 data: - id: 03cf54ad-a4a3-4cd1-afd5-e0ca2cf158a3 phone_number: 61436489205 country: AU type: MOBILE classification: BRONZE available_after: "2019-08-06T23:56:15.633Z" capabilities: - SMS Assignment: title: Assignment type: object properties: id: type: string metadata: type: object additionalProperties: type: string number_id: type: string label: type: string example: metadata: key1: value1 label: LabelTest0 id: be3cb602-7c00-4c87-ae4b-b8defc04f179 number_id: b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985 Metadata: title: Metadata type: object additionalProperties: type: string example: Key1: value1 Key2: value2 createAssignmentrequest: title: createAssignmentrequest required: - label - metadata type: object properties: label: type: string metadata: $ref: "#/components/schemas/Metadata" example: label: ExampleLabel metadata: Key1: value1 Key2: value2 updateAssignmentrequest: title: updateAssignmentrequest required: - label - metadata type: object properties: label: type: string metadata: $ref: "#/components/schemas/Metadata" example: label: ExampleLabel metadata: Key1: value1 Key2: value2 Types: title: Types enum: - MOBILE - LANDLINE - TOLL_FREE - SHORT_CODE type: string example: MOBILE,LANDLINE,TOLL_FREE sort_by: title: sort_by enum: - ACCOUNT - ACTION - DESTINATION_ADDRESS - DESTINATION_ADDRESS_COUNTRY - FORMAT - SOURCE_ADDRESS - SOURCE_ADDRESS_COUNTRY - TIMESTAMP type: string description: Field to sort results set by example: ACCOUNT sort_direction: title: sort_direction enum: - ASCENDING - DESCENDING type: string description: Order to sort results by. example: ASCENDING AssignedNumber: title: AssignedNumber type: object properties: assignment: $ref: "#/components/schemas/Assignment" number: $ref: "#/components/schemas/Number" AssignedNumberListResponse: title: AssignedNumberListResponse type: object properties: data: type: array items: $ref: "#/components/schemas/AssignedNumber" description: List of result items. pagination: $ref: "#/components/schemas/Pagination" example: pagination: next_token: 0428d673-0f75-4063-9493-e89d75f13438 page_size: 5 data: - assignment: metadata: key1: value1 label: LabelTest0 id: be3cb602-7c00-4c87-ae4b-b8defc04f179 number_id: b9ee3fe8-2c20-47b1-96e9-c5d12d7ed985 number: id: 03cf54ad-a4a3-4cd1-afd5-e0ca2cf158a3 phone_number: 61436489205 country: AU type: MOBILE classification: BRONZE available_after: "2019-08-06T23:56:15.633Z" capabilities: - SMS ShortUrl: title: ShortUrl type: object properties: click_count: type: number example: 3 view_count: type: number example: 2 message_id: type: string example: 00000000-0000-0000-0000-000000000000 long_url: type: string example: https://developers.sinch.com short_url: type: string example: https://nxt.to/abc1234 destination_number: type: string example: 61491570157 LogSummaryResult: title: LogSummaryResult type: object properties: total_clicks: type: number example: 3 unique_clicks: type: number example: 1 total_views: type: number example: 2 unique_views: type: number example: 1 short_urls_generated: type: number example: 1 short_urls: type: array items: $ref: "#/components/schemas/ShortUrl" description: List of short URLs. pagination: $ref: "#/components/schemas/Pagination" example: total_clicks: 3 unique_clicks: 1 total_views: 2 unique_views: 1 short_urls_generated: 1 short_urls: - click_count: 3 view_count: 2 message_id: 00000000-0000-0000-0000-000000000000 long_url: https://developers.sinch.com short_url: https://nxt.to/abc1234 destination_number: 61491570157 pagination: page: 1 page_size: 100 page_count: 3 Click: title: Click type: object properties: dt: type: string example: "2018-09-18T01:22:17.071493" user_agent: type: string example: Mozilla/5.0 (Windows NT... ip: type: string example: 127.0.0.1 View: title: View type: object properties: dt: type: string example: "2018-09-18T01:22:17.071493" user_agent: type: string example: Mozilla/5.0 (Windows NT... ip: type: string example: 127.0.0.1 LogsDetailResult: title: LogsDetailResult type: object properties: message_id: type: string example: 00000000-0000-0000-0000-000000000000 long_url: type: string example: https://developers.sinch.com short_url: type: string example: https://nxt.to/abc1234 destination_number: type: string example: 61491570157 click_count: type: number example: 3 view_count: type: number example: 2 clicks: type: array items: $ref: "#/components/schemas/Click" description: List of click events. views: type: array items: $ref: "#/components/schemas/View" description: List of view events. pagination: $ref: "#/components/schemas/Pagination" example: message_id: 00000000-0000-0000-0000-000000000000 long_url: https://developers.sinch.com short_url: https://nxt.to/abc1234 destination_number: 61491570157 click_count: 3 view_count: 2 clicks: - dt: "2018-09-18T01:22:17.071493" user_agent: Mozilla/5.0 (Windows NT... ip: 127.0.0.1 views: - dt: "2018-09-18T01:22:17.071493" user_agent: Mozilla/5.0 (Windows NT... ip: 127.0.0.1 pagination: page: 1 page_size: 100 page_count: 3 CreateWebhookresponse: title: CreateWebhookresponse description: | Webhook response object. No fields are strictly required in the schema; however, id, url, method, and retries are consistently populated. type: object properties: id: type: string format: uuid description: Unique identifier for the webhook. Always present. url: type: string description: HTTP(S) URL for the webhook endpoint. Always present. method: type: string description: HTTP method used when invoking the webhook. Always present. encoding: type: string description: Content encoding. Usually present; can be null if missing/unknown. headers: type: object additionalProperties: type: string description: Custom headers configured for the webhook. May be empty. events: type: array items: type: string description: Webhook event types subscribed to. May be empty. template: type: string description: Velocity template for the webhook request body. Only present if set. read_timeout: type: integer description: The read timeout in milliseconds. Only present if set. retries: type: integer description: The number of retry attempts. Always present (defaults to 0). retry_delay: type: integer description: The delay between retries in seconds. Only present when retries are configured. example: id: 76fa7010-8c1f-4a24-917a-4d62a54e744d url: http://webhook.com method: POST encoding: JSON headers: {} events: - ENROUTE_DR - DELIVERED_DR template: "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}" read_timeout: 5000 retries: 3 retry_delay: 30 RetrieveWebhookresponse: title: RetrieveWebhookresponse type: object properties: page: type: integer format: int32 description: The current page number. pageSize: type: integer format: int32 description: The number of webhooks returned per page. pageData: type: array description: The list of webhooks created for the connected account. items: $ref: "#/components/schemas/CreateWebhookresponse" example: page: 0 pageSize: 100 pageData: - id: 76fa7010-8c1f-4a24-917a-4d62a54e744d url: http://webhook.com method: POST encoding: JSON headers: {} events: - ENROUTE_DR - DELIVERED_DR template: "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}" read_timeout: 5000 retries: 3 retry_delay: 30 UpdateWebhook400response: title: UpdateWebhook400response required: - message type: object properties: message: type: string example: message: Something went wrong. Please try again later. CreateWebhookrequest: title: CreateWebhookrequest required: - url - method - encoding - events type: object properties: url: type: string maxLength: 1000 description: HTTP(S) URL for the webhook endpoint. method: type: string enum: - GET - POST - PATCH - PUT - DELETE description: HTTP method used when invoking the webhook. encoding: type: string enum: - JSON - FORM_ENCODED - XML description: Content encoding for the webhook request body. events: type: array items: type: string minItems: 1 description: Non-empty set of webhook event types to subscribe to. headers: type: object additionalProperties: type: string maxLength: 1000 description: | Optional map of custom headers. Content-Type header is not allowed. Key max length is 200 characters, value max length is 1000 characters. template: type: string description: Optional Velocity template for the webhook request body. read_timeout: type: integer minimum: 1 maximum: 60000 description: The read timeout for the webhook call in milliseconds (1-60000). retries: type: integer minimum: 0 maximum: 5 description: The number of times to retry a failed webhook call (0-5). retry_delay: type: integer minimum: 5 maximum: 60 description: The delay between retries in seconds (5-60). example: url: http://webhook.com method: POST encoding: JSON headers: {} events: - ENROUTE_DR - DELIVERED_DR template: "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}" read_timeout: 5000 retries: 3 retry_delay: 30 UpdateWebhookrequest: title: UpdateWebhookrequest description: | All fields are optional, but at least one must be provided. Empty body (all fields null) is rejected. Note: read_timeout, retries, and retry_delay are not supported on update (create-only). type: object properties: url: type: string maxLength: 1000 description: HTTP(S) URL for the webhook endpoint. method: type: string enum: - GET - POST - PATCH - PUT - DELETE description: HTTP method used when invoking the webhook. encoding: type: string enum: - JSON - FORM_ENCODED - XML description: Content encoding for the webhook request body. headers: type: object additionalProperties: type: string maxLength: 1000 description: | Optional map of custom headers. Content-Type header is not allowed. Key max length is 200 characters, value max length is 1000 characters. template: type: string description: Velocity template for the webhook request body. events: type: array items: type: string minItems: 1 description: | Webhook event types to subscribe to. If provided, must be non-empty (events: [] is rejected). example: url: http://webhook.com method: POST encoding: JSON headers: {} events: - ENROUTE_DR - DELIVERED_DR template: "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}" Getsignaturekeylistresponse: title: Getsignaturekeylistresponse type: object properties: key_id: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: type: string example: RSA digest: type: string example: SHA224 created: type: string example: "2018-01-18T10:16:12.364Z" enabled: type: boolean example: false example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: RSA digest: SHA224 created: "2018-01-18T10:16:12.364Z" enabled: true Enablesignaturekey400response: title: Enablesignaturekey400response required: - message - details type: object properties: message: type: string details: type: array items: type: string description: Additional error detail messages. example: message: Bad Request details: - "/key_id: Key id cannot be null" Disablethecurrentenabledsignaturekey.403response: title: Disablethecurrentenabledsignaturekey.403response required: - message type: object properties: message: type: string example: message: This feature has not been enabled in your account. Createsignaturekeyrequest: title: Createsignaturekeyrequest required: - digest - cipher type: object properties: digest: type: string cipher: type: string example: digest: SHA224 cipher: RSA Createsignaturekeyresponse: title: Createsignaturekeyresponse required: - key_id - public_key - cipher - digest - created - enabled type: object properties: key_id: type: string public_key: type: string cipher: type: string digest: type: string created: type: string enabled: type: boolean example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 public_key: MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCTIxtRyT5CuOD74r7UCT+AKzWNxvaAP9myjAqR7+vBnJKEvoPnmbKTnm6uLlxutnMbjKrnCCWnQ9vtBVnnd+ElhwLDPADfMcJoOqwi7mTcxucckeEbBsfsgYRfdacxgSZL8hVD1hLViQr3xwjEIkJcx1w3x8npvwMuTY0uW8+PjwIDAQAB cipher: RSA digest: SHA224 created: "2018-01-18T10:16:12.364Z" enabled: false Getsignaturekeydetailresponse: title: Getsignaturekeydetailresponse type: object properties: key_id: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: type: string example: RSA digest: type: string example: SHA224 created: type: string example: "2018-01-18T10:16:12.364Z" enabled: type: boolean example: false example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: RSA digest: SHA224 created: "2018-01-18T10:16:12.364Z" enabled: false Getenabledsignaturekeyresponse: title: Getenabledsignaturekeyresponse type: object properties: key_id: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: type: string example: RSA digest: type: string example: SHA224 created: type: string example: "2018-01-18T10:16:12.364Z" enabled: type: boolean example: true example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: RSA digest: SHA224 created: "2018-01-18T10:16:12.364Z" enabled: true Enablesignaturekeyrequest: title: Enablesignaturekeyrequest required: - key_id type: object properties: key_id: type: string example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 Enablesignaturekeyresponse: title: Enablesignaturekeyresponse type: object properties: key_id: type: string example: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: type: string example: RSA digest: type: string example: SHA224 created: type: string example: "2018-01-18T10:16:12.364Z" enabled: type: boolean example: true example: key_id: 7ca628a8-08b0-4e42-aeb8-960b37049c31 cipher: RSA digest: SHA224 created: "2018-01-18T10:16:12.364Z" enabled: true RichLink: title: RichLink type: object properties: image: type: string description: The image field is used to specify the url of the media file that you want to show in the link preview. Supported file formats include png, jpeg and gif. title: type: string description: The (optional) title that appears on your unfurled link. Maximum 80 characters. description: type: string description: An optional description, maximum 150 characters. MessageTemplate: title: MessageTemplate required: - content type: object properties: content: type: string description: The message content. This supports template placeholders. metadata: type: object description: Message metadata. This will be supplied to URL shortener and UG. Max 10 keys per campaign. rich_link: $ref: "#/components/schemas/RichLink" delivery_report: type: boolean description: Request a delivery report for the sent message Campaign: title: Campaign required: - template_id - message type: object properties: template_id: type: string description: Template to use for the landing page parameters: type: object description: Parameters to use for the landing page and the message content message: $ref: "#/components/schemas/MessageTemplate" Parameters: title: Parameters required: - title - bodyText - callToAction type: object properties: title: type: string bodyText: type: string callToAction: type: string example: title: This is a title bodyText: This is some body text callToAction: http://www.example.com/ CreateNewCampaignresponse: title: CreateNewCampaignresponse required: - id - template_id - parameters - message type: object properties: id: type: string template_id: type: string parameters: $ref: "#/components/schemas/Parameters" message: $ref: "#/components/schemas/Message" example: id: a94041bb-704b-48fa-ba0b-6f1538fc502f template_id: ac895f01-3149-4bf8-a8fe-01d3b8a9ba97 parameters: title: This is a title bodyText: This is some body text callToAction: http://www.example.com/ message: content: This is the message. metadata: key: value GetCampaignresponse: title: GetCampaignresponse required: - id - template_id - parameters - message type: object properties: id: type: string template_id: type: string parameters: $ref: "#/components/schemas/Parameters" message: $ref: "#/components/schemas/Message" example: id: a94041bb-704b-48fa-ba0b-6f1538fc502f template_id: ac895f01-3149-4bf8-a8fe-01d3b8a9ba97 parameters: title: This is a title bodyText: This is some body text callToAction: http://www.example.com/ message: content: This is the message. metadata: key: value Recipient: title: Recipient required: - number type: object properties: number: type: string description: The recipient phone number. Must be E.164 with a leading '+' parameters: type: object description: The recipient scoped template parameters scheduled: type: string description: A message can be scheduled for delivery in the future by setting the scheduled property. The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be provided in UTC and be no more than 31 days in the future. SendCampaignToRecipientsrequest: title: SendCampaignToRecipientsrequest required: - recipients type: object properties: recipients: type: array items: $ref: "#/components/schemas/Recipient" description: List of recipients. Parameters2: title: Parameters2 required: - firstName - lastName type: object properties: firstName: type: string lastName: type: string example: firstName: John lastName: English Recipient1: title: Recipient1 required: - id - number - parameters type: object properties: id: type: string number: type: string parameters: $ref: "#/components/schemas/Parameters2" example: id: 05f81030-95fb-4c17-8736-ac73948e8b82 number: 61491570156 parameters: firstName: John lastName: English SendCampaignToRecipientsresponse: title: SendCampaignToRecipientsresponse required: - recipients type: object properties: recipients: type: array items: $ref: "#/components/schemas/Recipient1" description: List of recipients. example: recipients: - id: 05f81030-95fb-4c17-8736-ac73948e8b82 number: 61491570156 parameters: firstName: John lastName: English - id: 01261663-9428-4a1d-9798-e8a1877cc29d number: 61491570158 parameters: firstName: Mary lastName: Example CreateLandingPage: title: CreateLandingPage required: - name - template_id type: object properties: name: type: string description: Landing Page name. Maximum 100 characters. template_id: type: string description: Template to use for the landing page. parameters: type: object description: Parameters to use for the landing page and the message content. fields: type: object description: Define the fields that have been used to the paramters. Title: title: Title required: - type type: object properties: type: type: string example: type: TEXT BodyText: title: BodyText required: - type type: object properties: type: type: string example: type: TEXT CtaUrl: title: CtaUrl required: - type type: object properties: type: type: string example: type: URL Fields: title: Fields required: - title - bodyText - ctaUrl type: object properties: title: $ref: "#/components/schemas/Title" bodyText: $ref: "#/components/schemas/BodyText" ctaUrl: $ref: "#/components/schemas/CtaUrl" example: title: type: TEXT bodyText: type: TEXT ctaUrl: type: URL CreateaLandingPageresponse: title: CreateaLandingPageresponse required: - id - name - template_id - parameters - fields - created_timestamp - modified_timestamp type: object properties: id: type: string name: type: string template_id: type: string parameters: $ref: "#/components/schemas/Parameters" fields: $ref: "#/components/schemas/Fields" created_timestamp: type: string modified_timestamp: type: string example: id: a94041bb-704b-48fa-ba0b-6f1538fc502f name: " My Landing Page" template_id: ac895f01-3149-4bf8-a8fe-01d3b8a9ba97 parameters: title: This is a ${title} bodyText: This is some ${bodyText} callToAction: ${ctaUrl} fields: title: type: TEXT bodyText: type: TEXT ctaUrl: type: URL created_timestamp: "2019-11-03T11:49:02.807Z" modified_timestamp: "2019-11-03T11:49:02.807Z" UpdateLandingPage: title: UpdateLandingPage type: object properties: name: type: string description: Landing Page name. Maximum 100 characters. template_id: type: string description: Template to use for the landing page. parameters: type: object description: Parameters to use for the landing page and the message content. fields: type: object description: Define the fields that have been used to the paramters. Parameters4: title: Parameters4 required: - pageTitle - pageText - callToAction type: object properties: pageTitle: type: string pageText: type: string callToAction: type: string example: pageTitle: The new page title pageText: The new body text callToAction: ${ctaUrl} UpdateaLandingPageresponse: title: UpdateaLandingPageresponse required: - id - name - template_id - parameters - fields - created_timestamp - modified_timestamp type: object properties: id: type: string name: type: string template_id: type: string parameters: $ref: "#/components/schemas/Parameters4" fields: $ref: "#/components/schemas/Fields" created_timestamp: type: string modified_timestamp: type: string example: id: a94041bb-704b-48fa-ba0b-6f1538fc502f name: " My Landing Page" template_id: ac895f01-3149-4bf8-a8fe-01d3b8a9ba97 parameters: pageTitle: The new page title pageText: The new body text callToAction: ${ctaUrl} fields: title: type: TEXT bodyText: type: TEXT ctaUrl: type: URL created_timestamp: "2019-11-03T11:49:02.807Z" modified_timestamp: "2019-11-04T11:49:02.807Z" EventSummary: title: EventSummary required: - event - total_events - unique_recipients type: object properties: event: type: string description: The event type to which this summary is for. See [Event Types](#events-types) for a list of available events. source: type: string description: The event source to which this summary is for, if applicable. total_events: type: number description: The total number of recorded events of this type and source. unique_recipients: type: number description: The unique number of recipients for which there exists at least one event of this type and source recorded. CampaignSummary: title: CampaignSummary required: - total_events - unique_engagements - event_summary type: object properties: total_events: type: number description: The total number of events record against this campaign. unique_engagements: type: number description: The unique number of recipients for which there exists at least one recorded event. event_summary: type: array items: $ref: "#/components/schemas/EventSummary" description: The event summary breakdown. CampaignEvent: title: CampaignEvent required: - campaign_id - recipient_id - number - event - timestamp type: object properties: campaign_id: type: string description: The campaign ID recipient_id: type: string description: The recipient ID to which this event corresponds to number: type: string description: The recipient's phone number event: type: string description: The event type. See [Event Types](#events-types) for a list of available events. source: type: string description: The source identifier. This identifies the element that produced the event. This may not be applicable for all events. timestamp: type: string description: The timestamp of the event, in ISO 8601 format. ListCampaignEventPage: title: ListCampaignEventPage required: - events - pagination type: object properties: events: type: array items: $ref: "#/components/schemas/CampaignEvent" description: The list of campaign events. pagination: $ref: "#/components/schemas/Pagination" Template: title: Template required: - id - name type: object properties: id: type: string name: type: string example: id: c9d7ce1d-20c4-4228-9ba1-6da2a3b4e5e0 name: Header image and 1 or 2 CTA Pagination1: title: Pagination required: - page - page_size - total_count type: object properties: page: type: number description: The current page number page_size: type: number description: The requested page size total_count: type: number description: The total number of items that match the query GetTemplatesresponse: title: GetTemplatesresponse required: - templates - pagination type: object properties: templates: type: array items: $ref: "#/components/schemas/Template" description: List of templates. pagination: $ref: "#/components/schemas/Pagination1" example: templates: - id: c9d7ce1d-20c4-4228-9ba1-6da2a3b4e5e0 name: Header image and 1 or 2 CTA - id: f56b5806-f732-4693-b87a-90b66a7d7bfc name: Header Image and 1 CTA - id: 7614456e-844f-4d83-bdfe-20c17ce0f97c name: Background image and 0 or 1 CTA pagination: next_page_token: qwerty123 page_size: 5 FontFamilyURL1: title: FontFamilyURL1 required: - type type: object properties: type: type: string example: type: TEXT SecondaryButtonTextColor: title: SecondaryButtonTextColor required: - type type: object properties: type: type: string example: type: TEXT PageTitle: title: PageTitle required: - type type: object properties: type: type: string example: type: TEXT PageTextColor: title: PageTextColor required: - type type: object properties: type: type: string example: type: TEXT BarcodeHeight: title: BarcodeHeight required: - type type: object properties: type: type: string example: type: TEXT ImageHeaderUrl: title: ImageHeaderUrl required: - type type: object properties: type: type: string example: type: IMAGE BarcodeMargin: title: BarcodeMargin required: - type type: object properties: type: type: string example: type: TEXT LogoLink: title: LogoLink required: - type type: object properties: type: type: string example: type: TEXT PrimaryButtonLink: title: PrimaryButtonLink required: - type type: object properties: type: type: string example: type: TEXT PrimaryButtonBackgroundColor: title: PrimaryButtonBackgroundColor required: - type type: object properties: type: type: string example: type: TEXT SecondaryButtonLink: title: SecondaryButtonLink required: - type type: object properties: type: type: string example: type: TEXT BarcodeWidth: title: BarcodeWidth required: - type type: object properties: type: type: string example: type: TEXT PrimaryButtonText: title: PrimaryButtonText required: - type type: object properties: type: type: string example: type: TEXT Headline: title: Headline required: - type type: object properties: type: type: string example: type: TEXT HeadlineColor: title: HeadlineColor required: - type type: object properties: type: type: string example: type: TEXT PageText: title: PageText required: - type type: object properties: type: type: string example: type: TEXT SecondaryButtonBackgroundColor: title: SecondaryButtonBackgroundColor required: - type type: object properties: type: type: string example: type: TEXT ImageLinkPreviewUrl: title: ImageLinkPreviewUrl required: - type type: object properties: type: type: string example: type: TEXT PageTextFontFamily: title: PageTextFontFamily required: - type type: object properties: type: type: string example: type: TEXT SecondaryButtonText: title: SecondaryButtonText required: - type type: object properties: type: type: string example: type: TEXT HeadlineFontFamily: title: HeadlineFontFamily required: - type type: object properties: type: type: string example: type: TEXT BarcodeLineColor: title: BarcodeLineColor required: - type type: object properties: type: type: string example: type: TEXT BarcodeValue: title: BarcodeValue required: - type type: object properties: type: type: string example: type: TEXT PrimaryButtonTextColor: title: PrimaryButtonTextColor required: - type type: object properties: type: type: string example: type: TEXT ImageLogoUrl: title: ImageLogoUrl required: - type type: object properties: type: type: string example: type: TEXT BarcodeDisplayValue: title: BarcodeDisplayValue required: - type type: object properties: type: type: string example: type: TEXT ButtonFontFamily: title: ButtonFontFamily required: - type type: object properties: type: type: string example: type: TEXT Fields2: title: Fields2 required: - fontFamilyURL1 - secondaryButtonTextColor - fontFamilyURL3 - pageTitle - fontFamilyURL2 - pageTextColor - barcodeHeight - imageHeaderUrl - barcodeMargin - logoLink - primaryButtonLink - primaryButtonBackgroundColor - secondaryButtonLink - barcodeWidth - primaryButtonText - headline - headlineColor - pageText - secondaryButtonBackgroundColor - imageLinkPreviewUrl - pageTextFontFamily - secondaryButtonText - headlineFontFamily - barcodeLineColor - barcodeValue - primaryButtonTextColor - imageLogoUrl - barcodeDisplayValue - buttonFontFamily type: object properties: fontFamilyURL1: $ref: "#/components/schemas/FontFamilyURL1" secondaryButtonTextColor: $ref: "#/components/schemas/SecondaryButtonTextColor" fontFamilyURL3: $ref: "#/components/schemas/FontFamilyURL1" pageTitle: $ref: "#/components/schemas/PageTitle" fontFamilyURL2: $ref: "#/components/schemas/FontFamilyURL1" pageTextColor: $ref: "#/components/schemas/PageTextColor" barcodeHeight: $ref: "#/components/schemas/BarcodeHeight" imageHeaderUrl: $ref: "#/components/schemas/ImageHeaderUrl" barcodeMargin: $ref: "#/components/schemas/BarcodeMargin" logoLink: $ref: "#/components/schemas/LogoLink" primaryButtonLink: $ref: "#/components/schemas/PrimaryButtonLink" primaryButtonBackgroundColor: $ref: "#/components/schemas/PrimaryButtonBackgroundColor" secondaryButtonLink: $ref: "#/components/schemas/SecondaryButtonLink" barcodeWidth: $ref: "#/components/schemas/BarcodeWidth" primaryButtonText: $ref: "#/components/schemas/PrimaryButtonText" headline: $ref: "#/components/schemas/Headline" headlineColor: $ref: "#/components/schemas/HeadlineColor" pageText: $ref: "#/components/schemas/PageText" secondaryButtonBackgroundColor: $ref: "#/components/schemas/SecondaryButtonBackgroundColor" imageLinkPreviewUrl: $ref: "#/components/schemas/ImageLinkPreviewUrl" pageTextFontFamily: $ref: "#/components/schemas/PageTextFontFamily" secondaryButtonText: $ref: "#/components/schemas/SecondaryButtonText" headlineFontFamily: $ref: "#/components/schemas/HeadlineFontFamily" barcodeLineColor: $ref: "#/components/schemas/BarcodeLineColor" barcodeValue: $ref: "#/components/schemas/BarcodeValue" primaryButtonTextColor: $ref: "#/components/schemas/PrimaryButtonTextColor" imageLogoUrl: $ref: "#/components/schemas/ImageLogoUrl" barcodeDisplayValue: $ref: "#/components/schemas/BarcodeDisplayValue" buttonFontFamily: $ref: "#/components/schemas/ButtonFontFamily" example: fontFamilyURL1: type: TEXT secondaryButtonTextColor: type: TEXT fontFamilyURL3: type: TEXT pageTitle: type: TEXT fontFamilyURL2: type: TEXT pageTextColor: type: TEXT barcodeHeight: type: TEXT imageHeaderUrl: type: IMAGE barcodeMargin: type: TEXT logoLink: type: TEXT primaryButtonLink: type: TEXT primaryButtonBackgroundColor: type: TEXT secondaryButtonLink: type: TEXT barcodeWidth: type: TEXT primaryButtonText: type: TEXT headline: type: TEXT headlineColor: type: TEXT pageText: type: TEXT secondaryButtonBackgroundColor: type: TEXT imageLinkPreviewUrl: type: TEXT pageTextFontFamily: type: TEXT secondaryButtonText: type: TEXT headlineFontFamily: type: TEXT barcodeLineColor: type: TEXT barcodeValue: type: TEXT primaryButtonTextColor: type: TEXT imageLogoUrl: type: TEXT barcodeDisplayValue: type: TEXT buttonFontFamily: type: TEXT GetTemplatesFieldsDefinitionresponse: title: GetTemplatesFieldsDefinitionresponse required: - fields type: object properties: fields: $ref: "#/components/schemas/Fields2" example: fields: fontFamilyURL1: type: TEXT secondaryButtonTextColor: type: TEXT fontFamilyURL3: type: TEXT pageTitle: type: TEXT fontFamilyURL2: type: TEXT pageTextColor: type: TEXT barcodeHeight: type: TEXT imageHeaderUrl: type: IMAGE barcodeMargin: type: TEXT logoLink: type: TEXT primaryButtonLink: type: TEXT primaryButtonBackgroundColor: type: TEXT secondaryButtonLink: type: TEXT barcodeWidth: type: TEXT primaryButtonText: type: TEXT headline: type: TEXT headlineColor: type: TEXT pageText: type: TEXT secondaryButtonBackgroundColor: type: TEXT imageLinkPreviewUrl: type: TEXT pageTextFontFamily: type: TEXT secondaryButtonText: type: TEXT headlineFontFamily: type: TEXT barcodeLineColor: type: TEXT barcodeValue: type: TEXT primaryButtonTextColor: type: TEXT imageLogoUrl: type: TEXT barcodeDisplayValue: type: TEXT buttonFontFamily: type: TEXT GetContactsRequest: type: object properties: nextPageToken: type: string prevPageToken: type: string pageSize: maximum: 1000 type: integer format: int32 listIds: type: array items: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee contactIds: type: array items: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee channelIds: type: array items: type: string example: "+15553456783" channelTypes: type: array items: type: string enum: - SMS - WHATSAPP - GBM - INSTAGRAM - FACEBOOK - EMAIL channelSubscriptionState: type: string enum: - SUBSCRIBED - UNSUBSCRIBED description: Get contacts page filter payload ContactCustomFieldData: required: - id - mergeTag - type - value type: object properties: id: type: string description: Custom Field id in UUID format format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee mergeTag: type: string description: Custom field merge tag example: contact_name value: type: string description: Custom field value example: John type: type: string description: Custom field type example: DATE enum: - DATE - NUMBER - PHONE - TEXT - URL - ZIP_CODE - NAME - EMAIL description: Custom field data ContactChannelData: required: - channelId - type type: object properties: channelId: type: string description: Contact channel id (in case phone number - in E164 international format) example: "+15553456783" type: type: string description: Contact channel type example: SMS enum: - SMS - WHATSAPP - GBM - INSTAGRAM - FACEBOOK - EMAIL subscriptionState: type: string description: Subscription state example: UNSUBSCRIBED enum: - SUBSCRIBED - UNSUBSCRIBED description: Contact channel data ContactListData: required: - id - name type: object properties: id: type: string description: List id in UUID format format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee name: type: string description: List name example: My list description: Contact list data ContactData: required: - accountId - alias - channels - country - createdDate - customFields - firstName - fullName - id - lastModifiedDate - lastName - lists - location - note - state - vendorId type: object properties: id: type: string description: Contact id in UUID format format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee accountId: type: string description: Account id vendorId: type: string description: Vendor id firstName: type: string description: Contact first name example: Adam lastName: type: string description: Contact last name example: Smith fullName: type: string description: Contact full name example: Adam Smith alias: type: string description: Contact alias example: VIP contact dateOfBirth: type: string description: Date of birth format: date example: "2022-08-18" country: type: string description: Country example: US state: type: string description: State example: CA location: type: string description: Location example: Sunset Blvd note: type: string description: Note example: Note createdDate: type: string description: Create date format: date-time example: "2022-08-18T09:15:03.112Z" lastModifiedDate: type: string description: Last modified date format: date-time example: "2022-08-18T09:15:03.112Z" customFields: type: array description: List of custom fields items: $ref: "#/components/schemas/ContactCustomFieldData" channels: type: array description: Contact channels items: $ref: "#/components/schemas/ContactChannelData" lists: type: array description: Contact lists items: $ref: "#/components/schemas/ContactListData" description: Contact data PageTokenDtoContactData: required: - content - totalElements type: object properties: content: type: array description: Page content and number of elements is restricted by page size items: $ref: "#/components/schemas/ContactData" nextPageToken: type: string description: Pagination token to retrieve the next page prevPageToken: type: string description: Pagination token to retrieve the previous page totalElements: type: integer description: Total number of elements format: int64 example: 25 description: Page token representation for search result CreateContactChannelRequest: required: - channelId - type type: object properties: channelId: type: string description: Contact channel id (in case phone number - in E164 international format) example: "+15553456783" type: type: string description: Contact channel type example: SMS enum: - SMS - WHATSAPP subscriptionState: type: string description: Subscription state example: UNSUBSCRIBED enum: - SUBSCRIBED - UNSUBSCRIBED description: Contact channel create payload CreateContactListRequest: required: - id type: object properties: id: type: string description: List id in UUID format format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee description: Contact creation list payload CreateCustomFieldRequest: required: - id - value type: object properties: id: type: string description: Custom Field id in UUID format format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee value: type: string description: Custom field value example: John description: Contact custom field create payload CreateContactRequest: required: - channels type: object properties: firstName: type: string description: Contact first name example: Adam lastName: type: string description: Contact last name example: Smith alias: type: string description: Contact alias. Used as an alternative name for your contact, as well as an email handle for email to sms example: user1234 dateOfBirth: type: string description: Date of birth format: date example: "2022-08-18" country: type: string description: Country example: US state: type: string description: State example: CA location: type: string description: Location example: Sunset Blvd note: type: string description: Note example: Note channels: type: array description: Contact channels items: $ref: "#/components/schemas/CreateContactChannelRequest" lists: type: array description: Contact lists items: $ref: "#/components/schemas/CreateContactListRequest" customFields: type: array description: Contact custom fields items: $ref: "#/components/schemas/CreateCustomFieldRequest" description: Contact create payload UpdateContactChannelRequest: required: - channelId - type type: object properties: channelId: type: string description: Contact channel id (in case phone number - in E164 international format) example: "+15553456783" type: type: string description: Contact channel type example: SMS enum: - SMS - WHATSAPP subscriptionState: type: string description: Subscription state example: UNSUBSCRIBED enum: - SUBSCRIBED - UNSUBSCRIBED description: Contact channel update payload UpdateContactRequest: type: object properties: firstName: type: string description: Contact first name example: Adam lastName: type: string description: Contact last name example: Smith alias: type: string description: Contact alias. Used as an alternative name for your contact, as well as an email handle for email to sms example: user1234 dateOfBirth: type: string description: Date of birth format: date example: "2022-08-18" country: type: string description: Country example: US state: type: string description: State example: CA location: type: string description: Location example: Sunset Blvd note: type: string description: Note example: Note channels: type: array description: Contact channels items: $ref: "#/components/schemas/UpdateContactChannelRequest" lists: type: array description: Contact lists items: $ref: "#/components/schemas/CreateContactListRequest" customFields: type: array description: Contact custom fields items: $ref: "#/components/schemas/CreateCustomFieldRequest" description: Contact update payload GetListsRequest: type: object properties: nextPageToken: type: string prevPageToken: type: string pageSize: maximum: 1000 type: integer format: int32 listIds: type: array items: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee alias: type: string name: type: string description: Get contact lists page filter ListData: required: - accountId - alias - createdDate - id - lastModifiedDate - name - vendorId type: object properties: id: type: string description: List id in UUID format format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee accountId: type: string description: Account id vendorId: type: string description: Vendor id name: type: string description: List name example: My group alias: type: string description: List alias example: VIP group createdDate: type: string description: Create date format: date-time example: "2022-08-18T09:15:03.112Z" lastModifiedDate: type: string description: Last modified date format: date-time example: "2022-08-18T09:15:03.112Z" description: List details data PageTokenDtoListData: required: - content - totalElements type: object properties: content: type: array description: Page content and number of elements is restricted by page size items: $ref: "#/components/schemas/ListData" nextPageToken: type: string description: Pagination token to retrieve the next page prevPageToken: type: string description: Pagination token to retrieve the previous page totalElements: type: integer description: Total number of elements format: int64 example: 25 description: Page token representation for search result CreateListRequest: required: - name type: object properties: name: type: string description: Group name example: My group alias: type: string description: Group alias example: Group1 description: Contact list create payload UpdateListRequest: required: - name type: object properties: name: type: string description: Contact list name example: My list alias: type: string description: Contact list alias example: List1 description: Contact list update payload UpdateContactsListRequest: type: object properties: contactsToAddIds: maxItems: 1000 minItems: 0 type: array items: type: string description: List of contacts to add to the list in UUID format format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee contactsToRemoveIds: maxItems: 1000 minItems: 0 type: array items: type: string description: List of contacts to remove from the list in UUID format format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee description: Contacts list update payload GetCustomFieldsRequest: type: object properties: nextPageToken: type: string prevPageToken: type: string pageSize: maximum: 1000 type: integer format: int32 customFieldIds: type: array items: type: string format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee label: type: string mergeTag: type: string description: Get custom fields page filter CustomFieldData: required: - accountId - createdDate - id - label - lastModifiedDate - maxLength - mergeTag - type - vendorId type: object properties: id: type: string description: Custom field id in UUID format format: uuid example: 025e93d3-051b-43f9-b12e-4b5842228dee accountId: type: string description: Account id example: accountId_67846328 vendorId: type: string description: Vendor id label: type: string description: Custom field label example: Contact name mergeTag: type: string description: Custom field merge tag example: contact_name maxLength: type: integer description: Custom field max length format: int32 example: 30 type: type: string description: Custom field type example: DATE enum: - DATE - NUMBER - PHONE - TEXT - URL - ZIP_CODE - NAME - EMAIL createdDate: type: string description: Create date format: date-time example: "2022-08-18T09:15:03.112Z" lastModifiedDate: type: string description: Last modified date format: date-time example: "2022-08-18T09:15:03.112Z" description: Custom field data PageTokenDtoCustomFieldData: required: - content - totalElements type: object properties: content: type: array description: Page content and number of elements is restricted by page size items: $ref: "#/components/schemas/CustomFieldData" nextPageToken: type: string description: Pagination token to retrieve the next page prevPageToken: type: string description: Pagination token to retrieve the previous page totalElements: type: integer description: Total number of elements format: int64 example: 25 description: Page token representation for search result CustomFieldCreateRequest: required: - label - maxLength - mergeTag - type type: object properties: label: type: string description: Custom field label example: Contact name mergeTag: type: string description: Custom field merge tag example: contact_name maxLength: type: integer description: Custom field max length format: int32 example: 30 type: type: string description: Custom field type example: DATE enum: - DATE - NUMBER - PHONE - TEXT - URL - ZIP_CODE - NAME - EMAIL description: Custom field create payload UpdateCustomFieldRequest: type: object properties: label: type: string description: Custom field label example: Contact name maxLength: type: integer description: Custom field max length format: int32 example: 30 description: Custom field update payload responses: PayloadTooLarge: description: Maximum upload size exceeded content: application/json: schema: $ref: "#/components/schemas/ApiError" UnsupportedMediaType: description: Unsupported media type content: application/json: schema: $ref: "#/components/schemas/ApiError" PaymentRequired: description: Current user does not have permissions to perform the requested operation content: application/json: schema: $ref: "#/components/schemas/ApiError" Unauthorized: description: No valid authentication details were provided BadRequest: description: Request has incorrect values content: application/json: schema: $ref: "#/components/schemas/InvalidInputApiError" Forbidden: description: The authenticated user or account doesn't have permission Conflict: description: Conflict. The entity already exists. content: application/json: schema: $ref: "#/components/schemas/ApiError" InternalServerError: description: Internal server error content: application/json: schema: $ref: "#/components/schemas/ApiError" RequestNotRecognised: description: Request not recognised BadGateway: description: Invalid server response ServerUnavailable: description: Server currently unavailable GatewayTimeout: description: Gateway time out NotFound: description: The specified resource not found content: application/json: schema: $ref: "#/components/schemas/ApiError" headers: ExpiresAfter: description: date in UTC when token expires schema: type: string format: date-time securitySchemes: basic_auth: type: http scheme: basic description: | HTTP Basic authentication using your API key as the username and API secret as the password. See the Basic Authentication guide tag. hmac_auth: type: apiKey in: header name: Authorization description: | HMAC request signing. Place the full `hmac username=...` credential in the Authorization header. See the HMAC Authentication guide tag. bearer_auth: type: http scheme: bearer bearerFormat: JWT description: | Bearer JWT authentication used by selected messaging-reports async download endpoints. Prefer Basic or HMAC for all other operations. x-tagGroups: - name: Guides tags: - Basic Authentication - HMAC Authentication - Sub-accounts - name: Messaging tags: - Messages - Delivery Reports - Replies - name: Numbers tags: - Source Address - Number Authorisation - Dedicated Numbers - name: Webhooks and security tags: - Webhooks Management - Signature Key Management - name: Reporting tags: - Messaging Reports - Short Trackable Links Reports - name: Contacts tags: - Contacts - name: Beta tags: - Mobile Landing Pages (beta)