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 existing clients by exact email address (any of the supplied user emails or the support email). Company-domain matching is not used by this endpoint.
- 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.
See the Client Onboarding Guide for the complete POST /clients workflow — request format, all response scenarios, detection algorithm, decision flow diagram, return URLs, and error handling. 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.