Debitura Clients API

openapi: 3.2.0
info:
  title: Debitura Referral Partner Clients API
  description: 'Welcome to the Debitura Referral API. This API allows you to set up new clients and track your revenue share with Debitura. You can also generate bearer tokens for use in the Customer API to create cases, check case status, and access all other endpoints. To get access to this API, please contact us at contact@debitura.com.


    📖 Full documentation, guides, and integration walkthroughs: https://docs.debitura.com/referral-partners'
  contact:
    name: Debitura Support
    url: https://www.debitura.com/integration
    email: contact@debitura.com
  version: v1
servers:
- url: https://referral-api.debitura.com
  description: Production
security:
- ApiKey: []
tags:
- name: Clients
  description: Clients
paths:
  /clients:
    post:
      tags:
      - Clients
      summary: Create and onboard a new client
      description: "Creates a new client (creditor) in the Debitura platform and links them to the authenticated referral partner.\n\nRequest Structure\n- **ExternalTenantId** (required) - Your unique identifier for this client (for correlation and future lookups)\n- **Client** (required) - Company information (name, registration number, country, address, contact details)\n- **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.\n- **Cases** (optional) - Optionally create multiple collection cases during client creation (validated upfront to prevent orphaned clients)\n\nOnboarding Flow\n1. **New Client (201/202)**\n   - Client and users are created in Debitura\n   - ReferralPartnerClientLink is established with revenue sharing percentage\n   - If onboarding is complete (terms signed), returns 201\n   - If onboarding pending (terms not signed), returns 202 with OnboardingLinks.Url for completing the process\n\n   **202 Response - Two URL Scenarios:**\n\n   **1a. New Client - Full Onboarding URL**\n   - Scenario: Client has never signed the SDCA (Standard Debt Collection Agreement)\n   - URL Pattern: `{onboardingBase}/companydetails/{referralPartnerClientLinkId}`\n   - User Journey: Multi-step onboarding (company details → users → sign SDCA)\n   - Use Case: First-time client registration\n\n   **1b. Existing Client - Contract Upgrade URL**\n   - Scenario: Client previously signed SDCA but terms have been updated (NeedsRefresh=true)\n   - URL Pattern: `{onboardingBase}/ContractUpgrade/Sign/{referralPartnerClientLinkId}`\n   - User Journey: Streamlined contract re-signing only (no company details re-entry)\n   - Use Case: SDCA version upgrade (e.g., new pricing tiers, updated legal terms)\n   - Note: This can happen to previously-ready clients (201 → 202 state transition)\n\n   **Important:** The `POST /clients` endpoint is idempotent and re-checks SDCA status on every call.\n   This means an existing client that previously returned `201 Created` may flip to `202 Accepted`\n   if Debitura releases a new SDCA version requiring re-signature.\n\n2. **Existing Client - Needs Linking (409 Conflict)**\n   There are TWO distinct 409 conflict scenarios - check the ConflictResponse.Type field to distinguish:\n\n   **2a. ClientExistsNeedsLinking** (Type: \"ClientExistsNeedsLinking\")\n   - Client already exists in Debitura (matched by user email or support email)\n   - A link request is created with an expiration window configured per-partner (`ApprovalTtlDays`, default 7 days, clamped 1–30)\n   - Existing client must approve the referral partner link via OnboardingLinks.Url\n   - If approved, IsAttributedClient will be FALSE (revenue only on partner-referred cases)\n   - 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.\n   - Returns 409 with OnboardingLinks.Url pointing to approval page\n\n   **2b. ClientAlreadyLinkedToAnotherPartner** (Type: \"AlreadyLinkedToAnotherPartner\")\n   - Client is already linked to a DIFFERENT referral partner\n   - Only one referral partner link per client is supported\n   - Cannot proceed - contact Debitura support for resolution\n   - Returns 409 with error message and support contact\n\n3. **Idempotency**\n   - Repeated calls with same ExternalTenantId return existing client status (201 or 202)\n   - No duplicate clients or links are created\n\nResponse Codes\n- **201 Created** - Client created and fully onboarded (terms signed, ready to create cases, IsAttributedClient=true)\n- **202 Accepted** - Client created but onboarding incomplete (OnboardingLinks.Url provided to complete, IsAttributedClient=true)\n- **400 Bad Request** - Validation errors (missing required fields, invalid data, duplicate CreditorReferences within request)\n- **409 Conflict** - Two scenarios (check ConflictResponse.Type):\n  - \"ClientExistsNeedsLinking\" - Client exists, needs approval link (if approved, IsAttributedClient=false)\n  - \"AlreadyLinkedToAnotherPartner\" - Client already linked to different partner (cannot proceed)\n- **422 Unprocessable Entity** - Business rule violation (field validation errors only, NOT partner matching failures)\n- **500 Internal Server Error** - Unexpected server error\n\nOptional Multi-Case Creation\nIf the Cases array is provided in the request:\n- ALL cases are validated BEFORE client creation (checks field validation and duplicate references)\n- Client is ALWAYS created to ensure referral partner link and future attribution\n- Cases with available collection partners are created successfully (CaseResults.SuccessfulCases)\n- Cases without available partners are NOT created and reported as failures (CaseResults.FailedCases)\n- If validation errors exist (primitives, duplicates), client creation is aborted and 400 is returned\n- Successful cases appear in CaseResults.SuccessfulCases with full case details\n- Failed cases appear in CaseResults.FailedCases with CaseIndex, CreditorReference, and error details (e.g., \"No collection partner available for jurisdiction\")\n\nUser Roles\n- **IsOnboardingUser=true** - User receives CreditorAdmin role (full access)\n- **IsOnboardingUser=false** - User receives CreditorUser role (limited access)\n\nRevenue Sharing (Fee Percentage Locked at Link Creation)\n- The referral fee percentage is snapshot from the partner's current configuration at the exact moment the client link is created\n- **This percentage is IMMUTABLE and will NEVER change for this client** - even if the partner's global fee percentage is updated later\n- The locked percentage is used for ALL revenue calculations for ALL cases created by this client, forever\n- This ensures predictable, stable revenue sharing and prevents disputes over retroactive fee changes\n- To see the locked percentage for a specific client, use GET /clients/{externalTenantId} (included in response)"
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.CreateClientRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.CreateClientRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.CreateClientRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.CreateClientRequest'
      responses:
        '201':
          description: Client created and fully onboarded (terms signed)
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientCreatedResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientCreatedResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientCreatedResponse'
        '202':
          description: Client created but onboarding incomplete (use OnboardingLinks.Url to complete)
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientCreatedResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientCreatedResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientCreatedResponse'
        '400':
          description: Invalid request (validation errors)
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '409':
          description: Client already exists - approval required to link (use OnboardingLinks.Url for approval)
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ConflictResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ConflictResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ConflictResponse'
        '422':
          description: Business rule violation (field validation errors only)
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorResponseApiDTO'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorResponseApiDTO'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorResponseApiDTO'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
    get:
      tags:
      - Clients
      summary: List all linked clients
      description: "Retrieves a paginated list of all clients (creditors) linked to the authenticated referral partner.\n\nResponse Data\nFor each client, the response includes:\n- **ExternalTenantId** - Your unique identifier for this client\n- **OnboardingDone** - Whether the client has completed onboarding (signed debt collection agreements)\n- **OnboardingLinks** - If onboarding incomplete, contains URL to complete the process\n- **Client** - Complete client information (ID, company name, registration number, country, address, contact details)\n- **Users** - List of all users associated with this client (ID, email, name)\n\nFiltering Parameters\n- **ExternalTenantId** - Filter to specific client by your identifier\n- **IsAttributedClient** - Filter by attribution status (true = created by you, false = linked later)\n- **DateCreatedFrom** - Filter clients linked on or after this date (ISO 8601 format)\n- **DateCreatedTo** - Filter clients linked on or before this date (ISO 8601 format)\n- **Query** - Search across company name, email, and registration number (case-insensitive)\n\nPagination\n- **Page** - Page number (default: 1, min: 1)\n- **PageSize** - Results per page (default: 50, min: 1, max: 100)\n- Response includes page metadata: total count, current page size, skip count\n\nSorting\n- **Sort** - Sort field and direction (format: 'field:direction')\n- Supported fields: dateCreated, name\n- Examples: 'dateCreated:desc', 'name:asc'\n- Default: dateCreated:desc (most recent first)\n\nUse Cases\n- List all your clients for dashboard display\n- Search for specific client by name, email, or registration number\n- Filter clients by onboarding status\n- Identify clients created by you vs. existing clients you linked\n- Monitor client link creation dates\n- Paginate through large client lists\n\nClient Attribution and Revenue Rules ⚠️ CRITICAL FOR REVENUE CALCULATIONS\n- **IsAttributedClient=true** - Client was created through the referral partner API\n  - Referral partner earns revenue on ALL cases (100% of cases)\n  - This is the default for clients created via POST /clients\n\n- **IsAttributedClient=false** - Client existed in Debitura before the link was established (409 conflict scenario)\n  - Referral partner earns revenue ONLY on cases created through the referral partnership\n  - Cases created directly by the client (not through partner) do NOT generate referral revenue\n  - This protects pre-existing client relationships\n\n**This distinction is the most important business rule for revenue calculations.** Always check IsAttributedClient when forecasting or reconciling revenue.\n\nOnly active (non-archived) client links are returned."
      parameters:
      - name: Page
        in: query
        description: 'Page number (default: 1)'
        schema:
          type: integer
          format: int32
      - name: PageSize
        in: query
        description: 'Results per page (default: 50, max: 100)'
        schema:
          type: integer
          format: int32
      - name: Query
        in: query
        description: Search query across CompanyName, OfficeEmail, and CompanyRegistrationNumber
        schema:
          type: string
      - name: ExternalTenantId
        in: query
        description: Filter by exact external tenant ID
        schema:
          type: string
      - name: IsAttributedClient
        in: query
        description: Filter by attribution status (true = attributed client, false = linked but not attributed)
        schema:
          type: boolean
      - name: DateCreatedFrom
        in: query
        description: Filter by link creation date (from)
        schema:
          type: string
          format: date-time
      - name: DateCreatedTo
        in: query
        description: Filter by link creation date (to)
        schema:
          type: string
          format: date-time
      - name: OnboardingDone
        in: query
        description: Filter by onboarding status (true = completed, false = pending)
        schema:
          type: boolean
      - name: Sort
        in: query
        description: 'Sort field and direction. Format: "field[:asc|desc]"

          Supported fields: dateCreated, name

          Examples: "dateCreated:desc", "name:asc"

          Default: dateCreated:desc'
        schema:
          type: string
      responses:
        '200':
          description: Clients retrieved successfully
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.GetClientsResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.GetClientsResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.GetClientsResponse'
        '400':
          description: Invalid request parameters
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
  /clients/{externalTenantId}:
    get:
      tags:
      - Clients
      summary: Get client by external tenant ID
      description: "Retrieves detailed information for a specific client using your unique identifier (External Tenant ID).\n\nPath Parameter\n- **externalTenantId** - Your unique identifier for this client (the same value used during client creation)\n\nResponse Data\nThe response includes complete client information:\n- **ExternalTenantId** - Your unique identifier for this client\n- **OnboardingDone** - Whether the client has completed onboarding (signed debt collection agreements)\n- **OnboardingLinks** - If onboarding incomplete, contains URL to complete the process\n- **Client** - Complete client information\n  - Debitura-assigned client ID (Guid)\n  - Company name and registration number\n  - Country and address details\n  - Contact information (email, phone)\n- **Users** - List of all users associated with this client\n  - User ID, email, first name, last name\n\nUse Cases\n- Look up client details using your internal identifier\n- Check client onboarding status\n- Retrieve Debitura client ID for use with the Customer API (via OAuth token endpoint)\n- Get client information before creating cases\n- Verify client link is still active\n\nError Cases\n- **404 Not Found** - No active client link exists for this External Tenant ID and your partner account\n  - Client was never created\n  - Client link was archived\n  - External Tenant ID belongs to different referral partner\n- **500 Internal Server Error** - Unexpected server error\n\nImportant Notes\n- Only returns active (non-archived) client links\n- External Tenant ID is case-sensitive\n- The client must be linked to your referral partner account\n- Use the returned client ID with the OAuth token endpoint to generate bearer tokens for Customer API access"
      parameters:
      - name: externalTenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Client retrieved successfully
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientCreatedResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientCreatedResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientCreatedResponse'
        '404':
          description: Client not found or link is archived
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
    delete:
      tags:
      - Clients
      summary: Reset a client (test environment only)
      description: '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'
      parameters:
      - name: externalTenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Client and all associated data successfully deleted
        '403':
          description: Endpoint not available in production environment
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '404':
          description: No active client link found for this externalTenantId
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
  /clients/{externalTenantId}/is-deletable:
    get:
      tags:
      - Clients
      summary: Check if a client can be deleted (test environment only)
      description: '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)'
      parameters:
      - name: externalTenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deletability check completed
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientDeletableResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientDeletableResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.ClientDeletableResponse'
        '403':
          description: Endpoint not available in production environment
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '404':
          description: No active client link found for this externalTenantId
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
  /clients/{externalTenantId}/withdraw:
    post:
      tags:
      - Clients
      summary: Withdraw an attributed client
      description: "Withdraws a client that never completed onboarding. Archives the referral partner link and closes all pending cases with close code CaseNeverStartedInternal.\n\nThe same externalTenantId can be re-submitted via POST /clients after withdrawal.\n\nPath Parameter\n- **externalTenantId** - Your internal identifier for the client\n\nBusiness Rules\n- Only attributed clients (IsAttributedClient = true) can be withdrawn\n- All cases for this client must be in PendingContractSigning status\n\nWhat Happens\n- The referral partner client link is archived\n- All pending cases are closed with close code CaseNeverStartedInternal\n\nAfter Withdrawal\n- The same externalTenantId can be re-submitted via POST /clients\n- A new client record will be created on re-submission\n\nError Cases\n- **404 Not Found** - No active client link exists for this externalTenantId and your partner account\n- **409 Conflict** - Client cannot be withdrawn because:\n  - IsAttributedClient = false (non-attributed clients cannot be withdrawn)\n  - One or more cases have progressed beyond PendingContractSigning"
      parameters:
      - name: externalTenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Client withdrawn successfully
        '404':
          description: No active client link found for this externalTenantId
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '409':
          description: Cannot withdraw — client not attributed or cases have progressed beyond onboarding
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
        '500':
          description: Internal server error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto'
  /clients/{externalTenantId}/kyc-verification:
    post:
      tags:
      - Clients
      summary: Submit KYC verification for a client
      description: 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.
      parameters:
      - name: externalTenantId
        in: path
        required: true
        schema:
          type: string
      - name: sendChatNotification
        in: query
        schema:
          type: boolean
          default: true
      - name: Idempotency-Key
        in: header
        description: 'Optional idempotency key (max 255 characters) for safely retrying this request. If a previous request used the same key with an identical body, the original terminal response is replayed verbatim. Reusing the key with a different body returns 422 with `Type: "IdempotencyConflict"`. Field-level 400 validation errors are not stored, so you may fix the request and retry with the same key.'
        schema:
          maxLength: 255
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.SubmitKycVerificationRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.SubmitKycVerificationRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Clients.SubmitKycVerificationRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/Debitura.Web.ReferralPartnerAp

# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/debitura/refs/heads/main/openapi/debitura-clients-api-openapi.yml