Issue a self-onboarding link

Generate a one-time URL so a merchant completes their own company profile under your workspace.

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

1. 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)
2. 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.

3. 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"
   
4. 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.

Related

Onboard a client company

Manual company creation flow.

Client KYB

Submit compliance after profile is complete.