Survey Configuration Guide

Overview

This document provides standardized guidance for configuring and implementing surveys within Azodha's API platform. Surveys enable structured data collection from patients and healthcare providers, supporting standardized assessments, intake processes, and ongoing monitoring.

Key Survey Components

Surveys vs. Survey Responses

• Surveys: Structured questionnaires created for an organization that defines the data collection framework.

• Survey Responses: Individual responses submitted by patients or providers after completing surveys.

When a survey is assigned to a patient, it creates a survey response object. The patient interacts with the survey to fill in the responses, which are then stored as survey responses distinct from the original survey structure.

Survey Features

1. Survey Versioning

The platform supports versioning of surveys to:

• Maintain historical versions of surveys for accuracy over time

• Enable longitudinal data collection and comparisons across different survey versions

• Allow updates without impacting previously collected data or ongoing surveys

2. Liquid Templates for Surveys

Each survey can have a Liquid template attached to render survey responses in a custom format:

• Convert responses to PDFs at key stages (completed, signed, or step-by-step)

• Present data in provider-friendly formats for easy review and analysis

• Create customized documentation that aligns with specific workflow needs

Creating a Survey

POST/api/v1/surveys

Creating a new survey

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>
organization_code	Organization_Code

Body

Name	Type	Description	Required
title	string	Title of the survey	Yes
status	enum	Survey status (draft, active, retired, unknown)	Yes
pageNumber	number	Page number for each question	Yes
linkId	string	Unique identifier for each question	Yes
heading	string	Section heading for each question	Yes
label	string	Question label	Yes
type	enum	Question type (checkBox, textArea, etc.)	Yes

Response

200 Success

{
  "success": true,
  "data": {
    "id": "599",
    "title": "Patient Intake Form",
    "status": "active",
    "organizationId": 5,
    "description": "Initial patient intake assessment",
    "item": [
      {
        "linkId": "personal-info",
        "heading": "Personal Information",
        "label": "Please provide your personal information",
        "pageNumber": 1,
        "type": "group",
        "item": [
          {
            "id": "10001",
            "linkId": "firstName",
            "heading": "First Name",
            "label": "First Name",
            "pageNumber": 1,
            "type": "string",
            "required": true
          },
          {
            "id": "10002",
            "linkId": "lastName",
            "heading": "Last Name",
            "label": "Last Name",
            "pageNumber": 1,
            "type": "string",
            "required": true
          },
          {
            "id": "10003",
            "linkId": "dob",
            "heading": "Date of Birth",
            "label": "Date of Birth",
            "pageNumber": 1,
            "type": "date",
            "required": true
          }
        ]
      }
    ]
  }
}

400 BusinessError

401 Unauthorised

403 Unauthorised

409 Conflict

Submitting Survey Responses

Survey responses are submitted when a user completes a survey. The platform captures these responses in a structured format for further processing and analysis.

Creating a Survey Response

PUT /api/v1/surveys/responses

Creating a Survey Response

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>
organization_code	Organization_Code

Body

Parameter	Type	Description	Required
personId	number	ID of the person completing the survey	Yes
surveyId	number	ID of the survey being completed	Yes
status	enum	Status of the response (completed, in-progress)	Yes
assessmentResponse	object	Survey answers	Yes

Response

200 Success

{
  "success": true,
  "data": {
    "id": 3771,
    "personId": 5451,
    "surveyId": 599,
    "status": "completed",
    "consumerEpisodeIntakeId": 9351,
    "assessmentResponse": {
      "firstName": [{"valueString": "Kelly"}],
      "lastName": [{"valueString": "Jill"}],
      "dob": [{"valueString": "1999-11-11"}]
    },
    "createdAt": "2025-04-08T12:30:45Z",
    "updatedAt": "2025-04-08T12:45:22Z"
  }
}

400 BusinessError

404 Not Found

Question Types and Formats

The platform supports various question types to accommodate different data collection needs:

• Text Entry: Short answer, paragraph, email, phone number

• Selection: Multiple choice, checkbox, dropdown, radio button

• Date/Time: Date, time, datetime

• Media: File upload, image

• Numeric: Number, decimal, integer

• Complex: Grid, linear scale, matrix

Survey Response Structure

The SurveyResponse model has the following structure:

interface SurveyResponse {
  id: number;
  surveyId: number;
  personId: number;
  status: "in-progress" | "completed" | "abandoned";
  assessmentResponse: {
    [key: string]: [
      {
        valueString: string | {
          name: string;
          cloudId: string;
          mimeType: string;
        }
      }
    ]
  };
  createdAt: Date;
  updatedAt: Date;
}

Advanced Survey Capabilities

Conditional Logic

The platform supports configuring conditional questions that display or hide based on specific answers. This enables dynamic surveys that adapt to user responses, showing only relevant questions and creating personalized user experiences while maintaining data integrity.

Workflow Integration

Survey statuses and question responses can trigger automated workflows configured through workflow APIs. This allows for streamlined processes such as routing completed surveys to specific providers, generating follow-up tasks, or initiating care pathways based on assessment results.

Audit and Versioning

The system maintains complete audit history tracking for all survey interactions, recording who accessed, modified, or completed surveys. Survey versioning ensures changes are properly tracked while preserving historical data integrity, allowing organizations to analyze trends and improvements over time.