Usage

The Usage APIs allow you to retrieve information about document retrieval queries for your organization. This data can be used for tracking, reporting, and reconciliation purposes.

Overview

HealthEx tracks document retrieval queries and categorizes them into two types:

• TEFCA queries: Queries made through the TEFCA (Trusted Exchange Framework and Common Agreement) network
• Non-TEFCA queries: Queries made through other supported networks

Authorization

Usage APIs require organization administrator permissions. Only users with the ORG_ADMIN permission can access these endpoints.

Endpoints

Get Usage Summary

Returns aggregate query counts for your organization within a specified date range.

GET https://api.healthex.io/v1/usage/summary?startDate={startDate}&endDate={endDate}
Authorization: Bearer <JWT Token>

Query Parameters

Parameter	Type	Required	Description
startDate	string (ISO 8601)	Yes	Start date for the usage period
endDate	string (ISO 8601)	Yes	End date for the usage period

Example Request

curl -X GET "https://api.healthex.io/v1/usage/summary?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer <JWT Token>"

Example Response

{
  "tefcaQueries": 150,
  "nonTefcaQueries": 75,
  "totalQueries": 225
}

Get Usage Details

Returns paginated patient-level query details for your organization within a specified date range.

GET https://api.healthex.io/v1/usage/details?startDate={startDate}&endDate={endDate}&page={page}&pageSize={pageSize}
Authorization: Bearer <JWT Token>

Query Parameters

Parameter	Type	Required	Description
startDate	string (ISO 8601)	Yes	Start date for the usage period
endDate	string (ISO 8601)	Yes	End date for the usage period
page	number	No	Page number (default: 1)
pageSize	number	No	Results per page (default: 20, max: 100)

Example Request

curl -X GET "https://api.healthex.io/v1/usage/details?startDate=2024-01-01T00:00:00Z&endDate=2024-01-31T23:59:59Z&page=1&pageSize=20" \
  -H "Authorization: Bearer <JWT Token>"

Example Response

{
  "total": 45,
  "page": 1,
  "pageSize": 20,
  "results": [
    {
      "patientId": "patient-uuid-1",
      "referenceIds": [
        "reference-id-1",
        "reference-id-2"
      ],
      "tefcaQueries": 3,
      "nonTefcaQueries": 2
    },
    {
      "patientId": "patient-uuid-2",
      "referenceIds": [],
      "tefcaQueries": 1,
      "nonTefcaQueries": 0
    }
  ]
}

Date Range Limits

• The date range cannot exceed 366 days
• endDate must be after startDate

Error Responses

Status Code	Description
400	Invalid date range (exceeds 366 days or endDate before startDate)
401	Unauthorized - Invalid or missing JWT token
403	Forbidden - User does not have ORG_ADMIN permission