1. Customer never received the activation or verification email
Problem
The customer completed the signup or onboarding form but did not receive a verification or welcome email from Debitura.
Likely causes
Spam or junk filter: The email was delivered but caught by the customer's email provider or corporate mail filter.
Expired verification link: Verification links are valid for 24 hours. If the customer waited too long, the link expired.
Disposable or temporary email address: Debitura blocks signups from disposable email services (such as mailinator, yopmail, guerrillamail, and 150+ similar providers). The signup will fail silently or return an error.
Fix
Ask the customer to check their spam or junk folder for emails from Debitura.
If the customer is on the confirmation page, they can use the "Resend verification email" option to request a new link. Each resend replaces the previous link.
If the verification link has expired (after 24 hours), clicking the old link will automatically trigger a new verification email.
If the customer used a disposable or temporary email address, they must re-register using a permanent business or personal email address.
Ask the customer to whitelist @debitura.com and [email protected] in their email settings.
2. Customer's email address is rejected during signup
Problem
The customer receives an error when trying to register, or the signup silently fails.
Likely cause
Debitura's spam detection system blocks registration from known disposable and temporary email services. Over 150 disposable email domains are blocked, including time-based services (such as 10minutemail), popular throwaway services (such as mailinator, guerrillamail), and other temporary mail providers.
Fix
Ask the customer to use a permanent business email address (their company domain) or a mainstream personal email provider (Gmail, Outlook, etc.).
Retry the signup or API call with the corrected email address.
3. 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.
Likely causes
There are three 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 already linked with a different ExternalTenantId - The customer is already linked to your partner account but under a different ExternalTenantId. The response includes Type: AlreadyLinkedDifferentTenant and shows the existing ExternalTenantId.
Scenario C: 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.
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. After approval, the link will have IsAttributedClient = false, meaning your platform earns fees only on cases submitted through your integration (via bearer token).
Scenario B: Use the existing ExternalTenantId shown in the response for this customer. Each customer can only have one ExternalTenantId per partner. If the ExternalTenantId must be changed, contact Debitura support.
Scenario C: Contact Debitura support at [email protected]. The customer cannot be linked to multiple referral partners at the same time.
4. 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
Check the error response for the specific field and validation message.
Ensure all required fields (ExternalTenantId, CompanyName, Country, Email) are present and correctly formatted.
If you included optional address fields, verify they meet the format requirements.
Correct the data and retry the API call.
5. 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:
Company Details - confirm or update company information
Users and Roles - optionally add team members (can be skipped)
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.
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
Redirect the customer to the OnboardingUrl from the API response. The onboarding flow picks up where the customer left off.
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. Resending delivers the same code again - the code does not change until the contract is successfully signed.
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.
6. 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
Redirect the customer to the OnboardingUrl from the 202 response. They will be taken directly to the contract re-signing flow.
No code changes are needed on your side. The API transparently manages SDCA version upgrades.
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.
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 broader integration issues beyond customer signup, see Integration troubleshooting checklist.