Client Lifecycle
A summary of how POST /clients responses are determined and how clients move through the onboarding process.
Response Codes
| Code | Meaning | Next Step |
|---|---|---|
| 201 | Client ready (SDCA signed) | Mint token, submit cases |
| 202 | Onboarding required (SDCA not signed) | Redirect user to onboarding URL |
| 409 | Client already exists | Handle based on conflictResponse.type |
Key Behaviors
- Idempotency — Calling
POST /clientswith the sameexternalTenantIdreturns the existing client state, not an error. Safe to retry. - Client detection — Debitura matches by email domain (company emails) or exact email (generic providers like gmail.com).
- Multi-brand — Use Divisions for multiple brands under one parent. One client account, multiple divisions. See Client Divisions.
- Withdrawal —
POST /clients/{externalTenantId}/withdrawarchives the link and closes all pending cases. Only works if all cases are inPendingContractSigning.
Full Implementation Guide
For the complete POST /clients workflow — request format, all response scenarios, detection algorithm, decision flow diagram, return URLs, error handling, and withdrawal — see:
How isAttributedClient affects your revenue is covered in Attribution. For onboarding URL patterns and branding, see White-Label UI. For the withdrawal endpoint, see the API reference.