---
title: "List all linked clients"
method: GET
path: "/clients"
tags: ["Clients"]
---
# List all linked clients
`GET /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.
## Query parameters
- `Page` integer
- `PageSize` integer
- `Query` string
- `ExternalTenantId` string
- `IsAttributedClient` boolean
- `DateCreatedFrom` string, date-time
- `DateCreatedTo` string, date-time
- `OnboardingDone` boolean
- `Sort` string
## Response `200`
Clients retrieved successfully
- DebituraWebReferralPartnerApiModelsClientsGetClientsResponse — Response model for listing clients linked to a referral partner
- `page` DebituraDomainModelBasePageData — Paging metadata describing a paged result set.
- `totalResults` integer — Total number of records for the query (filtered or all as applicable).
- `pageSize` integer — How many records are returned per page.
- `currentPage` integer — Which page number is being shown, calculated from the number of skipped items.
- `responseCount` integer — How many records are present in the current page.
- `totalPages` integer — Total number of pages available given Debitura.Domain.Model.Base.PageData.TotalResults and Debitura.Domain.Model.Base.PageData.PageSize. Returns 0 if Debitura.Domain.Model.Base.PageData.PageSize is 0 rather than dividing by zero.
- `summary` DebituraWebReferralPartnerApiModelsClientsClientsSummary
- `totalClients` integer
- `attributedClients` integer
- `onboardingComplete` integer
- `onboardingPending` integer
- `totalCases` integer
- `clients` DebituraWebReferralPartnerApiModelsClientsClientCreatedResponse[], nullable — List of linked clients
- `externalTenantId` string, nullable
- `onboardingDone` boolean
- `onboardingLinks` DebituraWebReferralPartnerApiModelsClientsOnboardingLinksDto
- `url` string, nullable
- `client` DebituraWebReferralPartnerApiModelsClientsCreditorDto
- `id` string, uuid
- `companyName` string, nullable
- `officeEmail` string, nullable
- `country` string, nullable
- `address` string, nullable
- `city` string, nullable
- `zipCode` string, nullable
- `companyRegistrationNumber` string, nullable
- `users` DebituraWebReferralPartnerApiModelsClientsUserDto[], nullable
- `id` integer
- `email` string, nullable
- `firstName` string, nullable
- `lastName` string, nullable
- `isAttributedClient` boolean
- `dateLinked` string, date-time
- `caseStats` DebituraWebReferralPartnerApiModelsClientsClientCaseStats
- `casesTotal` integer
- `casesClosed` integer
- `earningsUsd` number, double
- `kycStatus` 'NotRequired' | 'Pending' | 'Verified' — KYC (Know Your Customer) verification status for a client linked to a referral partner. Captures three distinct states that a simple boolean cannot express. Wire format is LOCKED to snake_case string values ("not_required", "pending", "verified") via Newtonsoft.Json StringEnumConverter with SnakeCaseNamingStrategy. The host serializer for this API is Newtonsoft.Json (AddNewtonsoftJson in Program.cs), so a System.Text.Json JsonStringEnumConverter attribute would be silently ignored — hence the explicit Newtonsoft converter here. The System.Text.Json JsonConverter attribute is declared in addition so that consumers (and our own integration tests) who parse responses using System.Text.Json can deserialize the string form back into this enum. The Newtonsoft converter is what actually controls outbound wire format on this host.
- `kycVerification` DebituraWebReferralPartnerApiModelsClientsKycVerificationDto
- `directorFullName` string, nullable
- `directorHomeAddress` string, nullable
- `directorDateOfBirth` string, date
- `dateCreated` string, date-time
- `verificationStatus` 'Processing' | 'Completed' — Partner/staff-settable review status for a Debitura.Domain.Model.Creditors.CreditorKycVerifications.CreditorKycVerification record. Distinct from the ReferralPartnerApi `KycStatus` enum, which describes whether a client has submitted KYC data at all — this enum describes whether data that has already been submitted has since been reviewed by the collection partner or Debitura staff. The unset/not-yet-reviewed state is represented by a null Debitura.Domain.Model.Creditors.CreditorKycVerifications.CreditorKycVerification.VerificationStatus column, not a third enum value here. A fresh KYC resubmission (a new row via `CreditorKycVerificationService.CreateAsync`) naturally leaves this column unset, resetting review status by design. Wire format is locked to named string values ("Processing", "Completed") via Newtonsoft.Json StringEnumConverter — every host this enum is exposed on (CollectionPartnerApi, CoreApi, ReferralPartnerApi) uses Newtonsoft (AddNewtonsoftJson in Program.cs), so a System.Text.Json JsonStringEnumConverter attribute alone would be silently ignored; both are declared so STJ-based consumers (and our own tests) can also deserialize the string form.
- `verificationStatusUpdatedAt` string, date-time, nullable — When Debitura.Web.ReferralPartnerApi.Models.Clients.KycVerificationDto.VerificationStatus was last set. Null until set.
- `caseResults` DebituraWebReferralPartnerApiModelsClientsMultiCaseResult — Result of creating multiple cases during client creation. Groups successful and failed case creation attempts.
- `successfulCases` DebituraWebExternalApiContractsV1CasesInvoiceDto[], nullable — Cases that were created successfully. Each element contains the full case details.
- `id` string, uuid
- `dateCreated` string, date-time
- `dateUpdated` string, date-time, nullable
- `reference` string, nullable
- `creditorReference` string, nullable
- `creditorComments` string, nullable
- `claimDescription` string, nullable
- `grossAmount` number, double
- `remainder` number, double
- `interestFees` number, double
- `reminderFees` number, double
- `collectionFees` number, double
- `totalAddedFees` number, double
- `currency` string, nullable
- `isTestCase` boolean
- `lifecycle` string, nullable
- `dueDate` string, date-time
- `date` string, date-time
- `dateFinished` string, date-time, nullable
- `dateCollectionStarted` string, date-time, nullable
- `closeCode` string, nullable
- `currentEngagementPhase` string, nullable — The current phase of the case's engagement: "Pre-legal", "Legal", or "Enforcement". A different axis from Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto.Lifecycle/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto.CloseCode — an Active case can be in any of the three phases. Null means "no active engagement" (e.g. lead / quoting / pre-contract-signing / unassigned, or a data-consistency gap) — this is a distinct third state, NOT a synonym for Pre-legal. Most cases legitimately read Pre-legal; phase only leaves Pre-legal on legal/enforcement quote flows. Not guaranteed to be monotonic: an admin correction can move phase backwards (e.g. Legal back to Pre-legal). Persists after case closure — reflects the case's last-known engagement phase, not the current Lifecycle. Note: this is a different field from a lead quote's own offered phase (the phase a partner's quote proposes to work the case at, if this case ever went through a quote flow) — this field is the case-level phase of its actual engagement, not a quote's terms.
- `claimType` string, nullable — The type of claim for this case (e.g. "Unpaid Invoice", "Loan Repayment", "Breach of Contract"). Null if not set.
- `creditorDivisionId` string, uuid, nullable
- `debtor` DebituraWebExternalApiContractsV1CasesDebtorDto — V1 Debtor DTO for external partner APIs. The debtor is the party that owes the debt.
- `type` string, required — Debtor type. Valid values: "Company" or "Person"
- `name` string, required — Debtor name (company name or person's full name)
- `contactPerson` string, nullable — Contact person at the company (required for companies, not used for persons)
- `companyRegistrationNumber` string, nullable — Company registration number (VAT number, CVR, org number, etc.)
- `address` string, nullable — Street address
- `zipCode` string, nullable — Postal/ZIP code
- `city` string, nullable — City name
- `state` string, nullable — State/region/province name
- `stateAlpha2` string, nullable — US state: two-letter code (e.g., "CA"), ISO 3166-2 format (e.g., "US-CA"), or full name (e.g., "California")
- `countryAlpha2` string, nullable — Country code (ISO 3166-1 alpha-2 format)
- `country` string, nullable — Country name
- `email` string, nullable — Email address for debtor contact
- `phone` string, nullable — Phone number (include country code)
- `collectionPartner` DebituraWebExternalApiContractsV1CasesCollectionPartnerDto — V1 Collection Partner DTO for external partner APIs
- `name` string, nullable
- `officeEmail` string, nullable
- `officePhone` string, nullable
- `publicSite` string, nullable
- `surveyCadenceMode` 0 | 1 — Controls which surveys are generated for cases assigned to this collection partner.
- `creditor` DebituraWebExternalApiContractsV1CasesCreditorDto — Creditor (client) information for external partner APIs. Represents the party that the debtor owes money to.
- `id` string, uuid — Unique identifier for the creditor
- `companyName` string, nullable — Company name of the creditor
- `companyRegistrationNumber` string, nullable — Company registration number (CVR, VAT number, etc.)
- `officeEmail` string, nullable — Primary office email address
- `officePhone` string, nullable — Primary office phone number
- `address` string, nullable — Street address
- `city` string, nullable — City
- `zipCode` string, nullable — Postal/ZIP code
- `state` string, nullable — State or region (if applicable)
- `country` string, nullable — Country name
- `division` DebituraWebExternalApiContractsV1CasesCreditorDivisionDto — Creditor division information for external partner APIs. Represents a specific division or department within a creditor organization.
- `id` string, uuid — Unique identifier for the division
- `name` string, nullable — Name of the division
- `bankAccount` DebituraWebExternalApiContractsV1CasesBankAccountDto — Bank account information for partner API. Full details provided as partners need this to: 1. Provide payment instructions to debtors (when debtor pays client directly) 2. Execute payouts to clients (when partner receives payment and pays out remainder)
- `id` integer — Bank account identifier
- `label` string, nullable — User-friendly label (e.g., "Main EUR Account")
- `scheme` string, nullable — Account scheme: IBAN, SWIFT, or LOCAL
- `currencyCode` string, nullable — Currency code (ISO 4217)
- `bankCountryCode` string, nullable — Bank country code (ISO Alpha-2)
- `accountHolderName` string, nullable — Account holder name (beneficiary)
- `iban` string, nullable — IBAN (for IBAN scheme accounts)
- `bic` string, nullable — BIC/SWIFT code (for IBAN and SWIFT scheme accounts)
- `accountNumber` string, nullable — Account number (for SWIFT and LOCAL scheme accounts)
- `localIdentifier` string, nullable — Local identifier (for LOCAL scheme accounts, e.g., sort code + account number)
- `localIdentifierType` string, nullable — Type of local identifier (e.g., "Sort Code", "Routing Number")
- `bankName` string, nullable — Bank name (optional)
- `bankAddress` string, nullable — Bank address (optional)
- `bankCity` string, nullable — Bank city (optional)
- `bankZipCode` string, nullable — Bank zip/postal code (optional)
- `bankState` string, nullable — Bank state/region (optional)
- `blendedAgeUpliftPoints` number, double, nullable — MULTI-INVOICE AGE BUCKET PRICING Calculated blended age uplift percentage points (0-20) for multi-invoice cases. Shows the additional fee percentage added due to invoice age. Formula: ((A12-A24)×10 + A24×20) / Total Principal Null for single-invoice cases (age uplift is calculated from due date instead).
- `preLegalSuccessFee` number, double, nullable — PRE-LEGAL SUCCESS FEE The total pre-legal success fee percentage for this case. Includes base fee + age-based uplift (blended or single-invoice). Null if pricing has not been calculated yet or if case is not in pre-legal phase. Example: 20.5 represents 20.5% success fee.
- `solutionUrl` string, nullable — When the case is created with allowPendingContracts=true and required contracts are unsigned, this URL points to the signing page. Null when contracts are already signed or not applicable.
- `signingHandoff` DebituraWebExternalApiContractsV1CasesSigningHandoffDto — Partner-facing handoff metadata for a creditor's pending signing chain. Returned on POST /cases responses (422 with pending-signing errors, or 200 with AllowPendingContracts=true when signings remain). Designed as an envelope so future fields (expiration, suggested email copy, etc.) can be added without polluting the parent DTO.
- `combinedSigningUrl` string, nullable — Single signing entry URL that walks the creditor through every pending step (SDCA upgrade → PoA → JPA → KYC) on the Creditors app and returns to the partner-supplied returnUrl when done.
- `exclusivePeriodEndDate` string, date-time, nullable — The date the exclusive collection period ends (or ended). Null if no collection period has been created for this case (e.g. custom-terms cases). Use GET /cases/{id}/exclusive-period for the full chain including extensions.
- `disputeStatus` string, nullable — Whether the claim is disputed by the debtor. Returns the description of Debitura.Domain.Model.Receiveables.Invoices.Enums.ClaimDisputeStatus: "Yes, the claim is disputed", "No, the claim is not disputed", or "Don't Know". Null when the dispute status has not been set on the case.
- `validation` DebituraDomainServicesCaseValidationCaseValidationLeanDto — Lean validation summary exposed on list endpoints of the External Customer API and Collection Partner API. Contains only Debitura.Domain.Services.CaseValidation.CaseValidationLeanDto.NeedsInfo — no join required. Derived purely from free Debitura.Domain.Model.Receiveables.Invoices.Invoice columns. When Debitura.Domain.Services.CaseValidation.CaseValidationLeanDto.NeedsInfo is `true`, callers should invoke `GET /cases/{id}/validation` to retrieve the full item-level breakdown (Debitura.Domain.Services.CaseValidation.CaseValidationStatusDto).
- `needsInfo` boolean — True when the latest validation run requires creditor action. Reads Debitura.Domain.Model.Receiveables.Invoices.Invoice.ValidationNeedsInfo directly.
- `assignedUser` DebituraWebExternalApiContractsV1CasesAssignedUserDto — Represents the creditor team member assigned to a case.
- `email` string, nullable — The assigned user's email address.
- `name` string, nullable — The assigned user's full name.
- `allocationOutstanding` DebituraWebExternalApiContractsV1CasesInvoiceAllocationOutstandingDto — Additive external-API read model. Per-bucket outstanding on the debt ledger, produced by the payment allocation engine (bucket total minus Σ active stored allocations — never re-derived from a model). Mirrors the internal `Debitura.Domain.Model.Receiveables.InvoiceEconomics.EconomicalAllocationOutstanding` shape.
- `principal` number, double
- `interest` number, double
- `reminderFees` number, double
- `collectionFees` number, double
- `failedCases` DebituraWebReferralPartnerApiModelsClientsCaseCreationFailure[], nullable — Cases that failed during creation. Each element contains error details and the original case index.
- `caseIndex` integer — Zero-based index of the failed case in the original Cases array.
- `creditorReference` string, nullable — Creditor reference from the failed case, if provided. Helps consumers identify which specific case failed.
- `errorType` string, nullable — Machine-readable error type code for programmatic error handling. Enables API consumers to handle different failure scenarios without parsing error messages. Possible values:- Debitura.Web.ReferralPartnerApi.Models.Clients.CaseCreationErrorTypes.NoPartnerAvailableNo collection partner available for the debtor's jurisdiction. The debtor is in a country/region where Debitura does not yet have collection partner coverage. Consider resubmitting with debtors in supported jurisdictions.
- Debitura.Web.ReferralPartnerApi.Models.Clients.CaseCreationErrorTypes.ValidationErrorThe request failed field-level validation. Check the Debitura.Web.ReferralPartnerApi.Models.Clients.CaseCreationFailure.ValidationErrors property for detailed field-specific errors. Common causes: missing required fields, invalid formats, business rule violations.
- Debitura.Web.ReferralPartnerApi.Models.Clients.CaseCreationErrorTypes.DuplicateReferenceThe provided CreditorReference already exists for this creditor or is duplicated in the current request. CreditorReference must be unique per creditor.
- Debitura.Web.ReferralPartnerApi.Models.Clients.CaseCreationErrorTypes.IdempotencyViolationThe client has already been created in a previous API call. Cases are not created on repeated calls to maintain idempotency. This is informational - the original operation already succeeded.
- Debitura.Web.ReferralPartnerApi.Models.Clients.CaseCreationErrorTypes.UnexpectedErrorAn unexpected system error occurred during case creation. This is a catch-all for errors not covered by other types. Contact Debitura support if this error persists.
Null if the error type cannot be determined or is not applicable.
- `errorMessage` string, nullable — High-level error message explaining why the case creation failed.
- `validationErrors` object, nullable — Detailed field-level validation errors if the failure was due to validation. Null if the failure was due to other reasons (e.g., no partner match).
- `signingHandoff` DebituraWebExternalApiContractsV1CasesSigningHandoffDto — Partner-facing handoff metadata for a creditor's pending signing chain. Returned on POST /cases responses (422 with pending-signing errors, or 200 with AllowPendingContracts=true when signings remain). Designed as an envelope so future fields (expiration, suggested email copy, etc.) can be added without polluting the parent DTO.
- `combinedSigningUrl` string, nullable — Single signing entry URL that walks the creditor through every pending step (SDCA upgrade → PoA → JPA → KYC) on the Creditors app and returns to the partner-supplied returnUrl when done.
## Other responses
- `400` — Invalid request parameters
- `500` — Internal server error
---
[API](https://skmtc.net/debitura/apis/debitura-referral-partner-api.md) · [All operations](https://skmtc.net/debitura/apis/debitura-referral-partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/debitura/debitura-referral-partner-api/versions/9c466e0e2bf4/schema)