NAV Navbar
Logo
Elegant Surveys

Developer API

Elegant Surveys Developer API can be used to integrate third party solutions to utilize responses collected through our application.

We offer a RESTful API which can be easily consumed in any programming language. If you need any help, please contact support@elegantsurveys.com.

Authentication

We use an API token to authenticate your requests. Please generate a token from the API access page

This token should be included with all requests as ‘token’ in the query string.

/<endpoint>/?token=<your-token>

Devices

List Devices

/devices

[
  {
    "id": 102,
    "name": "Reception Tablet",
    "added_at": "2016-04-07T03:53:03+05:30",
    "template": "General",
    "survey": "Overall Experience",
    "last_sync": "2017-01-15T06:38:14+05:30",
    "app_version": 23
  }
]

List of devices connected to this account

HTTP Request

GET https://app.elegantsurveys.com/data/v1/devices

Response

json array

Key Format Description
id integer Unique identifier of device
name string Name of device
added_at string RFC 3339 timestamp when device was added
template string Name of the template active on this device
survey string Name of the survey active on this device
last_sync string RFC 3339 timestamp when this device was last synced to the server
app_version integer Version of the application running when the device last synced.

Surveys

List Surveys

/surveys

[
  {
    "id": 44,
    "name": "Demo Questionnaire",
    "added_at": "2016-06-12T12:07:33+05:30",
    "devices_count": 0,
    "questions": [
      {
        "id": 511,
        "title": "How do you feel after your visit?",
        "type": "smiley",
        "options": null,
        "optional": true
      },
      {
        "id": 512,
        "title": "Rate your experience with us",
        "type": "star",
        "options": null,
        "optional": true
      },
      {
        "id": 513,
        "title": "How good did we do in these aspects?",
        "type": "multistar",
        "options": [
          "Ease of Use",
          "Quality",
          "Design"
        ],
        "optional": true
      },
      {
        "id": 514,
        "title": "Your experience with our staff",
        "type": "multismiley",
        "options": [
          "Friendliness",
          "Helpfulness",
          "Overall"
        ],
        "optional": true
      },
      {
        "id": 515,
        "title": "How did you know about us?",
        "type": "singleoption",
        "options": [
          "Facebook",
          "Advertisement",
          "Friends",
          "Other"
        ],
        "optional": true
      },
      {
        "id": 516,
        "title": "Which all applies for what you were looking for?",
        "type": "multioption",
        "options": [
          "High Quality",
          "Less Cost",
          "Durable",
          "Low Maintenance"
        ],
        "optional": true
      },
      {
        "id": 517,
        "title": "Were you able to find the right product?",
        "type": "polar",
        "options": null,
        "optional": true
      },
      {
        "id": 518,
        "title": "Tell us your views",
        "type": "grid",
        "options": {
          "rows": [
            "I found exactly what I need",
            "Billing was quick and easy",
            "I'll come back here for my next purchase"
          ],
          "columns": [
            "Disagree",
            "Neutral",
            "Agree"
          ]
        },
        "optional": true
      },
      {
        "id": 519,
        "title": "What describes your experience best?",
        "type": "singlesentence",
        "options": [
          "I knew exactly what I wanted and I made a purchase",
          "I know what I want but I couldn't find it here",
          "I was still trying to figure our the right product when I came in"
        ],
        "optional": true
      },
      {
        "id": 520,
        "title": "Did you have any of these experiences?",
        "type": "multisentence",
        "options": [
          "I'm glad that I found out your business",
          "There were too many choices and I couldn't choose one",
          "The billing process took too long and was tiring"
        ],
        "optional": true
      },
      {
        "id": 521,
        "title": "Please let us know your valuable comments or feedback",
        "type": "comment",
        "options": null,
        "optional": true
      },
      {
        "id": 522,
        "title": "Enter the name of our staff who served you",
        "type": "text",
        "options": null,
        "optional": true
      },
      {
        "id": 523,
        "title": "Enter your receipt number",
        "type": "number",
        "options": null,
        "optional": true
      },
      {
        "id": 572,
        "title": "Tell us about you",
        "type": "multifield",
        "options": [
          "Name",
          "Email",
          "Phone",
          "Send me special offers & promotions"
        ],
        "optional": false
      }
    ]
  }
]

List of surveys created

HTTP Request

GET https://app.elegantsurveys.com/data/v1/surveys

Response

json array

Key Format Description
id integer Unique identifier of the survey
name string Name of the survey
added_at string RFC 3339 timestamp when survey was created
devices_count integer Number of devices linked to this survey
questions array An array of questions in this survey (Refer below)

Questions Object

Key Format Description
id integer Unique identifier of this question
title string Title of the question
type string Question type identifier of this question. Refer question type identifier constants for possible values
options mixed Available options if applicable for a question type. Response type depends on the question type. Refer the question type details for possible formats.
optional boolean True if the question is marked as optional, False otherwise

Question Types and Options Format

Type Constant Description Options Format
star Rate out of 5 stars -
smiley Smileys -
polar Yes / No -
multistar Multiple Star Rating Array of strings
multismiley Multiple Smileys Array of strings
grid Grid Object (see example on the right)
multifield Multiple Input Fields Array of strings
singleoption Select an option Array of strings
multioption Select multiple options Array of strings
singlesentence Pick any sentence Array of strings
multisentence Pick multiple sentences Array of strings
comment Comment box -
text Text field -
number Number field -

Survey Responses

/surveys/responses

[
  {
    "id": 6989,
    "device_id": 84,
    "device_timestamp": "2017-01-02T12:40:56+05:30",
    "sync_timestamp": "2017-01-02T12:40:57+05:30",
    "selected_language": "en",
    "customer_info": {
      "name": "John Doe",
      "phone": "010-255-355",
      "email": "john@example.com"
    },
    "answers": [
      {
        "type": "smiley",
        "response": "Very Happy",
        "skipped": false
      },
      {
        "type": "star",
        "response": 5,
        "skipped": false
      },
      {
        "type": "multistar",
        "response": [
          3.5,
          4.5,
          3.5
        ],
        "skipped": false
      },
      {
        "type": "multismiley",
        "response": [
          "Neutral",
          "Happy",
          "Happy"
        ],
        "skipped": false
      },
      {
        "type": "singleoption",
        "response": "Facebook",
        "skipped": false
      },
      {
        "type": "multioption",
        "response": [
          "High Quality",
          "Less Cost"
        ],
        "skipped": false
      },
      {
        "type": "polar",
        "response": "Yes",
        "skipped": false
      },
      {
        "type": "grid",
        "response": [
          "Agree",
          "Neutral",
          "Neutral"
        ],
        "skipped": false
      },
      {
        "type": "singlesentence",
        "response": "I know what I want but I couldn't find it here",
        "skipped": false
      },
      {
        "type": "multisentence",
        "response": [
          "I'm glad that I found out your business",
          "There were too many choices and I couldn't choose one"
        ],
        "skipped": false
      },
      {
        "type": "comment",
        "response": "Great experience ",
        "skipped": false
      },
      {
        "type": "text",
        "response": "Alex",
        "skipped": false
      },
      {
        "type": "number",
        "response": "5566",
        "skipped": false
      },
      {
        "type": "multifield",
        "response": [
          "John",
          "john@example.com",
          "100-588-5588",
          true
        ],
        "skipped": false
      }
    ]
  }
]

The survey responses endpoint returns customer responses to a survey for the selected date range and selected devices.

HTTP Request

GET https://app.elegantsurveys.com/data/v1/surveys/responses

Query String Parameters

Name Format Description Example
survey_id integer Unique identifier of the survey 44
start_date string Start date of the date range for which responses are to be retrieved 2017-01-01
end_date string End date of the date range for which responses are to be retrieved 2017-01-02
device_ids array Array of the unique identifiers of the devices if responses from only those devices are required. Leave blank to not filter by device [10,18,50]

Response

json array

Key Format Description
id integer Unique identifier of this response
device_id integer Unique identifier of the device from which this response was submitted
device_timestamp string RFC 3339 timestamp when this response customer filled the response
sync_timestamp string RFC 3339 timestamp when this response was synced to server
selected_language string The language selected for the survey
customer_info object Standard customer information object if the option is enabled for this survey
answers array Array of answers object

Customer Info Object

Key Format Description
name string Name of the customer
phone string Phone number of the customer
email string Email address of the customer

Answers Object

Key Format Description
response mixed The response depends on the question type. Refer the question type details below for possible formats.
skipped boolean True if the question was not answered, False otherwise

Answer Response Formats

Refer the example on the right to understand the format better

Type Constant Response Format
star decimal
smiley string
polar string
multistar array of decimals
multismiley array of strings
grid object
multifield array of strings
singleoption string
multioption array of strings
singlesentence string
multisentence array of strings
comment string
text string
number string

Errors

These are the possible errors you might encounter.

{
  "code": 422,
  "message": "survey_id, start_date, and end_date are required and should be valid. device_ids should be an array if present."
}
Error Code Meaning
401 Invalid access code
422 Required input missing
404 Not found
405 Method not supported
429 Too many requests
503 Temporarily unavailable