Survey API guide

Owned by Flaviu Porutiu
Last updated: Jun 26, 2018


Table of contents

This edge is only active for the instances that have the survey module active.

If it's not active, all endpoints will return a success = 0 message.


Getting the default feedback survey

Returns the default feedback survey link.

This endpoint can only be used after setting a default survey using the root account on the platform.

If no default survey is set, the endpoint will return a success = 0.

GET /survey/default_scale

Request

 Click here to expand...


Request

Endpoint: /survey/default_scale

Method: GET

Only logged in: YES

Account privilege restriction: Any privilege

Headers:

 Click here to expand...
Header nameValue
X-Requested-With
XMLHttpRequest
X-Auth-TokenToken obtained from Login endpoint

Response

 Click here to expand...


Response

Http Code

Response

Description

200

 Success response
Success response
{
    "success": 1,
    "message": "link_to_survey"
}

Success response

 Base Object

Base object:

Object propertyDescription
successRepresents if the call was successful
messageRepresents the link to survey to be used for answering the survey

403

Forbidden
User cannot access the resource


Assigning / getting the scale for the user

Returns the survey data for the currently assigned scale or assigns a new one if a link is given.

GET /survey/get

Request

 Click here to expand...


Request

Endpoint: /survey/get

Method: GET

Only logged in: YES

Account privilege restriction: Any privilege

Headers:

 Click here to expand...
Header nameValue
X-Requested-With
XMLHttpRequest
X-Auth-TokenToken obtained from Login endpoint

Parameters:

 Click here to expand...
ParameterRequiredTypeDescription
survey_link
NO
StringSurvey link for the survey to be assigned to current user


Response

 Click here to expand...


Response

Http Code

Response

Description

200

 Success response
Success response
{
    "success": 1,
    "instance_id": 28,
    "scale": {
        "id": 15,
        "title": "Feedback form",
        "description": "<p>Please fill out this feedback form!</p>",
        "type": 2
    },
    "items": [
        {
            "id": 20,
            "title": "What do you think about our gym?",
            "position": 1,
            "answers": {
                "2": {
                    "id": 2,
                    "title": "Goodn't :(",
                    "position": 1,
                    "value": 0
                },
                "13": {
                    "id": 13,
                    "title": "Good",
                    "position": 2,
                    "value": 0
                }
            },
            "actual_answer": "",
            "actual_value": ""
        },
        {
            "id": 21,
            "title": "What do you think about our offers?",
            "position": 2,
            "answers": {
                "2": {
                    "id": 2,
                    "title": "Goodn't :(",
                    "position": 1,
                    "value": 0
                },
                "13": {
                    "id": 13,
                    "title": "Good",
                    "position": 2,
                    "value": 0
                }
            },
            "actual_answer": "",
            "actual_value": ""
        }
    ]
}

Success response

 Base Object

Base object:

Object propertyDescription
successRepresents if the call was successful
instance_idInternal survey instance ID
scaleThe survey object containing its data
itemsArray containing the survey items to which the user should respond to
 scale object

scale object:

Object propertyDescription
idInternal ID of the survey
titleSurvey title
descriptionSurvey HTML description
type

Internal type of the survey:

  • 1 - Single use per user
  • 2 - Multiple use per user
 items object

items object:

Object propertyDescription
idInternal ID of the survey item
titleSurvey item title
positionPosition in the survey
answers

Array of answers for the survey item

If it's empty, the user should be able to type in any response he wants.

actual_answer

An old answer given to that item (in case the user abandoned the survey before and now it came back)

Internal form - Mosly as an ID, used mostly for fixed answer questions

actual_value

An old answer given to that item (in case the user abandoned the survey before and now it came back)

Human readable form - Mostly as a text, used for open response questions

 answers object

answers object:

Object of type ID - Properties

Object propertyDescription
idInternal ID of the answer
titleTitle of the answer
positionPosition in the answer group
value

Internal value of the answer

403

Forbidden
User cannot access the resource


Responding to a survey

POST /survey/save

Request

 Click here to expand...


Request

Endpoint: /survey/save

Method: POST

Only logged in: YES

Account privilege restriction: Any privilege

Headers:

 Click here to expand...
Header nameValue
X-Requested-With
XMLHttpRequest
X-Auth-TokenToken obtained from Login endpoint

Parameters:

 Click here to expand...
ParameterRequiredTypeDescription
instance_id
YES
IntegerInstance ID given at the Get scale for user endpoint.
itemsYESArray of answer objects

Array of answer objects with the survey responses.

Answer object description:

ParameterRequiredTypeDescription
idYESIntegerSurvey item ID
actual_answerNOInteger

Survey answer ID

Used when the answer array is not empty when getting the survey data - Fixed answer question

actual_valueNOString

Survey answer - Plain text

Used when the answer array is empty when getting the survey data - Open response question


Response

 Click here to expand...


Response

Http Code

Response

Description

200

 Success response
Success response
{
    "success": 1,
}

Success response

 Base Object

Base object:

Object propertyDescription
successRepresents if the call was successful

403

Forbidden
User cannot access the resource


Canceling a survey

Cancels the survey answers for the given instance

This endpoint only works for type = 2 surveys

DELETE /survey/cancel/{survey_instance_id}

Request

 Click here to expand...


Request

Endpoint: /survey/delete/{survey_instance_id}

Method: DELETE

Only logged in: YES

Account privilege restriction: Any privilege

Headers:

 Click here to expand...
Header nameValue
X-Requested-With
XMLHttpRequest
X-Auth-TokenToken obtained from Login endpoint

Parameters:

 Click here to expand...
ParameterRequiredTypeDescription
survey_instance_id
YES
IntegerInstance ID given at the Get scale for user endpoint.


Response

 Click here to expand...


Response

Http Code

Response

Description

200

 Success response
Success response
{
    "success": 1,
}

Success response

 Base Object

Base object:

Object propertyDescription
successRepresents if the call was successful

403

Forbidden
User cannot access the resource