Client Onboarding

Create and link clients (creditors) to your referral partner account. Full Integration. With the Starter Integration, POST /collection-requests creates or finds the client for you.

Client lifecycle

Code	Meaning	Next step
201	Client ready (SDCA signed)	Mint a token, submit cases
202	Onboarding required (SDCA not signed, or needs re-signing)	Send the user to `onboardingLinks.url`
409	Client already exists, or an identical keyed request is still running	Handle by `type`, or `businessErrors[0].type` for `IdempotencyKeyInProgress`

Idempotent on externalTenantId. A repeat call returns the existing client state and creates no cases: every case in it is reported as IdempotencyViolation. Submit later cases through the Customer API with a bearer token.
Existing clients are matched by exact email address (any supplied user email or the support email). Company-domain matching is not used.
Several brands under one parent use Divisions: one client account, several divisions. See Client Divisions.
Withdrawal archives the link and closes all pending cases; see Client Withdrawal.

Overview

Before submitting cases on behalf of a client, you must create or link them in Debitura. This establishes the relationship between your platform, the client, and Debitura's collection network.

The flow:

Call POST /clients with your externalTenantId
Handle the response (201, 202, or 409)
If onboarding is required, present the onboarding URL to your client
Once onboarding is complete, mint a bearer token and submit cases

Create or Link a Client

POST https://referral-api.debitura.com/clients
XApiKey: YOUR_API_KEY
Content-Type: application/json

{
  "externalTenantId": "your-unique-client-id",
  "client": {
    "name": "Acme Corp",
    "registrationNumber": "12345678",
    "country": "GB",
    "address": "123 Business Street",
    "city": "London",
    "zipCode": "EC1A 1BB",
    "supportEmail": "support@acme.com"
  },
  "users": [
    {
      "email": "admin@acme.com",
      "name": "Jane Smith",
      "isOnboardingUser": true
    }
  ]
}

Required Fields

Field	Description
`externalTenantId`	Your unique identifier for this client. Used for all future operations.
`client.name`	Legal company name
`client.country`	ISO 3166-1 alpha-2 code (e.g. `"GB"`) or full English country name
`client.supportEmail`	Support email address for the client. Required.
`users`	At least one user. For multi-user requests, exactly one must have `isOnboardingUser: true`. Single-user requests auto-infer the onboarding user.
`users[].name`	Full name of the user (single field, not split into first/last)
`users[].email`	User's email address (validated format)

How Client Detection Works

When you call POST /clients, Debitura checks if the client already exists by matching email addresses from your request against existing users and creditors.

All emails are matched by exact email address only. Company-domain matching is intentionally disabled for this endpoint to avoid false-positive matches. alice@acme.com matches only alice@acme.com — it will not match bob@acme.com. This applies to both company and generic-provider emails (the supplied user emails and the client's support email).

Decision Flow

POST /clients
│
├─ Same externalTenantId already linked?
│  YES → Return existing client (201 or 202); no cases created
│
├─ Email exactly matches existing Debitura client?
│  │
│  ├─ That client linked to DIFFERENT partner?
│  │  YES → 409 ClientAlreadyLinkedToAnotherPartner
│  │
│  └─ Not linked yet?
│     YES → 409 ClientExistsNeedsLinking (approval required)
│
└─ No match found → Create new client (201 or 202)

Multi-Brand Organizations

One User Can Manage Multiple Clients

A Debitura user can have relations to multiple client (creditor) accounts. Reusing an existing user does not require merging otherwise separate businesses.

If your customer has multiple brands or legal entities under one parent, use Divisions — one client account with multiple divisions for case attribution. See Client Divisions.

If they are completely separate businesses, each needs its own client account with a unique externalTenantId. The same user can manage multiple businesses: for the same referral partner, a new external tenant can create a separate creditor while reusing that user's identity. Do not assume this always produces 409 ClientExistsNeedsLinking. See multi-entity flow for details.

Response Handling

201 Created — SDCA Onboarding Complete

The client's current SDCA-based onboarding check is complete. You can mint a token, but a future case can still require partner- or jurisdiction-specific PoA, JPA, or KYC before it proceeds.

202 Accepted — Onboarding Required

The client was created, but its SDCA-based onboarding check is incomplete. An active link can already mint a bearer token, and a case sent with allowPendingContracts: true can enter PendingContractSigning before onboarding finishes. Other case-specific requirements can still block submission.

{
  "externalTenantId": "your-unique-client-id",
  "onboardingDone": false,
  "onboardingLinks": {
    "url": "https://referral.debitura.com/onboarding/companydetails/..."
  }
}

Important: POST /clients suppresses the immediate standard creditor welcome email, so you must present the onboarding URL to your client (in-app, email, redirect). After the client successfully signs through the referral onboarding UI, Debitura automatically sends welcome or activation emails to the users. While production cases wait for the client's signature, Debitura also sends contract-signing reminders; see White-Label UI.

409 Conflict — Client Already Exists

A 409 indicates an onboarding conflict: an existing account/link or user identity conflict, a referral partner that is not accepting new referrals, or an in-progress keyed request. Inspect type or businessErrors[] as appropriate:

Type	Meaning	Action
`ClientExistsNeedsLinking`	User has a Debitura account, not linked to you	Present the approval URL — user chooses to link existing or create new
`ClientAlreadyLinkedToAnotherPartner`	Linked to a different partner	Contact Debitura support
`UserCreationFailed`	Unexpected onboarding-user identity conflict while creating a new client	Retry only after correcting the user identity; contact Debitura if it persists
`PartnerNotAcceptingReferrals`	The referral partner is not accepting new referrals	Contact Debitura support

These are the four conflict types currently returned in type by POST /clients. With an Idempotency-Key, a retry while the first request is still running returns 409 with businessErrors[0].type: IdempotencyKeyInProgress and Retry-After: 2 instead. An account that is not a creditor (e.g. a collection-partner user) is never matched. If its email is submitted as a user email, the request fails with 409 UserCreationFailed; if it is only the supportEmail, a new client is created. See InvalidClientType.

For ClientExistsNeedsLinking, the response includes an onboardingLinks.url. Present this URL to the user — they'll see a choice page where they can connect an existing Debitura account or set up a new one. After either choice, you receive a client.linked webhook and the client is ready.

Full guide: See Handling 409 Conflicts for the complete flow — what the user sees, the two resolution paths, how to create cases after the conflict is resolved, multi-entity scenarios, and revenue attribution impact.

Adding a Return URL

Append a return URL to redirect clients back to your platform after onboarding:

https://referral.debitura.com/onboarding/companydetails/abc123?returnUrl=https://yourapp.com/onboarding-complete

URL Encoding

If your return URL contains query parameters, URL-encode it first:

const returnUrl = encodeURIComponent('https://yourapp.com/done?clientId=123');
const onboardingUrl = `${baseUrl}?returnUrl=${returnUrl}`;

After successful completion of the signing or approval flow, Debitura appends completed=true to your returnUrl before redirecting (e.g. https://yourapp.com/onboarding-complete?completed=true). If the user abandons the flow, the redirect happens without this parameter — allowing you to distinguish a completed flow from an abandoned one.

See White-Label UI for customization options.

Including Cases

You can include cases in the POST /clients request. Cases are validated and created alongside the client.

Before the client is created, every case is checked. Invalid case fields (for example a creditorReference repeated within the request, claim-line or age-bucket errors, an unsupported debtor country, an invalid debtor type, or a missing debtor address or city) return 400, and a case below the minimum claim amount returns 422 with AmountBelowMinimum. In both cases nothing is created.
After the client is created, each case either appears in caseResults.successfulCases or in caseResults.failedCases with an errorType such as NoPartnerAvailable, CreditorBlocked, DuplicateReference, ValidationError or UnexpectedError. The response is still 201 or 202.

Embedded cases accept all three modes: a single due date, cumulative age buckets, or claimLines[] (max 1,000 lines per case and 1,000 across all cases in the request). Use Claim Amount and Age to choose between them and understand where invoice-level claim lines are available.

Client vs Debtor

The client object (your customer) has minimal required fields. The debtor object in each case has strict validation—see debtor requirements.

If the response is 409 ClientExistsNeedsLinking, the cases you submitted are persisted server-side and replayed against the creditor on the resolved client link (the selected existing account or newly created account) automatically once the user approves the link. AllowPendingContracts=true is forced on replay, so missing SDCA or PoA can place a case in PendingContractSigning. KYC is evaluated separately and does not itself force that lifecycle on the replay path. Failed replayed cases are reported via the cases.replay_failed webhook (one per failed case, with creditorReference and failureReason); a failed case is never created, so lifecycle cannot show it. See Handling 409 Conflicts for the full flow.

After Onboarding

Once onboarding is complete:

Mint a bearer token — See Authentication
Submit cases — See Create a Case (uses the Customer API)
Track progress — See Webhooks for real-time updates

Handling Abandoned Onboarding

If a user starts onboarding but doesn't complete it (closes browser, etc.):

Call POST /clients again with the same externalTenantId
You'll receive 202 Accepted with the existing link's deterministic onboarding URL
Redirect the user to continue where they left off

The API is idempotent—repeated calls return the existing client, not an error.

202 on retry, not 409

If you created the client (got 202), retrying the active link returns 202 again. A 409 usually reflects an existing-account/link conflict, but UserCreationFailed can also occur while a new client is being created.

See Client lifecycle for the summary.

Error Handling

Error	Cause	Solution
`400 Bad Request`	Invalid or missing fields, or invalid embedded cases	Check required fields and data formats
`401 Unauthorized`	Invalid API key	Verify your `XApiKey` header
`409 ClientExistsNeedsLinking`	Client exists in Debitura	Present approval URL to client (configurable per-partner TTL, default 7 days, max 30)
`409 ClientAlreadyLinkedToAnotherPartner`	Client linked to different partner	Contact Debitura support
`409 UserCreationFailed`	Onboarding-user identity conflict during new-client creation	Correct the user identity or contact Debitura support
`409 PartnerNotAcceptingReferrals`	Referral partner is paused or closed to new clients	Contact Debitura; if a paused account is reactivated, retry the same request and `Idempotency-Key`
`409` with `IdempotencyKeyInProgress`	Same `Idempotency-Key` request still running	Wait for `Retry-After` (2 seconds) and retry
`422 AmountBelowMinimum`	An embedded case is below the minimum claim amount	Remove or correct the case
`422 IdempotencyConflict`	`Idempotency-Key` reused with a different request	Use a new key for a different request

See Error Handling for the full error response format.

Client Withdrawal

To offboard a client and remove their link to your referral partner account:

POST https://referral-api.debitura.com/clients/{externalTenantId}/withdraw
XApiKey: YOUR_API_KEY

Requirements:

Only attributed clients (IsAttributedClient = true) can be withdrawn. Non-attributed clients return 409.
All cases must be in PendingContractSigning status. If any case has progressed further, returns 409.

What happens:

Validates the client is attributed and all cases are in PendingContractSigning
Closes all pending cases with the CaseNeverStartedInternal close code
Archives the referral partner client link

Returns 204 No Content on success. Returns 404 if no active link exists. Returns 409 Conflict if the client is non-attributed or cases have progressed beyond onboarding.

Withdrawal archives the link and closes the pending cases. It does not delete the client — their Debitura account, users, KYC record and signed contracts all survive. They simply stop being attributed to you.

Archiving the link also revokes everything that link authorised. Bearer tokens can no longer be minted for that externalTenantId (POST /oauth/token answers 404), and any onboarding, signing, Power of Attorney or KYC URL you had previously issued for the client stops working — the client sees the generic "Invalid or Missing Link" page instead. See Revoked Links.

Re-submitting a withdrawn client

You can bring a withdrawn client back by calling POST /clients again with the same externalTenantId. This re-links them and creates the cases in your payload as normal — you do not get the ClientExistsNeedsLinking 409 and your client is not asked to approve anything.

Re-linking applies when all of the following hold:

the same externalTenantId, submitted by the same referral partner
the previous link was an attributed one
the client Debitura resolves is the same client the archived link pointed at
that client currently has no active link to any referral partner

If any of these conditions does not hold, normal client detection applies: an active link to another partner returns ClientAlreadyLinkedToAnotherPartner; other existing-account conflicts can return ClientExistsNeedsLinking; unrecognized contact emails can create a new client.

Terms are re-snapshotted

A re-link creates a new link, not a revival of the old one, so the withdrawal remains in the audit trail. Your attribution carries over. On the Contract plan, the new link snapshots your current agreed percentage rather than the archived link's rate. New cases record their rate under the applicable plan; Link tiers and the Integration payout allowance follow the case referral rules. Re-linking does not reprice existing cases.

The relink itself does not emit client.linked. If relinking supersedes a pending link request, that cleanup can emit client.link_declined; you will also receive case.created events for submitted cases.

Client lifecycle​

Overview​

Create or Link a Client​

Required Fields​

How Client Detection Works​

Decision Flow​

Multi-Brand Organizations​

Response Handling​

201 Created — SDCA Onboarding Complete​

202 Accepted — Onboarding Required​

409 Conflict — Client Already Exists​

Adding a Return URL​

Including Cases​

After Onboarding​

Handling Abandoned Onboarding​

Error Handling​

Client Withdrawal​

Re-submitting a withdrawn client​