Skip to main content

Client Lifecycle

How POST /clients responses are determined and how Debitura detects existing clients.

Understanding Clients and Users​

One User = One Client

Debitura's user system is not multi-tenant. Each user belongs to exactly one client (creditor) account. A single user cannot be an administrator of multiple unrelated client accounts.

Multi-Brand Organizations​

If your customer has multiple brands, subsidiaries, or legal entities under one parent organization, they should use Divisions rather than creating separate client accounts:

  • One client account for the parent organization
  • Multiple divisions for each brand/entity
  • One externalTenantId maps to the client account
  • Cases are attributed to the appropriate division

See Client Divisions for details.

Separate Businesses​

If you need to onboard completely separate, unrelated businesses:

  • Each business requires its own client account
  • Each must have a unique externalTenantId
  • Each must use different email addresses (the onboarding user's email identifies the client)

Using the same admin email across different externalTenantId values will result in a 409 AlreadyLinkedDifferentTenant error.

Response Codes​

CodeMeaningNext Step
201Client readyMint token, submit cases
202Onboarding requiredRedirect user to SDCA signing
409Client already existsHandle based on conflictResponse.type

How Client Detection Works​

Debitura checks if a client already exists by matching email addresses from your request against existing users and creditors.

Matching Algorithm​

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, yahoo.com): Match by exact email only. alice@gmail.com only matches alice@gmail.com, not bob@gmail.com.

This prevents false positives—two unrelated Gmail users won't collide, but two employees at the same company will be recognized as the same client.

What Gets Checked​

  1. All users[].email addresses in your request
  2. The client.supportEmail if provided

These are matched against:

  • Existing Debitura user emails (via their creditor relationship)
  • Existing creditor office emails

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 AlreadyLinkedToAnotherPartner
│  │
│  ├─ That client linked to YOU with different externalTenantId?
│  │  YES → 409 AlreadyLinkedDifferentTenant
│  │
│  └─ Not linked yet?
│     YES → 409 ClientExistsNeedsLinking (approval required)
│
└─ No match found → Create new client (201 or 202)

409 Conflict Scenarios​

ClientExistsNeedsLinking​

The client has an existing Debitura account. They must approve linking to your platform.

{
  "conflictResponse": {
    "type": "ClientExistsNeedsLinking",
    "isAttributedClient": false
  }
}

Present the approval URL to your user. After approval, isAttributedClient will be false—see Attribution for fee implications.

AlreadyLinkedDifferentTenant​

You already linked this client, but with a different externalTenantId.

Example:

  1. You call POST /clients with externalTenantId: "tenant-A" and users: [{email: "john@acme.com"}]
  2. Client is created and linked
  3. Later, you call POST /clients with externalTenantId: "tenant-B" and same email john@acme.com
  4. Debitura detects: same client (email match), same partner (you), but different tenant ID
  5. Returns 409 AlreadyLinkedDifferentTenant

Solution: Use the original externalTenantId for this client. One client = one tenant ID per partner.

Multi-brand organizations

If your user manages multiple brands/entities within the same organization, don't create separate clients. Use divisions instead—one client account with multiple divisions for case attribution. See Client Divisions.

AlreadyLinkedToAnotherPartner​

The client is linked to a different referral partner. Only one partner per client is allowed.

Solution: Contact Debitura support.

Idempotency​

Calling POST /clients multiple times with the same externalTenantId is safe. The API returns the current client state.

Abandoned Onboarding​

If a user starts onboarding but doesn't complete it:

  1. Call POST /clients again with the same externalTenantId
  2. Returns 202 with a fresh onboarding URL
  3. User can continue where they left off

No duplicate client is created. Cases from your first call (if any) remain intact.

202 on retry, not 409

If you created the client, retrying returns 202. You only get 409 when the client existed in Debitura before your first call (detected via email matching).