Issue a self-onboarding link

Use this guide when you want the merchant to enter their own company details instead of creating the record fully via API. Fluide creates a placeholder company immediately and returns a tokenized URL the client opens once.

Prerequisites

Workspace and partner credentials — Onboard a client company
partner:client-company:manage permission

Steps

Issue the onboarding link

curl -sS -X POST "$FLUIDE_BASE_URL/api/v1/workspaces/$FLUIDE_WORKSPACE_ID/companies/onboarding-link" \
  -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": "Pending — Acme Corp",
    "ttlSeconds": 604800
  }'

The response includes:

company — placeholder record (save companyId now for acting-client headers)
onboarding.token — opaque token for the client form
onboarding.expiresAt — link expiry (default 7 days)

Share the URL with your client

Build the self-onboarding URL your product serves to merchants. The client completes country, currency, registration details, and other profile fields. When they submit, the token is consumed and the company record updates in place.

Poll or webhook for completion

List companies until the placeholder name updates and selfOnboardingToken is cleared:

curl -sS "$FLUIDE_BASE_URL/api/v1/workspaces/$FLUIDE_WORKSPACE_ID/companies/$FLUIDE_COMPANY_ID" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer"

Revoke an unused link (optional)

curl -sS -X DELETE "$FLUIDE_BASE_URL/api/v1/workspaces/$FLUIDE_WORKSPACE_ID/companies/$FLUIDE_COMPANY_ID/onboarding-link" \
  -H "Authorization: Bearer $FLUIDE_ACCESS_TOKEN" \
  -H "X-Fluide-Api-Key: $FLUIDE_API_KEY" \
  -H "X-Fluide-Client-Id: fluide-developer"

Tips

Issue the link before KYB if the merchant must confirm legal entity details themselves.
companyId is stable from the moment the link is issued — you can start storing acting-client headers immediately.
Placeholder country/currency (XX / XAF) intentionally fail readiness checks until the client submits valid values.

Troubleshooting

Problem	Resolution
Client sees “invalid or expired link”	Token expired or already consumed. Issue a new link or create the company manually.
Company stuck in placeholder state	Client has not submitted the form. Resend the URL or revoke and re-issue.

Onboard a client company

Manual company creation flow.

Client KYB

Submit compliance after profile is complete.

Overview

Service partner

HR & People

HR Operations

Payroll

Pay

Books

Access & Auth

Utils

Playbooks

Issue a self-onboarding link

Issue a self-onboarding link

Prerequisites

Steps

Tips

Troubleshooting

Onboard a client company

Client KYB

​Issue a self-onboarding link

​Prerequisites

​Steps

​Tips

​Troubleshooting

​Related

Onboard a client company

Client KYB

Issue a self-onboarding link

Prerequisites

Steps

Tips

Troubleshooting

Related