Client Onboarding

Create and link clients (creditors) to your referral partner account.

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:

1. Call POST /clients with your externalTenantId
2. Handle the response (201, 202, or 409)
3. If onboarding is required, present the onboarding URL to your client
4. 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)
│
├─ 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.

409 Conflict — Client Already Exists

The submitted user already exists in Debitura. Check the type field to determine the scenario:

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

These are the three conflict types currently returned by POST /clients. 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.

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 matched creditor 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:

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

Handling Abandoned Onboarding

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

1. Call POST /clients again with the same externalTenantId
2. You'll receive 202 Accepted with the existing link's deterministic onboarding URL
3. 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 complete decision tree.

Error Handling

Error	Cause	Solution
400 Bad Request	Invalid or missing fields	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

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:

1. Validates the client is attributed and all cases are in PendingContractSigning
2. Closes all pending cases with the CaseNeverStartedInternal close code
3. 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 does not hold — most commonly because the client has since linked to another partner — you get the ordinary ClientExistsNeedsLinking 409 and the standard approval flow applies.

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, but the referral fee percentage is taken from your current rate rather than the rate stored on the archived link — this is a new agreement formed today.

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.