Form C Submissions API

Endpoints for managing Form C submissions for ECM patients. Form C is a comprehensive ECM assessment form with 23 sections covering various aspects of patient care.

Overview

Form C submissions are comprehensive assessments used to document patient needs, health status, and care planning. The form data is stored as a JSONB object containing 23 distinct sections. Both admin and clinic endpoints are available for managing Form C submissions.

Form C Sections

The form_data field contains the following 23 sections:

Section	Description
`background_information`	Patient background and demographics
`engagement_purpose`	Purpose of ECM engagement
`culture`	Cultural considerations
`health_literacy`	Health literacy assessment
`ed_visits`	Emergency department visit history
`preventive_care`	Preventive care status
`physical_health`	Physical health assessment
`medications`	Medication management
`palliative_care`	Palliative care needs
`behavioral_health`	Behavioral health assessment
`substance_use`	Substance use assessment
`cognitive_function`	Cognitive function evaluation
`safety`	Safety concerns
`activities_of_daily_living`	ADL assessment
`housing_environment`	Housing and environment
`fall_risk`	Fall risk assessment
`medical_equipment`	Medical equipment needs
`social_determinants`	Social determinants of health
`isolation`	Social isolation assessment
`legal_involvement`	Legal involvement status
`eol_planning`	End-of-life planning
`community_ltss_services`	Community and LTSS services
`priorities`	Patient priorities and goals

Admin Endpoints

List All Form C Submissions

Retrieve a list of all Form C submissions across all patients.

Endpoint: GET /v1/admin/clinic/ecm/form_c_submissions
Authentication: Required (Admin role)

Query Parameters

Parameter	Type	Required	Description
`patient_id`	integer	No	Filter by patient ID
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (default: 25)

Example Request


GET /v1/admin/clinic/ecm/form_c_submissions?patient_id=123 HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Example Response


{
  "form_c_submissions": [
    {
      "id": 1,
      "patient_id": 123,
      "patient_name": "John Doe",
      "user_id": 456,
      "user_name": "Jane Coordinator",
      "created_at": "2024-11-27T12:00:00.000Z"
    },
    {
      "id": 2,
      "patient_id": 456,
      "patient_name": "Jane Smith",
      "user_id": 789,
      "user_name": "Bob Manager",
      "created_at": "2024-11-26T10:30:00.000Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 65,
    "per_page": 25
  }
}

Note: The list response intentionally omits form_data and updated_at to reduce data transfer. Use the Show endpoint to retrieve full submission details.

Get Form C Submission Details (Admin)

Retrieve the full details of a specific Form C submission.

Endpoint: GET /v1/admin/clinic/ecm/form_c_submissions/{id}
Authentication: Required (Admin role)

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Form C submission ID

Example Request


GET /v1/admin/clinic/ecm/form_c_submissions/1 HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Example Response


{
  "form_c_submission": {
    "id": 1,
    "patient_id": 123,
    "patient_name": "John Doe",
    "user_id": 456,
    "user_name": "Jane Coordinator",
    "form_data": {
      "background_information": {
        "date_of_assessment": "2024-11-27",
        "assessor_name": "Dr. Smith",
        "patient_name": "John Doe"
      },
      "engagement_purpose": {
        "reason_for_engagement": "Chronic disease management"
      },
      "culture": {
        "primary_language": "English",
        "interpreter_needed": false
      },
      "health_literacy": {
        "reading_level": "adequate",
        "understanding_instructions": true
      },
      "ed_visits": {
        "visits_last_year": 2,
        "reasons": ["Asthma exacerbation", "Anxiety attack"]
      },
      "preventive_care": {
        "last_physical_exam": "2024-06-15",
        "immunizations_current": true
      },
      "physical_health": {
        "chronic_conditions": ["Asthma", "Obesity"],
        "current_symptoms": []
      },
      "medications": {
        "current_medications": ["Albuterol", "Fluticasone"],
        "medication_adherence": "good"
      },
      "palliative_care": {
        "needs_assessment": false
      },
      "behavioral_health": {
        "mental_health_diagnosis": ["Anxiety"],
        "current_treatment": true
      },
      "substance_use": {
        "tobacco_use": false,
        "alcohol_use": false,
        "drug_use": false
      },
      "cognitive_function": {
        "cognitive_concerns": false
      },
      "safety": {
        "safety_concerns": false,
        "domestic_violence_screening": "negative"
      },
      "activities_of_daily_living": {
        "independent": true,
        "assistance_needed": []
      },
      "housing_environment": {
        "housing_status": "stable",
        "housing_type": "apartment"
      },
      "fall_risk": {
        "fall_history": false,
        "fall_risk_level": "low"
      },
      "medical_equipment": {
        "equipment_needed": ["Nebulizer"],
        "equipment_functional": true
      },
      "social_determinants": {
        "food_security": true,
        "transportation": true,
        "financial_stability": "moderate"
      },
      "isolation": {
        "social_support": true,
        "isolation_risk": "low"
      },
      "legal_involvement": {
        "current_legal_issues": false
      },
      "eol_planning": {
        "advance_directive": false,
        "discussed": false
      },
      "community_ltss_services": {
        "current_services": [],
        "services_needed": []
      },
      "priorities": {
        "patient_goals": ["Manage asthma better", "Reduce anxiety"],
        "care_plan_priorities": ["Medication adherence", "Mental health support"]
      }
    },
    "created_at": "2024-11-27T12:00:00.000Z",
    "updated_at": "2024-11-27T12:00:00.000Z"
  }
}

Clinic Endpoints

Create Form C Submission

Create a new Form C submission for a patient.

Endpoint: POST /v1/clinic/patients/ecm/form_c_submissions
Authentication: Required

Query Parameters

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient ID

Request Body Parameters

Parameter	Type	Required	Description
`form_c_submission`	object	Yes	Form C submission data
`form_c_submission.form_data`	object	Yes	Form data with section objects

Example Request


POST /v1/clinic/patients/ecm/form_c_submissions?patient_id=123 HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "form_c_submission": {
    "form_data": {
      "background_information": {
        "date_of_assessment": "2024-11-27",
        "assessor_name": "Dr. Smith",
        "patient_name": "John Doe"
      },
      "engagement_purpose": {
        "reason_for_engagement": "Chronic disease management"
      },
      "culture": {
        "primary_language": "English",
        "interpreter_needed": false
      }
    }
  }
}

Success Response


{
  "form_c_submission": {
    "id": 1,
    "patient_id": 123,
    "user_id": 456,
    "form_data": {
      "background_information": {
        "date_of_assessment": "2024-11-27",
        "assessor_name": "Dr. Smith",
        "patient_name": "John Doe"
      },
      "engagement_purpose": {
        "reason_for_engagement": "Chronic disease management"
      },
      "culture": {
        "primary_language": "English",
        "interpreter_needed": false
      }
    },
    "created_at": "2024-11-27T12:00:00.000Z",
    "updated_at": "2024-11-27T12:00:00.000Z"
  }
}

List Form C Submissions (Patient)

Retrieve a list of Form C submissions for a specific patient.

Endpoint: GET /v1/clinic/patients/ecm/form_c_submissions
Authentication: Required

Query Parameters

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient ID

Example Request


GET /v1/clinic/patients/ecm/form_c_submissions?patient_id=123 HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here

Example Response


{
  "form_c_submissions": [
    {
      "id": 1,
      "patient_id": 123,
      "user_id": 456,
      "created_at": "2024-11-27T12:00:00.000Z"
    },
    {
      "id": 2,
      "patient_id": 123,
      "user_id": 789,
      "created_at": "2024-11-26T10:30:00.000Z"
    }
  ]
}

Get Form C Submission Details (Patient)

Retrieve the full details of a specific Form C submission.

Endpoint: GET /v1/clinic/patients/ecm/form_c_submissions/{id}
Authentication: Required

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Form C submission ID

Query Parameters

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient ID

Example Request


GET /v1/clinic/patients/ecm/form_c_submissions/1?patient_id=123 HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here

JavaScript Example


const formData = {
  background_information: {
    date_of_assessment: '2024-11-27',
    assessor_name: 'Dr. Smith'
  },
  engagement_purpose: {
    reason_for_engagement: 'Chronic disease management'
  }
};
 
fetch('/v1/clinic/patients/ecm/form_c_submissions?patient_id=123', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-User-Token': 'YOUR_TOKEN'
  },
  body: JSON.stringify({
    form_c_submission: {
      form_data: formData
    }
  })
})
.then(response => response.json())
.then(data => console.log(data));

TypeScript/React Query Example


import { useQuery, useMutation } from '@tanstack/react-query';
 
// List Form C submissions for a patient
const { data: submissions } = useQuery({
  queryKey: ['patient', patientId, 'formCSubmissions'],
  queryFn: () => 
    fetch(`/v1/clinic/patients/ecm/form_c_submissions?patient_id=${patientId}`, {
      headers: { 'X-User-Token': token }
    }).then(res => res.json())
});
 
// Get a specific Form C submission
const { data: submission } = useQuery({
  queryKey: ['patient', patientId, 'formCSubmissions', submissionId],
  queryFn: () => 
    fetch(`/v1/clinic/patients/ecm/form_c_submissions/${submissionId}?patient_id=${patientId}`, {
      headers: { 'X-User-Token': token }
    }).then(res => res.json())
});
 
// Create a new Form C submission
const createMutation = useMutation({
  mutationFn: (formData: FormCData) =>
    fetch(`/v1/clinic/patients/ecm/form_c_submissions?patient_id=${patientId}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-User-Token': token
      },
      body: JSON.stringify({ form_c_submission: { form_data: formData } })
    }).then(res => res.json())
});

cURL Example


curl -X POST "https://your-api-domain.com/v1/clinic/patients/ecm/form_c_submissions?patient_id=123" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: YOUR_TOKEN" \
  -d '{
    "form_c_submission": {
      "form_data": {
        "background_information": {
          "date_of_assessment": "2024-11-27"
        }
      }
    }
  }'

Error Responses

404 Not Found


{
  "errors": ["Form C submission not found"]
}

422 Unprocessable Entity


{
  "errors": ["Form data can't be blank"]
}

Best Practices

Complete Sections: While not all sections are required, complete as many as possible for comprehensive documentation
Regular Updates: Create new Form C submissions periodically to track patient progress
Consistent Format: Use consistent data formats within each section
Date Format: Use ISO 8601 format (YYYY-MM-DD) for all date fields
Boolean Fields: Use true/false for boolean fields, not strings
Arrays: Use arrays for fields that can have multiple values (e.g., chronic conditions, medications)