When your POST /clients call returns a 409 ClientExistsNeedsLinking response, your customer already has a Debitura account and must approve linking it to your platform. This article walks through what they see at each step, what your platform receives, and how the cases in your original payload are now carried through automatically.

The 409 path is one of three responses you can get from POST /clients on the Referral Partner API. The three 409 response types are:

The ClientExistsNeedsLinking path triggers whenever the customer you are creating already exists in Debitura - either because they signed up directly at some point, or because another channel registered them. Instead of failing the request outright, the API creates a link approval request, emails the customer an approval URL, and asks them to confirm before any link is established between your platform and their account.

For the happy-path flow (where the customer is brand new to Debitura and walks through onboarding from scratch), see Referral Partners: What your client sees during onboarding. The 409 path branches off when the customer already has an account. The other two response types are covered briefly in Other 409 scenarios below.

Before the recent carry-through changes, two things made the 409 path painful for partners and confusing for customers:

Both are fixed. Cases from your original payload now carry through automatically and land in "Pending Contract Signing" until the customer signs. The customer is also redirected straight into the signing flow after approval, then back to your platform. The result is a smoother first-touch experience for the customer and fewer follow-up tickets for your support team.

There are two variants of the 409 path. The standard variant covers most cases. The multi-entity variant only triggers when the customer's contact email matches an existing user exactly.

When POST /clients returns a 409 with Type: ClientExistsNeedsLinking, the response includes an approval URL pointing to the link request page in the Debitura app. Your platform's job is to deliver that URL to the customer (by redirect, in-app prompt, or your own email). What happens next:

When the conflicting user matches the contact email exactly (rather than just by email domain), the 409 response carries an OnboardingUrl pointing to a Choice page in the Creditor App instead of the standard approval page. This is most common when the same person is acting as an accountant or operator across several legal entities.

On the Choice page, the customer picks one of two options:

In both options, the cases supplied in your original POST /clients payload are stored and replayed against the chosen or newly created entity. No data is lost between the two calls.

The approval URL expires after a configurable per-partner window. The default is 7 days; the maximum is 30 days. Chaser is currently configured for 30 days. To change your partner's value, email [email protected].

Expiry runs hourly as a background job, so a client.link_expired webhook can arrive up to one hour after the configured TTL technically passes. If a customer's link request expires unanswered, your platform can re-run the same POST /clients call with the same external tenant ID and payload to generate a fresh approval URL. See Referral Partners: When your customer's link request expires for the recovery script.

From the moment the 409 fires through to a final outcome, you receive a sequence of webhooks:

For the full event glossary, see Referral Partners: Webhook events (business meaning glossary).

Because the customer pre-existed in Debitura, the link is non-attributed (IsAttributedClient = false). You earn referral fees only on cases submitted through your integration using your bearer token. Cases the customer creates directly in the Debitura web app do not generate fees. For the full attribution rules, see Referral Partners: API and integration overview.

Concurrent approve or decline calls are processed atomically. Only one succeeds; the other receives a 409 Conflict and an error indicating the link has already been used. This means no duplicate cases are created, even if the customer (or you on their behalf) clicks Approve twice in quick succession or has two browser tabs open.

Today, the only collection partner that requires KYC verification is Oriel Collections (UK). If a 409 link request is approved for a customer who would route to Oriel and has no KYC record on file, the cases that carry through bypass KYC because the carry-through path does not enforce it. The gap self-heals on the next case your platform submits for the same customer through your API integration, which goes through the bearer-token path that does enforce KYC. So a UK customer may briefly have cases that look like nothing is happening until the next submission triggers the KYC requirement. For how to support a customer in this situation, see Referral Partners: How to support your customers using Debitura.

The walkthrough above covers ClientExistsNeedsLinking. The other two 409 response types resolve differently and are not covered in detail here.

When the 409 response carries Type: ClientAlreadyLinkedToAnotherPartner, the matched client is already linked to a different referral partner. Only one referral partner link per client is supported today. What to tell the customer: contact [email protected] to discuss options.

When the 409 response carries Type: InvalidClientType, the email or company details matched an existing Debitura account that belongs to a collection partner or another non-creditor entity - not a creditor. The user cannot be linked as a referral partner client in this state. What to tell the customer: they should create a separate Debitura creditor account, or contact [email protected] if this conflict is unexpected.