ECM Patients API

Administrative endpoints for managing ECM (Enhanced Care Management) patient records and eligibility information.

List ECM Patients

Get a paginated list of ECM patients with their eligibility information.

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

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination (default: 1)
`per_page`	integer	No	Number of items per page (default: 25)
`search`	string	No	Search term to filter patients by name or member_id
`status`	string	No	Filter by member record status
`provider_id`	integer	No	Filter by assigned provider

Example Request


GET /v1/admin/clinic/ecm/patients?page=1&per_page=25&search=John HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Example Response


{
  "patients": [
    {
      "id": 123,
      "name": "John Doe",
      "date_of_birth": "2010-05-15",
      "ecm_eligibility_information": {
        "id": 456,
        "member_id": "MEM0000000001",
        "cin": "CIN123456",
        "ecm_service_auth_id": "AUTH123456",
        "ecm_provider_name": "Esteem Health PSC",
        "ecm_benefit_auth_eff_date": "2024-01-01",
        "ecm_benefit_auth_end_date": "2024-12-31",
        "acuity_level": "high",
        "member_record_status": "new_member"
      },
      "case_load": {
        "provider_id": 789,
        "provider_name": "Dr. Smith",
        "olcm_user_id": 101,
        "olcm_name": "Jane Coordinator",
        "ilcm_user_id": 102,
        "ilcm_name": "Bob Manager"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 120,
    "per_page": 25
  }
}

Get ECM Patient Details

Retrieve detailed information about a specific ECM patient.

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

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Patient ID

Example Request


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

Example Response


{
  "patient": {
    "id": 123,
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "2010-05-15",
    "gender": "male",
    "address": {
      "street": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001"
    },
    "phone": "+18051234567",
    "email": "[email protected]",
    "services": ["ecm", "clinical"],
    "ecm_eligibility_information": {
      "id": 456,
      "member_id": "MEM0000000001",
      "cin": "CIN123456",
      "ecm_service_auth_id": "AUTH123456",
      "ecm_provider_name": "Esteem Health PSC",
      "ecm_npi": "1234567890",
      "ecm_benefit_auth_eff_date": "2024-01-01",
      "ecm_benefit_auth_end_date": "2024-12-31",
      "acuity_level": "high",
      "member_record_status": "new_member",
      "created_at": "2024-01-15T10:00:00.000Z",
      "updated_at": "2024-01-15T10:00:00.000Z"
    },
    "case_load": {
      "id": 789,
      "provider_id": 101,
      "provider_name": "Dr. Smith",
      "olcm_user_id": 102,
      "olcm_name": "Jane Coordinator",
      "ilcm_user_id": 103,
      "ilcm_name": "Bob Manager"
    },
    "ecm_authorizations": [
      {
        "id": 1,
        "auth_no": "AUTH0000000001",
        "auth_type": "ES",
        "authorization_type": "Form I",
        "status": "Approved",
        "start_date": "2024-01-01",
        "expiration_date": "2024-12-31"
      }
    ],
    "ecm_status_history": [
      {
        "id": 1,
        "status": "new_member",
        "changed_at": "2024-01-15T10:00:00.000Z",
        "changed_by": "System Import"
      }
    ],
    "activities_count": 15,
    "last_activity_at": "2024-11-20T14:30:00.000Z"
  }
}

Update ECM Patient

Update ECM patient information and eligibility data.

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

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	Patient ID

Request Body Parameters

Parameter	Type	Required	Description
`patient`	object	Yes	Patient data object
`patient.first_name`	string	No	Patient first name
`patient.last_name`	string	No	Patient last name
`patient.date_of_birth`	string	No	Date of birth (YYYY-MM-DD)
`patient.ecm_eligibility_information`	object	No	ECM eligibility data
`patient.ecm_eligibility_information.acuity_level`	string	No	Acuity level (low, medium, high)
`patient.ecm_eligibility_information.member_record_status`	string	No	Member record status

Example Request


PUT /v1/admin/clinic/ecm/patients/123 HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "patient": {
    "ecm_eligibility_information": {
      "acuity_level": "high",
      "member_record_status": "continuing_member"
    }
  }
}

Filter ECM Patients

Filter ECM patients with advanced criteria.

Endpoint: POST /v1/admin/clinic/ecm/patients/filter
Authentication: Required (Admin role)

Request Body Parameters

Parameter	Type	Required	Description
`search`	string	No	Search term
`sort_by`	string	No	Field to sort by
`sort_dir`	string	No	Sort direction (“ASC” or “DESC”)
`filters`	object	No	Filter criteria
`filters.status`	string	No	Member record status
`filters.acuity_level`	string	No	Acuity level
`filters.provider_id`	integer	No	Assigned provider ID
`filters.olcm_user_id`	integer	No	Outreach Lead Care Manager ID
`filters.ilcm_user_id`	integer	No	Intensive Lead Care Manager ID
`filters.authorization_status`	string	No	Authorization status
`page`	integer	No	Page number
`per_page`	integer	No	Items per page

Example Request


POST /v1/admin/clinic/ecm/patients/filter HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "search": "John",
  "filters": {
    "status": "new_member",
    "acuity_level": "high",
    "provider_id": 101
  },
  "sort_by": "created_at",
  "sort_dir": "DESC",
  "page": 1,
  "per_page": 25
}

Member Record Status Values

ECM patients can have the following member record statuses:

Status	Description
`new_member`	Newly enrolled ECM member
`continuing_member`	Existing member continuing services
`pending_member`	Member with pending authorization
`terminated_member`	Member whose services have been terminated
`inactive_member`	Member who is temporarily inactive

Acuity Levels

ECM patients are assigned acuity levels based on their care needs:

Level	Description
`low`	Low complexity, minimal care coordination needed
`medium`	Moderate complexity, regular care coordination
`high`	High complexity, intensive care coordination required

Error Responses

403 Forbidden


{
  "errors": ["Admin access required"]
}

404 Not Found


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

422 Unprocessable Entity


{
  "errors": ["Validation failed: Member ID can't be blank"]
}