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

# Create Client (Onboarding)

`POST /v1/fhir-onboarding/client`

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.

## Request body

- ClientCreateRequest — 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.
  - `ClientName` string, required — Name of the client
  - `ClientType` 'FhirProvider' | 'FhirAggregator' | 'FhirThirdParty' | 'FhirPayer', required — Type of FHIR client (FhirProvider, FhirAggregator, FhirThirdParty, FhirPayer)
  - `Agencies` AgencyOnboardingInput[], nullable — 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.
    - `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 rows for ClientType FhirPayer only: exactly one item with PayerId (optional Env, RateLimit, RateLimitWindow).
    - `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).
  - `Description` string, nullable — Client description

## Response `201`

Successful Response

- ClientCreateResponseWrapper — Wrapper for client create (onboarding) API response.
  - `Message` string, required — Response message
  - `Data` ClientCreateResponse, required — Response schema for client create (onboarding) — ClientSecret plus AgencyUsers or PayerUser.
    - `ClientId` string, required — Unique client identifier (UUID)
    - `ClientName` string, required — Name of the client
    - `ClientSecret` string, required — Generated client secret (UUID) - store securely; not persisted in FHIR DB
    - `ClientType` string, required — Type of FHIR client
    - `Description` string, nullable — Client description
    - `Status` string, required — Client status (Active/Inactive)
    - `AgencyUsers` AgencyUser[], nullable — Mapped agencies for non-payer types; omitted for FhirPayer
      - `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 — Mapped payer (Chha) for **FhirPayer** only; omitted for other types
      - `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, required — Rate limiting plan (Basic, Premium)
    - `CreatedAt` string, nullable — Creation 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)