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, FhirThirdParty);
            omitted for FhirPayer — use PayerUser
        PayerUser:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/PayerUser'
            - type: 'null'
          title: Payeruser
          description: >-
            Per-mapping payer rows for **FhirPayer** only (PayerId = ChhaID); omitted
            for other client types — use AgencyUsers
        OnboardingSummary:
          anyOf:
            - $ref: '#/components/schemas/OnboardingSummary'
            - type: 'null'
          description: Only when create/migrate skipped one or more agencies
        XApiKey:
          anyOf:
            - type: string
            - type: 'null'
          title: Xapikey
          description: AWS API Gateway x-api-key
        RateLimitingPlan:
          anyOf:
            - type: string
            - type: 'null'
          title: Ratelimitingplan
          description: Rate limiting plan (Basic, Premium)
        CreatedAt:
          anyOf:
            - type: string
            - type: 'null'
          title: Createdat
          description: Creation timestamp (ISO 8601)
        UpdatedAt:
          anyOf:
            - type: string
            - type: 'null'
          title: Updatedat
          description: Last update timestamp (ISO 8601)
    ClientOnboardingResponseWrapper:
      type: object
      required:
        - Message
        - Data
      title: ClientOnboardingResponseWrapper
      description: Wrapper for client onboarding API responses (GET).
      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
          ClientType: FhirProvider
          CreatedAt: '2026-01-12T07:45:30Z'
          Description: HHAx Client
          RateLimitingPlan: Basic
          Status: Active
          UpdatedAt: '2026-01-12T09:10:15Z'
          XApiKey: brcRWv6qZQanfxwoZYvuYpMpfTUsvxEnkli2n998
        Message: Client onboarding details retrieved successfully
      properties:
        Message:
          type: string
          title: Message
          description: Response message
        Data:
          $ref: '#/components/schemas/ClientOnboardingResponse'
          description: Client onboarding data
    ClientUpdateRequest:
      type: object
      title: ClientUpdateRequest
      description: |
        Request schema for updating client onboarding details (env-per-mapping model).

        Use `Agencies` for **FhirProvider** / **FhirAggregator** / **FhirThirdParty** mapping
        updates. Use `Payer` (exactly one item) for **FhirPayer** only; do not send
        `Agencies` for those clients. The server reads `ClientType` from the stored client;
        do not send `ClientType` on PATCH.

        `Agencies` mirrors the POST `/client` shape: each item carries its own optional
        `Env`. When `Env` is omitted for an item, the server discovers the HHA environment
        for that agency across configured tiers (`dbo.Vendors`). For **FhirPayer**, omitted
        `Env` on `Payer` uses `dbo.tblchhamaster` across mirrors (same rules as POST).
      example:
        Agencies:
          - AgencyId: 123
            Env: app
            RateLimit: 100
            RateLimitWindow: Second
          - AgencyId: 678
        Description: HHAx Client
        RateLimitingPlan: Premium
        Status: Inactive
      properties:
        Description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Client description
        Agencies:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/AgencyOnboardingInput'
            - type: 'null'
          title: Agencies
          description: >-
            Agencies to associate with this client (non-payer client types only); each
            item may set its own Env or omit it to trigger multi-env discovery
        Payer:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/PayerOnboardingInput'
            - type: 'null'
          title: Payer
          description: >-
            Payer mapping for ClientType FhirPayer only: exactly one item with PayerId
            (optional Env, RateLimit, RateLimitWindow). Omit when not changing mappings.
        RateLimitingPlan:
          anyOf:
            - type: string
            - type: 'null'
          title: Ratelimitingplan
          description: Rate limiting plan (Basic, Premium) - case insensitive
        Status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: Client status (Active, Inactive) - case insensitive
    ClientUpdateResponseWrapper:
      type: object
      required:
        - Message
        - Data
      title: ClientUpdateResponseWrapper
      description: Wrapper for client onboarding update API responses (PATCH).
      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
          ClientType: FhirProvider
          CreatedAt: '2026-02-02T14:28:18.479016Z'
          Description: HHAx Client Updated
          RateLimitingPlan: Premium
          Status: Active
          UpdatedAt: '2026-02-02T09:25:11.102958Z'
          XApiKey: brcRWv6qZQanfxwoZYvuYpMpfTUsvxEnkli2n998
        Message: Client onboarding details updated successfully
      properties:
        Message:
          type: string
          title: Message
          description: Response message
        Data:
          $ref: '#/components/schemas/ClientOnboardingResponse'
          description: Client onboarding data
    GenericReferenceItem:
      type: object
      required:
        - ReferenceCode
        - Seq
      title: GenericReferenceItem
      description: Single generic reference item from GenericReferences table.
      properties:
        ReferenceCode:
          type: string
          title: Referencecode
        Seq:
          type: integer
          title: Seq
        ReferenceValue:
          type: string
          title: Referencevalue
          default: ''
    GenericReferencesResponse:
      type: object
      required:
        - CompanyID
        - ReferenceType
      title: GenericReferencesResponse
      description: >-
        Response for GET /internal/generic-references: list of generic references by
        CompanyID and ReferenceType.
      properties:
        CompanyID:
          type: integer
          title: Companyid
        ReferenceType:
          type: string
          title: Referencetype
        References:
          type: array
          items:
            $ref: '#/components/schemas/GenericReferenceItem'
          title: References
          default: []
    HTTPValidationError:
      type: object
      title: HTTPValidationError
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
    OnboardingSummary:
      type: object
      title: OnboardingSummary
      description: Present when agencies or payers were skipped or mapped with inactive HHA status.
      properties:
        AgencyIds:
          anyOf:
            - type: array
              items:
                type: integer
            - type: 'null'
          title: Agencyids
          description: Agency or payer IDs from the request that were not mapped (skipped)
        Message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Human-readable explanation for skipped agencies or payers
        InactiveAgencyIds:
          anyOf:
            - type: array
              items:
                type: integer
            - type: 'null'
          title: Inactiveagencyids
          description: >-
            Agency IDs that were mapped but have inactive status in HHA (non-FhirPayer
            clients)
        InactivePayerId:
          anyOf:
            - type: array
              items:
                type: integer
            - type: 'null'
          title: Inactivepayerid
          description: >-
            Payer (Chha) IDs that were mapped but have inactive status in
            dbo.tblchhamaster (FhirPayer clients only)
        InactiveMessage:
          anyOf:
            - type: string
            - type: 'null'
          title: Inactivemessage
          description: >-
            Human-readable note when mapped rows are inactive in HHA (agency wording for
            providers; payer wording for FhirPayer)
    PayerDetailsResponse:
      type: object
      title: PayerDetailsResponse
      description: >-
        Response for GET /internal/payer: aggregator client, first active mapping as
        payer context.
      properties:
        Message:
          type: string
          title: Message
          default: ''
        ClientId:
          type: string
          title: Clientid
          default: ''
        XApiKey:
          type: string
          title: Xapikey
          default: ''
        BaseUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Baseurl
        PayerId:
          anyOf:
            - type: integer
            - type: 'null'
          title: Payerid
        UserId:
          type: integer
          title: Userid
          default: 0
        UserName:
          type: string
          title: Username
          default: ''
        Environment:
          type: string
          title: Environment
          default: ''
        Validation:
          type: object
          additionalProperties: true
          title: Validation
          default: {}
    PayerOnboardingInput:
      type: object
      required:
        - PayerId
      title: PayerOnboardingInput
      description: |
        One payer (Chha) item for **FhirPayer** onboarding and PATCH mapping updates.

        `PayerId` maps to `FHIR.ClientMappings.AgencyId`. When `Env` is omitted,
        empty, or whitespace-only, the server discovers the HHA tier using
        `dbo.tblchhamaster` across mirrors. When `Env` is set, it must be exactly
        app, app2, or cloud (case-insensitive, no leading or trailing spaces); the payer
        id must exist as `ChhaID` in `dbo.tblchhamaster` for that environment before mapping.
      properties:
        PayerId:
          type: integer
          exclusiveMinimum: 0
          title: Payerid
          description: >-
            Payer identifier (ChhaID in HHA dbo.tblchhamaster). Stored as
            ClientMappings.AgencyId.
        Env:
          anyOf:
            - type: string
            - type: 'null'
          title: Env
          description: >-
            Optional HHA environment: app, app2, or cloud (case-insensitive, no leading
            or trailing spaces). When omitted or empty, discovery uses
            dbo.tblchhamaster across tiers. When set, the payer id must exist in
            dbo.tblchhamaster for that environment.
        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).
    PayerUser:
      type: object
      required:
        - UserId
        - UserName
        - PayerId
        - RateLimit
        - RateLimitWindow
      title: PayerUser
      description: >-
        Payer (Chha) mapping row in onboarding responses for **FhirPayer** clients
        (response-only).
      properties:
        UserId:
          type: integer
          title: Userid
          description: System-generated HHA user ID
        UserName:
          type: string
          title: Username
          description: System-generated user name
        PayerId:
          type: integer
          title: Payerid
          description: Payer identifier (ChhaID); stored as ClientMappings.AgencyId
        Env:
          anyOf:
            - type: string
            - type: 'null'
          title: Env
          description: HHA environment stored on this mapping (app, app2, cloud)
        RateLimit:
          type: integer
          title: Ratelimit
          description: Allowed requests per RateLimitWindow for this payer mapping
        RateLimitWindow:
          type: string
          enum:
            - Second
            - Minute
          title: Ratelimitwindow
          description: Rate window granularity (Second, Minute)
    ProviderDetailsResponse:
      type: object
      title: ProviderDetailsResponse
      description: >-
        Response for GET /internal/provider: base URL, provider and user details,
        environment, validation.
      properties:
        Message:
          type: string
          title: Message
          default: ''
        ClientId:
          type: string
          title: Clientid
          default: ''
        XApiKey:
          type: string
          title: Xapikey
          default: ''
        BaseUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Baseurl
        ProviderVersion:
          anyOf:
            - type: number
            - type: 'null'
          title: Providerversion
        ProviderMinorVersion:
          anyOf:
            - type: number
            - type: 'null'
          title: Providerminorversion
        ProviderId:
          anyOf:
            - type: integer
            - type: 'null'
          title: Providerid
        ProviderTaxId:
          anyOf:
            - type: string
            - type: 'null'
          title: Providertaxid
        UserId:
          type: integer
          title: Userid
          default: 0
        UserName:
          type: string
          title: Username
          default: ''
        Environment:
          type: string
          title: Environment
          default: ''
        Validation:
          type: object
          additionalProperties: true
          title: Validation
          default: {}
    RateLimitConfigData:
      type: object
      required:
        - ClientId
        - ClientMappingId
        - Env
        - Agency
        - RateLimitWindow
      title: RateLimitConfigData
      description: Rate limit configuration for one unique client + agency + env combination.
      example:
        Agency:
          AgencyId: 123
          RateLimit: 50
        ClientId: 9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45
        ClientMappingId: 10123
        Env: app
        RateLimitWindow: Minute
      properties:
        ClientId:
          type: string
          title: Clientid
          description: FHIR client UUID
        ClientMappingId:
          type: integer
          title: Clientmappingid
          description: FHIR.ClientMappings primary key
        Env:
          type: string
          title: Env
          description: HHA environment for this mapping (app, app2, cloud)
        Agency:
          $ref: '#/components/schemas/AgencyRateLimitDetail'
          description: Agency identifier and its request rate limit
        RateLimitWindow:
          type: string
          title: Ratelimitwindow
          description: Rate window granularity (Second, Minute)
    RateLimitConfigResponse:
      type: object
      required:
        - Message
        - Data
      title: RateLimitConfigResponse
      description: Wrapper for GET /rate-limits/config response.
      example:
        Data:
          Agency:
            AgencyId: 123
            RateLimit: 50
          ClientId: 9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45
          ClientMappingId: 10123
          Env: app
          RateLimitWindow: Minute
        Message: Rate limiting configuration fetched successfully
      properties:
        Message:
          type: string
          title: Message
          description: Response message
        Data:
          $ref: '#/components/schemas/RateLimitConfigData'
          description: Rate limit configuration
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
      properties:
        loc:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
  securitySchemes:
    bearerAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.hhaexchange.com/v1/fhir/auth/token
          scopes:
            full_access: Read and write access for Internal Provider, Onboarding, and Rate limits.