ECM Activities API

Administrative endpoints for viewing and managing ECM patient activities. Activities track all interactions with ECM patients including tasks, notes, SMS, calls, emails, and in-person appointments.

Activity Types

The ECM system supports the following activity types:

Type	Description	Required Fields
`task`	A task assigned to a care coordinator	`message`, `assigned_to_id`
`note`	A general note about the patient	`body`, `assigned_to_id`
`sms`	An SMS message sent to or received from the patient	`body`, `text_message_id`, `assigned_to_id`
`call`	A phone call with the patient	`voice_call_id`, `assigned_to_id`
`email`	An email sent to the patient	`email_to`, `body`, `assigned_to_id`
`in_person_appointment`	An in-person meeting with the patient	`booked_at`, `assigned_to_id`

List Patient Activities

Get a paginated list of activities for a specific ECM patient.

Endpoint: GET /v1/clinic/ecm/patients/{patient_id}/activities
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 for pagination (default: 1)
`page_size`	integer	No	Number of items per page (default: 25)
`activity_type`	string	No	Filter by activity type
`assigned_to_id`	integer	No	Filter by assigned user ID
`status`	string	No	Filter by status (created, complete, cancelled)

Example Request


GET /v1/clinic/ecm/patients/123/activities?activity_type=task&status=created HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here

Example Response


{
  "activities": [
    {
      "id": 1,
      "activity_type": "task",
      "status": "created",
      "message": "Follow up with patient about medication",
      "subject": "Medication Follow-up",
      "body": null,
      "occurred_at": "2024-11-20T10:00:00.000Z",
      "patient_id": 123,
      "patient_name": "John Doe",
      "performed_by_id": 456,
      "performed_by_name": "Jane Coordinator",
      "assigned_to_id": 789,
      "assigned_to_name": "Bob Manager",
      "parent_id": null,
      "comments_count": 2,
      "created_at": "2024-11-20T10:00:00.000Z",
      "updated_at": "2024-11-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 65,
    "per_page": 25
  }
}

Get Activity Details

Retrieve detailed information about a specific activity.

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

Path Parameters

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

Example Request


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

Example Response


{
  "activity": {
    "id": 1,
    "activity_type": "task",
    "status": "created",
    "message": "Follow up with patient about medication",
    "subject": "Medication Follow-up",
    "body": "Need to check if patient has started new medication regimen",
    "occurred_at": "2024-11-20T10:00:00.000Z",
    "booked_at": null,
    "email_to": null,
    "transcript": null,
    "patient_id": 123,
    "patient_name": "John Doe",
    "performed_by_id": 456,
    "performed_by_name": "Jane Coordinator",
    "assigned_to_id": 789,
    "assigned_to_name": "Bob Manager",
    "parent_id": null,
    "blocked_by_id": null,
    "blocking_id": null,
    "voice_call_id": null,
    "text_message_id": null,
    "comments": [
      {
        "id": 1,
        "body": "Called patient, no answer",
        "user_id": 789,
        "user_name": "Bob Manager",
        "created_at": "2024-11-20T14:00:00.000Z"
      }
    ],
    "subtasks": [],
    "event": {
      "id": 1,
      "event_type": "task",
      "occurred_at": "2024-11-20T10:00:00.000Z",
      "status": "created"
    },
    "created_at": "2024-11-20T10:00:00.000Z",
    "updated_at": "2024-11-20T14:00:00.000Z"
  }
}

Create Activity

Create a new activity for an ECM patient.

Endpoint: POST /v1/clinic/ecm/patients/{patient_id}/activities
Authentication: Required

Path Parameters

Parameter	Type	Required	Description
`patient_id`	integer	Yes	Patient ID

Request Body Parameters

Parameter	Type	Required	Description
`activity`	object	Yes	Activity data object
`activity.activity_type`	string	Yes	Type of activity (task, note, sms, call, email, in_person_appointment)
`activity.assigned_to_id`	integer	Yes	User ID of the assignee
`activity.message`	string	Conditional	Task message (required for task type)
`activity.body`	string	Conditional	Activity body content (required for note, sms, email types)
`activity.subject`	string	No	Activity subject line
`activity.email_to`	string	Conditional	Email recipient (required for email type)
`activity.booked_at`	string	Conditional	Appointment date/time (required for in_person_appointment type)
`activity.voice_call_id`	integer	Conditional	Voice call ID (required for call type)
`activity.text_message_id`	integer	Conditional	Text message ID (required for sms type)
`activity.parent_id`	integer	No	Parent task ID for subtasks
`activity.blocked_by_id`	integer	No	ID of blocking activity
`activity.blocking_id`	integer	No	ID of activity this blocks
`activity.occurred_at`	string	No	When the activity occurred (ISO 8601)
`activity.status`	string	No	Activity status (created, complete, cancelled)
`activity.email_attachments`	array	No	Array of attachment URLs for email activities

Example Request - Create Task


POST /v1/clinic/ecm/patients/123/activities HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "activity": {
    "activity_type": "task",
    "assigned_to_id": 789,
    "message": "Schedule follow-up appointment with patient",
    "subject": "Follow-up Scheduling"
  }
}

Example Request - Create Note


POST /v1/clinic/ecm/patients/123/activities HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "activity": {
    "activity_type": "note",
    "assigned_to_id": 789,
    "body": "Patient reported feeling better after starting new medication. Will continue monitoring progress.",
    "subject": "Progress Note"
  }
}

Example Request - Create In-Person Appointment


POST /v1/clinic/ecm/patients/123/activities HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "activity": {
    "activity_type": "in_person_appointment",
    "assigned_to_id": 789,
    "booked_at": "2024-12-01T14:00:00.000Z",
    "subject": "Monthly Check-in",
    "body": "Monthly in-person check-in with patient and family"
  }
}

Example Request - Create Email Activity


POST /v1/clinic/ecm/patients/123/activities HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "activity": {
    "activity_type": "email",
    "assigned_to_id": 789,
    "email_to": "[email protected]",
    "subject": "Care Plan Update",
    "body": "Dear Parent,\n\nWe wanted to update you on your child's care plan...",
    "email_attachments": ["https://storage.example.com/documents/care-plan.pdf"]
  }
}

Success Response


{
  "activity": {
    "id": 2,
    "activity_type": "task",
    "status": "created",
    "message": "Schedule follow-up appointment with patient",
    "subject": "Follow-up Scheduling",
    "patient_id": 123,
    "performed_by_id": 456,
    "assigned_to_id": 789,
    "created_at": "2024-11-21T10:00:00.000Z",
    "updated_at": "2024-11-21T10:00:00.000Z"
  }
}

Update Activity

Update an existing activity.

Endpoint: PUT /v1/clinic/ecm/patients/{patient_id}/activities/{id}
Authentication: Required

Path Parameters

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

Request Body Parameters

Same as Create Activity, all fields optional.

Example Request - Mark Task Complete


PUT /v1/clinic/ecm/patients/123/activities/1 HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "activity": {
    "status": "complete"
  }
}

Delete Activity

Delete an activity.

Endpoint: DELETE /v1/clinic/ecm/patients/{patient_id}/activities/{id}
Authentication: Required

Path Parameters

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

Example Request


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

Success Response


HTTP/1.1 204 No Content

Subtasks

Activities of type task can have subtasks. Subtasks are created by setting the parent_id field to the ID of the parent task.

Example Request - Create Subtask


POST /v1/clinic/ecm/patients/123/activities HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "activity": {
    "activity_type": "task",
    "assigned_to_id": 789,
    "message": "Call patient to confirm appointment time",
    "parent_id": 1
  }
}

Activity Comments

Activities can have comments added by care coordinators.

Activity Comment Fields

Field	Type	Description
`id`	integer	Comment ID
`body`	string	Comment content
`user_id`	integer	ID of user who created the comment
`user_name`	string	Name of user who created the comment
`created_at`	string	When the comment was created

Events

When an activity is created, a corresponding event is automatically generated. Events are used for PRTF report generation and tracking patient encounters.

Event Fields

Field	Type	Description
`id`	integer	Event ID
`event_type`	string	Type of event (matches activity type)
`occurred_at`	string	When the event occurred
`status`	string	Event status
`subject`	string	Event subject
`body`	string	Event body
`duration`	integer	Duration in minutes

Error Responses

404 Not Found - Patient


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

404 Not Found - Activity


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

422 Unprocessable Entity


{
  "errors": ["Message can't be blank", "Assigned to can't be blank"]
}

Notes

All activities are automatically associated with the authenticated user as the performed_by user
Creating an activity automatically creates a corresponding event for PRTF reporting
Email activities will send an actual email to the specified recipient when created
SMS and call activities should be created through the Communications API which handles Twilio integration
Subtasks can only be created under task-type activities