---
title: "Migrate Client"
method: POST
path: "/v1/fhir-onboarding/client/migrate"
tags: ["Onboarding"]
---

# Migrate Client

`POST /v1/fhir-onboarding/client/migrate`

## Request

- Base URL: `https://api.hhaexchange.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.hhaexchange.com/v1/fhir-onboarding/client/migrate`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://api.hhaexchange.com/v1/fhir/auth/token` scopes: `write`

Migrate a client with ClientId, XApiKey, EntityType, and Entities (GlobalEntityId is a UUID). No AWS key creation and no IDP write.

## Request body

- ClientMigrateRequest: Request schema for migrating a client (EntityType + Entities).
  - `ClientId` string, required: Client identifier (UUID)
  - `ClientName` string, required: Name of the client
  - `ClientType` 'Provider' | 'Aggregator' | 'ThirdParty' | 'Payer', required: Type of FHIR client
  - `EntityType` 'Provider' | 'Payer', required: Provider or Payer.
  - `XApiKey` string, required: API key to store for this client
  - `Entities` EntityOnboardingInput[], required: Entities to map (each GlobalEntityId is a UUID)
    - `GlobalEntityId` string, required: Global entity UUID (Provider: Vendors.GlobalProviderId; Payer: TblCHHAMaster.GlobalPayerID).
    - `RateLimit` integer, nullable: Allowed requests per RateLimitWindow. Defaults to 50 when omitted. Must be a positive integer within configured limits per RateLimitWindow (validated on write).
    - `RateLimitWindow` string, nullable: Rate window granularity: Second or Minute (case-insensitive). Defaults to Minute when omitted (validated on write).
  - `Description` string, nullable: Client description
  - `Status` string, nullable: Client status (Active, Inactive)
  - `RateLimitingPlan` string, nullable: Rate limiting plan (Basic, Premium)

## Response `201`

Successful Response

- ClientMigrateResponseWrapper: Wrapper for client migrate API response.
  - `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
    - `EntityType` string, nullable: Provider or Payer.
    - `Description` string, nullable: Client description
    - `Status` string, required: Client status (Active/Inactive)
    - `Entities` EntityMappingResponse[], nullable: Mapped entities for this client.
      - `UserId` integer, required: System-generated HHA user ID
      - `UserName` string, required: System-generated user name
      - `AgencyId` integer, nullable: Resolved InternalId (VendorID) when EntityType is Provider
      - `PayerId` integer, nullable: Resolved InternalId (ChhaID) when EntityType is Payer
      - `GlobalEntityId` string, nullable: Global entity UUID (Provider: Vendors.GlobalProviderId; Payer: TblCHHAMaster.GlobalPayerID).
      - `Env` string, nullable: HHA environment for this mapping (app, app2, cloud)
      - `ProviderTaxId` string, nullable: Provider tax id when EntityType is Provider; null for Payer
      - `RateLimit` integer, required: Allowed requests per RateLimitWindow
      - `RateLimitWindow` 'Second' | 'Minute', required: Rate window (Second or Minute)
    - `OnboardingSummary` OnboardingSummary: Present when entities were skipped or mapped with inactive HHA status.
      - `GlobalEntityIds` string[], nullable: GlobalEntityId values from the request that were not mapped (skipped)
      - `AgencyIds` integer[], nullable: Legacy: Agency or payer IDs that were not mapped (optional back-compat)
      - `Message` string, nullable: Human-readable explanation for skipped entities
      - `InactiveAgencyIds` integer[], nullable: Agency IDs that were mapped but have inactive status in HHA (non-Payer clients)
      - `InactivePayerId` integer[], nullable: Payer (Chha) IDs that were mapped but have inactive status in dbo.tblchhamaster (Payer clients only)
      - `InactiveMessage` string, nullable: Human-readable note when mapped rows are inactive in HHA (agency wording for providers; payer wording for Payer)
    - `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

## Changes

- **2026-10-01** `f754b29e3de5`: 4 breaking, 4 info
  - removed the enum value `FhirAggregator` of the request property `ClientType`
  - removed the enum value `FhirPayer` of the request property `ClientType`
  - removed the enum value `FhirProvider` of the request property `ClientType`
  - removed the enum value `FhirThirdParty` of the request property `ClientType`
  - …4 more
- **2026-09-10** `33e78eb36727`: 2 breaking, 3 warning, 3 info
  - added the new required request property `Entities`
  - added the new required request property `EntityType`
  - removed the request property `Agencies`
  - removed the optional property `Data/AgencyUsers` from the response with the `201` status
  - …4 more

[Operation history](https://skmtc.dev/hhaexchange/apis/hhaexchange-api/changes/v1/fhir-onboarding/client/migrate/post.md)

---

[API](https://skmtc.dev/hhaexchange/apis/hhaexchange-api.md) - [All operations](https://skmtc.dev/hhaexchange/apis/hhaexchange-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hhaexchange/apis/hhaexchange-api/revisions/f754b29e3de5?raw)