{ "openapi": "3.1.1", "info": { "title": "DIY Surveys API", "description": "API services provided by the DIY Surveys platform.", "version": "3.2" }, "servers": [ { "url": "http://ireapi.diysurveys.com/" } ], "paths": { "/v3.2/Data/Import": { "post": { "tags": [ "Data" ], "summary": "Imports data based on a survey's custom import definition.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportDataModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ImportDataModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ImportDataModel" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ImportDataModel" } } }, "required": true }, "responses": { "200": { "description": "Successfully imported data. The response contains a list of results indicating the status of each record.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ImportResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ImportResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ImportResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ImportResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/ImportResponse" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/v3.2/Keyword": { "post": { "tags": [ "Keyword" ], "summary": "Add a keyword to your account.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/KeywordModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/KeywordModel" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/KeywordModel" } } }, "required": true }, "responses": { "200": { "description": "The ." } } }, "patch": { "tags": [ "Keyword" ], "summary": "Update a keyword in your account.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/KeywordModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/KeywordModel" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/KeywordModel" } } }, "required": true }, "responses": { "200": { "description": "The ." } } }, "delete": { "tags": [ "Keyword" ], "summary": "Delete a keyword from your account.", "parameters": [ { "name": "keyword", "in": "query", "description": "The keyword.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The ." } } }, "get": { "tags": [ "Keyword" ], "summary": "List keywords registered to your account.", "responses": { "200": { "description": "The ." } } } }, "/v3.2/Message/Lookup/{number}": { "get": { "tags": [ "Message" ], "summary": "Performs a lookup on the number and returns back useful information on its availability and type.", "parameters": [ { "name": "number", "in": "path", "description": "The number to check (E.164 digits only).", "required": true, "schema": { "pattern": "^[1-9]\\d{1,14}$", "type": "string" } } ], "responses": { "200": { "description": "The response contains the results of the lookup.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/LookupResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/LookupResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LookupResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/LookupResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/LookupResponse" } } } } } } }, "/v3.2/Message": { "post": { "tags": [ "Message" ], "summary": "The send message.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/MessageModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/MessageModel" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/MessageModel" } } }, "required": true }, "responses": { "200": { "description": "The message was sent successfully." } } } }, "/v3.2/Survey/GetResults": { "post": { "tags": [ "Survey" ], "summary": "Collect results of a survey.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultsRequestModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ResultsRequestModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ResultsRequestModel" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/ResultsRequestModel" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ResultsRequestModel" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/ResultsRequestModel" } }, "application/*+xml": { "schema": { "$ref": "#/components/schemas/ResultsRequestModel" } } }, "required": true }, "responses": { "200": { "description": "Returns the results in the desired format. For JSON, XML, CSV." } } } }, "/v3.2/TinyUrl/Register": { "post": { "tags": [ "TinyUrl" ], "summary": "Register a Url with the DIY Surveys Tiny URL Service.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UrlModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UrlModel" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/UrlModel" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/UrlModel" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/UrlModel" } }, "application/*+xml": { "schema": { "$ref": "#/components/schemas/UrlModel" } } }, "required": true }, "responses": { "200": { "description": "A Tiny URL" } } } }, "/v3.2/TinyUrl/RegisterList": { "post": { "tags": [ "TinyUrl" ], "summary": "Register a list of URLs with the DIY Surveys Tiny URL Service.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlListModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UrlListModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UrlListModel" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/UrlListModel" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/UrlListModel" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/UrlListModel" } }, "application/*+xml": { "schema": { "$ref": "#/components/schemas/UrlListModel" } } }, "required": true }, "responses": { "200": { "description": "A list of Tiny URLs" } } } }, "/v3.2/Webhook": { "get": { "tags": [ "Webhook" ], "summary": "Gets a list of webhooks for the current user.", "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebHookModel" } } }, "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebHookModel" } } }, "text/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebHookModel" } } }, "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebHookModel" } } }, "text/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebHookModel" } } } } } } } } }, "components": { "schemas": { "ImportDataListModel": { "type": "object", "description": "A model representing a single item in the import data list, allowing for dynamic properties to be included." }, "ImportDataModel": { "required": [ "reference", "list" ], "type": "object", "properties": { "reference": { "minLength": 1, "type": "string", "description": "The reference for the survey and import that can be found in the DIY Surveys Platform." }, "list": { "type": "array", "items": { "$ref": "#/components/schemas/ImportDataListModel" }, "description": "Gets or sets the list of data to import." } } }, "ImportResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the import operation for the respondent. Possible values: \"Success\", \"Error\"." }, "message": { "type": "string", "description": "Message providing additional information about the import operation." }, "title": { "type": "string", "description": "The title of the respondent (e.g., Mr., Ms., Dr.)." }, "firstName": { "type": "string", "description": "The first name of the respondent." }, "lastName": { "type": "string", "description": "The last name of the respondent." }, "mobileNumber": { "type": "string", "description": "The mobile number of the respondent." }, "emailAddress": { "type": "string", "description": "The email address of the respondent." }, "website": { "type": "string", "description": "The website of the respondent." }, "dateOfBirth": { "type": "string", "description": "The date of birth of the respondent." }, "when": { "type": "string", "description": "The date and time when the respondent was added." } }, "description": "Represents the response returned after importing data." }, "KeywordModel": { "type": "object", "properties": { "keyword": { "type": "string", "description": "The keyword that you wish to register." }, "type": { "type": "string" }, "response": { "type": "string" }, "finishDate": { "type": "string", "format": "date-time" } } }, "LookupResponse": { "type": "object", "properties": { "messageID": { "type": "string", "description": "The unique identifier for the lookup." }, "status": { "type": "string", "description": "The status of the message lookup operation. Possible values include \"Success\", \"Error\", or other relevant statuses." }, "carrier": { "type": "string", "description": "The carrier associated with the phone number that was looked up. This may include the name of the mobile network operator or service provider." }, "reachable": { "type": "boolean", "description": "A boolean value indicating whether the phone number is reachable. True if the number can be reached, false otherwise." }, "numberType": { "type": "string", "description": "The type of phone number that was looked up. This may include values such as \"Mobile\", \"Landline\", \"VoIP\", or other relevant classifications." } } }, "MessageModel": { "required": [ "destination", "message", "reply", "source" ], "type": "object", "properties": { "destination": { "pattern": "^[1-9]\\d{1,14}$", "type": "string", "description": "The destination number that the message is to be sent to. Must follow the E.164 digits only format." }, "lookup": { "type": [ "null", "boolean" ], "description": "Gets or sets the lookup." }, "message": { "minLength": 1, "type": "string", "description": "The message.Depending on the route this will be automatically split and concatenated. In some instances the message\nlength is limited.\nPlease check with DIY Surveys Support if you are unsure." }, "reply": { "type": "boolean", "description": "Indicates whether the message can be replied to. If the route support branded messages then setting this false alos\ngreater flexibility with the source." }, "source": { "minLength": 1, "type": "string", "description": "The source number or branded text (if the route supports it) that the message comes from.\nIf the message is set to reply to then it cannot be branded.\nA mobile number including the country code (e.g. 44123455678), a short code (e.g. 85001) or a string up to 11\ncharacters long (e.g. OnePoint)" }, "test": { "type": [ "null", "boolean" ], "description": "Gets or sets the test." }, "timeout": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets or sets the timeout.", "format": "int32" }, "when": { "type": [ "null", "string" ], "description": "Depending the account settings, optionally allows the message to be delayed until a certain time.", "format": "date-time" }, "type": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Type of message to override general SMS routing.", "format": "int16" }, "onBehalf": { "type": [ "null", "string" ] }, "window": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/WindowModel" }, "description": "Gets or sets the window." }, "surveyId": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets or sets the survey the message is associated with.", "format": "int32" } }, "description": "The message model." }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": [ "null", "string" ] }, "title": { "type": [ "null", "string" ] }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "format": "int32" }, "detail": { "type": [ "null", "string" ] }, "instance": { "type": [ "null", "string" ] } } }, "ResultsRequestModel": { "type": "object", "properties": { "format": { "type": "string", "description": "The format required for a report. Can be any one of CSV, PIPE, XMl or JSON" }, "header": { "type": [ "null", "boolean" ], "description": "Indicates whether a header is required for CSV and PIPE formatted results." }, "since": { "type": [ "null", "string" ], "description": "Gets results since this date.", "format": "date-time" }, "sortOrder": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "null", "integer", "string" ], "description": "Gets results for all surveys that have at least this question completed. To get all results use 1.", "format": "int32" }, "surveyReference": { "type": "string", "description": "The survey reference or '*' for all surveys." } }, "description": "The results request model." }, "UrlListModel": { "type": "object", "properties": { "urls": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/UrlModel" }, "description": "Gets or sets the urls." }, "urlList": { "type": [ "null", "array" ], "items": { "$ref": "#/components/schemas/UrlModel" } } }, "description": "The url list model." }, "UrlModel": { "type": "object", "properties": { "fullUrl": { "type": "string", "description": "The full URL to interpret into a tiny URL" }, "tinyDomain": { "type": [ "null", "string" ] }, "reuse": { "type": [ "null", "boolean" ] }, "slashtag": { "type": [ "null", "string" ] } }, "description": "The url model." }, "WebHookModel": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the webhook." }, "key": { "type": "string", "description": "The URL to which the webhook will send data." }, "secret": { "type": "string", "description": "The secret for the webhook." }, "payload": { "type": "string", "description": "The payload for the webhook." }, "contentType": { "type": "string", "description": "The content type for the webhook." }, "isActive": { "type": "boolean", "description": "Indicates whether the webhook is active." }, "events": { "type": "array", "items": { "type": "string" }, "description": "The types of events the web hook refers to." }, "method": { "type": "string", "description": "The HTTP method for the webhook." }, "timeout": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The timeout for the webhook.", "format": "int32" }, "totalTimeout": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The total timeout for the webhook.", "format": "int32" }, "retries": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The number of retries for the webhook.", "format": "int32" }, "status": { "pattern": "^-?(?:0|[1-9]\\d*)$", "type": [ "integer", "string" ], "description": "The status of the webhook.", "format": "int32" } }, "description": "Represents a webhook model used for configuring and managing webhooks in the application." }, "WindowModel": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "days": { "type": "string" } } } } }, "tags": [ { "name": "Data", "description": "Import custom respondent data for surveys." }, { "name": "Keyword", "description": "Add, update, delete and list Keywords." }, { "name": "Message", "description": "Send messages over Email, SMS and WhatsApp." }, { "name": "Survey", "description": "Collect results from a survey." }, { "name": "TinyUrl", "description": "convert single or multiple long urls into tiny urls." }, { "name": "Webhook", "description": "Manage webhooks for survey events." } ] }