Client Org Management Quick Start

This guide is for TPAs, benefits platforms, and multi-tenant integrators who need to programmatically create and manage Client Organizations.

If Lynx manages your single Client Org, skip this guide.

Who This Guide Is For

Use this guide if you are:

A TPA administering FSA, HRA, or HSA for multiple employer groups
An ICHRA platform onboarding employers
A benefits aggregator white-labeling Lynx
Any platform creating Client Orgs dynamically via API

How the Hierarchy Works

ROOT Client Org (Your TPA)
    ├── Employer A
    ├── Employer B
    ├── Employer C
    │       └── Division C1
    └── Employer D

Key Rules

Rule	Detail
Parent required	Must reference parentName
Products must exist on parent	No new products at child level
Parent must be Active	Required before creating children
Max 9 levels	Tree depth limit
Program inheritance	Child inherits card program
Token scope	Root token used for all operations

Prerequisites

Before calling the API:

Parent Client Org is Active
API credentials available
Products already configured
Business details collected (EIN, contacts, address)

Create a Child Client Org

Endpoint

POST https://sandbox.lynx-fh.co/enrollments/client

Request Body

{
  "data": {
    "clientOrg": {
      "client": { "name": "YOUR_CLIENT_TENANT" },
      "name": "ACME_CORP_2026",
      "displayName": "Acme Corporation",
      "parentName": "YOUR_PARENT_CLIENT_ORG",
      "ein": "123456789",
      "einType": "Corporation",
      "stateIncorporated": "MA",
      "type": "Employer",
      "websiteUrl": "https://acme.example.com",
      "businessYears": "15",
      "addresses": [{
        "line1": "123 Main Street",
        "line2": "Suite 400",
        "city": "Boston",
        "stateProvince": "MA",
        "postalCode": "02101",
        "country": "US",
        "primaryIndicator": true
      }],
      "emails": [{
        "emailAddress": "[email protected]",
        "primaryIndicator": true
      }],
      "phones": [{
        "phoneNumber": "6175551234",
        "countryCode": "1",
        "primaryIndicator": true
      }],
      "clientOrgProducts": [
        { "product": { "name": "FSA" } },
        { "product": { "name": "LPFSA" } }
      ],
      "clientOrgContacts": [{
        "firstName": "Jane",
        "lastName": "Smith",
        "title": "Benefits Administrator",
        "type": "Administrator",
        "relationshipType": "Primary",
        "primaryIndicator": true,
        "dateOfBirth": "1985-03-15",
        "addresses": [{
          "line1": "123 Main Street",
          "city": "Boston",
          "stateProvince": "MA",
          "postalCode": "02101",
          "country": "US",
          "primaryIndicator": true
        }],
        "emails": [{
          "emailAddress": "[email protected]",
          "primaryIndicator": true
        }],
        "phones": [{
          "phoneNumber": "6175551234",
          "countryCode": "1",
          "primaryIndicator": true
        }]
      }]
    }
  },
  "idempotency": {
    "idempotencyKey": "acme-corp-2026-enrollment-001"
  }
}

Required Fields

Field	Description
client.name	Tenant name
name	Unique client org ID
parentName	Parent org
ein	Employer ID
addresses	At least one primary
emails	At least one primary
phones	At least one primary
clientOrgProducts	At least one product
clientOrgContacts	At least one contact
idempotencyKey	Unique request ID

Optional Fields

Field	Description	Default
displayName	Friendly name	Same as name
einType	Corp/LLC/etc	—
stateIncorporated	State code	—
type	Org type	—
websiteUrl	Website	—
businessYears	Years active	—
newCardPackageIndicator	Custom card design	false
allowEnrollmentIndicator	Allow enrollment	true
kybRequiredIndicator	KYB required	Inherited

Response

{
  "data": "ACME_CORP_2026"
}

Card Program Options

Option 1: Inherit (Default)

Same BIN
Same card package
Same purses

Option 2: Explicit Create

{
  "data": {
    "clientOrg": {},
    "cardProgram": {
      "createCardProgram": true
    }
  }
}

Option 3: No Card Program

{
  "data": {
    "clientOrg": {},
    "cardProgram": {
      "createCardProgram": false
    }
  }
}

Status Lifecycle

Status	Meaning	Next Step
New	Created	Wait
PendingReview	KYB pending	—
App_Approved	Ready	Activation
Active	Ready	Enroll members

Check Status

GET https://sandbox.lynx-fh.co/clientorg/{clientOrgName}

Get Plan Summary

GET https://sandbox.lynx-fh.co/clientorg/{clientOrgName}/plan/summary

Best Practices

Naming Convention

{TENANT}_{EMPLOYER_ID}_{YEAR}

Example:

ACME_TPA_EMPLOYER_12345_2026

Token Management

Use root org token
Applies across hierarchy
No child credentials needed

Testing

Create test org
Enroll test member
Validate card issuance

Webhooks

Event	Meaning
lynx.clientOrgCreated	Created
lynx.clientOrgActive	Active
lynx.clientOrgProductAdded	Product added

Example: ICHRA Platform Flow

Lynx provisions root org
Create child org via API
Wait for Active
Get plan summary
Enroll members
Issue virtual cards

Example: TPA Flow

Lynx provisions root org
Create employer org
Configure plan
Enroll members
Issue cards
Process claims