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, do not rely on calling POST /clients again: a repeated request for an externalTenantId that is already linked returns the customer's current onboarding state and does not update the existing user's email. Correct the user's email 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 sign-in and company choice, 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 409 error scenarios listed under Likely causes and how to resolve them.

Likely causes

The 409 scenarios covered here are:

  • 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.

  • Scenario C: Your referral account is paused or closed to new referrals - Debitura has paused or closed your referral account for new customers, so every new customer request is refused. The response includes Type: PartnerNotAcceptingReferrals. No customer, user or link is created.

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 (data.onboardingLinks.url) to the customer by redirect, an in-app prompt or your own email - Debitura does not email it. The customer must approve linking your platform to their existing Debitura account. What happens on approval:

    • The link is normally created with IsAttributedClient = false, so your platform earns fees only on cases submitted through your integration. If you previously held an attributed link to this same customer, approval preserves attributed status.

    • 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, and a cases.replay_failed webhook for any stored case that cannot be created.

    • 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, then deliver the newly returned approval URL to the customer yourself - Debitura does not email it. 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.

  • Scenario C: Contact Debitura at [email protected]. Changing the customer's email or creating the customer under another identity will not get around it: while your account is paused or closed, every new customer request is refused. Customers already linked to you, and their case submissions, are not closed by this account state. A paused account can be resumed; a closed account cannot be reopened. After your account is resumed, your integration can retry the same request with the same idempotency key. For the technical response format, see Developer Docs: Referral Partner API.

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 request must include your ExternalTenantId for the customer, the client's name, country and support email, and at least one named user with an email address. If you send several users, exactly one must be designated as the onboarding user. 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, client name, country and support email, and at least one named user with an email address) are present and correctly formatted. For the full request format, see Developer Docs: Referral Partner API.

  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 onboarding URL (onboardingLinks.url), but the customer has not completed the onboarding process.

Likely cause

The customer needs to complete Debitura's onboarding flow before the account is fully activated. The main 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 onboarding URL (onboardingLinks.url) 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 client account. If the original user on the onboarding link was deleted, the flow uses the oldest active admin on that same client account. Confirm which active admin should receive the signing code and check that person's mailbox. If the client has no active admin left, the onboarding steps stop with a "not found" error and nothing is reported back through the API or a webhook; contact [email protected]. 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. Correct the onboarding user's email address to a reachable one in the onboarding flow's Users and Roles step on the same link, then use Resend code; repeating POST /clients does not update it, so a new link does not help.

  3. If you no longer have the onboarding URL, call POST /clients again with the same ExternalTenantId. For a customer who is already linked, it returns the current onboarding state: 202 with the onboarding URL while signing is outstanding, or 201 once onboarding is complete. A repeated request does not update the existing user's details or create cases included in it - submit later cases through the Customer API.

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 onboarding URL (onboardingLinks.url) 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?