---
title: "Migrate Client (Data Migration)"
method: POST
path: "/v1/fhir-onboarding/client/migrate"
tags: ["Onboarding", "Onboarding"]
---

# Migrate Client (Data Migration)

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

Migrate one client with provided ClientId, XApiKey, and agencies. Creates FHIR.Clients, HHA users, and FHIR.ClientMappings. No AWS key creation, no IDP write.

## Request body

- ClientMigrateRequest — Request schema for migrating a client (data migration API).
  - `ClientId` string, required — Client identifier (UUID) to migrate
  - `ClientName` string, required — Name of the client
  - `ClientType` 'FhirProvider' | 'FhirAggregator' | 'FhirThirdParty' | 'FhirPayer', required — Type of FHIR client (FhirProvider, FhirAggregator, FhirThirdParty, FhirPayer)
  - `XApiKey` string, required — API key to store for this client (from Identity/ClientVendors)
  - `Agencies` AgencyOnboardingInput[], required — Agencies to map after migrate (same shape as create)
    - `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).
  - `Description` string, nullable — Client description
  - `Status` string, nullable — Client status (Active, Inactive) - default Active
  - `RateLimitingPlan` string, nullable — Rate limiting plan (Basic, Premium) - default Basic

## 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
    - `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/revisions/17ca04f67931/schema)