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 [email protected].
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": "[email protected]"
},
"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",
"[email protected]",
"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 |
| 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 |