General Questionnaires API

Endpoints for managing questionnaires and surveys.

List Questionnaires

Get a list of available questionnaires.

Endpoint: GET /v1/questionnaires
Authentication: Required

Query Parameters

Example Request

GET /v1/questionnaires?category=screening&active=true HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here

Get Questionnaire Details

Endpoint: GET /v1/questionnaires/{id}
Authentication: Required

Path Parameters

Example Request

GET /v1/questionnaires/123 HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here

Marketing Questionnaires

List Marketing Questionnaires

Get questionnaires used for marketing and outreach.

Endpoint: GET /v1/marketing_questionnaires
Authentication: Not required

Query Parameters

Create Marketing Questionnaire Response

Endpoint: POST /v1/marketing_questionnaires
Authentication: Not required

Request Body Parameters

Example Request

POST /v1/marketing_questionnaires HTTP/1.1
Content-Type: application/json
 
{
  "marketing_questionnaire": {
    "questionnaire_id": 456,
    "email": "[email protected]",
    "responses": [
      {
        "question_id": 1,
        "answer": "Yes"
      },
      {
        "question_id": 2,
        "answer": "Sometimes"
      }
    ]
  }
}

Questionnaire Responses

Create Questionnaire Response

Endpoint: POST /v1/questionnaire_responses
Authentication: Required

Request Body Parameters

Example Request

POST /v1/questionnaire_responses HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "questionnaire_response": {
    "questionnaire_id": 123,
    "patient_id": 1049,
    "responses": [
      {
        "question_id": 1,
        "answer": "Often"
      },
      {
        "question_id": 2,
        "answer": "3"
      }
    ]
  }
}

Update Questionnaire Response

Endpoint: PUT /v1/questionnaire_responses/{id}
Authentication: Required

Path Parameters

Questionnaire Invites

Create Questionnaire Invite

Send an invitation to complete a questionnaire.

Endpoint: POST /v1/questionnaire_invites
Authentication: Required

Request Body Parameters

Example Request

POST /v1/questionnaire_invites HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "questionnaire_invite": {
    "questionnaire_id": 123,
    "patient_id": 1049,
    "email": "[email protected]",
    "due_date": "2023-11-01",
    "message": "Please complete this questionnaire before your next appointment."
  }
}

Response Format

Questionnaire Response

{
  "id": 123,
  "title": "Child Behavior Checklist",
  "description": "Assessment of child behavioral and emotional problems",
  "category": "screening",
  "age_group": "child",
  "estimated_duration": 15,
  "active": true,
  "questions": [
    {
      "id": 1,
      "text": "How often does your child have difficulty concentrating?",
      "type": "multiple_choice",
      "options": ["Never", "Sometimes", "Often", "Always"],
      "required": true
    }
  ],
  "created_at": "2023-10-20T10:00:00.000Z",
  "updated_at": "2023-10-20T10:00:00.000Z"
}

Questionnaire Response Submission

{
  "id": 456,
  "questionnaire_id": 123,
  "patient_id": 1049,
  "status": "completed",
  "score": 25,
  "responses": [
    {
      "question_id": 1,
      "question_text": "How often does your child have difficulty concentrating?",
      "answer": "Often",
      "score": 3
    }
  ],
  "completed_at": "2023-10-27T14:30:00.000Z",
  "created_at": "2023-10-27T14:00:00.000Z"
}

Questionnaire Categories

Common categories include:

• screening - Initial screening questionnaires
• diagnostic - Diagnostic assessment tools
• outcome - Outcome measurement tools
• progress - Progress tracking questionnaires
• satisfaction - Satisfaction surveys
• intake - Intake and registration forms

Question Types

• multiple_choice - Multiple choice questions
• scale - Rating scale questions (1-5, 1-10, etc.)
• text - Free text responses
• yes_no - Yes/No questions
• checkbox - Multiple selection checkboxes
• date - Date input questions

Response Status Values

• started - Response has been started
• in_progress - Response is being completed
• completed - Response has been completed
• submitted - Response has been submitted for review
• reviewed - Response has been reviewed by clinician

Error Responses

422 Unprocessable Entity

{
  "errors": {
    "questionnaire_id": ["can't be blank"],
    "patient_id": ["can't be blank"],
    "responses": ["can't be blank"]
  }
}

404 Not Found

{
  "errors": "Questionnaire not found"
}

Notes

• Marketing questionnaires can be completed without authentication
• Questionnaire invites are sent via email with secure links
• Responses are automatically scored based on questionnaire configuration
• Some questionnaires may have age or demographic restrictions
• Completed questionnaires can be reviewed by authorized clinicians
• Progress tracking questionnaires help monitor treatment outcomes