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.

Company domains (acme.com, business.co.uk): match by domain suffix. If you send alice@acme.com, it matches any existing user at @acme.com.

Generic providers (gmail.com, outlook.com): match by exact email only. alice@gmail.com only matches alice@gmail.com, not bob@gmail.com.

Decision Flow

POST /clients
│
├─ Same externalTenantId already linked?
│  YES → Return existing client (201 or 202)
│
├─ Email/domain 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

:::info 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
InvalidClientType	Not a creditor account	Contact Debitura support

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

:::warning 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}`;

:::

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.

:::warning 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.

:::note 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
409 InvalidClientType	Matched account is not a creditor (e.g. a collection partner)	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 CaseNeverStarted 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.

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