ECM Activities API (Clinic)

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

Overview

ECM activities are the primary way care coordinators document patient interactions. Each activity type has specific required fields and generates corresponding events for PRTF reporting.

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`

Activity Status

Status	Description
`created`	Activity has been created but not completed
`complete`	Activity has been completed
`cancelled`	Activity has been cancelled

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 (default: 1)
`page_size`	integer	No	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": [],
    "twilio_call": null,
    "twilio_sms": null,
    "event": {
      "id": 1,
      "event_type": "task",
      "occurred_at": "2024-11-20T10:00:00.000Z"
    },
    "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
`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
`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)
`activity.parent_id`	integer	No	Parent task ID for subtasks
`activity.occurred_at`	string	No	When the activity occurred (ISO 8601)
`activity.status`	string	No	Activity status

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.",
    "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"
  }
}

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

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

Success Response


HTTP/1.1 204 No Content

Activity Comments

Add comments to activities for additional documentation.

Add Comment

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

Request Body Parameters

Parameter	Type	Required	Description
`comment`	object	Yes	Comment data object
`comment.body`	string	Yes	Comment content

Example Request


POST /v1/clinic/ecm/patients/123/activities/1/comments HTTP/1.1
Content-Type: application/json
X-User-Token: your_token_here
 
{
  "comment": {
    "body": "Called patient, left voicemail. Will try again tomorrow."
  }
}

Success Response


{
  "comment": {
    "id": 2,
    "body": "Called patient, left voicemail. Will try again tomorrow.",
    "user_id": 789,
    "user_name": "Bob Manager",
    "activity_id": 1,
    "created_at": "2024-11-21T15:00:00.000Z"
  }
}

Subtasks

Create subtasks under a parent task activity.

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
  }
}

Subtasks are returned in the subtasks array when viewing the parent activity.

JavaScript Example


// Create a task
const createTask = async (patientId, message, assignedToId) => {
  const response = await fetch(`/v1/clinic/ecm/patients/${patientId}/activities`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-User-Token': 'YOUR_TOKEN'
    },
    body: JSON.stringify({
      activity: {
        activity_type: 'task',
        assigned_to_id: assignedToId,
        message: message
      }
    })
  });
  
  return response.json();
};
 
// Mark activity complete
const completeActivity = async (patientId, activityId) => {
  const response = await fetch(`/v1/clinic/ecm/patients/${patientId}/activities/${activityId}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'X-User-Token': 'YOUR_TOKEN'
    },
    body: JSON.stringify({
      activity: {
        status: 'complete'
      }
    })
  });
  
  return response.json();
};
 
// Add comment
const addComment = async (patientId, activityId, body) => {
  const response = await fetch(`/v1/clinic/ecm/patients/${patientId}/activities/${activityId}/comments`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-User-Token': 'YOUR_TOKEN'
    },
    body: JSON.stringify({
      comment: { body }
    })
  });
  
  return response.json();
};

cURL Examples

Create Task


curl -X POST "https://your-api-domain.com/v1/clinic/ecm/patients/123/activities" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: YOUR_TOKEN" \
  -d '{
    "activity": {
      "activity_type": "task",
      "assigned_to_id": 789,
      "message": "Follow up with patient"
    }
  }'

Mark Complete


curl -X PUT "https://your-api-domain.com/v1/clinic/ecm/patients/123/activities/1" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: YOUR_TOKEN" \
  -d '{
    "activity": {
      "status": "complete"
    }
  }'

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 performed_by
Creating an activity (except notes) automatically creates a corresponding event for PRTF reporting
For SMS and call activities, use the Communications API which handles Twilio integration
Subtasks can only be created under task-type activities
The parent_id must reference an existing task activity