{"openapi":"3.1.0","info":{"title":"FastAPI","description":"\n## APIs\n\n**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.\n\n**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.\n\n**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.\n\n**Onboarding API** — Create, Read, Update, and Migrate FHIR clients. Manages client configuration, agency mappings, and API keys.\n\n**Configuration (Rate limits)** — Read per-client/agency/env rate limit configuration.\n\n## Authentication\n\n**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.\n","version":"0.1.0"},"paths":{"/v1/fhir-onboarding/client":{"post":{"tags":["Onboarding","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":{"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"}}}}},"required":true},"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":["write"]}]}},"/v1/fhir-onboarding/client/migrate":{"post":{"tags":["Onboarding","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":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientMigrateRequest"}}},"required":true},"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":["write"]}]}},"/v1/fhir-onboarding/client/{client_id}":{"get":{"tags":["Onboarding","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,"schema":{"type":"string","description":"Unique identifier of the client whose onboarding details are to be retrieved","title":"Client Id"},"description":"Unique identifier of the client whose onboarding details are to be retrieved","example":"9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45"}],"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":["read"]}]},"patch":{"tags":["Onboarding","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,"schema":{"type":"string","description":"Unique identifier of the client whose onboarding configuration is being updated","title":"Client Id"},"description":"Unique identifier of the client whose onboarding configuration is being updated","example":"9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45"}],"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":["write"]}]}},"/v1/internal/provider":{"get":{"tags":["Internal"],"summary":"Get provider details","description":"Returns base URL, provider and user details, environment, validation, and GlobalProviderId. Client ID and API key are required. **At least one** of ProviderTaxId, VendorId, or GlobalProviderId is required; you may send more than one if every value resolves to the same agency in HHA (otherwise the request is rejected). 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,"schema":{"type":"string","description":"Client ID (mandatory)","title":"Clientid"},"description":"Client ID (mandatory)"},{"name":"XApiKey","in":"query","required":true,"schema":{"type":"string","description":"API key (mandatory)","title":"Xapikey"},"description":"API key (mandatory)"},{"name":"ProviderTaxId","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Federal tax number (numeric). One of ProviderTaxId, VendorId, or GlobalProviderId required.","title":"Providertaxid"},"description":"Federal tax number (numeric). One of ProviderTaxId, VendorId, or GlobalProviderId required."},{"name":"VendorId","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"HHA VendorID / agency id. One of ProviderTaxId, VendorId, or GlobalProviderId required.","title":"Vendorid"},"description":"HHA VendorID / agency id. One of ProviderTaxId, VendorId, or GlobalProviderId required."},{"name":"GlobalProviderId","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"dbo.Vendors.GlobalProviderId (UUID). One of ProviderTaxId, VendorId, or GlobalProviderId required.","title":"Globalproviderid"},"description":"dbo.Vendors.GlobalProviderId (UUID). One of ProviderTaxId, VendorId, or GlobalProviderId required."},{"name":"AppVersionId","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"integer"}},{"type":"null"}],"description":"One or more app version IDs (optional; default [35]) for URL lookup.","title":"Appversionid"},"description":"One or more app version IDs (optional; default [35]) for URL lookup."}],"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":["read"]}]}},"/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,"schema":{"type":"string","description":"Client ID (mandatory)","title":"Clientid"},"description":"Client ID (mandatory)"},{"name":"XApiKey","in":"query","required":true,"schema":{"type":"string","description":"API key (mandatory)","title":"Xapikey"},"description":"API key (mandatory)"},{"name":"ProviderId","in":"query","required":true,"schema":{"type":"integer","description":"Provider ID / Vendor ID (CompanyID) (mandatory)","title":"Providerid"},"description":"Provider ID / Vendor ID (CompanyID) (mandatory)"},{"name":"ReferenceType","in":"query","required":true,"schema":{"type":"string","description":"Reference type (e.g., 'EmergencyContactRelationship') (mandatory)","title":"Referencetype"},"description":"Reference type (e.g., 'EmergencyContactRelationship') (mandatory)"}],"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":["read"]}]}},"/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 \"One of ProviderTaxId, VendorId, or GlobalProviderId 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,"schema":{"type":"string","description":"Client ID (mandatory)","title":"Clientid"},"description":"Client ID (mandatory)"},{"name":"XApiKey","in":"query","required":true,"schema":{"type":"string","description":"API key (mandatory)","title":"Xapikey"},"description":"API key (mandatory)"}],"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":["read"]}]}},"/v1/rate-limits/config":{"get":{"tags":["Configuration","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,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"FHIR client UUID (required). Example: 9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45","title":"Clientid"},"description":"FHIR client UUID (required). Example: 9b2f1a6e-3c84-4d8e-9b8a-7e2c9f2a1c45"},{"name":"AgencyId","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Agency (vendor) identifier — required; must be a positive integer","title":"Agencyid"},"description":"Agency (vendor) identifier — required; must be a positive integer"},{"name":"Env","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"HHA environment (required): app, app2, or cloud","title":"Env"},"description":"HHA environment (required): app, app2, or cloud"}],"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":["read"]}]}}},"components":{"schemas":{"AgencyOnboardingInput":{"properties":{"AgencyId":{"type":"integer","exclusiveMinimum":0.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)."}},"type":"object","required":["AgencyId"],"title":"AgencyOnboardingInput","description":"One agency item used by onboarding, migrate, and update requests.\n\nField requirements:\n- ``AgencyId`` is **required** (positive integer; agency/vendor identifier).\n- ``Env`` is **optional**. When omitted, the server discovers the HHA tier\n  that owns this agency by probing the configured HHA databases\n  (app, app2, cloud) in order.\n- ``RateLimit`` / ``RateLimitWindow`` are **optional**. Defaults to 50 / Minute."},"AgencyRateLimitDetail":{"properties":{"AgencyId":{"type":"integer","title":"Agencyid","description":"Agency (vendor) identifier"},"RateLimit":{"type":"integer","title":"Ratelimit","description":"Allowed requests per RateLimitWindow"}},"type":"object","required":["AgencyId","RateLimit"],"title":"AgencyRateLimitDetail","description":"Per-agency portion of the rate limit config response."},"AgencyUser":{"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)"}},"type":"object","required":["UserId","UserName","AgencyId","RateLimit","RateLimitWindow"],"title":"AgencyUser","description":"Agency row in onboarding responses: user + mapping env + rate limit fields (response-only)."},"ClientCreateRequest":{"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":[{"items":{"$ref":"#/components/schemas/AgencyOnboardingInput"},"type":"array"},{"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":[{"items":{"$ref":"#/components/schemas/PayerOnboardingInput"},"type":"array"},{"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"}},"type":"object","required":["ClientName","ClientType"],"title":"ClientCreateRequest","description":"Request schema for creating (onboarding) a new FHIR client.\n\nUse ``Agencies`` for **FhirProvider** / **FhirAggregator** / **FhirThirdParty**.\nUse ``Payer`` (exactly one item) for **FhirPayer** only; do not send ``Agencies`` for payers."},"ClientCreateResponse":{"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":[{"items":{"$ref":"#/components/schemas/AgencyUser"},"type":"array"},{"type":"null"}],"title":"Agencyusers","description":"Mapped agencies for non-payer types; omitted for FhirPayer"},"PayerUser":{"anyOf":[{"items":{"$ref":"#/components/schemas/PayerUser"},"type":"array"},{"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)"}},"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"}},"ClientCreateResponseWrapper":{"properties":{"Message":{"type":"string","title":"Message","description":"Response message"},"Data":{"$ref":"#/components/schemas/ClientCreateResponse","description":"Client onboarding data"}},"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"}},"ClientMigrateRequest":{"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":{"items":{"$ref":"#/components/schemas/AgencyOnboardingInput"},"type":"array","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"}},"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"}},"ClientMigrateResponseWrapper":{"properties":{"Message":{"type":"string","title":"Message","description":"Response message"},"Data":{"$ref":"#/components/schemas/ClientOnboardingResponse","description":"Client onboarding data"}},"type":"object","required":["Message","Data"],"title":"ClientMigrateResponseWrapper","description":"Wrapper for client migrate API response."},"ClientOnboardingResponse":{"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":[{"items":{"$ref":"#/components/schemas/AgencyUser"},"type":"array"},{"type":"null"}],"title":"Agencyusers","description":"Per-mapping agency rows (FhirProvider, FhirAggregator, FhirThirdParty); omitted for FhirPayer — use PayerUser"},"PayerUser":{"anyOf":[{"items":{"$ref":"#/components/schemas/PayerUser"},"type":"array"},{"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)"}},"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"}},"ClientOnboardingResponseWrapper":{"properties":{"Message":{"type":"string","title":"Message","description":"Response message"},"Data":{"$ref":"#/components/schemas/ClientOnboardingResponse","description":"Client onboarding data"}},"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"}},"ClientUpdateRequest":{"properties":{"Description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Client description"},"Agencies":{"anyOf":[{"items":{"$ref":"#/components/schemas/AgencyOnboardingInput"},"type":"array"},{"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":[{"items":{"$ref":"#/components/schemas/PayerOnboardingInput"},"type":"array"},{"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"}},"type":"object","title":"ClientUpdateRequest","description":"Request schema for updating client onboarding details (env-per-mapping model).\n\nUse ``Agencies`` for **FhirProvider** / **FhirAggregator** / **FhirThirdParty** mapping\nupdates. Use ``Payer`` (exactly one item) for **FhirPayer** only; do not send\n``Agencies`` for those clients. The server reads ``ClientType`` from the stored client;\ndo not send ``ClientType`` on PATCH.\n\n``Agencies`` mirrors the POST ``/client`` shape: each item carries its own optional\n``Env``. When ``Env`` is omitted for an item, the server discovers the HHA environment\nfor that agency across configured tiers (``dbo.Vendors``). For **FhirPayer**, omitted\n``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"}},"ClientUpdateResponseWrapper":{"properties":{"Message":{"type":"string","title":"Message","description":"Response message"},"Data":{"$ref":"#/components/schemas/ClientOnboardingResponse","description":"Client onboarding data"}},"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"}},"GenericReferenceItem":{"properties":{"ReferenceCode":{"type":"string","title":"Referencecode"},"Seq":{"type":"integer","title":"Seq"},"ReferenceValue":{"type":"string","title":"Referencevalue","default":""}},"type":"object","required":["ReferenceCode","Seq"],"title":"GenericReferenceItem","description":"Single generic reference item from GenericReferences table."},"GenericReferencesResponse":{"properties":{"CompanyID":{"type":"integer","title":"Companyid"},"ReferenceType":{"type":"string","title":"Referencetype"},"References":{"items":{"$ref":"#/components/schemas/GenericReferenceItem"},"type":"array","title":"References","default":[]}},"type":"object","required":["CompanyID","ReferenceType"],"title":"GenericReferencesResponse","description":"Response for GET /internal/generic-references: list of generic references by CompanyID and ReferenceType."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"OnboardingSummary":{"properties":{"AgencyIds":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"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":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Inactiveagencyids","description":"Agency IDs that were mapped but have inactive status in HHA (non-FhirPayer clients)"},"InactivePayerId":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"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)"}},"type":"object","title":"OnboardingSummary","description":"Present when agencies or payers were skipped or mapped with inactive HHA status."},"PayerDetailsResponse":{"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":{"additionalProperties":true,"type":"object","title":"Validation","default":{}}},"type":"object","title":"PayerDetailsResponse","description":"Response for GET /internal/payer: aggregator client, first active mapping as payer context."},"PayerOnboardingInput":{"properties":{"PayerId":{"type":"integer","exclusiveMinimum":0.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)."}},"type":"object","required":["PayerId"],"title":"PayerOnboardingInput","description":"One payer (Chha) item for **FhirPayer** onboarding and PATCH mapping updates.\n\n``PayerId`` maps to ``FHIR.ClientMappings.AgencyId``. When ``Env`` is omitted,\nempty, or whitespace-only, the server discovers the HHA tier using\n``dbo.tblchhamaster`` across mirrors. When ``Env`` is set, it must be exactly\napp, app2, or cloud (case-insensitive, no leading or trailing spaces); the payer\nid must exist as ``ChhaID`` in ``dbo.tblchhamaster`` for that environment before mapping."},"PayerUser":{"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)"}},"type":"object","required":["UserId","UserName","PayerId","RateLimit","RateLimitWindow"],"title":"PayerUser","description":"Payer (Chha) mapping row in onboarding responses for **FhirPayer** clients (response-only)."},"ProviderDetailsResponse":{"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"},"GlobalProviderId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Globalproviderid"},"UserId":{"type":"integer","title":"Userid","default":0},"UserName":{"type":"string","title":"Username","default":""},"Environment":{"type":"string","title":"Environment","default":""},"Validation":{"additionalProperties":true,"type":"object","title":"Validation","default":{}}},"type":"object","title":"ProviderDetailsResponse","description":"Response for GET /internal/provider: base URL, provider and user details, environment, validation."},"RateLimitConfigData":{"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)"}},"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"}},"RateLimitConfigResponse":{"properties":{"Message":{"type":"string","title":"Message","description":"Response message"},"Data":{"$ref":"#/components/schemas/RateLimitConfigData","description":"Rate limit configuration"}},"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"}},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"bearerAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.hhaexchange.com/v1/fhir/auth/token","scopes":{"read":"Read-only access.","write":"Write access."}}}}}}}