---
title: "Update Client Onboarding Details"
method: PATCH
path: "/v1/fhir-onboarding/client/{client_id}"
tags: ["Onboarding", "Onboarding"]
---

# Update Client Onboarding Details

`PATCH /v1/fhir-onboarding/client/{client_id}`

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.

## Path parameters

- `client_id` string, required — Unique identifier of the client whose onboarding configuration is being updated

## Request body

- ClientUpdateRequest — 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).
  - `Description` string, nullable — Client description
  - `Agencies` AgencyOnboardingInput[], nullable — 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
    - `AgencyId` integer, required — Agency (vendor) identifier. Required; must be a positive integer.
    - `Env` string, nullable — 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` integer, nullable — Allowed requests per RateLimitWindow. Defaults to 50 when omitted. Must be a positive integer when provided (validated on write).
    - `RateLimitWindow` string, nullable — Rate window granularity: Second or Minute (case-insensitive). Defaults to Minute when omitted (validated on write).
  - `Payer` PayerOnboardingInput[], nullable — Payer mapping for ClientType FhirPayer only: exactly one item with PayerId (optional Env, RateLimit, RateLimitWindow). Omit when not changing mappings.
    - `PayerId` integer, required — Payer identifier (ChhaID in HHA dbo.tblchhamaster). Stored as ClientMappings.AgencyId.
    - `Env` string, nullable — 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` integer, nullable — Allowed requests per RateLimitWindow. Defaults to 50 when omitted. Must be a positive integer when provided (validated on write).
    - `RateLimitWindow` string, nullable — Rate window granularity: Second or Minute (case-insensitive). Defaults to Minute when omitted (validated on write).
  - `RateLimitingPlan` string, nullable — Rate limiting plan (Basic, Premium) - case insensitive
  - `Status` string, nullable — Client status (Active, Inactive) - case insensitive

## Response `200`

Successful Response

- ClientUpdateResponseWrapper — Wrapper for client onboarding update API responses (PATCH).
  - `Message` string, required — Response message
  - `Data` ClientOnboardingResponse, required — Response schema for client onboarding details (GET/PATCH/migrate ``Data``).
    - `ClientId` string, required — Unique client identifier (UUID)
    - `ClientName` string, required — Name of the client
    - `ClientType` string, required — Type of FHIR client
    - `Description` string, nullable — Client description
    - `Status` string, required — Client status (Active/Inactive)
    - `AgencyUsers` AgencyUser[], nullable — Per-mapping agency rows (FhirProvider, FhirAggregator, FhirThirdParty); omitted for FhirPayer — use PayerUser
      - `UserId` integer, required — System-generated HHA user ID
      - `UserName` string, required — System-generated user name
      - `AgencyId` integer, required — Agency identifier
      - `Env` string, nullable — HHA environment stored on this mapping (app, app2, cloud)
      - `ProviderTaxId` string, nullable — Federal tax number from HHA for this agency in this Env (response only)
      - `RateLimit` integer, required — Allowed requests per RateLimitWindow for this agency
      - `RateLimitWindow` 'Second' | 'Minute', required — Rate window granularity (Second, Minute)
    - `PayerUser` PayerUser[], nullable — Per-mapping payer rows for **FhirPayer** only (PayerId = ChhaID); omitted for other client types — use AgencyUsers
      - `UserId` integer, required — System-generated HHA user ID
      - `UserName` string, required — System-generated user name
      - `PayerId` integer, required — Payer identifier (ChhaID); stored as ClientMappings.AgencyId
      - `Env` string, nullable — HHA environment stored on this mapping (app, app2, cloud)
      - `RateLimit` integer, required — Allowed requests per RateLimitWindow for this payer mapping
      - `RateLimitWindow` 'Second' | 'Minute', required — Rate window granularity (Second, Minute)
    - `OnboardingSummary` OnboardingSummary — Present when agencies or payers were skipped or mapped with inactive HHA status.
      - `AgencyIds` integer[], nullable — Agency or payer IDs from the request that were not mapped (skipped)
      - `Message` string, nullable — Human-readable explanation for skipped agencies or payers
      - `InactiveAgencyIds` integer[], nullable — Agency IDs that were mapped but have inactive status in HHA (non-FhirPayer clients)
      - `InactivePayerId` integer[], nullable — Payer (Chha) IDs that were mapped but have inactive status in dbo.tblchhamaster (FhirPayer clients only)
      - `InactiveMessage` string, nullable — Human-readable note when mapped rows are inactive in HHA (agency wording for providers; payer wording for FhirPayer)
    - `XApiKey` string, nullable — AWS API Gateway x-api-key
    - `RateLimitingPlan` string, nullable — Rate limiting plan (Basic, Premium)
    - `CreatedAt` string, nullable — Creation timestamp (ISO 8601)
    - `UpdatedAt` string, nullable — Last update timestamp (ISO 8601)

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/hhaexchange/apis/fastapi.md) · [All operations](https://skmtc.net/hhaexchange/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hhaexchange/fastapi/versions/17ca04f67931/schema)