openapi: 3.1.0
info:
title: HHAeXchange FHIR API
description: |
## APIs
**Internal (Provider)** — Returns base URL, provider and user details, environment, and validation in one call. Use when you need to resolve provider context for a client.
**Internal (Generic References)** — Returns generic reference data from HHA database by CompanyID and ReferenceType. Use when you need to fetch reference codes and values for a specific provider and reference category.
**Internal (Payer)** — Validates ClientId and XApiKey and returns payer context for **FhirAggregator** or **FhirPayer** clients (first active ClientMappings row by lowest Id). **FhirProvider** clients receive **400** with **ProviderTaxId is required** (use Internal Provider). **PayerId** and **Validation.PayerID** are **AgencyId**. BaseUrl is always null.
**Onboarding API** — Create, Read, Update, and Migrate FHIR clients. Manages client configuration, agency mappings, and API keys.
**Configuration (Rate limits)** — Read per-client/agency/env rate limit configuration.
## Authentication
**OAuth2 (Bearer)** — Obtain an access token using the client credentials flow from the token endpoint. Send it in the request header as `Authorization: Bearer <token>`. API Gateway validates the token before the request reaches the API.
version: 0.1.0
servers:
- url: https://api.hhaexchange.com
description: HHAeXchange FHIR API
paths:
/v1/fhir-onboarding/client:
post:
tags:
- Onboarding
summary: Create Client (Onboarding)
description: >-
Onboard a new FHIR client (same endpoint for all client types). Generates
ClientId and ClientSecret; ClientSecret is returned once. In Swagger, open
**Request body** → **Examples** and choose **FhirProvider** (Agencies payload)
or **FhirPayer** (Payer payload) to load the matching JSON.
operationId: create_client_v1_fhir_onboarding_client_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClientCreateRequest'
examples:
FhirProvider:
summary: FhirProvider
description: >-
Provider-style onboarding: **Agencies** array (VendorID per row);
optional Env and rate limits.
value:
ClientName: Client 1
ClientType: FhirProvider
Agencies:
- AgencyId: 123
Env: app
RateLimit: 50
RateLimitWindow: Minute
- AgencyId: 678
- AgencyId: 789
Env: cloud
RateLimit: 50
RateLimitWindow: Minute
Description: HHAx Client
FhirPayer:
summary: FhirPayer
description: >-
Payer onboarding: exactly one object in **Payer** (PayerId = ChhaID;
stored as ClientMappings.AgencyId).
value:
ClientName: Client 1
ClientType: FhirPayer
Payer:
- PayerId: 789
Env: cloud
RateLimit: 50
RateLimitWindow: Minute
Description: HHAx Client
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ClientCreateResponseWrapper'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- bearerAuth:
- full_access
/v1/fhir-onboarding/client/migrate:
post:
tags:
- Onboarding
summary: Migrate Client (Data Migration)
description: >-
Migrate one client with provided ClientId, XApiKey, and agencies. Creates
FHIR.Clients, HHA users, and FHIR.ClientMappings. No AWS key creation, no
IDP write.
operationId: migrate_client_v1_fhir_onboarding_client_migrate_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClientMigrateRequest'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ClientMigrateResponseWrapper'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- bearerAuth:
- full_access
/v1/fhir-onboarding/client/{client_id}:
get:
tags:
- Onboarding
summary: Get Client Onboarding Details
description: Retrieve the complete onboarding configuration for an existing FHIR client.
operationId: get_client_v1_fhir_onboarding_client__client_id__get
parameters:
- name: client_id
in: path
required: true
description: Unique identifier of the client whose onboarding details are to be retrieved
example: 9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45
schema:
type: string
description: Unique identifier of the client whose onboarding details are to be retrieved
title: Client Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ClientOnboardingResponseWrapper'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- bearerAuth:
- full_access
patch:
tags:
- Onboarding
summary: Update Client Onboarding Details
description: >-
Update the onboarding configuration of an existing FHIR client. Use
**Agencies** for FhirProvider / FhirAggregator / FhirThirdParty mapping
updates, or **Payer** (exactly one item) for **FhirPayer** clients. In
Swagger, open **Request body** → **Examples** to load provider vs payer
sample JSON.
operationId: update_client_v1_fhir_onboarding_client__client_id__patch
parameters:
- name: client_id
in: path
required: true
description: Unique identifier of the client whose onboarding configuration is being updated
example: 9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45
schema:
type: string
description: Unique identifier of the client whose onboarding configuration is being updated
title: Client Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClientUpdateRequest'
examples:
FhirProvider:
summary: FhirProvider / Aggregator / ThirdParty
description: Mapping update via **Agencies**; stored ClientType must not be FhirPayer.
value:
Description: HHAx Client
Agencies:
- AgencyId: 123
Env: app
RateLimit: 100
RateLimitWindow: Second
- AgencyId: 678
RateLimitingPlan: Premium
Status: Inactive
FhirPayer:
summary: FhirPayer
description: 'Payer mapping update: exactly one object in **Payer** (PayerId = ChhaID).'
value:
Description: HHAx Client
Payer:
- PayerId: 789
Env: cloud
RateLimit: 80
RateLimitWindow: Second
RateLimitingPlan: Basic
Status: Active
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ClientUpdateResponseWrapper'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- bearerAuth:
- full_access
/v1/internal/provider:
get:
tags:
- Internal
summary: Get provider details
description: >-
Returns base URL, provider and user details, environment, and validation.
Client ID, API key, and ProviderTaxId are required. Environment and HHA
session use ClientMappings.Env for the resolved agency. AppVersionId is
optional; when omitted, BaseUrl, ProviderVersion, and ProviderMinorVersion
are null; ProviderId is the resolved VendorID (same as Validation.VendorID).
operationId: get_provider_v1_internal_provider_get
parameters:
- name: ClientId
in: query
required: true
description: Client ID (mandatory)
schema:
type: string
description: Client ID (mandatory)
title: Clientid
- name: XApiKey
in: query
required: true
description: API key (mandatory)
schema:
type: string
description: API key (mandatory)
title: Xapikey
- name: ProviderTaxId
in: query
required: false
description: Provider tax ID (mandatory; resolves agency and mapping env)
schema:
anyOf:
- type: string
- type: 'null'
description: Provider tax ID (mandatory; resolves agency and mapping env)
title: Providertaxid
- name: AppVersionId
in: query
required: false
description: One or more app version IDs (optional; default [35]) for URL lookup.
schema:
anyOf:
- type: array
items:
type: integer
- type: 'null'
description: One or more app version IDs (optional; default [35]) for URL lookup.
title: Appversionid
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProviderDetailsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- bearerAuth:
- full_access
/v1/internal/generic-references:
get:
tags:
- Internal
summary: Get generic references
description: >-
Returns generic references from HHA GenericReferences table by CompanyID
(ProviderId/VendorId) and ReferenceType. Client ID and API key are required
for authentication and to determine the correct HHA database environment.
Returns all active reference records matching the specified CompanyID and
ReferenceType.
operationId: get_generic_references_v1_internal_generic_references_get
parameters:
- name: ClientId
in: query
required: true
description: Client ID (mandatory)
schema:
type: string
description: Client ID (mandatory)
title: Clientid
- name: XApiKey
in: query
required: true
description: API key (mandatory)
schema:
type: string
description: API key (mandatory)
title: Xapikey
- name: ProviderId
in: query
required: true
description: Provider ID / Vendor ID (CompanyID) (mandatory)
schema:
type: integer
description: Provider ID / Vendor ID (CompanyID) (mandatory)
title: Providerid
- name: ReferenceType
in: query
required: true
description: Reference type (e.g., 'EmergencyContactRelationship') (mandatory)
schema:
type: string
description: Reference type (e.g., 'EmergencyContactRelationship') (mandatory)
title: Referencetype
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/GenericReferencesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- bearerAuth:
- full_access
/v1/internal/payer:
get:
tags:
- Internal
summary: Get payer details (FHIR Aggregator or FhirPayer)
description: >-
Validates ClientId and XApiKey against FHIR.Clients. The client must have
ClientType FhirAggregator or FhirPayer. FhirProvider clients receive **400**
with "ProviderTaxId is required" (use GET /v1/internal/provider). Returns the
first active ClientMappings row (lowest Id): PayerId and Validation.PayerID
are AgencyId (payer/agency in HHA), and Environment is derived from the
mapping Env. BaseUrl is always null.
operationId: get_payer_v1_internal_payer_get
parameters:
- name: ClientId
in: query
required: true
description: Client ID (mandatory)
schema:
type: string
description: Client ID (mandatory)
title: Clientid
- name: XApiKey
in: query
required: true
description: API key (mandatory)
schema:
type: string
description: API key (mandatory)
title: Xapikey
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PayerDetailsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- bearerAuth:
- full_access
/v1/rate-limits/config:
get:
tags:
- Configuration
summary: Get Rate Limit Configuration
description: >-
Retrieve the rate limit configuration for a specific client, agency, and
environment combination. The triple (ClientId, AgencyId, Env) uniquely
identifies one ClientMapping row on SB/PROD. On QA/IMPL (single HHA mirror),
the resolved mapping may use a different stored Env than the query parameter;
see response `Data.Env`. Returns the per-second or per-minute request limit
stored on that mapping. Falls back to application defaults (50 / Minute) when
no explicit configuration has been saved.
operationId: get_rate_limit_config_v1_rate_limits_config_get
parameters:
- name: ClientId
in: query
required: false
description: >-
FHIR client UUID (required). Example:
9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45
schema:
anyOf:
- type: string
- type: 'null'
description: >-
FHIR client UUID (required). Example:
9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45
title: Clientid
- name: AgencyId
in: query
required: false
description: Agency (vendor) identifier — required; must be a positive integer
schema:
anyOf:
- type: string
- type: 'null'
description: Agency (vendor) identifier — required; must be a positive integer
title: Agencyid
- name: Env
in: query
required: false
description: 'HHA environment (required): app, app2, or cloud'
schema:
anyOf:
- type: string
- type: 'null'
description: 'HHA environment (required): app, app2, or cloud'
title: Env
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RateLimitConfigResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- bearerAuth:
- full_access
components:
schemas:
AgencyOnboardingInput:
type: object
required:
- AgencyId
title: AgencyOnboardingInput
description: |
One agency item used by onboarding, migrate, and update requests.
Field requirements:
- `AgencyId` is **required** (positive integer; agency/vendor identifier).
- `Env` is **optional**. When omitted, the server discovers the HHA tier
that owns this agency by probing the configured HHA databases
(app, app2, cloud) in order.
- `RateLimit` / `RateLimitWindow` are **optional**. Defaults to 50 / Minute.
properties:
AgencyId:
type: integer
exclusiveMinimum: 0
title: Agencyid
description: Agency (vendor) identifier. Required; must be a positive integer.
Env:
anyOf:
- type: string
- type: 'null'
title: Env
description: >-
Optional HHA environment (app, app2, cloud), case-insensitive, no
leading or trailing spaces. When omitted or empty, the server discovers
the tier from HHA databases.
RateLimit:
anyOf:
- type: integer
- type: 'null'
title: Ratelimit
description: >-
Allowed requests per RateLimitWindow. Defaults to 50 when omitted. Must
be a positive integer when provided (validated on write).
RateLimitWindow:
anyOf:
- type: string
- type: 'null'
title: Ratelimitwindow
description: >-
Rate window granularity: Second or Minute (case-insensitive). Defaults to
Minute when omitted (validated on write).
AgencyRateLimitDetail:
type: object
required:
- AgencyId
- RateLimit
title: AgencyRateLimitDetail
description: Per-agency portion of the rate limit config response.
properties:
AgencyId:
type: integer
title: Agencyid
description: Agency (vendor) identifier
RateLimit:
type: integer
title: Ratelimit
description: Allowed requests per RateLimitWindow
AgencyUser:
type: object
required:
- UserId
- UserName
- AgencyId
- RateLimit
- RateLimitWindow
title: AgencyUser
description: >-
Agency row in onboarding responses: user + mapping env + rate limit fields
(response-only).
properties:
UserId:
type: integer
title: Userid
description: System-generated HHA user ID
UserName:
type: string
title: Username
description: System-generated user name
AgencyId:
type: integer
title: Agencyid
description: Agency identifier
Env:
anyOf:
- type: string
- type: 'null'
title: Env
description: HHA environment stored on this mapping (app, app2, cloud)
ProviderTaxId:
anyOf:
- type: string
- type: 'null'
title: Providertaxid
description: Federal tax number from HHA for this agency in this Env (response only)
RateLimit:
type: integer
title: Ratelimit
description: Allowed requests per RateLimitWindow for this agency
RateLimitWindow:
type: string
enum:
- Second
- Minute
title: Ratelimitwindow
description: Rate window granularity (Second, Minute)
ClientCreateRequest:
type: object
required:
- ClientName
- ClientType
title: ClientCreateRequest
description: |
Request schema for creating (onboarding) a new FHIR client.
Use `Agencies` for **FhirProvider** / **FhirAggregator** / **FhirThirdParty**.
Use `Payer` (exactly one item) for **FhirPayer** only; do not send `Agencies` for payers.
properties:
ClientName:
type: string
minLength: 1
title: Clientname
description: Name of the client
ClientType:
type: string
enum:
- FhirProvider
- FhirAggregator
- FhirThirdParty
- FhirPayer
title: Clienttype
description: Type of FHIR client (FhirProvider, FhirAggregator, FhirThirdParty, FhirPayer)
Agencies:
anyOf:
- type: array
items:
$ref: '#/components/schemas/AgencyOnboardingInput'
- type: 'null'
title: Agencies
description: >-
Agencies to map for non-payer client types; each row may set Env or rely
on multi-env discovery (dbo.Vendors). Required unless ClientType is
FhirPayer.
Payer:
anyOf:
- type: array
items:
$ref: '#/components/schemas/PayerOnboardingInput'
- type: 'null'
title: Payer
description: >-
Payer rows for ClientType FhirPayer only: exactly one item with PayerId
(optional Env, RateLimit, RateLimitWindow).
Description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Client description
ClientCreateResponse:
type: object
required:
- ClientId
- ClientName
- ClientSecret
- ClientType
- Status
- RateLimitingPlan
title: ClientCreateResponse
description: Response schema for client create (onboarding) — ClientSecret plus AgencyUsers or PayerUser.
example:
AgencyUsers:
- AgencyId: 123
Env: app
ProviderTaxId: 12-3456789
RateLimit: 50
RateLimitWindow: Minute
UserId: -6789
UserName: FHIRAPIUser_1_123
- AgencyId: 678
Env: app2
RateLimit: 50
RateLimitWindow: Minute
UserId: -4567
UserName: FHIRAPIUser_1_678
- AgencyId: 789
Env: cloud
RateLimit: 100
RateLimitWindow: Second
UserId: -8765
UserName: FHIRAPIUser_1_789
ClientId: 9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45
ClientName: Client 1
ClientSecret: 3f9c7a21-82b4-4c91-a8e7-6b4f2c9a1d78
ClientType: FhirProvider
CreatedAt: '2026-01-12T07:45:30Z'
Description: HHAx Client
RateLimitingPlan: Basic
Status: Active
XApiKey: brcRWv6qZQanfxwoZYvuYpMpfTUsvxEnkli2n998
properties:
ClientId:
type: string
title: Clientid
description: Unique client identifier (UUID)
ClientName:
type: string
title: Clientname
description: Name of the client
ClientSecret:
type: string
title: Clientsecret
description: Generated client secret (UUID) - store securely; not persisted in FHIR DB
ClientType:
type: string
title: Clienttype
description: Type of FHIR client
Description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Client description
Status:
type: string
title: Status
description: Client status (Active/Inactive)
AgencyUsers:
anyOf:
- type: array
items:
$ref: '#/components/schemas/AgencyUser'
- type: 'null'
title: Agencyusers
description: Mapped agencies for non-payer types; omitted for FhirPayer
PayerUser:
anyOf:
- type: array
items:
$ref: '#/components/schemas/PayerUser'
- type: 'null'
title: Payeruser
description: Mapped payer (Chha) for **FhirPayer** only; omitted for other types
OnboardingSummary:
anyOf:
- $ref: '#/components/schemas/OnboardingSummary'
- type: 'null'
description: Only when one or more input agencies were not mapped
XApiKey:
anyOf:
- type: string
- type: 'null'
title: Xapikey
description: AWS API Gateway x-api-key
RateLimitingPlan:
type: string
title: Ratelimitingplan
description: Rate limiting plan (Basic, Premium)
CreatedAt:
anyOf:
- type: string
- type: 'null'
title: Createdat
description: Creation timestamp (ISO 8601)
ClientCreateResponseWrapper:
type: object
required:
- Message
- Data
title: ClientCreateResponseWrapper
description: Wrapper for client create (onboarding) API response.
example:
Data:
AgencyUsers:
- AgencyId: 123
Env: app
ProviderTaxId: 12-3456789
RateLimit: 50
RateLimitWindow: Minute
UserId: -6789
UserName: FHIRAPIUser_1_123
- AgencyId: 678
Env: app2
RateLimit: 50
RateLimitWindow: Minute
UserId: -4567
UserName: FHIRAPIUser_1_678
- AgencyId: 789
Env: cloud
RateLimit: 100
RateLimitWindow: Second
UserId: -8765
UserName: FHIRAPIUser_1_789
ClientId: 9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45
ClientName: Client 1
ClientSecret: 3f9c7a21-82b4-4c91-a8e7-6b4f2c9a1d78
ClientType: FhirProvider
CreatedAt: '2026-01-12T07:45:30Z'
Description: HHAx Client
RateLimitingPlan: Basic
Status: Active
XApiKey: brcRWv6qZQanfxwoZYvuYpMpfTUsvxEnkli2n998
Message: Client onboarded successfully
properties:
Message:
type: string
title: Message
description: Response message
Data:
$ref: '#/components/schemas/ClientCreateResponse'
description: Client onboarding data
ClientMigrateRequest:
type: object
required:
- ClientId
- ClientName
- ClientType
- XApiKey
- Agencies
title: ClientMigrateRequest
description: Request schema for migrating a client (data migration API).
example:
Agencies:
- AgencyId: 123
Env: app
RateLimit: 50
RateLimitWindow: Minute
- AgencyId: 456
- AgencyId: 789
Env: cloud
RateLimit: 50
RateLimitWindow: Minute
ClientId: 9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45
ClientName: Migrated Client One
ClientType: FhirProvider
Description: Migrated from legacy
RateLimitingPlan: Basic
Status: Active
XApiKey: brcRWv6qZQanfxwoZYvuYpMpfTUsvxEnkli2n998
properties:
ClientId:
type: string
minLength: 1
title: Clientid
description: Client identifier (UUID) to migrate
ClientName:
type: string
minLength: 1
title: Clientname
description: Name of the client
ClientType:
type: string
enum:
- FhirProvider
- FhirAggregator
- FhirThirdParty
- FhirPayer
title: Clienttype
description: Type of FHIR client (FhirProvider, FhirAggregator, FhirThirdParty, FhirPayer)
XApiKey:
type: string
minLength: 1
title: Xapikey
description: API key to store for this client (from Identity/ClientVendors)
Agencies:
type: array
items:
$ref: '#/components/schemas/AgencyOnboardingInput'
minItems: 1
title: Agencies
description: Agencies to map after migrate (same shape as create)
Description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Client description
Status:
anyOf:
- type: string
- type: 'null'
title: Status
description: Client status (Active, Inactive) - default Active
default: Active
RateLimitingPlan:
anyOf:
- type: string
- type: 'null'
title: Ratelimitingplan
description: Rate limiting plan (Basic, Premium) - default Basic
default: Basic
ClientMigrateResponseWrapper:
type: object
required:
- Message
- Data
title: ClientMigrateResponseWrapper
description: Wrapper for client migrate API response.
properties:
Message:
type: string
title: Message
description: Response message
Data:
$ref: '#/components/schemas/ClientOnboardingResponse'
description: Client onboarding data
ClientOnboardingResponse:
type: object
required:
- ClientId
- ClientName
- ClientType
- Status
title: ClientOnboardingResponse
description: Response schema for client onboarding details (GET/PATCH/migrate `Data`).
example:
AgencyUsers:
- AgencyId: 123
Env: app
ProviderTaxId: 12-3456789
RateLimit: 50
RateLimitWindow: Minute
UserId: -6789
UserName: FHIRAPIUser_1_123
- AgencyId: 678
Env: app2
RateLimit: 50
RateLimitWindow: Minute
UserId: -4567
UserName: FHIRAPIUser_1_678
- AgencyId: 789
Env: cloud
RateLimit: 100
RateLimitWindow: Second
UserId: -8765
UserName: FHIRAPIUser_1_789
ClientId: 9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45
ClientName: Client 1
ClientType: FhirProvider
CreatedAt: '2026-01-12T07:45:30Z'
Description: HHAx Client
RateLimitingPlan: Basic
Status: Active
UpdatedAt: '2026-01-12T09:10:15Z'
XApiKey: brcRWv6qZQanfxwoZYvuYpMpfTUsvxEnkli2n998
properties:
ClientId:
type: string
title: Clientid
description: Unique client identifier (UUID)
ClientName:
type: string
title: Clientname
description: Name of the client
ClientType:
type: string
title: Clienttype
description: Type of FHIR client
Description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Client description
Status:
type: string
title: Status
description: Client status (Active/Inactive)
AgencyUsers:
anyOf:
- type: array
items:
$ref: '#/components/schemas/AgencyUser'
- type: 'null'
title: Agencyusers
description: >-
Per-mapping agency rows (FhirProvider, FhirAggregator,
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hhaexchange/refs/heads/main/openapi/hhaexchange-fhir-openapi.yml