Source: https://docs.debitura.com/referral-partners/integration-guides/client-onboarding-conflicts

# Handling 409 Conflicts

What happens when [`POST /clients`](https://docs.debitura.com/api/referral-partner-api/clients.md#create-and-onboard-a-new-client) returns 409 — and how to handle each scenario.

This guide assumes you've read [Client Onboarding](https://docs.debitura.com/referral-partners/integration-guides/client-onboarding.md).

Full Integration

With the [Starter Integration](https://docs.debitura.com/referral-partners/integration-guides/starter-integration.md), you don't handle 409s. The request waits as `awaiting_approval`, Debitura emails the client the approval invitation, and the approval link is your `solutionUrl`.

<a id="overview"></a>

## Overview

A `409 Conflict` 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 | What it means | What to do |
| --- | --- | --- |
| `ClientExistsNeedsLinking` | User has a Debitura account, not linked to you | Present the approval URL — user decides what to do |
| `ClientAlreadyLinkedToAnotherPartner` | User is linked to a different referral partner | Hard block — contact Debitura support |
| `UserCreationFailed` | Unexpected onboarding-user identity conflict during new-client creation — e.g. the email belongs to a non-creditor account | Correct the user identity or contact Debitura support |
| `PartnerNotAcceptingReferrals` | The referral partner is not accepting new referrals | Contact Debitura support |

These are the four conflict types the API returns in `type`. When you send an `Idempotency-Key`, a retry that arrives while the first request is still running also returns `409`, but with `businessErrors[0].type: IdempotencyKeyInProgress` and a `Retry-After: 2` header instead of `type`; wait and retry. A matched account that is not a creditor surfaces differently — see [InvalidClientType](https://docs.debitura.com/referral-partners/integration-guides/client-onboarding-conflicts.md#invalidclienttype) below.

<a id="how-debitura-detects-existing-clients"></a>

## How Debitura detects existing clients

Debitura matches the submitted email addresses against existing accounts using [exact-email matching](https://docs.debitura.com/referral-partners/integration-guides/client-onboarding.md#how-client-detection-works) — domain-suffix matching is intentionally disabled for this endpoint. If a match is found and the user isn't already linked to your partnership, you get a 409 with an approval URL.

<a id="clientexistsneedslinking"></a>

## ClientExistsNeedsLinking

```json
{
  "type": "ClientExistsNeedsLinking",
  "message": "Client already exists in Debitura. Approval required to link to referral partner.",
  "data": {
    "externalTenantId": "your-tenant-id",
    "onboardingLinks": {
      "url": "https://app.debitura.com/ReferralPartner/Approve?token=abc123..."
    },
    "isAttributedClient": false
  }
}
```

Present `onboardingLinks.url` to the user. Debitura does not email the approval URL to the user, so you are responsible for delivering it (see [White-Label UI](https://docs.debitura.com/referral-partners/concepts/white-label-ui.md) for the emails Debitura does send). If you call `POST /clients` again while the request is pending, you get the same approval URL back.

Approval URLs expire after a configurable per-partner TTL (`ApprovalTtlDays`, default 7 days, clamped 1–30 days). Subscribe to `client.link_expired` to detect expiry; resubmit `POST /clients` with the same `externalTenantId` to generate a fresh approval URL.

You receive a [`client.link_requested`](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md#clientlink_requested) webhook immediately when the 409 fires — this confirms the approval URL has been issued. If the user doesn't act, you receive a [`client.link_expired`](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md#clientlink_expired) webhook when the link request expires.

No information about the matched account is returned

For privacy, the 409 response does not reveal any details about the user's existing Debitura account. You only receive back your own `externalTenantId` and the approval URL.

The response body includes `client` (a default-valued placeholder creditor object) and `users` (an empty array) for JSON-shape stability — do not rely on either being populated. Emails of the matched account are never returned.

<a id="what-the-user-sees"></a>

### What the user sees

When the user follows the approval URL, they log in and see a **choice page** with up to two options:

**"Connect to existing account"** — shown when the user manages a Debitura creditor that is not already linked to your partnership. The user can select which existing account to link.

**"Set up a new account"** — always available. Creates a fresh creditor from the company details you submitted in the original request.

If all of the user's existing accounts are already linked to you (the [multi-entity scenario](https://docs.debitura.com/referral-partners/integration-guides/client-onboarding-conflicts.md#multi-entity-same-user-multiple-companies)), only "Set up a new account" is shown.

<a id="path-a-user-connects-an-existing-account"></a>

### Path A: User connects an existing account

The user selects one of their existing creditor accounts to link to your partnership.

1.  A `ReferralPartnerClientLink` is created for the existing creditor (the link points at the creditor the user picked — not a brand-new one)
2.  You receive a [`client.linked`](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md#clientlinked) webhook
3.  `isAttributedClient` is normally `false` — the user existed in Debitura before your referral. Exception: if your partnership previously held an attributed link to that client that was since archived (withdrawn), attribution is preserved (`true`). See [Attribution](https://docs.debitura.com/referral-partners/concepts/attribution.md) for how this affects revenue.

Cases from your original `POST /clients` payload are **created automatically** on this path immediately after the user approves the link. `AllowPendingContracts=true` is forced on replay regardless of what you sent on the original request — so if the SDCA, PoA or JPA are not yet signed at the time of approval, cases enter the `Pending contract signing` lifecycle state instead of failing with a `422`. KYC is not checked on replay, so missing KYC neither blocks the case nor puts it in `Pending contract signing`. They advance automatically once the client signs. You receive `case.created` webhooks for each successful case; failures are reported through the `cases.replay_failed` webhook, one per failed case (a failed case is never created, so it has no `lifecycle`). Other case creation failures (e.g. duplicate `creditorReference`) are reported per-case but do not block the link. If case creation does not complete when the user approves, Debitura retries it automatically every 15 minutes for up to 7 days after approval.

After approval, the user is directed to the signing flow to complete any outstanding contracts.

Concurrent approval requests

If two approval requests for the same client arrive simultaneously, only one succeeds. The second returns a `409` indicating the link request has already been processed. This is expected — you will receive a single `client.linked` webhook.

<a id="path-b-user-creates-a-new-account"></a>

### Path B: User creates a new account

The user creates a fresh creditor account from the company details you originally submitted.

1.  A new creditor is created from the stored company details
2.  The user is added as admin and redirected to sign the SDCA
3.  You receive a [`client.linked`](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md#clientlinked) webhook
4.  Any cases included in your original `POST /clients` payload are replayed against the new creditor from the stored request (same validation pipeline as first-time creation). `AllowPendingContracts=true` is forced on replay regardless of what you sent on the original request — so if the SDCA, PoA or JPA are not yet signed at replay time, cases enter the `Pending contract signing` lifecycle state instead of failing with a `422`. KYC is not checked on replay, so missing KYC neither blocks the case nor puts it in `Pending contract signing`. They automatically advance once the client signs. You receive `case.created` webhooks for each successful case; failures are reported through the `cases.replay_failed` webhook, one per failed case (a failed case is never created, so it has no `lifecycle`). Cases whose `creditorReference` already exists for this client link are skipped silently — no duplicate is created and no `cases.replay_failed` webhook is sent. Case creation failures do **not** block the account creation; the link is already persisted.
5.  `isAttributedClient` is `false` — because the _user_ already existed in Debitura, even though the creditor account is new

<a id="creating-cases-after-the-link-is-established"></a>

### Creating cases after the link is established

`POST /clients` is an **onboarding endpoint only**. Once a link exists for the `externalTenantId`, re-calling `POST /clients` does **not** create or retry cases. Every case in the request is reported as a failure with `errorType: "IdempotencyViolation"` (message `"Client already exists; cases not created on repeated call"`) and the case-creation pipeline is never run — nothing is created.

The cases included in your original onboarding request are still created automatically when the link is established (see Path A and Path B above). But to **add new cases or retry failed ones after the link exists**, switch to the bearer-token Customer API flow documented in [case submission](https://docs.debitura.com/referral-partners/integration-guides/case-submission.md). Do not re-call `POST /clients` to submit cases — it will silently report every case as an `IdempotencyViolation` and create none.

A repeat call returns `201` or `202` (depending on SDCA status) with all submitted cases listed under `caseResults.failedCases`:

```json
{
  "externalTenantId": "your-tenant-id",
  "caseResults": {
    "successfulCases": [],
    "failedCases": [
      {
        "caseIndex": 0,
        "creditorReference": "INV-001",
        "errorType": "IdempotencyViolation",
        "errorMessage": "Client already exists; cases not created on repeated call"
      }
    ]
  }
}
```

<a id="multi-entity-same-user-multiple-companies"></a>

## Multi-entity: same user, multiple companies

A common real-world scenario: your user manages Company A (already onboarded through your platform) and now wants to add Company B.

Calling `POST /clients` with a new `externalTenantId` but the same user email does not return a 409 when the user's only existing account is Company A, already linked to you under `tenant-a`. Company B is created directly (`201`/`202`), the existing user is reused, and Company B has `isAttributedClient: true`. A `409 ClientExistsNeedsLinking` (and `false` via **"Set up a new account"**) happens only if the email matches some other creditor not linked to you.

After Company B is created, the user can switch between their companies in the Debitura portal. Both companies are linked to your partnership, each with its own `externalTenantId`:

| Company | externalTenantId | isAttributedClient |
| --- | --- | --- |
| Company A (first onboarded) | `tenant-a` | `true` |
| Company B (added later) | `tenant-b` | `true` |

Each company has independent cases, contracts, and [revenue tracking](https://docs.debitura.com/referral-partners/integration-guides/revenue-tracking.md). Use the `externalTenantId` to distinguish them in your system.

<a id="clientalreadylinkedtoanotherpartner"></a>

## ClientAlreadyLinkedToAnotherPartner

The user's Debitura account is already linked to a different referral partner. Only one partner link per creditor is allowed.

```json
{
  "type": "ClientAlreadyLinkedToAnotherPartner",
  "message": "This client is already linked to another referral partner. Only one referral partner link per client is currently supported. Please contact Debitura support at contact@debitura.com for assistance.",
  "data": {
    "externalTenantId": "your-tenant-id"
  }
}
```

This is a hard block. Contact [partnerships@debitura.com](mailto:partnerships@debitura.com) to discuss resolution.

The `data` object echoes your `externalTenantId` for request correlation only — no information about the other partner or the matched creditor is returned.

<a id="invalidclienttype"></a>

## InvalidClientType

`InvalidClientType` is defined in the conflict-type enum but is **not currently returned** by `POST /clients`. A non-creditor account (e.g. a collection-partner user) is never matched by client detection. If its email is submitted as a user email, the request fails with `409 UserCreationFailed`; if only the `supportEmail` matches, a new client is created.

<a id="attribution-for-409-flows"></a>

## Attribution for 409 flows

409 resolution paths normally set `isAttributedClient = false` — meaning you earn referral fees only on cases submitted through your API, not on cases the client creates directly. Exception: on "Connect to existing account", if your partnership previously held an attributed link to that client that was since archived (withdrawn), attribution is preserved (`true`). The attribution flag is fixed on the link. Referral rates are recorded per case under the applicable plan; see [Case referral rates](https://docs.debitura.com/referral-partners/concepts/attribution.md#fee-percentage-snapshot) for Contract snapshots, Link tiers and the separate Integration payout allowance.

**Business context:** See [Referral Program Overview](https://support.debitura.com/en/articles/13908998-referral-partners-referral-program-overview-what-you-earn-when-and-what-counts) for the full revenue model. For the technical details of attributed vs non-attributed, see [Attribution](https://docs.debitura.com/referral-partners/concepts/attribution.md).
