PRTF Reports API

Administrative endpoints for generating PRTF (Provider Reporting Template File) reports for ECM patients. PRTF reports are California DHCS-required compliance reports showing ECM patient encounters and activities.

Overview

PRTF reports are generated as CSV files following California DHCS ECM reporting requirements. The reports include patient demographics, engagement status, encounter counts, and outreach information for a specified date range. Generated reports are uploaded to S3 storage and a presigned URL is provided for download.

Generate PRTF Report

Generate a new PRTF report for ECM patients within a specified date range.

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

Request Body Parameters

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date for the reporting period (YYYY-MM-DD)
`end_date`	string	Yes	End date for the reporting period (YYYY-MM-DD)
`provider_npi`	string	No	Filter by specific provider NPI. If not provided, includes all providers
`provider_name`	string	No	Provider name for the report header
`provider_phone`	string	No	Provider phone number for the report header

Example Request


POST /v1/admin/clinic/ecm/prtf_reports HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "start_date": "2024-07-01",
  "end_date": "2024-07-31",
  "provider_npi": "1234567890",
  "provider_name": "Dr. John Smith",
  "provider_phone": "5551234567"
}

Example Request - All Providers


POST /v1/admin/clinic/ecm/prtf_reports HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "start_date": "2024-07-01",
  "end_date": "2024-07-31"
}

Success Response


{
  "message": "PRTF report generated successfully",
  "prtf_report": {
    "id": 1,
    "filename": "PRTF_1234567890_072024_11242024.csv",
    "start_date": "2024-07-01",
    "end_date": "2024-07-31",
    "provider_npi": "1234567890",
    "provider_name": "Dr. John Smith",
    "provider_phone": "5551234567",
    "patient_count": 45,
    "url": "https://s3.amazonaws.com/bucket/path/to/file.csv?X-Amz-Algorithm=...",
    "created_at": "2024-11-24T14:30:00.000Z",
    "created_by_id": 123
  }
}

Error Response


{
  "errors": [
    "start_date and end_date are required",
    "Invalid date format. Use YYYY-MM-DD"
  ]
}

List PRTF Reports

Retrieve a paginated list of all PRTF reports that have been generated.

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

Query Parameters

Parameter	Type	Required	Description
`per_page`	integer	No	Number of items per page (default: 25)
`page`	integer	No	Page number (default: 1)

Example Request


GET /v1/admin/clinic/ecm/prtf_reports?per_page=10 HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Example Response


{
  "prtf_reports": [
    {
      "id": 1,
      "filename": "PRTF_1234567890_072024_11242024.csv",
      "start_date": "2024-07-01",
      "end_date": "2024-07-31",
      "provider_npi": "1234567890",
      "provider_name": "Dr. John Smith",
      "provider_phone": "5551234567",
      "patient_count": 45,
      "file_url": "https://s3.amazonaws.com/bucket/path/to/file.csv?X-Amz-Algorithm=...",
      "created_at": "2024-11-24T14:30:00.000Z",
      "created_by_id": 123
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 25,
    "per_page": 10
  }
}

Response Fields

Field	Type	Description
`id`	integer	Unique identifier for the PRTF report
`filename`	string	Generated filename for the report
`start_date`	string	Start date of the reporting period
`end_date`	string	End date of the reporting period
`provider_npi`	string	Provider NPI (null if report includes all providers)
`provider_name`	string	Provider name used in the report
`provider_phone`	string	Provider phone number used in the report
`patient_count`	integer	Number of patients included in the report
`file_url`	string	Presigned S3 URL to download the report (expires in 30 minutes)
`created_at`	string	Timestamp when the report was generated
`created_by_id`	integer	ID of the user who generated the report

Get PRTF Report Details

Retrieve details of a specific PRTF report.

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

Path Parameters

Parameter	Type	Required	Description
`id`	integer	Yes	PRTF report ID

Example Request


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

Example Response


{
  "prtf_report": {
    "id": 1,
    "filename": "PRTF_1234567890_072024_11242024.csv",
    "start_date": "2024-07-01",
    "end_date": "2024-07-31",
    "provider_npi": "1234567890",
    "provider_name": "Dr. John Smith",
    "provider_phone": "5551234567",
    "patient_count": 45,
    "file_url": "https://s3.amazonaws.com/bucket/path/to/file.csv?X-Amz-Algorithm=...",
    "created_at": "2024-11-24T14:30:00.000Z",
    "created_by_id": 123,
    "created_by_name": "Admin User"
  }
}

PRTF Report Contents

The PRTF report is a CSV file containing approximately 50 columns of data for each ECM patient. The report includes:

Patient Demographics

Member ID (CIN)
Patient name
Date of birth
Gender
Address
Phone number

Eligibility Information

ECM provider name
ECM provider NPI
Authorization dates
Acuity level
Member record status

Engagement Status

Enrollment date
Current status
Status change dates

Encounter Counts

The report tracks encounters within the reporting period:

Encounter Type	Description
Telehealth Encounters	Phone calls and video appointments
In-Person Encounters	Face-to-face appointments
Telehealth Outreach	Phone calls, SMS, and emails
In-Person Outreach	In-person outreach attempts

Event Type Mapping for PRTF

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
`in_person_appointment`	In-Person Encounter, In-Person Outreach

Lead Care Manager Information

oLCM (Outreach Lead Care Manager) name
iLCM (Intensive Lead Care Manager) name

Filename Format

The PRTF report filename follows this format:


PRTF_{PROVIDER_NPI or ALL}_{MMYYYY}_{MMDDYYYY}.csv

Examples:

PRTF_1234567890_072024_11242024.csv - Report for specific provider
PRTF_ALL_072024_11242024.csv - Report for all providers

Report Generation Logic

The PRTF report generation follows these rules:

Patient Selection: Only includes ECM patients who were active during the specified date range
Status History: Only includes patients with status history entries within the date range
Provider Filter: If provider_npi is provided, only patients associated with that provider are included
Event Counting: Counts events (activities) within the date range for each patient
S3 Upload: The generated file is automatically uploaded to S3
URL Generation: A presigned URL is provided for download (expires in 30 minutes)

cURL Example


curl -X POST "https://your-api-domain.com/v1/admin/clinic/ecm/prtf_reports" \
  -H "Content-Type: application/json" \
  -H "X-User-Token: YOUR_TOKEN" \
  -d "{
    \"start_date\": \"2024-07-01\",
    \"end_date\": \"2024-07-31\",
    \"provider_npi\": \"1234567890\",
    \"provider_name\": \"Dr. John Smith\",
    \"provider_phone\": \"5551234567\"
  }"

JavaScript Example


const generatePrtfReport = async () => {
  const response = await fetch('/v1/admin/clinic/ecm/prtf_reports', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-User-Token': 'YOUR_TOKEN'
    },
    body: JSON.stringify({
      start_date: '2024-07-01',
      end_date: '2024-07-31',
      provider_npi: '1234567890',
      provider_name: 'Dr. John Smith',
      provider_phone: '5551234567'
    })
  });
  
  const data = await response.json();
  
  if (data.prtf_report && data.prtf_report.url) {
    // Download the report
    window.open(data.prtf_report.url, '_blank');
  }
  
  return data;
};

Error Responses

403 Forbidden


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

404 Not Found


{
  "errors": ["PRTF report not found"]
}

422 Unprocessable Entity


{
  "errors": [
    "start_date and end_date are required",
    "Invalid date format. Use YYYY-MM-DD",
    "end_date must be after start_date"
  ]
}

Best Practices

Date Range: Use monthly date ranges for standard DHCS reporting
Provider Filter: Generate separate reports per provider for easier tracking
Download Promptly: Presigned URLs expire after 30 minutes
Regular Generation: Generate reports on a regular schedule (monthly recommended)
Verification: Review patient counts to ensure all expected patients are included
Activity Tracking: Ensure all patient activities are properly documented before generating reports