ECM Events API

Clinic endpoints for viewing ECM events. Events are automatically generated from activities and are used for PRTF (Provider Reporting Template File) report generation.

Overview

ECM events represent patient encounters and interactions that are tracked for compliance reporting. Events are automatically created when activities are created, and they contain the data needed for PRTF report generation.

Event Types

The ECM system supports the following event types:

Event Type	Description	Generated From
`sms`	SMS communication event	SMS activity
`call`	Phone call event	Call activity
`task`	Task completion event	Task activity
`email`	Email communication event	Email activity
`appointment`	Appointment event	In-person appointment activity
`meeting`	Meeting event	Meeting activity

Event to PRTF Mapping

Events are categorized for PRTF reporting as follows:

Event Type	PRTF Category
`call`	Telehealth Encounter / Telehealth Outreach
`appointment`	Telehealth Encounter / In-Person Encounter
`sms`	Telehealth Outreach
`email`	Telehealth Outreach
`meeting`	In-Person Encounter
`task`	Counted separately

List Patient Events

Get a list of events for a specific ECM patient.

Endpoint: GET /v1/clinic/ecm/patients/{patient_id}/events
Authentication: Required

Path Parameters

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient ID

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Items per page (default: 25)
`event_type`	string	No	Filter by event type
`start_date`	string	No	Filter events after this date (YYYY-MM-DD)
`end_date`	string	No	Filter events before this date (YYYY-MM-DD)

Example Request


GET /v1/clinic/ecm/patients/123/events?event_type=call&start_date=2024-11-01&end_date=2024-11-30 HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here

Example Response


{
  "events": [
    {
      "id": 1,
      "event_type": "call",
      "occurred_at": "2024-11-20T10:00:00.000Z",
      "subject": "Follow-up call",
      "body": "Called patient to discuss medication adherence",
      "duration": 15,
      "status": "complete",
      "patient_id": 123,
      "patient_name": "John Doe",
      "activity_id": 456,
      "created_at": "2024-11-20T10:00:00.000Z",
      "updated_at": "2024-11-20T10:15:00.000Z"
    },
    {
      "id": 2,
      "event_type": "sms",
      "occurred_at": "2024-11-18T14:30:00.000Z",
      "subject": "Appointment reminder",
      "body": "Reminder: Your appointment is tomorrow at 2pm",
      "duration": null,
      "status": "complete",
      "patient_id": 123,
      "patient_name": "John Doe",
      "activity_id": 457,
      "created_at": "2024-11-18T14:30:00.000Z",
      "updated_at": "2024-11-18T14:30:00.000Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 2,
    "total_count": 35,
    "per_page": 25
  }
}

Get Event Details

Retrieve detailed information about a specific event.

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

Path Parameters

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient ID
`id`	integer	Yes	Event ID

Example Request


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

Example Response


{
  "event": {
    "id": 1,
    "event_type": "call",
    "occurred_at": "2024-11-20T10:00:00.000Z",
    "subject": "Follow-up call",
    "body": "Called patient to discuss medication adherence. Patient reported taking medications as prescribed.",
    "duration": 15,
    "status": "complete",
    "patient_id": 123,
    "patient_name": "John Doe",
    "activity_id": 456,
    "activity": {
      "id": 456,
      "activity_type": "call",
      "status": "complete",
      "performed_by_id": 789,
      "performed_by_name": "Jane Coordinator",
      "assigned_to_id": 789,
      "assigned_to_name": "Jane Coordinator"
    },
    "created_at": "2024-11-20T10:00:00.000Z",
    "updated_at": "2024-11-20T10:15:00.000Z"
  }
}

Event Counts

Get event counts for a patient within a date range. This is useful for generating summary reports.

Endpoint: GET /v1/clinic/ecm/patients/{patient_id}/events/counts
Authentication: Required

Path Parameters

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient ID

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date (YYYY-MM-DD)
`end_date`	string	Yes	End date (YYYY-MM-DD)

Example Request


GET /v1/clinic/ecm/patients/123/events/counts?start_date=2024-11-01&end_date=2024-11-30 HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here

Example Response


{
  "patient_id": 123,
  "start_date": "2024-11-01",
  "end_date": "2024-11-30",
  "counts": {
    "total": 25,
    "by_type": {
      "sms": 10,
      "call": 8,
      "email": 3,
      "appointment": 2,
      "task": 2,
      "meeting": 0
    },
    "prtf_categories": {
      "telehealth_encounters": 10,
      "in_person_encounters": 2,
      "telehealth_outreach": 21,
      "in_person_outreach": 0
    }
  }
}

Event Fields

Field	Type	Description
`id`	integer	Unique event identifier
`event_type`	string	Type of event (sms, call, task, email, appointment, meeting)
`occurred_at`	string	When the event occurred (ISO 8601)
`subject`	string	Event subject/title
`body`	string	Event description/content
`duration`	integer	Duration in minutes (for calls and appointments)
`status`	string	Event status
`patient_id`	integer	Associated patient ID
`activity_id`	integer	Associated activity ID
`created_at`	string	When the event was created
`updated_at`	string	When the event was last updated

Automatic Event Generation

Events are automatically generated when activities are created. The mapping is:

Activity Type	Event Type
`task`	`task`
`note`	No event generated
`sms`	`sms`
`call`	`call`
`email`	`email`
`in_person_appointment`	`appointment`

Note: Note-type activities do not generate events as they are internal documentation and not patient encounters.

JavaScript Example


// List patient events
const getPatientEvents = async (patientId, startDate, endDate) => {
  const params = new URLSearchParams({
    start_date: startDate,
    end_date: endDate
  });
  
  const response = await fetch(
    `/v1/clinic/ecm/patients/${patientId}/events?${params}`,
    {
      headers: {
        'X-User-Token': 'YOUR_TOKEN'
      }
    }
  );
  
  return response.json();
};
 
// Get event counts
const getEventCounts = async (patientId, startDate, endDate) => {
  const params = new URLSearchParams({
    start_date: startDate,
    end_date: endDate
  });
  
  const response = await fetch(
    `/v1/clinic/ecm/patients/${patientId}/events/counts?${params}`,
    {
      headers: {
        'X-User-Token': 'YOUR_TOKEN'
      }
    }
  );
  
  return response.json();
};
 
// Usage
const events = await getPatientEvents(123, '2024-11-01', '2024-11-30');
const counts = await getEventCounts(123, '2024-11-01', '2024-11-30');

cURL Example


# List patient events
curl -X GET "https://your-api-domain.com/v1/clinic/ecm/patients/123/events?start_date=2024-11-01&end_date=2024-11-30" \
  -H "X-User-Token: YOUR_TOKEN"
 
# Get event counts
curl -X GET "https://your-api-domain.com/v1/clinic/ecm/patients/123/events/counts?start_date=2024-11-01&end_date=2024-11-30" \
  -H "X-User-Token: YOUR_TOKEN"

Error Responses

404 Not Found - Patient


{
  "errors": ["Patient not found"]
}

404 Not Found - Event


{
  "errors": ["Event not found"]
}

422 Unprocessable Entity


{
  "errors": ["start_date and end_date are required"]
}

Best Practices

Date Filtering: Always use date filters when listing events to improve performance
PRTF Alignment: Use event counts to verify data before generating PRTF reports
Activity Association: Events are always linked to activities - use the activity for full details
Duration Tracking: Ensure call and appointment durations are recorded for accurate reporting
Regular Review: Review event counts regularly to ensure all patient interactions are being tracked