ECM Form C API (Clinic)

Clinic endpoints for creating and viewing Form C submissions for ECM patients. Form C is a comprehensive ECM assessment form used by care coordinators to document patient needs and care planning.

Overview

Form C submissions are comprehensive assessments that care coordinators complete to document patient health status, social determinants, and care planning priorities. The form contains 23 sections covering various aspects of patient care.

Form C Sections

The form_data field contains the following 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

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": "Jane Coordinator",
        "patient_name": "John Doe",
        "member_id": "MEM0000000001"
      },
      "engagement_purpose": {
        "reason_for_engagement": "Chronic disease management",
        "referral_source": "Health plan"
      },
      "culture": {
        "primary_language": "English",
        "interpreter_needed": false,
        "cultural_considerations": "None identified"
      },
      "health_literacy": {
        "reading_level": "adequate",
        "understanding_instructions": true,
        "needs_assistance": false
      },
      "physical_health": {
        "chronic_conditions": ["Asthma", "Obesity"],
        "current_symptoms": [],
        "pain_level": 0
      },
      "medications": {
        "current_medications": [
          {"name": "Albuterol", "dose": "90mcg", "frequency": "as needed"},
          {"name": "Fluticasone", "dose": "110mcg", "frequency": "twice daily"}
        ],
        "medication_adherence": "good",
        "barriers_to_adherence": []
      },
      "behavioral_health": {
        "mental_health_diagnosis": ["Anxiety"],
        "current_treatment": true,
        "treatment_type": "Therapy"
      },
      "social_determinants": {
        "food_security": true,
        "transportation": true,
        "financial_stability": "moderate",
        "employment_status": "employed"
      },
      "priorities": {
        "patient_goals": ["Manage asthma better", "Reduce anxiety"],
        "care_plan_priorities": ["Medication adherence", "Mental health support"],
        "barriers_to_goals": ["Time constraints"]
      }
    }
  }
}

Success Response


{
  "form_c_submission": {
    "id": 1,
    "patient_id": 123,
    "user_id": 456,
    "form_data": {
      "background_information": { ... },
      "engagement_purpose": { ... },
      "culture": { ... },
      "health_literacy": { ... },
      "physical_health": { ... },
      "medications": { ... },
      "behavioral_health": { ... },
      "social_determinants": { ... },
      "priorities": { ... }
    },
    "created_at": "2024-11-27T12:00:00.000Z",
    "updated_at": "2024-11-27T12:00:00.000Z"
  }
}

List Form C Submissions

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-10-15T10:30:00.000Z"
    }
  ]
}

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

Get Form C Submission Details

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

Example Response


{
  "form_c_submission": {
    "id": 1,
    "patient_id": 123,
    "user_id": 456,
    "user_name": "Jane Coordinator",
    "form_data": {
      "background_information": {
        "date_of_assessment": "2024-11-27",
        "assessor_name": "Jane Coordinator",
        "patient_name": "John Doe",
        "member_id": "MEM0000000001"
      },
      "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"
  }
}

Member ID (CIN)

The member_id field in the background information section corresponds to the patient’s unique ECM identifier. This is sometimes referred to as:

CIN (Client Index Number)
Payer ID (less common)

This identifier is used to match patients across MIF imports and authorization files.

JavaScript Example


// Create Form C submission
const createFormC = async (patientId, formData) => {
  const response = await fetch(
    `/v1/clinic/patients/ecm/form_c_submissions?patient_id=${patientId}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-User-Token': 'YOUR_TOKEN'
      },
      body: JSON.stringify({
        form_c_submission: {
          form_data: formData
        }
      })
    }
  );
  
  return response.json();
};
 
// List Form C submissions
const listFormC = async (patientId) => {
  const response = await fetch(
    `/v1/clinic/patients/ecm/form_c_submissions?patient_id=${patientId}`,
    {
      headers: {
        'X-User-Token': 'YOUR_TOKEN'
      }
    }
  );
  
  return response.json();
};
 
// Get Form C details
const getFormC = async (patientId, submissionId) => {
  const response = await fetch(
    `/v1/clinic/patients/ecm/form_c_submissions/${submissionId}?patient_id=${patientId}`,
    {
      headers: {
        'X-User-Token': 'YOUR_TOKEN'
      }
    }
  );
  
  return response.json();
};
 
// Usage
const formData = {
  background_information: {
    date_of_assessment: '2024-11-27',
    assessor_name: 'Jane Coordinator'
  },
  priorities: {
    patient_goals: ['Manage chronic conditions']
  }
};
 
await createFormC(123, formData);

TypeScript/React Query Example


import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
 
interface FormCData {
  background_information?: Record<string, any>;
  engagement_purpose?: Record<string, any>;
  culture?: Record<string, any>;
  health_literacy?: Record<string, any>;
  // ... other sections
  priorities?: Record<string, any>;
}
 
// List Form C submissions
const useFormCSubmissions = (patientId: number) => {
  return useQuery({
    queryKey: ['patient', patientId, 'formCSubmissions'],
    queryFn: async () => {
      const response = await fetch(
        `/v1/clinic/patients/ecm/form_c_submissions?patient_id=${patientId}`,
        { headers: { 'X-User-Token': token } }
      );
      return response.json();
    }
  });
};
 
// Get Form C details
const useFormCSubmission = (patientId: number, submissionId: number) => {
  return useQuery({
    queryKey: ['patient', patientId, 'formCSubmissions', submissionId],
    queryFn: async () => {
      const response = await fetch(
        `/v1/clinic/patients/ecm/form_c_submissions/${submissionId}?patient_id=${patientId}`,
        { headers: { 'X-User-Token': token } }
      );
      return response.json();
    }
  });
};
 
// Create Form C submission
const useCreateFormC = (patientId: number) => {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async (formData: FormCData) => {
      const response = await 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 } })
        }
      );
      return response.json();
    },
    onSuccess: () => {
      queryClient.invalidateQueries(['patient', patientId, 'formCSubmissions']);
    }
  });
};

cURL Example


# Create Form C submission
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",
          "assessor_name": "Jane Coordinator"
        },
        "priorities": {
          "patient_goals": ["Manage chronic conditions"]
        }
      }
    }
  }'
 
# List Form C submissions
curl -X GET "https://your-api-domain.com/v1/clinic/patients/ecm/form_c_submissions?patient_id=123" \
  -H "X-User-Token: YOUR_TOKEN"
 
# Get Form C details
curl -X GET "https://your-api-domain.com/v1/clinic/patients/ecm/form_c_submissions/1?patient_id=123" \
  -H "X-User-Token: YOUR_TOKEN"

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 over time
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
Member ID: Include the patient’s member_id (CIN) in the background_information section for reference