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 = One Client

Debitura's user system is not multi-tenant. Each user belongs to exactly one client (creditor) account.

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 — each POST /clients call with a new externalTenantId for that user returns 409 ClientExistsNeedsLinking, and the user picks "Set up a new account" on the approval page to create the new entity. See multi-entity flow for details.

Response Handling

201 Created — Client Ready

The client is fully onboarded and ready. Proceed to mint a token and submit cases.

202 Accepted — Onboarding Required

The client was created but must complete onboarding before cases can be submitted.

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

Important: Debitura does not send emails for referral flows. You must present the onboarding URL to your client (in-app, email, redirect).

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

These are the only two 409 conflict types. If the matched account is not a creditor (e.g. a collection partner), the request fails with a 500 Internal Server Error — a data-integrity case that should not occur in practice. 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.

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 cases land in PendingContractSigning lifecycle state if SDCA/PoA/KYC are not yet signed. There is no case.failed webhook on this path — detect failures via the case lifecycle field. 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 a fresh 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 returns 202 again. You only get 409 if the client existed in Debitura before your first call.

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
500 Internal Server Error	Matched account is not a creditor (e.g. a collection partner) — data-integrity anomaly, not a 409	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.

Irreversible

Client withdrawal is permanent. To re-link the client, they must go through the full onboarding flow again.