Skip to main content

Referral Partners: Customer signup / activation issues

If a customer you referred to Debitura is unable to sign up, complete onboarding, or activate their account, this page covers the most common causes and how to resolve them. Most sections follow the pattern: problem, likely cause, and fix.

1. Customer never received the activation or verification email

Problem

The customer was sent to Debitura through your platform's onboarding flow, but they say they never received an email with the link or verification code.

Key fact: in the referral partner flow, Debitura does not email the onboarding link to the customer. Your platform is responsible for presenting the onboarding URL to the customer (by redirect, in-app prompt, or your own email). If the customer expects an email from Debitura but does not receive one, that is by design - check that your own platform delivered the link.

Likely causes

  • Your platform did not present the link: The "Send to Collection" flow may not have redirected or shown the URL after the API call returned. Confirm with your developer that the onboardingLinks.url from the 202 response was passed to the customer.

  • Email typo: If your platform sent the link to the customer by email, the customer's email address may be wrong. Verify the email used in the original API call.

  • Spam or junk filter: If the customer is expecting the SDCA signing 2FA code (sent by Debitura by email during signing) and that has not arrived, ask them to check spam or junk.

Fix

  1. Confirm your platform actually delivered the onboarding URL to the customer.

  2. If the email address used in the API call was wrong, generate a new onboarding link by calling POST /clients again with the corrected email and the same externalTenantId. Note: this only works before the customer has reached the Users and Roles onboarding step. Once an onboarding user record already exists, POST /clients is idempotent and will NOT update that user's email - the partner must correct it directly in the onboarding flow's Users and Roles step instead.

  3. If the customer reached the SDCA signing step but the 6-digit code did not arrive, see Section 4 below.

  4. Ask the customer to whitelist @debitura.com and [email protected] if Debitura emails (such as the SDCA verification code or the welcome email) are getting filtered.

2. API returns 409 Conflict when creating a customer

Problem

Your platform calls POST /clients on the Referral Partner API and receives a 409 Conflict response instead of a 201 or 202.

For a full step-by-step walkthrough of what your customer experiences on the 409 path - including the standard approval page, the multi-entity Choice variant, the carry-through of cases from your original payload, and the configurable approval window - see Referral Partners: 409 conflict path - what your customer sees and what your platform does. This troubleshooting article focuses on the two error scenarios and how to resolve them.

Likely causes

There are two distinct 409 scenarios:

  • Scenario A: Customer already exists in Debitura The customer already has a Debitura account (created independently or through another channel). The response includes Type: ClientExistsNeedsLinking and an approval URL.

  • Scenario B: Customer linked to another referral partner - The customer is already linked to a different referral partner. Only one referral partner link per customer is supported. The response includes Type: ClientAlreadyLinkedToAnotherPartner.

Exception - a customer you previously withdrew does not produce a 409. If you withdraw a customer and later call POST /clients again with the same ExternalTenantId, Debitura re-links the original account and creates your cases normally: no 409, no approval URL, and no client.* webhook. This holds only while the archived link was an attributed one, the matched account is the same account that link pointed at, and that account currently has no active link to any partner. If one of those does not hold, the re-link does not happen - but the outcome is not always Scenario A. Depending on what Debitura matched, you may get the Scenario A approval path, a conflict saying the account is already linked to another partner, or an ordinary new-client creation. See Referral Partners: 409 conflict path.

Fix

  • Scenario A: Send the approval URL from the response to the customer. The customer must approve linking your platform to their existing Debitura account. What happens on approval:

    • The link is created with IsAttributedClient = false. Your platform earns fees only on cases submitted through your integration.

    • Cases from your original POST /clients payload are created automatically on the existing client account. If the client has not yet signed the SDCA or PoA, those cases land in "Pending Contract Signing" and advance automatically once signing completes. Note for developers: there is no case.failed event on this path - detect outstanding signing via the case lifecycle field, not by waiting for a failure event.

    • You receive a case.created webhook for each case created at approval time.

    • The customer is then redirected into the signing flow for any outstanding requirements (SDCA, PoA, JPA, and KYC where applicable), then back to your platform.

    What happens if the customer never responds: the link request expires after the configured approval window and you receive a client.link_expired webhook. To recover, call POST /clients again with the same payload to generate a fresh link request. See Webhook events glossary for what client.link_requested and client.link_expired mean.

    What happens if the customer clicks the link twice (or you and the customer click at the same time): the second action returns a 409 Conflict and an error indicating the link has already been used. Only one approval or decline is processed per link request, so no duplicate cases are created.

    Approval link expiry: the default approval window is 7 days, configurable per partner up to 30 days. Chaser is set to 30 days. To change your partner's value, email [email protected].

  • Scenario B: Contact Debitura support at [email protected]. The customer cannot be linked to multiple referral partners at the same time.

3. API returns 400 Bad Request when creating a customer

Problem

Your platform calls POST /clients and receives a 400 validation error. No customer account is created.

Likely cause

One or more required fields are missing or have invalid values. The required fields are: ExternalTenantId, CompanyName, Country, and Email. Address fields (Address, ZipCode, City, State) are optional in the API request. If provided, they must meet format requirements (for example, Address max 500 characters, ZipCode max 20 characters).

Fix

  1. Check the error response for the specific field and validation message.

  2. Ensure all required fields (ExternalTenantId, CompanyName, Country, Email) are present and correctly formatted.

  3. If you included optional address fields, verify they meet the format requirements.

  4. Correct the data and retry the API call.

4. Customer is stuck at "Onboarding Required" (API returns 202)

Problem

The API returns 202 Accepted with an OnboardingUrl, but the customer has not completed the onboarding process.

Likely cause

The customer needs to complete Debitura's 4-step onboarding flow before the account is fully activated. The steps are:

  1. Company Details - confirm or update company information

  2. Users and Roles - optionally add team members (can be skipped)

  3. Sign Agreements - sign the Standard Debt Collection Agreement (SDCA), which requires email-based two-factor authentication (a 6-digit code sent to the registered email). For clients with existing active cases, a Power of Attorney document will also appear in this step.

  4. Complete - confirmation page

The customer may have dropped off at any of these steps, or may be unable to complete the SDCA signing due to the 2FA verification code not arriving.

Fix

  1. Redirect the customer to the OnboardingUrl from the API response. The onboarding flow picks up where the customer left off.

  2. If the customer cannot complete SDCA signing because the 2FA code did not arrive: ask them to check spam/junk, and use the "Resend code" option on the signing screen. The code is valid for 30 minutes. While it is still valid, resending sends that same code again rather than replacing it - receiving an identical code is expected, not a fault. Only once the code has actually expired does a resend issue a fresh code with a new 30-minute lifetime, and the old one stops working. Either way, have the customer enter the code from the most recent email. Entering a wrong code is harmless: an incorrect guess does not consume or invalidate the stored code, and there is no attempt limit or lockout, so the customer can simply retype the correct one. Also check whether the person originally designated to sign (added during the Users and Roles onboarding step) still exists on the creditor account - if they have been removed, no code is sent and no other colleague on the account receives it as a fallback - and this fails silently from your side: nothing is surfaced through the API or a webhook, so it looks identical to a code that simply never arrived. Resending or checking spam will not help in this case; the partner needs to confirm the onboarding link's designated user, or generate a fresh onboarding link naming a replacement. If the customer is on a browser with aggressive cookie or tracking-blocking extensions, the form may not submit correctly - suggest an incognito window or a different browser. If the customer's email server is rejecting mail from Debitura's sender (SendGrid), the code will never arrive no matter how many times it is resent - the partner needs to update that onboarding user's email address to a reachable one and request a fresh onboarding link.

  3. The POST /clients endpoint is idempotent. Call it again with the same ExternalTenantId to get a fresh OnboardingUrl at any time.

For more on contracts and signing, see Contracts & signatures overview. For a step-by-step view of what the customer sees during onboarding, see What your client sees during onboarding.

5. Customer was previously active but now returns 202 again

Problem

A customer who was previously fully onboarded (API returned 201) now returns 202 Accepted when you call POST /clients.

Likely cause

Debitura has released a new version of the Standard Debt Collection Agreement (SDCA). The API automatically detects when a customer needs to re-sign the updated agreement. This typically happens 1 to 2 times per year due to regulatory changes or new feature requirements.

Fix

  1. Redirect the customer to the OnboardingUrl from the 202 response. They will be taken directly to the contract re-signing flow.

  2. No code changes are needed on your side. The API transparently manages SDCA version upgrades.

  3. After the customer re-signs, subsequent calls to POST /clients will return 201 again.

Developer Docs: Developers: Want to automate this with the API? See Developer Docs: Referral Partner API.

6. Same contact email used for two different client companies

Problem

You onboarded two different client companies using the same contact email (for example, one person who manages several client accounts), and you are not sure whether their accounts have been merged or mixed together.

What happens

This is expected and is not a bug. Your client can sign in to both companies using that same email, but each company's cases and data stay completely separate. Sharing a login email only shares the sign-in identity - it does not link or merge the two companies, which remain independent client accounts. (This case previously failed with a server error; it now succeeds automatically.)

Fix

No action is needed. If your client is concerned that using one email means their companies are combined, you can reassure them that the accounts are kept separate. Only escalate if you actually see one company's cases or data appearing under the other.

Developer Docs: Developers: Want to automate this with the API? See Developer Docs: Referral Partner API.

Escalation

If none of the above resolves the issue, contact Debitura support and include the following information:

  • Your Referral Partner name and Partner ID

  • The customer's ExternalTenantId (your internal identifier for the customer)

  • The customer's company name, email address, and country

  • The exact API response (HTTP status code and full response body)

  • Timestamps of the failed attempts

  • Screenshots of any error messages the customer sees in the onboarding flow

Contact: [email protected]. For full SLA, escalation path, and what to include in a support request, see Referral Partners: Support channels, SLA, and escalation.

For broader integration issues beyond customer signup, see Integration troubleshooting checklist.

Related Articles
Did this answer your question?