{ "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\nThe Sinch APIs provide powerful business messaging capabilities across sending, receiving, and processing SMS, MMS, and rich messaging. \n\nAll requests to the Sinch REST API must be authenticated, this can either be done using Basic Authentication or by signing with a HMAC signature.\n\n\n\n# Base URI\n \nThe API uses the following base URI\n\nFor EU instance please use https://eu.app.api.sinch.com\n\nFor APAC instance, use https://au.app.api.sinch.com\n\n# Credentials\n \nTo access the API, an API key and secret are required.\n \n[Sign up for a developer account here to get access](https://support.app.sinch.com/hc/en-us/categories/10516535548943-Sinch-Engage-Developer-Guides)\n\n# Features\n### De-Duplication \nDe-Duplication helps you avoid having to undertake data cleansing before commencing send outs. \nIt 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.\n\n### Social Sending \nSocial 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). \nMessages 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.\n\n### Familiar Sender\nFamiliar Sender ensures all communication sent to a customer are from the same phone number. \nThis 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.\n\n### Character Converter\nCharacters in a message may not always fall within the GSM-7 supported character set, and when this occurs all \noutbound messages will be encoded using UCS-2 leading to the customer being double-charged for the SMS. Character Converter \ncan help you avoid being double-charged for your SMS by converting all characters into the GSM-7 format ensuring you always \nget the maximum characters into an SMS. Bear in mind, this will downgrade all your unicode characters so for instance, \nyour emojis will be translated into a string of unknown characters (eg: �). To enable this, you don't need to make any \nchanges to your application, just an account configuration change by Sinch's support team.\n" }, "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": "\nEvery request requires an `Authorization` header in the following format:\n```plain\nAuthorization: Basic Base64(api_key:api_secret)\n```\nWhere 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.\n### Example request with Basic Authentication\n```plain\nPOST /v1/messages HTTP/1.1\nHost: eu.app.api.sinch.com\nAccept: application/json\nContent-Type: application/json\nAuthorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp\n{\n \"messages\": [\n {\n \"content\": \"Hello World\",\n \"destination_number\": \"+61491570156\",\n \"format\": \"SMS\"\n }\n ]\n} \n```\n_Note: spaces are used as indentation in the body of the above request._" }, { "name": "HMAC Authentication", "kind": "nav", "description": "\nEvery request requires an `Authorization` header in the following formats:\nFor a request with a request body:\n```plain\nAuthorization: hmac username=\"\", algorithm=\"hmac-sha256\", headers =\"Date Content-MD5 request-line\", signature=\"\"\n```\n\nFor a request _without_ a request body:\n\n```plain\nAuthorization: hmac username=\"\", algorithm=\"hmac-sha256\", headers=\"Date request-line\", signature=\"\"\n```\n### To create this header\n#### Step 1\nAdd 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\n#### Step 2\nIf 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\n#### Step 3\nCreate a signing string by concatenating the `Date` header, the\n`Content-MD5` header (if set) and the request line with line breaks:\n```plain\nDate: Sat, 30 Jul 2016 05:13:23 GMT\\nContent-MD5: 10fd4feab20d38432480c07301e49616\\nPOST /v1/messages HTTP/1.1\n```\nor\n```plain\nDate: Sat, 30 Jul 2016 05:13:23 GMT\\nGET /v1/messages/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1\n```\n#### Step 4\nCreate a SHA256 HMAC hash using the signing string and the secret key (both converted to bytes using UTF-8) ```HMAC-SHA256(signing string, secret)```\n#### Step 5\nBase64 encode the HMAC hash and include it as the signature in the ```Authorization``` header\n### Example request with body\n```plain\nPOST /v1/messages HTTP/1.1\nHost: eu.app.api.sinch.com\nAccept: application/json\nContent-Type: application/json\nDate: Sat, 30 Jul 2016 05:18:52 GMT\nAuthorization: hmac username=\"uCXUdoogNfCsehEClbO2\", algorithm=\"hmac-sha256\", headers=\"Date Content-MD5 request-line\", signature=\"Ia4G5lkhH/3NDYpix+8ZHUnp6bA=\"\nContent-MD5: 5407644fa83bec240dede971307e0cad\nContent-Length: 133\n{\n \"messages\": [\n {\n \"content\": \"Hello World\",\n \"destination_number\": \"+61491570156\",\n \"format\": \"SMS\"\n }\n ]\n}\n```\n_Note: spaces are used as indentation in the body of the above request._\n### Example request without body\n```plain\nGET /v1/messages/404b941b-2a29-469f-b114-9ea3e16bbe18 HTTP/1.1\nHost: eu.app.api.sinch.com\nAccept: application/json\nDate: Sat, 30 Jul 2016 05:18:52 GMT\nAuthorization: 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\nUsing API keys at the parent account level, you can perform actions on behalf of a sub-account. \n\nThis feature is supported by the Messages, Replies, Delivery Reports and Webhooks APIs. \n\nTo do this\n include a header key ```Account``` with the sub-account ID as the value. For example:\n ```Account: mySubAccount```\n\n **Example request with Sending from sub-accounts**\n\n ```plain\n POST /v1/messages HTTP/1.1\n Host: eu.app.api.sinch.com\n Accept: application/json\n Content-Type: application/json\n Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp\n Account: SubAccount\n {\n \"messages\": [\n {\n \"content\": \"Hello World\",\n \"destination_number\": \"+61491570156\",\n \"delivery_report\": true\n }\n ]\n } \n ```\n" }, { "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:\n* Messages - Messages delivered from an application to a handset.\n* 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.\n* Replies - Messages sent from a handset to an application. These messages are typically a reply to a previously sent message.\n![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.\n\n**What is Trusted Sender ID?**\n\nSimply 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\").\n\nWith 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.\n\nCurrently, 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.\n\n### Alpha Tag\n 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. \n \n 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.\n \n Alpha Tags appear as the \"From\" number when you receive messages.\n \n A good alpha tag meets at least one of the following valid use cases: \n * Business names\n * Trademark names \n * Product or service name\n * an acronym, initialism, or contraction of your entity\n \n 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:\n * 6-11 characters long\n * Only contains characters from the following sets:\n * A-Z\n * a-z\n * 0-9\n * _ (underscore)\n * \\- (hyphen)\n \n 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```\n \n To register an Alpha Tag as a sender ID you must:\n 1. Make a request to the **Request a Sender Address** endpoint\n 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\n \n Once the alpha tag has been approved, you can begin using it as a Sender ID for SMS messages.\n\n ### Personal Number\n 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.\n \n 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.\n\n 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```\n\n To register a personal number as a Sender ID you must:\n 1. Make a request to the **Request a Sender Address** endpoint\n 2. A unique verification code will be sent to the requested number\n 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.\n\n ⚠️ 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.\n\n ### Requesting a Source Address on behalf of a sub-account\n 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: \n ```Account: mySubAccount```\n\n **Example request with Request a Sender Address from a sub-account**\n ```plain\n POST /v1/messaging/numbers/sender_address/requests HTTP/1.1\n Host: eu.app.api.sinch.com\n Accept: application/json\n Content-Type: application/json\n Authorization: Basic dGhpc2lzYWtleTp0aGlzaXNhc2VjcmV0Zm9ybW1iYXNpY2F1dGhyZXN0YXBp\n Account: mySubAccount\n {\n \"sender_address\": \"+61341234131\",\n \"sender_address_type\": \"INTERNATIONAL\",\n \"usage_type\": \"OWN_NUMBER\",\n \"destination_countries\": [\n \"AU\"\n ],\n \"reason\": \"I confirm that my business has a valid use case\",\n \"label\": \"my number sample\"\n } \n ```\n *Note: The use of the Account header key applies to all Source Address endpoints.*\n" }, { "name": "Delivery Reports", "description": "If a callback URL is specified in the submit message request, then changes to the message status, \nreplies 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. \n\nAll 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.\n\nDelivery Reports may carry an additional charge. For pricing, please contact your Account Manager or Support Team ().\n\nTo 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.\n\nFor delivery reports or changes in the status of a message, the POST request to the specified URL will be as follows:\n \n _Note, multiple delivery report notifications will be received for a single message._\n\n```javascript\n{\n \"callback_url\":\"http://mockbin.org/bin/ac52ebd4-eca1-4c86-bf38-4dce79633906\",\n \"delivery_report_id\":\"693e87f2-a553-4281-9ffe-ddf04cbc4bf3\",\n \"source_number\":\"+61491570156\",\n \"date_received\":\"2016-11-03T11:49:02.807Z\",\n \"status\":\"delivered\",\n \"delay\":0,\n \"billing_units\":1,\n \"submitted_date\":\"2016-11-03T11:49:01.551Z\",\n \"original_text\":\"Hello world!\",\n \"message_id\":\"389dc1a8-62a4-4110-ba61-af94806c006f\",\n \"vendor_account_id\":{\n \"vendor_id\":\"SinchEU\",\n \"account_id\":\"MyAccount\"\n },\n \"error_code\":\"220\",\n \"metadata\":{\n \"key\":\"value\"\n }\n}\n```\n\n\nThe properties included in the notification are as follows:\n\n* **Callback URL**: The URL specified as the callback URL in the original submit message request.\n\n* **Delivery Report ID**: A unique ID for the delivery report that this notification represents.\n\n* **Source Number**: The destination address of the original message.\n\n* **Date Received**: The date and time at which this notification was generated in UTC.\n\n* **Status**: The status of the message as indicated by this delivery report. The status field can be one of the following values:\n\n * `enroute`: Message has been received by the gateway and is being processed (or waiting to be processed).\n\n * `submitted`: Message has been submitted to a provider/carrier for delivery.\n\n * `delivered`: Message delivery has been confirmed by the provider, including to the handset (where possible).\n\n * `expired`: The message has expired.\n\n * `rejected`: The message will not be delivered - permanent failure. Reasons may include usage limit exceeded, insufficient credit, number blocked, or content filtered\n\n * `failed`: The message has failed. Reasons may include no active routes to destination or undeliverable by downstream provider.\n\n* **Delay**: _Deprecated, no longer in use_\n\n* **Billing Units**: The number of billing units charged for the message.\n\n* **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.\n\n* **Original Text**: Text of the original message.\n\n* **Message ID**: ID of the original message.\n\n* **Vendor Account ID**: The account used to submit the original message. The vendor will always be `SinchEU`\n\n* **Error Code**: A status code which provides additional information about the message status:\n\n * `101`: Message being processed by the gateway.\n \n * `102`: Message is being rerouted to a different provider after failing via the first provider.\n \n * `151`: Message held for screening.\n \n * `200`: Message submitted to downstream provider for delivery.\n \n * `210`: Message accepted by downstream provider.\n \n * `211`: Message is enroute for delivery by provider.\n \n * `212`: Message submitted. Delivery pending.\n \n * `213`: Message scheduled for delivery by downstream provider.\n \n * `220`: Message delivered.\n \n * `221`: Message delivered to the handset.\n \n * `320`: Message validity period has expired (prior to submission).\n \n * `401`: Message validity period has expired (before delivery).\n \n * `301`: Usage threshold reached. Message discarded.\n \n * `302`: Destination address blocked. Message discarded.\n \n * `303`: Source address blocked. Message discarded.\n \n * `304`: Message dropped. Contact support.\n \n * `305`: Message discarded due to duplicate detection.\n \n * `402`: Message rejected by downstream provider.\n \n * `403`: Message skipped by downstream provider.\n \n * `410`: Invalid source address.\n \n * `411`: Invalid destination address.\n \n * `412`: Destination address blocked.\n \n * `413`: SMS service unavailable on destination.\n \n * `414`: Destination unreachable.\n \n * `330`: Gateway failure.\n \n * `331`: Message discarded.\n \n * `332`: No available route to destination.\n \n * `333`: Source address unsupported for this destination.\n \n * `400`: Message failed; undeliverable.\n \n * `405`: Message cancelled or deleted by provider.\n" }, { "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.\nThis 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\na Sinch Account. The API allows two kinds of reports, _Detailed Reports_ and _Summary Reports_.\n\nDetailed 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.\n" }, { "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.\n\nThe reporting API has endpoints specific to \nthis feature, allowing users to obtain details regarding \nthe number of click-throughs on each URL.\n\nTo enable this feature on your account, contact your account manager or contact support on [support@app.sinch.com](mailto:support@app.sinch.com).\n\nTo 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).\n" }, { "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 \nthese are calls to your own system, you should be provided with an extra level of security \nwhen calling your resources.\n\nThe Sinch Signature Key API provides a number of endpoints \nfor managing key used to sign each unique request to ensure security \nand the requests can't (easily) be spoofed. This is similar to using \nHMAC in your outbound messaging (rather than HTTP Basic).\n\nThe Signature Key API provides seven main endpoints:\n- ```Create signature key``` Create a new signature key for signature verification in webhooks.\n- ```Get signature key detail``` Retrieve the current detail of a signature key using the key_id returned in the ```create signature key``` endpoint.\n- ```Delete signature key``` Delete a signature key using the key_id returned in the ```create signature key``` endpoint.\n- ```Get signature key list``` Retrieve the paginated list of signature keys.\n- ```Enable signature key``` Enable a signature key using the key_id returned in the ```create signature key``` endpoint.\n- ```Get enabled signature key``` Retrieve the current enabled signature key.\n- ```Disable an enabled signature key``` Disable the current enabled signature key.\n" }, { "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. \n\n*Note: This API is only available in the APAC region.*\n \n## Concepts\n\nThe 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.\n\n## Parameters\n\nCampaign 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.\n\nWhen resolving parameters sets, Recipient parameters override Campaign parameters with the same name.\n\nParameter 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.\n\nThe SMS message that is to be sent to each user is defined at the Campaign level. \n\nThe message itself can consist of parameter references surrounded in `${...}`, for example:\n\n```Hello ${firstName} ${lastName}, this is your message.```\n\n## Sending Mobile Landing Pages \n\nFrom end to end, sending a Mobile Landing Pages involves the following steps: \n\n### Step 1: Create a campaign\n\nChoose 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 \nspecifies the desired parameters for the template_id and sets up a message template:\n\n```\n{\n \"template_id\": \"ac895f01-3149-4bf8-a8fe-01d3b8a9ba97\",\n \"parameters\": {\n \"pageTitle\": \"The page title\",\n \"pageText\": \"The body text\",\n \"imageUrl\": \"https://example.com/image.jpg\",\n \"secondaryImageUrl\": \"https://www.example.com/optional_secondary_image.jpg\",\n \"buttonLink\": \"https://example.com/\",\n \"buttonText\": \"Call to Action Button Text\",\n \"secondaryButtonLink\": \"https://example.com/optional_secondary_button\",\n \"secondaryButtonText\": \"Secondary Call to Action Button\"\n },\n \"message\": {\n \"content\": \"Hello ${firstName} ${lastName}, this is the SMS message body\",\n \"metadata\": {\n \"key\": \"value\"\n }\n }\n}\n```\n\nInside 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.\n\n### Step 2: Send to recipients\n\nUsing 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 \n(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: \n\n```\n{\n \"recipients\": [\n {\n \"number\": \"+6140000000\",\n \"parameters\": { \"firstName\":\"Joe\", \"lastName\",\"Bloe\" }\n },\n {\n \"number\": \"+6141111111\",\n \"parameters\": { \"firstName\":\"Jane\", \"lastName\",\"Doe\" }\n }\n ]\n}\n```\n\n## Landing Page Store\n\nThe 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 \noptionally use this data store to programatically send landing pages that have been designed and configured in the hub.\n\nIf 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. \nYou will then need to copy those template and parameters into a campaign. \n\n## Template Parameters\n\nEach 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.\n\n| Parameter | Required | Tyep|Description |\n|------------------|-------------|-----------|-----------|\n| imageBackgroundUrl | Optional - depends on MLP template. |image| Width: 750 pixels, height: 1624 pixels, size: less than 300 kB, type: png, gif, or jpg|\n| barcodeValue | Optional - depends on MLP template. |text| Alphanumeric string. We will use CODE-128 format 1-D barcode. |\n| barcodeDisplayValue | Optional - defaults to true. Otherwise, use false |text| Indicates whether the barcode value is shown below the barcode image|\n| barcodeHeight| Optional| text||\n| barcodeMargin| Optional| text||\n| barcodeWidth| Optional| text||\n| 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') |\n| pageText | |html| For personalisation, use the following format: \"Hi ${firstName}, thanks for visiting…\"|\n| 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') |\n| imageHeaderUrl | Optional - depends on MLP template |image| Width: 750 pixels, height: 375 pixels, size: less than 300 kB, type: png, gif, or jpg.|\n| headline | |text| For personalisation, use the following format: \"Hi ${firstName}, thanks for visiting…\". Specifications: 60 characters or less recommended|\n| 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') |\n| pageTitle | |text| HTML page title shown on browser tab. Specifications: 60 characters or less recommended.|\n| imageLogoUrl |Optional |image| Specifications: width: 300 pixels, height: 120 pixels, size: less than 300 kB, type: png, gif, or jpg|\n| logoLink | Optional|url| For personalisation, use the following format: \"https://example.com/?cid=${customerId}\"|\n| primaryButtonLink | |url| For personalisation, use the following format: \"https://example.com/?cid=${customerId}\"|\n| primaryButtonText | |text| For personalisation, use the following format: \"${firstName}, shop now\". Specifications: 36 characters or less recommended |\n| 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') |\n| 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') |\n| secondaryButtonLink | Optional - depends on MLP template |url| For personalisation, use the following format: \"https://example.com/?cid=${customerId}\"|\n| secondaryButtonText | Optional - depends on MLP template |text| For personalisation, use the following format: \"Hi ${firstName}, thanks for visiting…\". Specifications: 36 characters or less recommended |\n| 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') |\n| 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') |\n| 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`)|\n| 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`)|\n| 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`)|\n| pageTextFontFamily | |text| Specify the font family of page text |\n| headlineFontFamily | |text| Specify the font family of headline text |\n| buttonFontFamily | |text| Specify the font family of button text |\n\n## Template Catalogue\n\n | Name and preview | Template ID |\n |-------------------|-------------|\n | ![](https://developers.sinch.com/wp-content/templates/Template1.png) | 7614456e-844f-4d83-bdfe-20c17ce0f97c |\n | ![](https://developers.sinch.com/wp-content/templates/Template2.png) | f56b5806-f732-4693-b87a-90b66a7d7bfc |\n |![](https://developers.sinch.com/wp-content/templates/template3.png) | c9d7ce1d-20c4-4228-9ba1-6da2a3b4e5e0 |\n" }, { "name": "Contacts", "description": "The API provides access to two main resources:\n\n * **Contacts**: Data associated with the individuals you need to contact.\n * **Lists**: Groups of contacts created for specific purposes.\n * **Custom Fields**: Additional fields that can be tailored to complement the basic contact fields.\n" } ], "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\nin the send messages endpoint.\n\nA successful request to the get message status endpoint will return a\nresponse body as follows:\n\n```javascript\n\n{\n \"format\": \"SMS\",\n \"content\": \"My first message!\",\n \"metadata\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\"\n },\n \"message_id\": \"877c19ef-fa2e-4cec-827a-e1df9b5509f7\",\n \"callback_url\": \"https://my.callback.url.com\",\n \"delivery_report\": true,\n \"destination_number\": \"+61401760575\",\n \"scheduled\": \"2016-11-03T11:49:02.807Z\",\n \"source_number\": \"+61491570157\",\n \"source_number_type\": \"INTERNATIONAL\",\n \"message_expiry_timestamp\": \"2016-11-03T11:49:02.807Z\",\n \"status\": \"enroute\"\n}\n\n```\n\nThe status property of the response indicates the current status of the\nmessage. See the Delivery Reports section of this documentation for more information on message\nstatuses. The expiry date for getting an entity is 45 days.\n\n*Note: If an invalid or nonexistent message ID parameter is specified\nin the request, then a HTTP 404 Not Found response will be returned*\n", "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\";\n\ntry \n{\n GetMessageStatusResponse result = messages.GetMessageStatusAsync(messageId).Result;\n}\ncatch (APIException e){};" }, { "lang": "Java", "label": "Java", "source": "String messageId = \"messageId2\";\n\nmessagesController.getMessageStatusAsync(messageId, new APICallBack() {\n public void onSuccess(HttpContext context, GetMessageStatusResponse response) {\n // TODO success callback handler\n }\n public void onFailure(HttpContext context, Throwable error) {\n // TODO failure callback handler\n }\n});" }, { "lang": "JavaScript", "label": "JavaScript", "source": "let messageId = 'messageId2';\n\nconst promise = controller.getMessageStatus(messageId);\npromise.then((response) => {\n // this block will be executed on successful endpoint call\n // `response` will be of type 'GetMessageStatusResponse'\n}, (err) => {\n // this block will be executed on endpoint call failure\n // `err` is an 'object' containing more information about the error\n});" }, { "lang": "PHP", "label": "PHP", "source": "$messageId = 'messageId2';\n\n$result = $messagesController->getMessageStatus($messageId);" }, { "lang": "Python", "label": "Python", "source": "message_id = 'messageId2'\n\nresult = 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.\n\nA scheduled message can be cancelled by updating the status of a message\nfrom ```scheduled``` to ```cancelled```. This is done by submitting a PUT request to the\nmessages endpoint using the message ID as a parameter (the same endpoint used above to retrieve\nthe status of a message). The expiry date for getting an entity is 45 days.\n\nThe body of the request simply needs to contain a ```status``` property with the value set to ```cancelled```.\n\n```javascript\n\n{\n \"status\": \"cancelled\"\n}\n\n```\n\n*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*\n", "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\";\nCancelScheduledMessageRequest body = new CancelScheduledMessageRequest();\nbody.Status = \"cancelled\";\n\ntry \n{\n dynamic result = messages.CancelScheduledMessageAsync(messageId, body).Result;\n}\ncatch (APIException e){};" }, { "lang": "Java", "label": "Java", "source": "String messageId = \"messageId2\";\nCancelScheduledMessageRequest body = new CancelScheduledMessageRequest();\nbody.setStatus(\"cancelled\");\n\nmessagesController.cancelScheduledMessageAsync(messageId, body, new APICallBack() {\n public void onSuccess(HttpContext context, DynamicResponse response) {\n // TODO success callback handler\n }\n public void onFailure(HttpContext context, Throwable error) {\n // TODO failure callback handler\n }\n});" }, { "lang": "JavaScript", "label": "JavaScript", "source": "let messageId = 'messageId2';\nlet body = new lib.CancelScheduledMessageRequest();\nbody.status = 'cancelled';\n\nconst promise = controller.cancelScheduledMessage(messageId, body);\npromise.then((response) => {\n // this block will be executed on successful endpoint call\n // `response` will be of type 'mixed'\n}, (err) => {\n // this block will be executed on endpoint call failure\n // `err` is an 'object' containing more information about the error\n});" }, { "lang": "PHP", "label": "PHP", "source": "$messageId = 'messageId2';\n$body = new Models\\CancelScheduledMessageRequest;\n$body->status = 'cancelled';\n\n$result = $messagesController->cancelScheduledMessage($messageId, $body);" }, { "lang": "Python", "label": "Python", "source": "message_id = 'messageId2'\nbody = CancelScheduledMessageRequest()\nbody.status = 'cancelled'\n\nresult = 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\nmessages for delivery.\n\nThe most basic message has the following structure:\n\n```javascript\n\n{\n \"messages\": [\n {\n \"content\": \"My first message!\",\n \"destination_number\": \"+61491570156\"\n }\n ]\n}\n\n```\n\nMore advanced delivery features can be specified by setting the\nfollowing properties in a message:\n\n- ```callback_url``` A URL can be included with each message to which\nWebhooks 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.\n\n- ```content``` The content of the message. This can be a Unicode string, up to 5,000 characters long.\n Message content is required.\n\n- ```delivery_report``` Delivery reports can be requested with each\nmessage. If delivery reports are requested, a webhook will be submitted to the ```callback_url``` property specified for the message (or to the webhooks)\n specified for the account every time the status of the message changes as it is processed. The\n current status of the message can also be retrieved via the Delivery Reports endpoint of the\n Messages API. Delivery reports are optional and by default will not be requested.\n\n- ```destination_number``` The destination number the message should be\ndelivered to. This should be specified in E.164\n international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164.\n A destination number is required. \n⚠️ 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.\n\n- ```format``` The format specifies which format the message will be\nsent as, ```SMS``` (text message), ```MMS``` (multimedia message)\n or ```TTS``` (text to speech). With ```TTS``` format, we will call the destination number and read out the\n message using a computer generated voice. Specifying a format is optional, by default ```SMS``` will be used.\n\n- ```source_number_type``` If a source number is specified, the type of\nsource number may also be\n specified. This is recommended when using a source address type that is not an internationally\n formatted number, available options are ```INTERNATIONAL```, ```ALPHANUMERIC``` or ```SHORTCODE```. Specifying a\n source number type is only valid when the ```source_number``` parameter is specified and is optional.\n If a source number is specified and no source number type is specified, the source number type will be\n inferred from the source number, however this may be inaccurate.\n\n- ```source_number```[optional] Specify a source number to be used. Refer to the section below for more information on source numbers. \n⚠️ The number or sender ID must be registered to your account (from 1-Mar-2024).\n\n #### Source number (sender ID)\n \n There are several options for the number or sender ID that will show as the source of an outbound message. Some things to note:\n - If you do not specify a source number, the message will be sent with the default number for your account.\n - 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.\n - If your account has multiple numbers, you can specify which source number to use in the request.\n - If your account does not have a number, your message may be sent using our shared number pool (in certain countries only)\n - `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.\n - `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.\n If you need to register a large number of source numbers/sender IDs, consider using our [Source Address API](#tag/Source-Address)\n \n ⚠️ 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.\n\n- ```media``` The media is used to specify a list of URLs of the media file(s) that you are trying to send. \nSupported file formats include png, jpeg and gif. ```format``` parameter must be set to ```MMS``` for this to\nwork.\n\n- ```subject``` The subject field is used to denote subject of the MMS\nmessage and has a maximum size of 64 characters long. Specifying a\nsubject is optional.\n\n- ```scheduled``` A message can be scheduled for delivery in the future\nby setting the scheduled property.\n The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be\n provided in UTC and is optional. If no scheduled property is set, the message will be delivered immediately.\n\n- ```message_expiry_timestamp``` A message expiry timestamp can be\nprovided to specify the latest time\n at which the message should be delivered. If the message cannot be delivered before the specified\n message expiry timestamp elapses, the message will be discarded. Specifying a message expiry \n timestamp is optional.\n\n- ```metadata``` Metadata can be included with the message which will\nthen be included with any delivery\n reports or replies matched to the message. This can be used to create powerful two-way messaging\n applications without having to store persistent data in the application. Up to 10 key / value metadata data\n pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to \n 256 characters long. Specifying metadata for a message is optional.\n\nThe response body of a successful POST request to the messages endpoint\nwill include a ```messages``` property which contains a list of all messages submitted. The list of\nmessages submitted will reflect the list of messages included in the request, but each message\nwill also contain two new properties, ```message_id``` and ```status```. The returned message ID\nwill be a 36 character UUID which can be used to check the status of the message via the Get Message\nStatus endpoint. The status of the message which reflect the status of the message at submission\ntime which will always be ```queued```. See the Delivery Reports section of this documentation for\nmore information on message statuses.\n\n*Note: when sending multiple messages in a request, all messages must be valid for the request \nto be successful. If any messages in the request are invalid, no messages will be sent.*\n", "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();\nbody.Messages = new List();\n\nMessage body_messages_0 = new Message();\nbody_messages_0.CallbackUrl = \"https://my.callback.url.com\";\nbody_messages_0.Content = \"My first message\";\nbody_messages_0.DestinationNumber = \"+61491570156\";\nbody_messages_0.DeliveryReport = true;\nbody_messages_0.Format = Format.SMS;\nbody_messages_0.MessageExpiryTimestamp = DateTime.Parse(\"2016-11-03T11:49:02.807Z\");\nbody_messages_0.Metadata = APIHelper.JsonDeserialize(\"{\\\"key1\\\":\\\"value1\\\",\\\"key2\\\":\\\"value2\\\"}\");\nbody_messages_0.Scheduled = DateTime.Parse(\"2016-11-03T11:49:02.807Z\");\nbody_messages_0.SourceNumber = \"+61491570157\";\nbody_messages_0.SourceNumberType = SourceNumberType.INTERNATIONAL;\nbody.Messages.Add(body_messages_0);\n\nMessage body_messages_1 = new Message();\nbody_messages_1.CallbackUrl = \"https://my.callback.url.com\";\nbody_messages_1.Content = \"My second message\";\nbody_messages_1.DestinationNumber = \"+61491570158\";\nbody_messages_1.DeliveryReport = true;\nbody_messages_1.Format = Format.MMS;\nbody_messages_1.MessageExpiryTimestamp = DateTime.Parse(\"2016-11-03T11:49:02.807Z\");\nbody_messages_1.Metadata = APIHelper.JsonDeserialize(\"{\\\"key1\\\":\\\"value1\\\",\\\"key2\\\":\\\"value2\\\"}\");\nbody_messages_1.Scheduled = DateTime.Parse(\"2016-11-03T11:49:02.807Z\");\nbody_messages_1.SourceNumber = \"+61491570159\";\nbody_messages_1.SourceNumberType = SourceNumberType.INTERNATIONAL;\nbody_messages_1.Media = new List();\nbody_messages_1.Media.Add(\"https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg\");\nbody_messages_1.Subject = \"This is an MMS message\";\nbody.Messages.Add(body_messages_1);\n\n\ntry \n{\n SendMessagesResponse result = messages.SendMessagesAsync(body).Result;\n}\ncatch (APIException e){};" }, { "lang": "Java", "label": "Java", "source": "SendMessagesRequest body = new SendMessagesRequest();\nbody.setMessages(new LinkedList());\n\nMessage body_messages_0 = new Message();\nbody_messages_0.setCallbackUrl(\"https://my.callback.url.com\");\nbody_messages_0.setContent(\"My first message\");\nbody_messages_0.setDestinationNumber(\"+61491570156\");\nbody_messages_0.setDeliveryReport(true);\nbody_messages_0.setFormat(FormatEnum.SMS);\nbody_messages_0.setMessageExpiryTimestamp(new DateTime(\"2016-11-03T11:49:02.807Z\", DateTimeZone.UTC));\nbody_messages_0.setMetadata(com.messagemedia.messages.APIHelper.deserialize(\"{\\\"key1\\\":\\\"value1\\\",\\\"key2\\\":\\\"value2\\\"}\"));\nbody_messages_0.setScheduled(new DateTime(\"2016-11-03T11:49:02.807Z\", DateTimeZone.UTC));\nbody_messages_0.setSourceNumber(\"+61491570157\");\nbody_messages_0.setSourceNumberType(SourceNumberTypeEnum.INTERNATIONAL);\nbody.getMessages().add(body_messages_0);\n\nMessage body_messages_1 = new Message();\nbody_messages_1.setCallbackUrl(\"https://my.callback.url.com\");\nbody_messages_1.setContent(\"My second message\");\nbody_messages_1.setDestinationNumber(\"+61491570158\");\nbody_messages_1.setDeliveryReport(true);\nbody_messages_1.setFormat(FormatEnum.MMS);\nbody_messages_1.setMessageExpiryTimestamp(new DateTime(\"2016-11-03T11:49:02.807Z\", DateTimeZone.UTC));\nbody_messages_1.setMetadata(com.messagemedia.messages.APIHelper.deserialize(\"{\\\"key1\\\":\\\"value1\\\",\\\"key2\\\":\\\"value2\\\"}\"));\nbody_messages_1.setScheduled(new DateTime(\"2016-11-03T11:49:02.807Z\", DateTimeZone.UTC));\nbody_messages_1.setSourceNumber(\"+61491570159\");\nbody_messages_1.setSourceNumberType(SourceNumberTypeEnum.INTERNATIONAL);\nbody_messages_1.setMedia(new LinkedList());\nbody_messages_1.getMedia().add(\"https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg\");\nbody_messages_1.setSubject(\"This is an MMS message\");\nbody.getMessages().add(body_messages_1);\n\n\nmessagesController.sendMessagesAsync(body, new APICallBack() {\n public void onSuccess(HttpContext context, SendMessagesResponse response) {\n // TODO success callback handler\n }\n public void onFailure(HttpContext context, Throwable error) {\n // TODO failure callback handler\n }\n});\n" }, { "lang": "JavaScript", "label": "JavaScript", "source": "let body = new lib.SendMessagesRequest();\nbody.messages = [];\n\nbody.messages[0] = new lib.Message();\nbody.messages[0].callbackUrl = 'https://my.callback.url.com';\nbody.messages[0].content = 'My first message';\nbody.messages[0].destinationNumber = '+61491570156';\nbody.messages[0].deliveryReport = true;\nbody.messages[0].format = lib.FormatEnum.SMS;\nbody.messages[0].messageExpiryTimestamp = moment('2016-11-03T11:49:02.807Z').parseZone('2016-11-03T11:49:02.807Z');\nbody.messages[0].metadata = JSON.parse('{\"key1\":\"value1\",\"key2\":\"value2\"}');\nbody.messages[0].scheduled = moment('2016-11-03T11:49:02.807Z').parseZone('2016-11-03T11:49:02.807Z');\nbody.messages[0].sourceNumber = '+61491570157';\nbody.messages[0].sourceNumberType = lib.SourceNumberTypeEnum.INTERNATIONAL;\n\nbody.messages[1] = new lib.Message();\nbody.messages[1].callbackUrl = 'https://my.callback.url.com';\nbody.messages[1].content = 'My second message';\nbody.messages[1].destinationNumber = '+61491570158';\nbody.messages[1].deliveryReport = true;\nbody.messages[1].format = lib.FormatEnum.MMS;\nbody.messages[1].messageExpiryTimestamp = moment('2016-11-03T11:49:02.807Z').parseZone('2016-11-03T11:49:02.807Z');\nbody.messages[1].metadata = JSON.parse('{\"key1\":\"value1\",\"key2\":\"value2\"}');\nbody.messages[1].scheduled = moment('2016-11-03T11:49:02.807Z').parseZone('2016-11-03T11:49:02.807Z');\nbody.messages[1].sourceNumber = '+61491570159';\nbody.messages[1].sourceNumberType = lib.SourceNumberTypeEnum.INTERNATIONAL;\nbody.messages[1].media = ['https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg'];\nbody.messages[1].subject = 'This is an MMS message';\n\n\nconst promise = controller.sendMessages(body);\npromise.then((response) => {\n // this block will be executed on successful endpoint call\n // `response` will be of type 'SendMessagesResponse'\n}, (err) => {\n // this block will be executed on endpoint call failure\n // `err` is an 'object' containing more information about the error\n});" }, { "lang": "PHP", "label": "PHP", "source": "$body = new Models\\SendMessagesRequest;\n$body->messages = array();\n\n$body->messages[0] = new Models\\Message;\n$body->messages[0]->callbackUrl = 'https://my.callback.url.com';\n$body->messages[0]->content = 'My first message';\n$body->messages[0]->destinationNumber = '+61491570156';\n$body->messages[0]->deliveryReport = true;\n$body->messages[0]->format = Models\\FormatEnum::SMS;\n$body->messages[0]->messageExpiryTimestamp = DateTimeHelper::fromRfc3339DateTime('2016-11-03T11:49:02.807Z');\n$body->messages[0]->metadata = MessageMediaMessagesLib\\APIHelper::deserialize('{\"key1\":\"value1\",\"key2\":\"value2\"}');\n$body->messages[0]->scheduled = DateTimeHelper::fromRfc3339DateTime('2016-11-03T11:49:02.807Z');\n$body->messages[0]->sourceNumber = '+61491570157';\n$body->messages[0]->sourceNumberType = Models\\SourceNumberTypeEnum::INTERNATIONAL;\n\n$body->messages[1] = new Models\\Message;\n$body->messages[1]->callbackUrl = 'https://my.callback.url.com';\n$body->messages[1]->content = 'My second message';\n$body->messages[1]->destinationNumber = '+61491570158';\n$body->messages[1]->deliveryReport = true;\n$body->messages[1]->format = Models\\FormatEnum::MMS;\n$body->messages[1]->messageExpiryTimestamp = DateTimeHelper::fromRfc3339DateTime('2016-11-03T11:49:02.807Z');\n$body->messages[1]->metadata = MessageMediaMessagesLib\\APIHelper::deserialize('{\"key1\":\"value1\",\"key2\":\"value2\"}');\n$body->messages[1]->scheduled = DateTimeHelper::fromRfc3339DateTime('2016-11-03T11:49:02.807Z');\n$body->messages[1]->sourceNumber = '+61491570159';\n$body->messages[1]->sourceNumberType = Models\\SourceNumberTypeEnum::INTERNATIONAL;\n$body->messages[1]->media = array('https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg');\n$body->messages[1]->subject = 'This is an MMS message';\n\n\n$result = $messagesController->sendMessages($body);" }, { "lang": "Python", "label": "Python", "source": "body = SendMessagesRequest()\nbody.messages = []\n\nbody.messages.append(Message())\nbody.messages[0].callback_url = 'https://my.callback.url.com'\nbody.messages[0].content = 'My first message'\nbody.messages[0].destination_number = '+61491570156'\nbody.messages[0].delivery_report = True\nbody.messages[0].format = FormatEnum.SMS\nbody.messages[0].message_expiry_timestamp = dateutil.parser.parse('2016-11-03T11:49:02.807Z')\nbody.messages[0].metadata = jsonpickle.decode('{\"key1\":\"value1\",\"key2\":\"value2\"}')\nbody.messages[0].scheduled = dateutil.parser.parse('2016-11-03T11:49:02.807Z')\nbody.messages[0].source_number = '+61491570157'\nbody.messages[0].source_number_type = SourceNumberTypeEnum.INTERNATIONAL\n\nbody.messages.append(Message())\nbody.messages[1].callback_url = 'https://my.callback.url.com'\nbody.messages[1].content = 'My second message'\nbody.messages[1].destination_number = '+61491570158'\nbody.messages[1].delivery_report = True\nbody.messages[1].format = FormatEnum.MMS\nbody.messages[1].message_expiry_timestamp = dateutil.parser.parse('2016-11-03T11:49:02.807Z')\nbody.messages[1].metadata = jsonpickle.decode('{\"key1\":\"value1\",\"key2\":\"value2\"}')\nbody.messages[1].scheduled = dateutil.parser.parse('2016-11-03T11:49:02.807Z')\nbody.messages[1].source_number = '+61491570159'\nbody.messages[1].source_number_type = SourceNumberTypeEnum.INTERNATIONAL\nbody.messages[1].media = ['https://images.pexels.com/photos/1018350/pexels-photo-1018350.jpeg?cs=srgb&dl=architecture-buildings-city-1018350.jpg']\nbody.messages[1].subject = 'This is an MMS message'\n\n\nresult = 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:\n | Sender ID | sender_address_type | usage_type |\n |--- |--- |--- |\n | Alpha tag | `ALPHANUMERIC` | `ALPHANUMERIC` |\n | Personal number | `INTERNATIONAL` | `OWN_NUMBER` | \n\nThe other parameters required for your request will depend on the type of Sender ID you are registering.\n\n### Sender ID is an Alpha Tag\nThe following parameters are used when registering an alpha tag as a Sender ID:\n - ```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.\n - ```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.\n - ```sender_address_type:``` **(Required)**. For alpha tags this is always ALPHANUMERIC\n - ```usage_type:``` **(Required)**. For alpha tags this is always ALPHANUMERIC\n - ```label:``` **(Optional)**. A reference name for the sender ID to allow you to easily track it.\n - ```reason:``` **(Required)**. This is a specifically formatted string made up of the following sub-items (all of which are required):\n\n - `useCase:` one of the following:\n - `SOLE_TRADER_NAME`\n - `COMPANY_NAME`\n - `PARTNERSHIP_NAME`\n - `REGISTERED_TRUST_NAME`\n - `CO_OPERATIVE_NAME`\n - `INDIGENOUS_CORPORATION_NAME`\n - `REGISTERED_ORGANISATION_NAME`\n - `PERSONAL_NAME`\n - `AUSTRALIAN_TRADEMARK`\n - `INTERNATIONAL_TRADEMARK`\n - `AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY`\n - `FOREIGN_GOVERNMENT_AGENCY_OR_ENTITY`\n - `PRODUCT_OR_SERVICE_NAME`\n - `ACRONYM_INITIALISM`\n - `CONTRACTION_OF_NAME`\n - `OTHER`\n - `description:` A description used if OTHER was selected as the use case. Limited to 200 characters.\n\n - `email:` The preferred contact email for our approval team when additional details are required.\n\n - `australianGovernmentAgencyOrEntityName:` The name of your organisation.\n\n - `abn:` Your organisation’s Australian Business Number\n\n - `statement:` A legal declaration\n - If applying for your own business: \"We are authorized to use the Sender ID with a valid use case.\"\n - 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.\"\n\nThe reason parameter must contain all the above items. A well formatted reason looks like the following:\n - \"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\"\n\n### Sender ID is a Personal Number\nThe following parameters are used when registering a personal mobile phone number as a Sender ID: \n\n - ```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. \n\n - ```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. \n\n - ```sender_address_type:``` **(Required)**. For personal numbers this is always INTERNATIONAL \n\n - ```usage_type:``` **(Required)**. For personal numbers this is always OWN_NUMBER \n\n - ```label:``` **(Optional)**. A reference name for the sender ID to allow you to easily track it. \n\n - ```Reason:``` **(Required)**. A string describing why you wish to register the number as a Sender ID. Limited to 200 characters.\n", "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": "{\n \"useCase\":\"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY\",\n \"description\":\"bal bla\",\n \"email\":\"xample@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", "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": "{\n \"useCase\":\"AUSTRALIAN_GOVERNMENT_AGENCY_OR_ENTITY\",\n \"description\":\"bal bla\",\n \"email\":\"xample@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", "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.\nThe following parameters are required for this request:\n - ```id:``` The UUID received in the API response of your request to the **Request a Sender Address** endpoint.\n - ```verification_code:``` The six-digit code received via SMS to the phone number that you are attempting to register\n", "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\n\n| Description | sender_address_type | usage_type |\n| ---------------- | ------------------- | ------------ |\n| Own Number | INTERNATIONAL | OWN_NUMBER |\n\nOWN_NUMBER Sender Addresses require reverification every 12 months to allow continued use.\nThe reverification process is quite similar to the original verification process for the Sender Address, and requires a fresh 2FA check.\n\nTo reverify an OWN_NUMBER Sender Address:\n 1. Retrieve the UUID for the OWN_NUMBER using the **Get all approved sender addresses** endpoint\n 2. Make a request to this endpoint to trigger the 2FA check\n 3. Make a POST request to the **Submit verification code endpoint**, providing the new 2FA code in the body of the request\n", "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.\nA successful request to the get message status endpoint will return a response body as follows:\n```javascript\n{\n \"id\": \"365dd65f-7101-46cd-8e79-e49c5620eb15\",\n \"sender_address\": \"sample\",\n \"sender_address_type\": \"ALPHANUMERIC\",\n \"usage_type\": \"ALPHANUMERIC\",\n \"destination_countries\": [\n \"AU\"\n ],\n \"reason\": \"This is my approval reason\",\n \"label\": \"label\"\n \"status\": \"APPROVED\",\n \"account_id\": \"sample\",\n \"created_date\": \"2023-09-07T05:48:26.741Z\",\n \"last_modified_date\": \"2023-09-07T05:49:20.888Z\"\n}\n```\n", "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.\n", "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.\n", "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.\nAcceptable values are EXPIRED and EXPIRING. This parameter requires both the sender_address_type and usage_type parameters to be present.\n", "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\n", "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.\n", "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.\n", "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.\nDelivery reports are a notification of the change in status of a message as it is being processed.\nEach request to the check delivery reports endpoint will return any delivery reports received that\nhave not yet been confirmed using the confirm delivery reports endpoint. A response from the check\ndelivery reports endpoint will have the following structure:\n```javascript\n{\n \"delivery_reports\": [\n {\n \"callback_url\": \"https://my.callback.url.com\",\n \"delivery_report_id\": \"01e1fa0a-6e27-4945-9cdb-18644b4de043\",\n \"source_number\": \"+61491570157\",\n \"date_received\": \"2017-05-20T06:30:37.642Z\",\n \"status\": \"enroute\",\n \"delay\": 0,\n \"billing_units\": 1,\n \"submitted_date\": \"2017-05-20T06:30:37.639Z\",\n \"original_text\": \"My first message!\",\n \"message_id\": \"d781dcab-d9d8-4fb2-9e03-872f07ae94ba\",\n \"vendor_account_id\": {\n \"vendor_id\": \"SinchEU\",\n \"account_id\": \"MyAccount\"\n },\n \"metadata\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\"\n }\n },\n {\n \"callback_url\": \"https://my.callback.url.com\",\n \"delivery_report_id\": \"0edf9022-7ccc-43e6-acab-480e93e98c1b\",\n \"source_number\": \"+61491570158\",\n \"date_received\": \"2017-05-21T01:46:42.579Z\",\n \"status\": \"enroute\",\n \"delay\": 0,\n \"billing_units\": 1,\n \"submitted_date\": \"2017-05-21T01:46:42.574Z\",\n \"original_text\": \"My second message!\",\n \"message_id\": \"fbb3b3f5-b702-4d8b-ab44-65b2ee39a281\",\n \"vendor_account_id\": {\n \"vendor_id\": \"SinchEU\",\n \"account_id\": \"MyAccount\"\n },\n \"metadata\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\"\n }\n }\n ]\n}\n```\nEach delivery report will contain details about the message, including any metadata specified\nand the new status of the message (as each delivery report indicates a change in status of a\nmessage) and the timestamp at which the status changed. Every delivery report will have a \nunique delivery report ID for use with the confirm delivery reports endpoint.\n*Note: The source number and destination number properties in a delivery report are the inverse of\nthose specified in the message that the delivery report relates to. The source number of the\ndelivery report is the destination number of the original message.*\nSubsequent requests to the check delivery reports endpoint will return the same delivery reports\nand a maximum of 100 delivery reports will be returned in each request. Applications should use the\nconfirm delivery reports endpoint in the following pattern so that delivery reports that have been\nprocessed are no longer returned in subsequent check delivery reports requests. The expiry date for getting an entity is 45 days.\n1. Call check delivery reports endpoint\n2. Process each delivery report\n3. Confirm all processed delivery reports using the confirm delivery reports endpoint\n*Note: It is recommended to use the Webhooks feature to receive reply messages rather than\npolling 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() {\n public void onSuccess(HttpContext context, CheckDeliveryReportsResponse response) {\n // TODO success callback handler\n }\n public void onFailure(HttpContext context, Throwable error) {\n // TODO failure callback handler\n }\n});" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const promise = controller.checkDeliveryReports();\npromise.then((response) => {\n // this block will be executed on successful endpoint call\n // `response` will be of type 'CheckDeliveryReportsResponse'\n}, (err) => {\n // this block will be executed on endpoint call failure\n // `err` is an 'object' containing more information about the error\n});" }, { "lang": "PHP", "label": "PHP", "source": "$result = $deliveryReportsController->checkDeliveryReports();" }, { "lang": "Python", "label": "Python", "source": "result = delivery_reports_controller.check_delivery_reports()\n" } ] } }, "/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.\nThe confirm delivery reports endpoint is intended to be used in conjunction with the check delivery\nreports endpoint to allow for robust processing of delivery reports. Once one or more delivery\nreports have been processed, they can then be confirmed using the confirm delivery reports endpoint so they\nare no longer returned in subsequent check delivery reports requests.\nThe confirm delivery reports endpoint takes a list of delivery report IDs as follows:\n```javascript\n{\n \"delivery_report_ids\": [\n \"011dcead-6988-4ad6-a1c7-6b6c68ea628d\",\n \"3487b3fa-6586-4979-a233-2d1b095c7718\",\n \"ba28e94b-c83d-4759-98e7-ff9c7edb87a1\"\n ]\n}\n```\nThe 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();\nbody.setDeliveryReportIds(new LinkedList());\nbody.getDeliveryReportIds().add(\"011dcead-6988-4ad6-a1c7-6b6c68ea628d\");\nbody.getDeliveryReportIds().add(\"3487b3fa-6586-4979-a233-2d1b095c7718\");\nbody.getDeliveryReportIds().add(\"ba28e94b-c83d-4759-98e7-ff9c7edb87a1\");\n\ndeliveryReportsController.confirmDeliveryReportsAsReceivedAsync(body, new APICallBack() {\n public void onSuccess(HttpContext context, DynamicResponse response) {\n // TODO success callback handler\n }\n public void onFailure(HttpContext context, Throwable error) {\n // TODO failure callback handler\n }\n});" }, { "lang": "JavaScript", "label": "JavaScript", "source": "let body = new lib.ConfirmDeliveryReportsAsReceivedRequest();\nbody.deliveryReportIds = ['011dcead-6988-4ad6-a1c7-6b6c68ea628d', '3487b3fa-6586-4979-a233-2d1b095c7718', 'ba28e94b-c83d-4759-98e7-ff9c7edb87a1'];\n\nconst promise = controller.confirmDeliveryReportsAsReceived(body);\npromise.then((response) => {\n // this block will be executed on successful endpoint call\n // `response` will be of type 'mixed'\n}, (err) => {\n // this block will be executed on endpoint call failure\n // `err` is an 'object' containing more information about the error\n});" }, { "lang": "PHP", "label": "PHP", "source": "$body = new Models\\ConfirmDeliveryReportsAsReceivedRequest;\n$body->deliveryReportIds = array('011dcead-6988-4ad6-a1c7-6b6c68ea628d', '3487b3fa-6586-4979-a233-2d1b095c7718', 'ba28e94b-c83d-4759-98e7-ff9c7edb87a1');\n\n$result = $deliveryReportsController->confirmDeliveryReportsAsReceived($body);" }, { "lang": "Python", "label": "Python", "source": "body = ConfirmDeliveryReportsAsReceivedRequest()\nbody.delivery_report_ids = ['011dcead-6988-4ad6-a1c7-6b6c68ea628d', '3487b3fa-6586-4979-a233-2d1b095c7718', 'ba28e94b-c83d-4759-98e7-ff9c7edb87a1']\n\nresult = 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.\nReplies are messages that have been sent from a handset in response to a message sent by an\napplication or messages that have been sent from a handset to a inbound number associated with\nan account, known as a dedicated inbound number (contact for more\ninformation on dedicated inbound numbers).\nEach request to the check replies endpoint will return any replies received that have not yet\nbeen confirmed using the confirm replies endpoint. A response from the check replies endpoint\nwill have the following structure:\n```javascript\n{\n \"replies\": [\n {\n \"metadata\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\"\n },\n \"message_id\": \"877c19ef-fa2e-4cec-827a-e1df9b5509f7\",\n \"reply_id\": \"a175e797-2b54-468b-9850-41a3eab32f74\",\n \"date_received\": \"2016-12-07T08:43:00.850Z\",\n \"callback_url\": \"https://my.callback.url.com\",\n \"destination_number\": \"+61491570156\",\n \"source_number\": \"+61491570157\",\n \"vendor_account_id\": {\n \"vendor_id\": \"SinchEU\",\n \"account_id\": \"MyAccount\"\n },\n \"content\": \"My first reply!\"\n },\n {\n \"metadata\": {\n \"key1\": \"value1\",\n \"key2\": \"value2\"\n },\n \"message_id\": \"8f2f5927-2e16-4f1c-bd43-47dbe2a77ae4\",\n \"reply_id\": \"3d8d53d8-01d3-45dd-8cfa-4dfc81600f7f\",\n \"date_received\": \"2016-12-07T08:43:00.850Z\",\n \"callback_url\": \"https://my.callback.url.com\",\n \"destination_number\": \"+61491570157\",\n \"source_number\": \"+61491570158\",\n \"vendor_account_id\": {\n \"vendor_id\": \"SinchEU\",\n \"account_id\": \"MyAccount\"\n },\n \"content\": \"My second reply!\"\n }\n ]\n}\n```\nEach reply will contain details about the reply message, as well as details of the message the reply was sent\nin response to, including any metadata specified. Every reply will have a reply ID to be used with the\nconfirm replies endpoint.\n*Note: The source number and destination number properties in a reply are the inverse of those\nspecified in the message the reply is in response to. The source number of the reply message is the\nsame as the destination number of the original message, and the destination number of the reply\nmessage is the same as the source number of the original message. If a source number\nwasn't specified in the original message, then the destination number property will not be present\nin the reply message.*\nSubsequent requests to the check replies endpoint will return the same reply messages and a maximum\nof 100 replies will be returned in each request. Applications should use the confirm replies endpoint\nin the following pattern so that replies that have been processed are no longer returned in\nsubsequent check replies requests. The expiry date for getting an entity is 45 days.\n1. Call check replies endpoint\n2. Process each reply message\n3. Confirm all processed reply messages using the confirm replies endpoint\n*Note: It is recommended to use the Webhooks feature to receive reply messages rather than polling\nthe 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() {\n public void onSuccess(HttpContext context, CheckRepliesResponse response) {\n // TODO success callback handler\n }\n public void onFailure(HttpContext context, Throwable error) {\n // TODO failure callback handler\n }\n});" }, { "lang": "JavaScript", "label": "JavaScript", "source": "const promise = controller.checkReplies();\npromise.then((response) => {\n // this block will be executed on successful endpoint call\n // `response` will be of type 'CheckRepliesResponse'\n}, (err) => {\n // this block will be executed on endpoint call failure\n // `err` is an 'object' containing more information about the error\n});" }, { "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.\nThe confirm replies endpoint is intended to be used in conjunction with the check replies endpoint\nto allow for robust processing of reply messages. Once one or more reply messages have been processed\nthey can then be confirmed using the confirm replies endpoint so they are no longer returned in\nsubsequent check replies requests.\nThe confirm replies endpoint takes a list of reply IDs as follows:\n```javascript\n{\n \"reply_ids\": [\n \"011dcead-6988-4ad6-a1c7-6b6c68ea628d\",\n \"3487b3fa-6586-4979-a233-2d1b095c7718\",\n \"ba28e94b-c83d-4759-98e7-ff9c7edb87a1\"\n ]\n}\n```\nThe 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();\nbody.setReplyIds(new LinkedList());\nbody.getReplyIds().add(\"011dcead-6988-4ad6-a1c7-6b6c68ea628d\");\nbody.getReplyIds().add(\"3487b3fa-6586-4979-a233-2d1b095c7718\");\nbody.getReplyIds().add(\"ba28e94b-c83d-4759-98e7-ff9c7edb87a1\");\n\nrepliesController.confirmRepliesAsReceivedAsync(body, new APICallBack() {\n public void onSuccess(HttpContext context, DynamicResponse response) {\n // TODO success callback handler\n }\n public void onFailure(HttpContext context, Throwable error) {\n // TODO failure callback handler\n }\n});" }, { "lang": "JavaScript", "label": "JavaScript", "source": "let body = new lib.ConfirmRepliesAsReceivedRequest();\nbody.replyIds = ['011dcead-6988-4ad6-a1c7-6b6c68ea628d', '3487b3fa-6586-4979-a233-2d1b095c7718', 'ba28e94b-c83d-4759-98e7-ff9c7edb87a1'];\n\nconst promise = controller.confirmRepliesAsReceived(body);\npromise.then((response) => {\n // this block will be executed on successful endpoint call\n // `response` will be of type 'mixed'\n}, (err) => {\n // this block will be executed on endpoint call failure\n // `err` is an 'object' containing more information about the error\n});" }, { "lang": "PHP", "label": "PHP", "source": "$body = new Models\\ConfirmRepliesAsReceivedRequest;\n$body->replyIds = array('011dcead-6988-4ad6-a1c7-6b6c68ea628d', '3487b3fa-6586-4979-a233-2d1b095c7718', 'ba28e94b-c83d-4759-98e7-ff9c7edb87a1');\n\n$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\n\nIn 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.\n", "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.\nNOTE: 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.\nIn the example +61491570157 will be removed from the blacklist.\nNOTE: 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.\nIn the example given +61491570157 is on the blacklist.\nNOTE: 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. \nUse the body of the request to specify a label or metadata \nfor this number assignment.\n\nIf you receive a *conflict* error then the number that you have selected is unavailable for assignment. \nThis means that the number is either already assigned to another account, \nor has an available_after date in the future. Should this occur, perform \nanother 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.\nA successful request to the retrieve webhook endpoint will return a response body as follows:\n\n```\n{\n \"page\": 0,\n \"pageSize\": 100,\n \"pageData\": [\n {\n \"id\": \"76fa7010-8c1f-4a24-917a-4d62a54e744d\",\n \"url\": \"http://webhook.com\",\n \"method\": \"POST\",\n \"encoding\": \"JSON\",\n \"headers\": {},\n \"events\": [\n \"ENROUTE_DR\",\n \"DELIVERED_DR\"\n ],\n \"template\": \"{\\\"id\\\":\\\"$mtId\\\",\\\"status\\\":\\\"$statusCode\\\"}\",\n \"read_timeout\": 5000,\n \"retries\": 3,\n \"retry_delay\": 30\n }\n ]\n}\n```\n\n*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.\n\nA webhook would typically have the following structure:\n\n```\n{\n \"url\": \"http://webhook.com\",\n \"method\": \"POST\",\n \"encoding\": \"JSON\",\n \"headers\": {},\n \"events\": [\n \"ENROUTE_DR\",\n \"DELIVERED_DR\"\n ],\n \"template\": \"{\\\"id\\\":\\\"$mtId\\\",\\\"status\\\":\\\"$statusCode\\\"}\",\n \"read_timeout\": 5000,\n \"retries\": 3,\n \"retry_delay\": 30\n}\n```\n\nA valid webhook must consist of the following properties:\n\n- ```url``` The configured URL which will trigger the webhook when a selected event occurs.\n\n- ```method``` The methods to map CRUD (create, retrieve, update, delete) operations to HTTP requests.\n\n- ```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.\n\n- ```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.\n\n- ```events``` Event or events that will trigger the webhook. At least one event should be present.\n\n- ```template``` The structure of the payload that will be returned. You can format this in JSON or XML.\n\n- ```read_timeout``` (Optional) The read timeout for the call to the Webhook in milliseconds. Set to 20000 by default, max 60000.\n\n- ```retries``` (Optional) The read timeout for the call to the Webhook in milliseconds. Set to 20000 by default, max 60000.\n\n- ```retry_delay``` (Optional) The delay period between retries in seconds. Minimum of 5, max 60.\n\n\n\n\n#### Types of Events\n\nYou 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.\n\nA webhook will be triggered when any one or more of the events occur:\n\n+ **SMS** \n + `RECEIVED_SMS` Receive an SMS\n + `OPT_OUT_SMS` Opt-out occurred\n+ **MMS**\n + `RECEIVED_MMS` Receive an MMS\n+ **DR (Delivery Reports)**\n + `ENROUTE_DR` Message is enroute\n + `EXPIRED_DR` Message has expired\n + `REJECTED_DR` Message is rejected\n + `FAILED_DR` Message has failed\n + `DELIVERED_DR` Message is delivered\n + `SUBMITTED_DR` Message is submitted\n\n#### Template Parameters\n\nYou 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.\n\nKeep in mind, if you've chosen JSON as the format, you must escape the JSON in the template value (see example above).\n\nThe table illustrates a list of all the parameters that can be included in the template and which event types it can be applied to.\n\n| Data | Parameter Name | Example | Event Type |\n|:--|--|--|--:|\n| **Service Type** | $format, $type *- `$type` will be deprecated in the future; use `$format` instead*| `SMS` | `DR` `MO` `MO MMS` |\n| **Message ID** | $mtId, $messageId| `877c19ef-fa2e-4cec-827a-e1df9b5509f7` | `DR` `MO` `MO MMS`|\n| **Delivery Report ID** |$drId, $reportId| `01e1fa0a-6e27-4945-9cdb-18644b4de043` | `DR` |\n| **Reply ID**| $moId, $replyId| `a175e797-2b54-468b-9850-41a3eab32f74` | `MO` `MO MMS` |\n| **Account ID** | $accountId| `DeveloperPortal7000` | `DR` `MO` `MO MMS` |\n| **Message Timestamp** | $submittedTimestamp| `2016-12-07T08:43:00.850Z` | `DR` `MO` `MO MMS` |\n| **Provider Timestamp** | $receivedTimestamp| `2016-12-07T08:44:00.850Z` | `DR` `MO` `MO MMS` |\n| **Message Status** | $status| `enroute` | `DR` |\\n| **Status Code** | $statusCode| `200` | `DR` |\n| **External Metadata** | $metadata.get('key')| `name` | `DR` `MO` `MO MMS` |\n| **Source Address**| $sourceAddress| `+61491570156` | `DR` `MO` `MO MMS` |\n| **Destination Address**| $destinationAddress| `+61491593156` | `MO` `MO MMS` |\n| **Message Content**| $mtContent, $messageContent, $esc.json($!mtContent) *- when used in `JSON` encoded `template`*| `Hi Derp` | `DR` `MO` `MO MMS` |\n| **Reply Content**| $moContent, $replyContent, $esc.json($!moContent) *- when used in `JSON` encoded `template`*| `Hello Derpina` | `MO` `MO MMS` |\n| **Retry Count**| $retryCount| `1` | `DR` `MO` `MO MMS` |\n| **Billing Unit**| $billingUnits| `1` | `DR` |\n| **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` |\n\n#### Example Webhook Request with Templates\n\n##### MO / MO MMS\n\n```\n{\n \"url\": \"http://webhook.com\",\n \"method\": \"POST\",\n \"encoding\": \"JSON\",\n \"events\": [\"RECEIVED_MMS\"],\n \"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 }}\"\n}\n```\n\n##### DR (Delivery Report)\n\n```\n{\n \"url\": \"http://webhook.com\",\n \"method\": \"POST\",\n \"encoding\": \"JSON\",\n \"events\": [\"DELIVERED_DR\"],\n \"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 }}\"\n}\n```\n\n #### Message Statuses\n\nDelivery Reports indicate message status. A message can have one of the following statuses:\n* `enroute`: Message has been received by the gateway and is being processed (or waiting to be processed).\n* `submitted`: Message has been submitted to a provider/carrier for delivery.\n* `delivered`: Message delivery has been confirmed by the provider, including to the handset (where possible).\n* `expired`: The message has expired.\n* `rejected`: The message will not be delivered - permanent failure. Reasons may include usage limit exceeded, insufficient credit, number blocked, or content filtered\n* `failed`: The message has failed. Reasons may include no active routes to destination or undeliverable by downstream provider.\n\n#### Message Status Codes\nStatus codes provide more granular insight into a message's status. A message can have one of the following status codes:\n* `101`: Message being processed by the gateway.\n* `102`: Message is being rerouted to a different provider after failing via the first provider.\n* `151`: Message held for screening.\n* `200`: Message submitted to downstream provider for delivery.\n* `210`: Message accepted by downstream provider.\n* `211`: Message is enroute for delivery by provider.\n* `212`: Message submitted. Delivery pending.\n* `213`: Message scheduled for delivery by downstream provider.\n* `220`: Message delivered.\n* `221`: Message delivered to the handset.\n* `320`: Message validity period has expired (prior to submission).\n* `401`: Message validity period has expired (before delivery).\n* `301`: Usage threshold reached. Message discarded.\n* `302`: Destination address blocked. Message discarded.\n* `303`: Source address blocked. Message discarded.\n* `304`: Message dropped. Contact support.\n* `305`: Message discarded due to duplicate detection.\n* `402`: Message rejected by downstream provider.\n* `403`: Message skipped by downstream provider.\n* `410`: Invalid source address.\n* `411`: Invalid destination address.\n* `412`: Destination address blocked.\n* `413`: SMS service unavailable on destination.\n* `414`: Destination unreachable.\n* `330`: Gateway failure.\n* `331`: Message discarded.\n* `332`: No available route to destination.\n* `333`: Source address unsupported for this destination.\n* `400`: Message failed; undeliverable.\n* `405`: Message cancelled or deleted by provider.\n\n*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.*\n", "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.\nA webhook can be cancelled by appending the UUID of the webhook to the endpoint and submitting a DELETE request to the /webhooks/messages endpoint.\n\nA successful request to the retrieve webhook endpoint will return a null response.\n\n*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).\n\nAll 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.\n\nA successful request to the update webhook endpoint will return a response body as follows:\n\n```\n{\n \"id\": \"76fa7010-8c1f-4a24-917a-4d62a54e744d\",\n \"url\": \"http://webhook.com\",\n \"method\": \"POST\",\n \"encoding\": \"JSON\",\n \"headers\": {},\n \"events\": [\n \"ENROUTE_DR\",\n \"DELIVERED_DR\"\n ],\n \"template\": \"{\\\"id\\\":\\\"$mtId\\\",\\\"status\\\":\\\"$statusCode\\\"}\",\n \"read_timeout\": 5000,\n \"retries\": 3,\n \"retry_delay\": 30\n}\n```\n\n*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.\n\nA successful request for the ```get signature key list``` endpoint will return a response body as follows:\n\n```javascript\n[\n {\n \"key_id\": \"7ca628a8-08b0-4e42-aeb8-960b37049c31\",\n \"cipher\": \"RSA\",\n \"digest\": \"SHA224\",\n \"created\": \"2018-01-18T10:16:12.364Z\",\n \"enabled\": false\n }\n]\n```", "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:\n\n- The ```private key``` stored in Sinch is used to create the signature.\n\n- The ```public key``` is returned and stored at your side to verify the signature in webhooks.\n\nYou need to enable your signature key after creating.\n\nThe most basic body has the following structure:\n\n```javascript\n{\n \"digest\": \"SHA224\",\n \"cipher\": \"RSA\"\n}\n```\n\n- ```digest``` is used to hash the message. The valid values for digest type are: SHA224, SHA256, SHA512\n\n- ```cipher``` is used to encrypt the hashed message. The valid value for cipher type is: RSA\n\nA successful request for the ```create signature key``` endpoint will return a response body as follows:\n\n```javascript\n{\n \"key_id\": \"7ca628a8-08b0-4e42-aeb8-960b37049c31\",\n \"public_key\": \"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCTIxtRyT5CuOD74r7UCT+AKzWNxvaAP9myjAqR7+vBnJKEvoPnmbKTnm6uLlxutnMbjKrnCCWnQ9vtBVnnd+ElhwLDPADfMcJoOqwi7mTcxucckeEbBsfsgYRfdacxgSZL8hVD1hLViQr3xwjEIkJcx1w3x8npvwMuTY0uW8+PjwIDAQAB\",\n \"cipher\": \"RSA\",\n \"digest\": \"SHA224\",\n \"created\": \"2018-01-18T10:16:12.364Z\",\n \"enabled\": false\n}\n```\n\nThe response body of a successful POST request to the ```create signature key``` endpoint will contain six properties:\n\n- ```key_id``` will be a 36 character UUID which can be used to enable, delete or get the details.\n\n- ```public_key``` is used to decrypt the signature.\n\n- ```cipher``` same as cipher in request body.\n\n- ```digest``` same as digest in request body.\n\n- ```created``` is the created date.\n\n- ```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.\n\nA successful request for the ```get signature key detail``` endpoint will return a response body as follows:\n\n```javascript\n{\n \"key_id\": \"7ca628a8-08b0-4e42-aeb8-960b37049c31\",\n \"cipher\": \"RSA\",\n \"digest\": \"SHA224\",\n \"created\": \"2018-01-18T10:16:12.364Z\",\n \"enabled\": false\n}\n```\n\n*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.\n\nA successful request for the ```delete signature key``` endpoint will return an empty response body.\n\n*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.\nThere 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.\n\nThe most basic body has the following structure:\n\n```javascript\n{\n \"key_id\": \"7ca628a8-08b0-4e42-aeb8-960b37049c31\"\n}\n```\n\nThe response body of a successful PATCH request to ```enable signature key``` endpoint will contain the ```enabled``` properties with the value is true as follows:\n\n```javascript\n{\n \"key_id\": \"7ca628a8-08b0-4e42-aeb8-960b37049c31\",\n \"cipher\": \"RSA\",\n \"digest\": \"SHA224\",\n \"created\": \"2018-01-18T10:16:12.364Z\",\n \"enabled\": true\n}\n```\n\n*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.\n\nA successful request for the ```get enabled signature key``` endpoint will return a response body as follows:\n\n```javascript\n{\n \"key_id\": \"7ca628a8-08b0-4e42-aeb8-960b37049c31\",\n \"cipher\": \"RSA\",\n \"digest\": \"SHA224\",\n \"created\": \"2018-01-18T10:16:12.364Z\",\n \"enabled\": true\n}\n```\n\n*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.\n\nA successful request for the ```disable the current enabled signature key``` endpoint will return no content when successful.\nIf there is an enabled key, it will be disabled; and the 204 status code is returned.\nIf 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.\n\n### Events Types\n\nThe campaign report consists of a series of events, that were generated by recipients when\ninteracting with the generated mobile landing page. The set of events that are currently supported\nare as follows:\n\n| Event Type | Event Source | Description |\n|:------------------|:-------------|:-----------------------------------------------|\n| `PAGE_OPEN` | n/a | The page was opened in a browser. |\n| `BUTTON_CLICKED` | Button label | One of the Call to Action buttons was clicked. |\n| `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.\n\nThis will contain the following bits of information:\n\n- The total number of events recorded for the particular campaign.\n\n- The number of unique engagements. This is the number of recipients for which there exists at least one recorded event.\n\n- A breakdown of the number of the total number of events grouped by the event type and event source\n\nThe event breakdown will return the following information for each event and source type:\n\n- The total number of recorded events of that type and source\n\n- The number of unique recipients for which that event and source was recorded for at least once\n\nFor 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.\n\n### Events Types\n\nThe campaign report consists of a series of events, that were generated by recipients when\ninteracting with the generated mobile landing page. The set of events that are currently supported\nare as follows:\n\n| Event Type | Event Source | Description |\n|:------------------|:-------------|:-----------------------------------------------|\n| `PAGE_OPEN` | n/a | The page was opened in a browser. |\n| `BUTTON_CLICKED` | Button label | One of the Call to Action buttons was clicked. |\n| `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.\n\nAt 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.\n\n### Events Types\n\nThe campaign report consists of a series of events, that were generated by recipients when\ninteracting with the generated mobile landing page. The set of events that are currently supported\nare as follows:\n\n| Event Type | Event Source | Description |\n|:------------------|:-------------|:-----------------------------------------------|\n| `PAGE_OPEN` | n/a | The page was opened in a browser. |\n| `BUTTON_CLICKED` | Button label | One of the Call to Action buttons was clicked. |\n| `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).\n\nAt 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).\n", "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).\n", "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).\n", "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\n```\n{\n \"myKey\": \"myValue\",\n \"anotherKey\": \"anotherValue\"\n}\n```", "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\n```\n{\n \"myKey\": \"myValue\",\n \"anotherKey\": \"anotherValue\"\n}\n```", "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\n```\n{\n \"myKey\": \"myValue\",\n \"anotherKey\": \"anotherValue\"\n}\n```", "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\n```\n{\n \"myKey\": \"myValue\",\n \"anotherKey\": \"anotherValue\"\n}\n```", "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\n```\n{\n \"myKey\": \"myValue\",\n \"anotherKey\": \"anotherValue\"\n}\n```", "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\n```\n{\n \"myKey\": \"myValue\",\n \"anotherKey\": \"anotherValue\"\n}\n```" }, "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\n```\n{\n \"myKey\": \"myValue\",\n \"anotherKey\": \"anotherValue\"\n}\n```", "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;\nhowever, id, url, method, and retries are consistently populated.\n", "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.\nKey max length is 200 characters, value max length is 1000 characters.\n" }, "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.\nEmpty body (all fields null) is rejected.\nNote: read_timeout, retries, and retry_delay are not supported on update (create-only).\n", "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.\nKey max length is 200 characters, value max length is 1000 characters.\n" }, "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.\nIf provided, must be non-empty (events: [] is rejected).\n" } }, "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.\n" }, "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.\n" }, "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.\n" } } }, "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)" ] } ] }