Digital Research - Documentation

Survey Structure

The survey is configured using a JSON object with the following top-level properties:

title: The title of the survey userid: Creator's user ID questions: Array of question objects


{
    "title": "Customer Feedback for Some Company",
    "intro": "This is a quick survey for some company, please complete as much as you would like.",
    "questions": [
        // Array of question objects
    ]
}

Each question in the "questions" array is an object with these common properties:

type: Question type name: Unique identifier question: Question text required: Boolean options: Configuration object

1. Radio Button Question


{
    "type": "radio",
    "name": "overall-experience",
    "question": "What was your overall experience with the service",
    "required": true,
    "options": {
        "1": "Poor",
        "2": "Acceptable",
        "3": "Average",
        "4": "Good",
        "5": "Great"
    }
}

The options object contains key-value pairs where:

The key is the value submitted with the form
The value is the label displayed to the user

This creates a set of radio buttons where users can select only one option.

2. Binary Question


{
    "type": "binary",
    "name": "happy",
    "question": "Are you happy",
    "required": true,
    "options": {
        "mode": "truefalse"
    }
}

The options object contains:

mode: Determines the labels for the two buttons

Available modes:

truefalse yesno onezero positivenegative onoff openclose highlow inout lightdark updown

Any other field can depend on the true/false status of a binary field. This is achieved by using the "dependson" directive in the question configuration, as below.

3. Select Question


{
    "type": "select",
    "name": "provider",
    "question": "What is your current mental state",
    "required": true,
    "dependson": "some-binary-question"
    "options": {
        "1": "Suicidal",
        "2": "Depressed",
        "3": "Managing",
        "4": "Ok",
        "5": "Good",
        "6": "Excellent"
    }
}

The options object contains key-value pairs where:

The key is the value submitted with the form
The value is the label displayed to the user

This creates a dropdown select menu where users can choose one option from the list.

4. Slider Question


{
    "type": "slider",
    "name": "satisfaction",
    "question": "How satisfied are you with your solution",
    "required": true,
    "options": {
        "min": 1,
        "max": 10,
        "step": 1,
        "minLabel": "Not satisfied",
        "maxLabel": "Very satisfied"
    }
}

The options object contains:

min: Minimum value of the slider
max: Maximum value of the slider
step: Step increment between values
minLabel: Label for the minimum value
maxLabel: Label for the maximum value

This creates a horizontal slider that allows users to select a value within the specified range.

5. Text Question


{
    "type": "text",
    "name": "name",
    "question": "What is your name?",
    "required": true,
    "placeholder": "Enter your full name",    
    "options": {
        "maxlength": 100
    }
}

The options object contains:

placeholder: Text displayed when the field is empty
maxlength: Maximum number of characters allowed

This creates a single-line text input field for short answers.

6. Textarea Question


{
    "type": "textarea",
    "name": "feedback",
    "question": "Please provide any additional feedback",
    "required": false,
    "placeholder": "Enter your feedback here...",    
    "options": {
        "rows": 5,
        "maxlength": 500
    }
}

The options object contains:

placeholder: Text displayed when the field is empty
rows: Number of visible text rows
maxlength: Maximum number of characters allowed

This creates a multi-line text area for longer responses.

7. Checkbox Question


{
    "type": "checkbox",
    "name": "sugar",
    "question": "Do you like sugar",
    "required": true,
    "options": {
        "1": "Yes",
        "checked":false
    }
}

The options object contains configuration for the checkbox:

value determines the value when checked
checked determines if the checkbox starts checked

8. Date Question


{
    "type": "date",
    "name": "contract_start",
    "question": "When did your contract start?",
    "required": true,
    "options": {
        "min": "2020-01-01",
        "max": "2023-12-31"
    }
}

The options object contains:

min: Earliest selectable date (YYYY-MM-DD format)
max: Latest selectable date (YYYY-MM-DD format)

This creates a date picker that allows users to select a date within the specified range.

9. Email Question


{
    "type": "email",
    "name": "email",
    "question": "What is your email address?",
    "required": true,
    "placeholder": "your.name@example.com"    
    "options": {
        "maxlength": 100
    }
}

The options object contains:

placeholder: Text displayed when the field is empty
maxlength: Maximum number of characters allowed

This creates an email input field with built-in email format validation.

10. Number Question


{
    "type": "number",
    "name": "household_size",
    "question": "How many people live in your household?",
    "required": true,
    "options": {
        "min": 1,
        "max": 10,
        "step": 1
    }
}

The options object contains:

min: Minimum allowed value
max: Maximum allowed value
step: Increment between values

This creates a number input field that only accepts numerical values within the specified range.

Create Survey

Endpoint: /api/survey/create.php

Method: POST

Description: Creates a new survey with the provided JSON structure.

Request Body: JSON survey structure as shown in the examples above.

Response: Returns the created survey ID and a status message.

Example Response:

{
    "status": "success",
    "message": "Survey created successfully",
    "survey_id": 42
}

Get Survey

Endpoint: /api/survey/get.php?id={survey_id}

Method: GET

Description: Retrieves a survey by its ID.

Parameters:

id (required): The ID of the survey to retrieve.

Response: Returns the complete survey structure.

Example Response:

{
    "status": "success",
    "survey": {
        "id": 42,
        "title": "Customer Feedback for Broadband Genius",
        "userid": 7,
        "created_at": "2023-06-15 14:30:22",
        "questions": [
            // Question objects as shown in examples
        ]
    }
}

Submit Response

Endpoint: /api/survey/submit.php

Method: POST

Description: Submits a response to a survey.

Request Body:

{
    "survey_id": 42,
    "responses": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "provider": "bt",
        "overall-experience": "4",
        "satisfaction": 8,
        "services": ["internet", "tv"],
        "feedback": "Great service overall!"
    }
}

Response: Returns a confirmation of the submission.

Example Response:

{
    "status": "success",
    "message": "Response submitted successfully",
    "response_id": 156
}

List Surveys

Endpoint: /api/survey/list.php

Method: GET

Description: Lists all surveys for the authenticated user.

Parameters:

page (optional): Page number for pagination (default: 1)
limit (optional): Number of surveys per page (default: 10)

Response: Returns a list of surveys.

Example Response:

{
    "status": "success",
    "total": 25,
    "page": 1,
    "limit": 10,
    "surveys": [
        {
            "id": 42,
            "title": "Customer Feedback for Broadband Genius",
            "created_at": "2023-06-15 14:30:22",
            "responses_count": 18
        },
        // More survey objects
    ]
}

Get Survey Responses

Endpoint: /api/survey/responses.php?id={survey_id}

Method: GET

Description: Retrieves all responses for a specific survey.

Parameters:

id (required): The ID of the survey to retrieve responses for.
page (optional): Page number for pagination (default: 1)
limit (optional): Number of responses per page (default: 50)

Response: Returns a list of responses for the specified survey.

Example Response:

{
    "status": "success",
    "survey_id": 42,
    "survey_title": "Customer Feedback for Broadband Genius",
    "total_responses": 18,
    "page": 1,
    "limit": 50,
    "responses": [
        {
            "id": 156,
            "submitted_at": "2023-06-16 09:45:12",
            "data": {
                "name": "John Doe",
                "email": "john.doe@example.com",
                "provider": "bt",
                "overall-experience": "4",
                "satisfaction": 8,
                "services": ["internet", "tv"],
                "feedback": "Great service overall!"
            }
        },
        // More response objects
    ]
}

Delete Survey

Endpoint: /api/survey/delete.php

Method: POST

Description: Deletes a survey and all its responses.

Request Body:

{
    "survey_id": 42
}

Response: Returns a confirmation of the deletion.

Example Response:

{
    "status": "success",
    "message": "Survey deleted successfully"
}

Export Survey Responses

Endpoint: /api/survey/export.php?id={survey_id}&format={format}

Method: GET

Description: Exports survey responses in the specified format.

Parameters:

id (required): The ID of the survey to export responses for.
format (required): Export format, one of: csv, json, or excel

Response: Returns a file download in the requested format.

Error Responses

All API endpoints return appropriate HTTP status codes along with error messages when issues occur:

Status Code	Description	Example Response
400	Bad Request - Invalid input data	`{ "status": "error", "message": "Invalid survey structure" }`
401	Unauthorized - Authentication required	`{ "status": "error", "message": "Authentication required" }`
403	Forbidden - Insufficient permissions	`{ "status": "error", "message": "You don't have permission to access this survey" }`
404	Not Found - Resource not found	`{ "status": "error", "message": "Survey not found" }`
500	Internal Server Error	`{ "status": "error", "message": "An unexpected error occurred" }`

API Authentication

All API requests require authentication using an API key. The API key should be included in the request headers:

X-API-Key: your_api_key_here

To obtain an API key, please contact our support team or generate one in your account dashboard.

Important: Keep your API key secure and never share it publicly. If you believe your API key has been compromised, you should regenerate it immediately from your account dashboard.

API Rate Limits

To ensure fair usage and system stability, API requests are subject to rate limiting:

Standard accounts: 100 requests per minute
Premium accounts: 500 requests per minute
Enterprise accounts: Custom limits based on your agreement

When rate limits are exceeded, the API will return a 429 Too Many Requests status code with the following response:

{
    "status": "error",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 30
}

The retry_after value indicates the number of seconds to wait before making another request.

Survey JSON Configuration Documentation

Question Types

API Endpoints

Error Handling

Authentication

Rate Limiting