Skip to Content
Admin APIFinancials

Admin Financials API

Administrative endpoints for managing financial data and billing information.

Financial Appointments

List Financial Appointments

Get appointments with financial/billing information.

Endpoint: GET /v1/admin/clinic/financials/appointments
Authentication: Required (Admin role)

Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number for pagination
page_sizeintegerNoNumber of items per page
start_datestringNoStart date filter (YYYY-MM-DD)
end_datestringNoEnd date filter (YYYY-MM-DD)
provider_idintegerNoFilter by provider ID
billing_statusstringNoFilter by billing status
payment_statusstringNoFilter by payment status

Example Request

GET /v1/admin/clinic/financials/appointments?start_date=2023-10-01&end_date=2023-10-31&billing_status=billed HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here

Filter Financial Appointments

Endpoint: POST /v1/admin/clinic/financials/appointments/filter_appointments
Authentication: Required (Admin role)

Request Body Parameters

ParameterTypeRequiredDescription
searchstringNoSearch term
sort_bystringNoField to sort by
sort_dirstringNoSort direction
filtersobjectNoFilter criteria with available parameters: date (object with start_date/end_date), status (string), appointment_type (string), insurance_plan_id (integer), provider_name (string)
page_sizeintegerNoNumber of items per page

Example Request

POST /v1/admin/clinic/financials/appointments/filter_appointments HTTP/1.1
Content-Type: application/json
X-User-Token: your_admin_token_here
 
{
  "search": "therapy",
  "filters": {
    "billing_status": "pending",
    "amount_range": {
      "min": 100,
      "max": 200
    },
    "insurance_type": "commercial"
  },
  "sort_by": "service_date",
  "sort_dir": "DESC",
  "page_size": 50
}

Response Format

Financial Appointment Response

{
  "id": 789,
  "patient_id": 1049,
  "provider_id": 456,
  "scheduled_at": "2023-10-27T14:30:00.000Z",
  "service_date": "2023-10-27",
  "status": "completed",
  "billing_status": "billed",
  "payment_status": "paid",
  "financial_details": {
    "cpt_code": "90834",
    "diagnosis_codes": ["F41.1"],
    "billed_amount": 150.00,
    "allowed_amount": 120.00,
    "patient_responsibility": 30.00,
    "insurance_payment": 90.00,
    "adjustment_amount": 30.00
  },
  "insurance_info": {
    "primary_insurance": "Blue Cross Blue Shield",
    "policy_number": "ABC123456789",
    "group_number": "GRP001"
  },
  "created_at": "2023-10-20T10:00:00.000Z",
  "updated_at": "2023-10-28T16:00:00.000Z"
}

Billing Status Values

  • pending - Appointment completed, billing pending
  • billed - Claim has been submitted to insurance
  • paid - Payment has been received
  • denied - Claim was denied by insurance
  • partial_payment - Partial payment received
  • write_off - Amount written off
  • patient_balance - Patient owes balance

Payment Status Values

  • unpaid - No payment received
  • partial - Partial payment received
  • paid_in_full - Full payment received
  • overpaid - Overpayment received
  • refunded - Payment was refunded
  • disputed - Payment is disputed

Insurance Types

  • commercial - Commercial insurance
  • medicare - Medicare
  • medicaid - Medicaid
  • self_pay - Self-pay/uninsured
  • workers_comp - Workers’ compensation
  • other - Other insurance type

Financial Metrics

Revenue Summary

{
  "total_billed": 15000.00,
  "total_collected": 12500.00,
  "total_adjustments": 2000.00,
  "total_write_offs": 500.00,
  "collection_rate": 0.833,
  "average_reimbursement": 125.00
}

Aging Report

{
  "current": 5000.00,
  "30_days": 2000.00,
  "60_days": 1000.00,
  "90_days": 500.00,
  "over_90_days": 250.00
}

Error Responses

403 Forbidden

{
  "errors": "Admin access required"
}

422 Unprocessable Entity

{
  "errors": {
    "start_date": ["must be a valid date"],
    "end_date": ["must be after start date"],
    "amount_range": ["min must be less than max"]
  }
}

404 Not Found

{
  "errors": "Financial record not found"
}

Notes

  • All admin financial endpoints require administrative privileges
  • Financial data includes billing amounts, payments, and adjustments
  • Insurance information is included for billing and claims processing
  • Aging reports help track outstanding receivables
  • Collection rates and metrics support financial analysis
  • Payment status tracking helps with revenue cycle management
  • All financial data is handled with appropriate security measures
  • Reports can be filtered by multiple financial criteria
ReportsUsers