---
title: "List all linked clients"
method: GET
path: "/clients"
tags: ["Clients"]
---

# List all linked clients

`GET /clients`

## Request

- Base URL: `https://referral-api.debitura.com`
- URL: `https://referral-api.debitura.com/clients`
- Auth: API key in header `XApiKey`

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 TotalResults and PageSize. Returns 0 if 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. Sent as snake_case string values: "not_required", "pending", "verified".
    - `kycVerification` DebituraWebReferralPartnerApiModelsClientsKycVerificationDto
      - `directorFullName` string, nullable
      - `directorHomeAddress` string, nullable
      - `directorDateOfBirth` string, date
      - `dateCreated` string, date-time
      - `verificationStatus` 'Processing' | 'Completed' | 'null', nullable: Partner/staff-set review status (Processing/Completed) for this submission. Null = not yet reviewed. Note: distinct from the sibling `ClientResponse.KycStatus` field, which describes whether KYC data has been submitted at all.
      - `verificationStatusUpdatedAt` string, date-time, nullable: When 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 Lifecycle/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 "Private" (case-insensitive)
          - `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: Deprecated: kept as a number and never removed, but not extended. Survey-generation cadence: 0 = Standard (rolling monthly survey), 1 = DecisionPointOnly (no rolling surveys).
        - `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. One of: "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` DebituraWebExternalApiContractsV1CasesCaseValidationLeanDto: Stable v1 validation summary used by ordinary and list mappings.
          - `needsInfo` boolean
        - `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: Outstanding amount per bucket on the case: each bucket's total minus the payments allocated to it.
          - `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. <b>Possible values:</b><list type="bullet"><item><term>NoPartnerAvailable</term><description>No 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.</description></item><item><term>ValidationError</term><description>The request failed field-level validation. Check the ValidationErrors property for detailed field-specific errors. Common causes: missing required fields, invalid formats, business rule violations.</description></item><item><term>DuplicateReference</term><description>The provided CreditorReference already exists for this creditor or is duplicated in the current request. CreditorReference must be unique per creditor.</description></item><item><term>IdempotencyViolation</term><description>The 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.</description></item><item><term>UnexpectedError</term><description>An 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.</description></item></list> 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

## Changes

- **2026-10-12** `7b3700202dec`: 3 breaking, 3 warning
  - the response property `clients/items/kycVerification/verificationStatus` became nullable for the status `200` (media type: text/plain)
  - the response property `clients/items/kycVerification/verificationStatus` became nullable for the status `200` (media type: application/json)
  - the response property `clients/items/kycVerification/verificationStatus` became nullable for the status `200` (media type: text/json)
  - added the new `undefined` enum value to the `clients/items/kycVerification/verificationStatus` response property for the response status `200` (media type: text/plain)
  - …2 more
- **2026-10-01** `739ec0889478`: 3 info
  - response property `clients/items/caseResults/successfulCases/items/collectionPartner/surveyCadenceMode` deprecated (media type: text/plain)
  - response property `clients/items/caseResults/successfulCases/items/collectionPartner/surveyCadenceMode` deprecated (media type: application/json)
  - response property `clients/items/caseResults/successfulCases/items/collectionPartner/surveyCadenceMode` deprecated (media type: text/json)

[Operation history](https://skmtc.dev/debitura/apis/debitura-referral-partner-api/changes/clients/get.md)

---

[API](https://skmtc.dev/debitura/apis/debitura-referral-partner-api.md) - [All operations](https://skmtc.dev/debitura/apis/debitura-referral-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/debitura/apis/debitura-referral-partner-api/revisions/cf12c7f270d9?raw)