Skip to main content

​
Onboard a client company

Use this guide when your SERVICE_PARTNER integration onboards a new merchant. You will create (or reuse) a workspace, add a client company under it, and capture the UUIDs needed for product API calls.
Client companies live inside your partner organization — they do not get a separate Fluide org. Your machine JWT tenantId stays your partner org; acting headers pick the merchant. See Multi-tenancy.

​
Prerequisites

  • Developer API key and machine JWT — Authorization
  • Your account is a SERVICE_PARTNER organization with partner:workspace:manage and partner:client-company:manage
  • Sandbox base URL: https://test.api.fluidehr.com

​
Steps

1

List or create a workspace

Workspaces group client companies (e.g. production vs sandbox, or by region).
# List existing workspaces
curl -sS "$FLUIDE_BASE_URL/api/v1/workspaces" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer"

# Create a workspace (if needed)
curl -sS -X POST "$FLUIDE_BASE_URL/api/v1/workspaces" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production merchants"}'
Save workspaceId from the response.
2

Create the client company

curl -sS -X POST "$FLUIDE_BASE_URL/api/v1/workspaces/$FLUIDE_WORKSPACE_ID/companies" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "countryCode": "CM",
    "currency": "XAF"
  }'
Save companyId from the response. Fluide automatically provisions a default operating wallet on Pay and seeds Books for the new company.
3

Store IDs in your integration

Persist both UUIDs per merchant in your database:
FieldHeader / usage
workspaceIdX-Workspace-Id on product API calls
companyIdX-Acting-Company-Id on product API calls
4

Verify with a product API call

curl -sS "$FLUIDE_BASE_URL/api/v1/hr/employees" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer" \
  -H "X-Workspace-Id: $FLUIDE_WORKSPACE_ID" \
  -H "X-Acting-Company-Id: $FLUIDE_COMPANY_ID"
A 200 with an empty list confirms scoping works — you are ready to add employees.

​
Tips

  • A Default workspace is auto-created when you complete SERVICE_PARTNER onboarding — you can use it instead of creating a new one.
  • Prefer a dedicated sandbox workspace for test merchants so production IDs never mix with test data.
  • Optional fields (industry, registrationNumber, taxId, etc.) can be set on create or updated later via PATCH.

​
Troubleshooting

ProblemResolution
403 / partner:workspace:manageYour developer account needs partner workspace permissions. Ensure onboarding completed as SERVICE_PARTNER.
403 on product APIs after createAdd both acting-client headers. Bearer alone scopes to partner org, not the merchant.
Company missing from listConfirm you are listing GET /workspaces/{id}/companies with the same workspace UUID used at create time.

Self-onboarding link

Let the merchant fill in their own profile.

Client KYB

Submit compliance documents for regulated products.

Workspaces API

Full workspace and company endpoint reference.