Clients

Retrieves a paginated list of all clients (creditors) linked to the authenticated referral partner.

Response Data For each client, the response includes:

• ExternalTenantId - Your unique identifier for this client
• OnboardingDone - Whether the client has completed onboarding (signed debt collection agreements)
• OnboardingLinks - If onboarding incomplete, contains URL to complete the process
• Client - Complete client information (ID, company name, registration number, country, address, contact details)
• Users - List of all users associated with this client (ID, email, name)

Filtering Parameters

• ExternalTenantId - Filter to specific client by your identifier
• IsAttributedClient - Filter by attribution status (true = created by you, false = linked later)
• DateCreatedFrom - Filter clients linked on or after this date (ISO 8601 format)
• DateCreatedTo - Filter clients linked on or before this date (ISO 8601 format)
• Query - Search across company name, email, and registration number (case-insensitive)

Pagination

• Page - Page number (default: 1, min: 1)
• PageSize - Results per page (default: 50, min: 1, max: 100)
• Response includes page metadata: total count, current page size, skip count

Sorting

• Sort - Sort field and direction (format: 'field:direction')
• Supported fields: dateCreated, name
• Examples: 'dateCreated:desc', 'name:asc'
• Default: dateCreated:desc (most recent first)

Use Cases

• List all your clients for dashboard display
• Search for specific client by name, email, or registration number
• Filter clients by onboarding status
• Identify clients created by you vs. existing clients you linked
• Monitor client link creation dates
• Paginate through large client lists

Client Attribution and Revenue Rules ⚠️ CRITICAL FOR REVENUE CALCULATIONS

• IsAttributedClient=true - Client was created through the referral partner API

  • Referral partner earns revenue on ALL cases (100% of cases)
  • This is the default for clients created via POST /clients

• IsAttributedClient=false - Client existed in Debitura before the link was established (409 conflict scenario)

  • Referral partner earns revenue ONLY on cases created through the referral partnership
  • Cases created directly by the client (not through partner) do NOT generate referral revenue
  • This protects pre-existing client relationships

This distinction is the most important business rule for revenue calculations. Always check IsAttributedClient when forecasting or reconciling revenue.

Only active (non-archived) client links are returned.

Creates a new client (creditor) in the Debitura platform and links them to the authenticated referral partner.

Request Structure

• ExternalTenantId (required) - Your unique identifier for this client (for correlation and future lookups)
• Client (required) - Company information (name, registration number, country, address, contact details)
• Users (required, 1-N) - At least one user with email and name. For multiple users, exactly one must have IsOnboardingUser=true. Single-user requests auto-infer the onboarding user.
• Cases (optional) - Optionally create multiple collection cases during client creation (validated upfront to prevent orphaned clients)

Onboarding Flow

1. New Client (201/202)

   • Client and users are created in Debitura
   • ReferralPartnerClientLink is established with revenue sharing percentage
   • If onboarding is complete (terms signed), returns 201
   • If onboarding pending (terms not signed), returns 202 with OnboardingLinks.Url for completing the process

   202 Response - Two URL Scenarios:

   1a. New Client - Full Onboarding URL

   • Scenario: Client has never signed the SDCA (Standard Debt Collection Agreement)
   • URL Pattern: {onboardingBase}/companydetails/{referralPartnerClientLinkId}
   • User Journey: Multi-step onboarding (company details → users → sign SDCA)
   • Use Case: First-time client registration

   1b. Existing Client - Contract Upgrade URL

   • Scenario: Client previously signed SDCA but terms have been updated (NeedsRefresh=true)
   • URL Pattern: {onboardingBase}/ContractUpgrade/Sign/{referralPartnerClientLinkId}
   • User Journey: Streamlined contract re-signing only (no company details re-entry)
   • Use Case: SDCA version upgrade (e.g., new pricing tiers, updated legal terms)
   • Note: This can happen to previously-ready clients (201 → 202 state transition)

   Important: Without Idempotency-Key, externalTenantId only prevents a duplicate client/link; it does not make case-bearing retries safe or replay the original response. Exact response replay and case-safe retries require Idempotency-Key. Client/link lookups still re-check SDCA status, so an unkeyed call for an existing client that previously returned 201 Created may flip to 202 Accepted if Debitura releases a new SDCA version requiring re-signature.

2. Existing Client - Needs Linking (409 Conflict) Business conflicts use ConflictResponse.Type; keyed requests can additionally return IdempotencyKeyInProgress while the winning request is still running:

   2a. ClientExistsNeedsLinking (Type: "ClientExistsNeedsLinking")

   • Client already exists in Debitura (matched by user email or support email)
   • A link request is created with an expiration window configured per-partner (ApprovalTtlDays, default 7 days, clamped 1–30)
   • Existing client must approve the referral partner link via OnboardingLinks.Url
   • If approved, IsAttributedClient will be FALSE (revenue only on partner-referred cases)
   • Cases submitted in the original request are persisted and replayed against the linked creditor automatically when the user approves. AllowPendingContracts=true is forced on replay so cases land in PendingContractSigning rather than 422-failing on missing SDCA/PoA/KYC.
   • Returns 409 with OnboardingLinks.Url pointing to approval page

   2b. ClientAlreadyLinkedToAnotherPartner (Type: "ClientAlreadyLinkedToAnotherPartner")

   • Client is already linked to a DIFFERENT referral partner
   • Only one referral partner link per client is supported
   • Cannot proceed - contact Debitura support for resolution
   • Returns 409 with error message and support contact

3. Idempotency

   • Without an Idempotency-Key, repeated calls with the same ExternalTenantId keep the existing business-key behaviour and return the current client status without duplicating the client or link
   • Optionally send an Idempotency-Key of up to 255 characters. The key is scoped to the authenticated referral partner and retained for 24 hours
   • The same key with the same effective request body replays the original terminal status and body, including approval-required 409 responses
   • Effective comparison follows this endpoint's execution rules. For one user, IsOnboardingUser=false and true are equivalent because the user is always selected for onboarding. Omitted and empty Cases/ClaimLines are equivalent. Within Cases, AllowPendingContracts and AssignedUserEmail do not change referral-onboarding execution; unsafe ReturnUrl values are dropped; valid debtor Type casing is normalized; ContactPerson is ignored for Private debtors; and State is ignored when StateAlpha2 is supplied.
   • The same key with a different effective body returns 422 with businessErrors[0].type = IdempotencyConflict; a retry while the first request is still running returns 409 with businessErrors[0].type = IdempotencyKeyInProgress and Retry-After: 2
   • Field-validation 400 responses and failures before any durable effect do not consume the key. A failure after client, link, approval-request, or case work starts is sealed and replayed to prevent duplicates

4. Previously Withdrawn Client - Re-linked (201/202)

   • Applies when you re-submit an ExternalTenantId you previously withdrew via POST /clients/{externalTenantId}/withdraw, AND the re-submission still identifies that same client — that is, it carries a user email or supportEmail already registered on it
   • The ORIGINAL client is re-linked rather than duplicated: a new active link is created on the same Debitura client, IsAttributedClient stays true, and the archived link is retained for audit
   • Cases in the re-submission are created against that client. A CreditorReference used by a case that the withdrawal closed can be reused — such a case no longer reserves it
   • Any approval request still pending for this ExternalTenantId is resolved as declined, and a client.link_declined webhook is sent for it
   • Falls back to the 409 handling in scenario 2 if the ExternalTenantId now resolves to a DIFFERENT client, if that client has since linked to another partner, or if the withdrawn link was not attributed to you
   • Creates a new client as in scenario 1 — no re-link, no 409 — if the re-submission carries no contact email we recognise. A matching email is our only independent confirmation that this is the same client; without one we cannot tell a genuine re-submission apart from the same ExternalTenantId being reused for somebody else
   • The re-link does not update the client or add users. Client details and Users in the re-submission are ignored, and the new link keeps the original onboarding user — send a new contact through the normal user-invitation flow instead

Response Codes

• 201 Created - Client created and fully onboarded (terms signed, ready to create cases, IsAttributedClient=true)
• 202 Accepted - Client created but onboarding incomplete (OnboardingLinks.Url provided to complete, IsAttributedClient=true)
• 400 Bad Request - Validation errors (missing required fields, invalid data, duplicate CreditorReferences within request). Most validation failures return a single-message ApiErrorResponseDto. Field-length violations (Client.Name, Client.SupportPhone, Client.RegistrationNumber, Client.SupportEmail, Users[].Email) are the one exception: they return a field-keyed error dictionary instead, e.g. { "Client.Name": ["Name must not exceed 80 characters (received 95)."] }, so multiple field problems can be reported together in one round-trip.
• 409 Conflict - Business conflicts or keyed-request contention:
  • ConflictResponse.Type = "ClientExistsNeedsLinking" - Client exists, needs approval link (if approved, IsAttributedClient=false)
  • ConflictResponse.Type = "ClientAlreadyLinkedToAnotherPartner" - Client already linked to different partner (cannot proceed)
  • ConflictResponse.Type = "PartnerNotAcceptingReferrals" - The referral partner is paused or closed and takes no new clients; existing clients are unaffected
  • businessErrors[0].type = "IdempotencyKeyInProgress" - Another request with the same partner, key, and effective body is still running; retry after the Retry-After delay
• 422 Unprocessable Entity - Business rule violation, including businessErrors[0].type = "IdempotencyConflict" when the same key is reused with a different effective body
• 500 Internal Server Error - Unexpected server error

Optional Multi-Case Creation If the Cases array is provided in the request:

• ALL cases are validated BEFORE client creation (checks field validation and duplicate references)
• Client is ALWAYS created to ensure referral partner link and future attribution
• Cases with available collection partners are created successfully (CaseResults.SuccessfulCases)
• Cases without available partners are NOT created and reported as failures (CaseResults.FailedCases)
• If validation errors exist (primitives, duplicates), client creation is aborted and 400 is returned
• Successful cases appear in CaseResults.SuccessfulCases with full case details
• Failed cases appear in CaseResults.FailedCases with CaseIndex, CreditorReference, and error details (e.g., "No collection partner available for jurisdiction")

Claim Amount and Aging on each case Each entry in Cases accepts the claim amount in one of three ways:

1. amountToRecover plus a single dueDate
2. amountToRecover plus the cumulative amountToRecoverOver6/12/24Months buckets
3. claimLines[] — send the unpaid invoices and let us do the arithmetic (recommended for multi-invoice claims)

"claimLines": [
  { "dueDate": "2024-01-15", "amount": 423.42, "reference": "INV-1001" },
  { "dueDate": "2025-05-02", "amount": 700.87, "reference": "INV-1042" }
]

• amount is the outstanding balance on that invoice, already net of payments and credit notes.
• We derive amountToRecover and all three age buckets from the lines, so send claimLines instead of amountToRecover and the bucket fields. Sending both is a 400.
• If you omit the case-level dueDate, it is set to the oldest due date across that case's lines; an explicit dueDate is honoured.
• Maximum 1000 lines per case, and a maximum of 1000 lines in total across all entries in Cases. Per-line errors are keyed by case and line index, e.g. Cases[0].ClaimLines[2].DueDate.
• claimLines is a pricing input only — it is not stored and is not shown to the collecting partner.

User Roles

• IsOnboardingUser=true - User receives CreditorAdmin role (full access)
• IsOnboardingUser=false - User receives CreditorUser role (limited access)

Revenue Sharing (Fee Percentage Locked at Link Creation)

• The referral fee percentage is snapshot from the partner's current configuration at the exact moment the client link is created
• This percentage is IMMUTABLE and will NEVER change for this client - even if the partner's global fee percentage is updated later
• The locked percentage is used for ALL revenue calculations for ALL cases created by this client, forever
• This ensures predictable, stable revenue sharing and prevents disputes over retroactive fee changes
• To see the locked percentage for a specific client, use GET /clients/{externalTenantId} (included in response)

Retrieves detailed information for a specific client using your unique identifier (External Tenant ID).

Path Parameter

• externalTenantId - Your unique identifier for this client (the same value used during client creation)

Response Data The response includes complete client information:

• ExternalTenantId - Your unique identifier for this client
• OnboardingDone - Whether the client has completed onboarding (signed debt collection agreements)
• OnboardingLinks - If onboarding incomplete, contains URL to complete the process
• Client - Complete client information
  • Debitura-assigned client ID (Guid)
  • Company name and registration number
  • Country and address details
  • Contact information (email, phone)
• Users - List of all users associated with this client
  • User ID, email, first name, last name

Use Cases

• Look up client details using your internal identifier
• Check client onboarding status
• Retrieve Debitura client ID for use with the Customer API (via OAuth token endpoint)
• Get client information before creating cases
• Verify client link is still active

Error Cases

• 404 Not Found - No active client link exists for this External Tenant ID and your partner account
  • Client was never created
  • Client link was archived
  • External Tenant ID belongs to different referral partner
• 500 Internal Server Error - Unexpected server error

Important Notes

• Only returns active (non-archived) client links
• External Tenant ID is case-sensitive
• The client must be linked to your referral partner account
• Use the returned client ID with the OAuth token endpoint to generate bearer tokens for Customer API access

Deletes a client and all associated data, allowing you to re-create the client from scratch.

⚠️ TEST ENVIRONMENT ONLY - This endpoint is only available on the test environment (testreferral-api.debitura.com). Calling this endpoint on production will return 403 Forbidden.

Use Cases

• Testing the full onboarding flow multiple times
• Resetting after changing your internal tenant structure during development
• Cleaning up test data without manual intervention

What Gets Deleted (cascade)

• All collection cases and invoices for the client
• All leads for the client
• The Creditor account (removes email from matching algorithm)
• The ReferralPartnerClientLink is archived
• Associated users are cleaned up if they have no other relations

After Reset

• You can call POST /clients with any externalTenantId using the same email
• The matching algorithm will not find the deleted client
• A completely new client will be created (IsAttributedClient=true)

Important

• You can only reset clients that are linked to your partner account
• Pending link requests (409 scenario) cannot be reset - only actual links

Checks whether a client can be safely deleted for testing purposes.

⚠️ TEST ENVIRONMENT ONLY - This endpoint is only available on the test environment.

Use this endpoint before calling DELETE to verify the client can be removed.

A client can be deleted if:

• They have no active collection cases (only pending cases are allowed)
• They have no leads with active quotes

Returns

• isDeletable: true if the client can be deleted
• blockers: list of reasons why deletion is blocked (if any)

Withdraws a client that never completed onboarding. Archives the referral partner link and closes all pending cases with close code CaseNeverStartedInternal.

The same externalTenantId can be re-submitted via POST /clients after withdrawal.

Path Parameter

• externalTenantId - Your internal identifier for the client

Business Rules

• Only attributed clients (IsAttributedClient = true) can be withdrawn
• All cases for this client must be in PendingContractSigning status

What Happens

• The referral partner client link is archived
• All pending cases are closed with close code CaseNeverStartedInternal

What Does NOT Happen

• The client record itself is not deleted or anonymised. The company, its users, its KYC record and any signed agreements are all retained

After Withdrawal

• The same externalTenantId can be re-submitted via POST /clients
• Provided the re-submission still identifies the SAME client — that is, it carries a user email or supportEmail already registered on it — it re-links that original client rather than creating a second one: a new active link is established on the same Debitura client, attribution (IsAttributedClient=true) is preserved, and the archived link is kept for audit. The call returns 201/202 as normal — not a 409
• Any cases in the re-submission are created against that client. A CreditorReference used by a case that this withdrawal closed can be reused, because such a case no longer reserves it
• Any approval request left pending for this externalTenantId is resolved as declined, since the link it was asking the client to approve now exists
• Re-submitting with entirely different contact emails does NOT re-link. A matching email is our only independent confirmation that this is the same client; without one we cannot tell a genuine re-submission apart from the same externalTenantId being reused for somebody else — so a new client is created, exactly as before this behaviour existed
• The re-link does not update the client or add users. Client details and Users in the re-submission are ignored, and the new link keeps the original onboarding user
• Re-linking only applies to your own withdrawn client. If the externalTenantId now resolves to a different client, or that client has since linked to another partner, the normal 409 ClientExistsNeedsLinking / AlreadyLinkedToAnotherPartner handling applies unchanged

Error Cases

• 404 Not Found - No active client link exists for this externalTenantId and your partner account
• 409 Conflict - Client cannot be withdrawn because:
  • IsAttributedClient = false (non-attributed clients cannot be withdrawn)
  • One or more cases have progressed beyond PendingContractSigning

Submits KYC/AML director verification data for an existing client. Multiple submissions are allowed; the latest record is used for verification checks. When sendChatNotification is true (default), a system message is posted on all active cases for this client to notify the collection partner.