Reports API Documentation

This document provides examples for executing and retrieving reports via the GraphQL API.

Overview

The Reports API consists of two main operations:

executeReport - Initiates a report generation
reportExecution - Retrieves the status and download URL for a generated report

Authentication

All requests require authentication via session headers. Include your API credentials in the request headers.

Mutations

executeReport

Initiates the generation of a report. Reports are processed asynchronously.

Signature:

executeReport(
  params: jsonb!
  type: ReportTypeEnum!
): ExecuteReport

Response Type:

type ExecuteReport {
  createdAt: timestamptz!
  message: String
  reportExecutionId: uuid
  status: ExecuteReportStatusEnum!
}

Queries

reportExecution

Retrieves the status and download URL for a report execution.

Signature:

reportExecution(id: uuid!): ReportExecution

Response Type:

type ReportExecution {
  url: String!
  status: ExecuteReportStatusEnum!
  message: String
}

Status Values:

DONE - Report is ready for download
EXPIRED - Report is expired
FAILED - Report generation failed
PENDING - Report is queued for processing
PROCESSING - Report is currently being generated

Note: Download URLs are valid for 24 hours after report generation.

Report Types

1. Accounts Receivable Report

The AR Report provides a detailed overview of outstanding balances owed to the practice by patients.

Type: ACCOUNTS_RECEIVABLE

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include in the report
referenceDate (date string, format: YYYY-MM-DD) - The date to calculate A/R balances

Example Request:

mutation {
  executeReport(
    type: ACCOUNTS_RECEIVABLE
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      referenceDate: "2026-01-31"
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

Example Response:

{
  "data": {
    "executeReport": {
      "reportExecutionId": "7f3e8c90-1234-5678-90ab-cdef12345678",
      "status": "PENDING",
      "createdAt": "2026-01-31T10:30:00Z",
      "message": null
    }
  }
}

2. Adjustments Report

This Adjustments report details all adjustments and corrections in a given time period, across all your locations.

Type: ADJUSTMENTS

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
startDate (date string, format: YYYY-MM-DD) - Start of date range
endDate (date string, format: YYYY-MM-DD) - End of date range
adjustmentTypeIds (array of strings) - The specific adjustment types to include (DISCOUNT_ADJUSTMENT, DISCOUNT_REVERSE_ADJUSTMENT, FIX_ADJUSTMENT, REFUND, PAYMENT_CORRECTION, WRITE_OFF)

Example Request:

mutation {
  executeReport(
    type: ADJUSTMENTS
    params: {
      locationIds: [
        "550e8400-e29b-41d4-a716-446655440000"
        "660e8400-e29b-41d4-a716-446655440001"
      ]
      startDate: "2026-01-01"
      endDate: "2026-01-31"
      adjustmentTypeIds: ["DISCOUNT_ADJUSTMENT"]
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

3. Cash Flow Report

This report compares expected revenue from invoices with actual collected payments over a chosen date range, helping assess AR performance and cash flow.

Type: CASH_FLOW

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
startDate (date string, format: YYYY-MM-DD) - Start of date range
endDate (date string, format: YYYY-MM-DD) - End of date range
financialPayorTypes (array of strings) - Payor types to include (INSURANCE_PAY, MEDICAID, PRIVATE_PAY)

Example Request:

mutation {
  executeReport(
    type: CASH_FLOW
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      startDate: "2026-01-01"
      endDate: "2026-01-31"
      financialPayorTypes: ["INSURANCE_PAY", "PRIVATE_PAY"]
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

4. Collections Report

The collections report is a summary of payments taken by type. This is totals only. For individual details, please use the transaction report.

Type: COLLECTIONS

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
startDate (date string, format: YYYY-MM-DD) - Start of date range
endDate (date string, format: YYYY-MM-DD) - End of date range
financialPayorTypes (array of strings) - Payor types to include (INSURANCE_PAY, MEDICAID, PRIVATE_PAY)

Example Request:

mutation {
  executeReport(
    type: COLLECTIONS
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      startDate: "2026-01-01"
      endDate: "2026-01-31"
      financialPayorTypes: ["INSURANCE_PAY", "MEDICAID", "PRIVATE_PAY"]
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

5. Financial Report

Provides a comprehensive financial overview of the practice. This report includes production, collections, adjustments, and accounts receivable metrics for a complete financial snapshot.

Type: FINANCIAL

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
referenceDate (date string, format: YYYY-MM-DD) - The date for financial snapshot
financialPayorTypes (array of strings) - Payor types to include (INSURANCE_PAY, MEDICAID, PRIVATE_PAY)

Example Request:

mutation {
  executeReport(
    type: FINANCIAL
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      referenceDate: "2026-01-31"
      financialPayorTypes: ["INSURANCE_PAY", "PRIVATE_PAY"]
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

6. Patient Referrals Report

This report shows which referral sources perform best and worst, including top referring professionals and gross and net production by referral type, to help you improve referral performance.

Type: PATIENT_REFERRALS

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
startDate (date string, format: YYYY-MM-DD) - Start of date range
endDate (date string, format: YYYY-MM-DD) - End of date range

Example Request:

mutation {
  executeReport(
    type: PATIENT_REFERRALS
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      startDate: "2026-01-01"
      endDate: "2026-01-31"
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

7. Practice Efficiency Report

This report shows key timing metrics like wait times, appointment length, provider time, and actual duration to help identify workflow issues and improve scheduling.

Type: PRACTICE_EFFICIENCY

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
startDate (date string, format: YYYY-MM-DD) - Start of date range
endDate (date string, format: YYYY-MM-DD) - End of date range

Example Request:

mutation {
  executeReport(
    type: PRACTICE_EFFICIENCY
    params: {
      locationIds: [
        "550e8400-e29b-41d4-a716-446655440000"
        "660e8400-e29b-41d4-a716-446655440001"
      ]
      startDate: "2026-01-01"
      endDate: "2026-01-31"
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

8. Practice Monitor Report

This report provides a detailed breakdown by location, highlighting production, accounts receivable, and key performance indicators (KPI) Gain insights into performance across multiple locations.

Type: PRACTICE_MONITOR

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
startDate (date string, format: YYYY-MM-DD) - Start of date range
endDate (date string, format: YYYY-MM-DD) - End of date range

Example Request:

mutation {
  executeReport(
    type: PRACTICE_MONITOR
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      startDate: "2026-01-01"
      endDate: "2026-01-31"
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

9. Production by Transaction Date Report

This report lists all production with detailed individual records.

Type: PRODUCTION

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
startDate (date string, format: YYYY-MM-DD) - Start of date range
endDate (date string, format: YYYY-MM-DD) - End of date range
financialPayorTypes (array of strings) - Payor types to include (INSURANCE_PAY, MEDICAID, PRIVATE_PAY)

Example Request:

mutation {
  executeReport(
    type: PRODUCTION
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      startDate: "2026-01-01"
      endDate: "2026-01-31"
      financialPayorTypes: ["INSURANCE_PAY", "PRIVATE_PAY"]
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

10. Token Migration Report

This report identifies payment tokens that need to be migrated to new payment providers, including tokens tied to active payment plans and reusable tokens.

Type: TOKEN_MIGRATION

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
referenceDate (date string, format: YYYY-MM-DD) - The date for migration snapshot

Example Request:

mutation {
  executeReport(
    type: TOKEN_MIGRATION
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      referenceDate: "2026-01-31"
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

11. Treatment Efficiency & Value Report

This report measures how efficiently treatment plans are delivered, comparing expected vs. actual case duration, average fee and value per visit, and the mix of appointment types that make up each plan.

Type: TREATMENT_EFFICIENCY_VALUE

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
startDate (date string, format: YYYY-MM-DD) - Start of date range, matched against the case's completion date
endDate (date string, format: YYYY-MM-DD) - End of date range, matched against the case's completion date

Optional Parameters:

providerIds (array of UUIDs) - Provider(s) to filter by. When omitted, all providers are included
includeVirtualVisits (boolean) - Whether to include virtual visits when counting eligible appointments. Defaults to false
includeEmergencyVisits (boolean) - Whether to include emergency visits when counting eligible appointments. Defaults to false
eligibleAppointmentTypeIds (array of UUIDs) - Appointment type(s) eligible to count toward the visit metrics. When omitted, all non-excluded appointment types are eligible

Example Request:

mutation {
  executeReport(
    type: TREATMENT_EFFICIENCY_VALUE
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      startDate: "2026-01-01"
      endDate: "2026-01-31"
      providerIds: ["770e8400-e29b-41d4-a716-446655440002"]
      includeVirtualVisits: false
      includeEmergencyVisits: false
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

Note: Unlike other reports, this report's output contains three related datasets — summary, appointmentMix, and raw — instead of a single columns/values pair. See Report Output Format below.

12. Transactions Report

The Transaction Report contains detailed records of all financial transactions, including payments, charges, transfers, and more.

Type: TRANSACTIONS

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
startDate (date string, format: YYYY-MM-DD) - Start of date range
endDate (date string, format: YYYY-MM-DD) - End of date range
transactionTypeIds (array of strings) - The specific transaction types to include (APPLIED_PAYMENT, CHARGE_TRANSFER, CORRECTIONS, DISCOUNT_REVERSE, DISCOUNT, FIX_ADJUSTMENT, INSTALLMENT_CHARGE, LATE_FEE, MIGRATION_FIX, MISC_FEE_CHARGE, PAYMENT_PLAN_ROLLBACK, PAYMENT_PLAN, PAYMENT, REFUND, RETAIL_FEE, TRANSFER_CHARGE, TX_FEE_CHARGE, UNAPPLIED_PAYMENT, WRITE_OFF)

Example Request:

mutation {
  executeReport(
    type: TRANSACTIONS
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      startDate: "2026-01-01"
      endDate: "2026-01-31"
      transactionTypeIds: ["TX_FEE_CHARGE", "REFUND"]
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

12. Unapplied Payments Report

This helps you identify payments that haven't been applied to invoices. Use it to apply payments or determine if a refund is due when no outstanding balance.

Type: UNAPPLIED_PAYMENTS

Required Parameters:

locationIds (array of UUIDs) - Location(s) to include
startDate (date string, format: YYYY-MM-DD) - Start of date range
endDate (date string, format: YYYY-MM-DD) - End of date range

Example Request:

mutation {
  executeReport(
    type: UNAPPLIED_PAYMENTS
    params: {
      locationIds: ["550e8400-e29b-41d4-a716-446655440000"]
      startDate: "2026-01-01"
      endDate: "2026-01-31"
    }
  ) {
    reportExecutionId
    status
    createdAt
    message
  }
}

Retrieving Report Results

After executing a report, use the reportExecutionId to check the status and retrieve the download URL.

Example Request:

query {
  reportExecution(id: "<UUID>") {
    status
    url
    message
  }
}

Example Response (Processing):

{
  "data": {
    "reportExecution": {
      "status": "PROCESSING",
      "url": null,
      "message": "Report is being generated"
    }
  }
}

Example Response (Complete):

{
  "data": {
    "reportExecution": {
      "status": "DONE",
      "url": "<url>",
      "message": null
    }
  }
}

Example Response (Failed):

{
  "data": {
    "reportExecution": {
      "status": "FAILED",
      "url": null,
      "message": "<Error Message>"
    }
  }
}

Report Output Format

All reports are returned as JSON files with the following characteristics:

Column Names: camelCase format
Enums/Constants: UPPER_CASE with underscores
Date Format: ISO 8601 (YYYY-MM-DD)
Timestamp Format: ISO 8601 with timezone
Currency Values: Decimal format with 2 decimal places
IDs: UUID format

Example JSON Structure:

{
  "id": "<UUID>",
  "reportType": "financial",
  "columns": [
    "Column1",
    "Column2",
    ...
  ],
  "values": [["Row1Column1Value", "Row1Column2Value", ...], ["Row2Column1Value", "Row2Column2Value", ...], ...],
  "filters": {
    "locations": ["UUID_1","UUID_2"],
    "referenceDate": "YYYY-MM-DD"
  }
}

Date Validation:

endDate cannot be before startDate
date format YYYY-MM-DD

UUID Validation:

All ID parameters must be valid UUIDs
Invalid UUIDs will return a validation error

Rate Limiting

Reports older than 24 hours are automatically deleted

Best Practices

Poll for Results: Poll the reportExecution query every 30-60 seconds until status is DONE or FAILED
Download Promptly: Download reports within 24 hours of generation
Validate Dates: Ensure date ranges are valid before submitting
Handle Failures: Implement retry logic for failed reports
Store Execution IDs: Keep track of reportExecutionId values for audit purposes

Support

For API support or questions, please contact your system administrator or refer to the main API documentation.

Was this helpful?