Skip to Content
Admin APIReports

Admin Reports API

Administrative endpoints for generating reports and analytics.

Weekly Metrics

Get Weekly Metrics

Generate weekly performance metrics.

Endpoint: GET /v1/admin/clinic/reports/weekly_metrics
Authentication: Required (Admin role)

Query Parameters

ParameterTypeRequiredDescription
week_startstringNoStart of week (YYYY-MM-DD)
week_endstringNoEnd of week (YYYY-MM-DD)
provider_idintegerNoFilter by provider ID
departmentstringNoFilter by department

Example Request

GET /v1/admin/clinic/reports/weekly_metrics?week_start=2023-10-23&week_end=2023-10-29 HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Response Format

{
  "week_start": "2023-10-23",
  "week_end": "2023-10-29",
  "metrics": {
    "total_appointments": 125,
    "completed_appointments": 118,
    "cancelled_appointments": 5,
    "no_show_appointments": 2,
    "new_patients": 8,
    "total_revenue": 18750.00,
    "average_session_duration": 52,
    "provider_utilization": 0.85
  },
  "daily_breakdown": [
    {
      "date": "2023-10-23",
      "appointments": 25,
      "revenue": 3750.00
    }
  ]
}

Patient Reports

Patient Follow-up Schedules

Generate follow-up schedule reports for patients.

Endpoint: POST /v1/admin/clinic/reports/patients/follow_up_schedules
Authentication: Required (Admin role)

Request Body Parameters

ParameterTypeRequiredDescription
report_paramsobjectYesReport parameters
report_params.start_datestringYesStart date (YYYY-MM-DD)
report_params.end_datestringYesEnd date (YYYY-MM-DD)
report_params.provider_idsarrayNoArray of provider IDs
report_params.patient_statusstringNoFilter by patient status

Example Request

POST /v1/admin/clinic/reports/patients/follow_up_schedules HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "report_params": {
    "start_date": "2023-10-01",
    "end_date": "2023-10-31",
    "provider_ids": [456, 789],
    "patient_status": "active"
  }
}

Response Format

{
  "report_id": "RPT-2023-001",
  "status": "generating",
  "estimated_completion": "2023-10-27T15:30:00.000Z",
  "download_url": null
}

Provider Reports

Provider Appointments with Rates

Generate provider appointment reports with billing rates.

Endpoint: POST /v1/admin/clinic/reports/providers/appointments_with_rates
Authentication: Required (Admin role)

Request Body Parameters

ParameterTypeRequiredDescription
report_paramsobjectYesReport parameters
report_params.start_datestringYesStart date (YYYY-MM-DD)
report_params.end_datestringYesEnd date (YYYY-MM-DD)
report_params.provider_idsarrayNoArray of provider IDs
report_params.include_ratesbooleanNoInclude billing rates
report_params.group_bystringNoGrouping option

Example Request

POST /v1/admin/clinic/reports/providers/appointments_with_rates HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "report_params": {
    "start_date": "2023-10-01",
    "end_date": "2023-10-31",
    "provider_ids": [456],
    "include_rates": true,
    "group_by": "provider"
  }
}

Response Format

{
  "report_id": "RPT-2023-002",
  "status": "completed",
  "generated_at": "2023-10-27T15:45:00.000Z",
  "download_url": "https://storage.example.com/reports/provider-appointments-2023-002.pdf",
  "summary": {
    "total_appointments": 45,
    "total_revenue": 6750.00,
    "average_rate": 150.00
  }
}

Report Status

Get Report Status

Check the status of a generated report.

Endpoint: GET /v1/admin/clinic/reports/{report_id}/status
Authentication: Required (Admin role)

Path Parameters

ParameterTypeRequiredDescription
report_idstringYesReport ID

Response Format

{
  "report_id": "RPT-2023-001",
  "status": "completed",
  "progress_percentage": 100,
  "generated_at": "2023-10-27T15:45:00.000Z",
  "download_url": "https://storage.example.com/reports/follow-up-schedules-2023-001.pdf",
  "expires_at": "2023-11-27T15:45:00.000Z"
}

Download Report

Download Generated Report

Endpoint: GET /v1/admin/clinic/reports/{report_id}/download
Authentication: Required (Admin role)

Path Parameters

ParameterTypeRequiredDescription
report_idstringYesReport ID

Report Types

Available report types:

  • weekly_metrics - Weekly performance metrics
  • patient_follow_up - Patient follow-up schedules
  • provider_appointments - Provider appointment reports
  • revenue_summary - Revenue and billing summary
  • utilization_report - Provider utilization report
  • outcome_metrics - Patient outcome metrics

Report Status Values

  • queued - Report is queued for generation
  • generating - Report is being generated
  • completed - Report generation completed
  • failed - Report generation failed
  • expired - Report download link has expired

Report Formats

Available report formats:

  • pdf - PDF document
  • excel - Excel spreadsheet
  • csv - Comma-separated values
  • json - JSON data format

Error Responses

403 Forbidden

{
  "errors": "Admin access required"
}

422 Unprocessable Entity

{
  "errors": {
    "start_date": ["can't be blank", "must be a valid date"],
    "end_date": ["must be after start date"]
  }
}

404 Not Found

{
  "errors": "Report not found or expired"
}

Notes

  • All admin report endpoints require administrative privileges
  • Reports are generated asynchronously for large datasets
  • Download links expire after 30 days for security
  • Report generation may take several minutes for large date ranges
  • Multiple report formats are available depending on the report type
  • Reports can be filtered by provider, department, or other criteria
  • Generated reports are stored securely and access is logged
AvailabilityFinancials