Skip to main content

Create and onboard a new client

POST 
/clients

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: The POST /clients endpoint is idempotent and re-checks SDCA status on every call. This means 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) There are TWO distinct 409 conflict scenarios - check the ConflictResponse.Type field to distinguish:

    2a. ClientExistsNeedsLinking (Type: "ClientExistsNeedsLinking")

    • Client already exists in Debitura (matched by user email or support email)
    • A link request is created with 7-day expiration
    • Existing client must approve the referral partner link via OnboardingLinks.Url
    • If approved, IsAttributedClient will be FALSE (revenue only on partner-referred cases)
    • Returns 409 with OnboardingLinks.Url pointing to approval page

    2b. ClientAlreadyLinkedToAnotherPartner (Type: "AlreadyLinkedToAnotherPartner")

    • 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

    • Repeated calls with same ExternalTenantId return existing client status (201 or 202)
    • No duplicate clients or links are created

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)
  • 409 Conflict - Two scenarios (check ConflictResponse.Type):
    • "ClientExistsNeedsLinking" - Client exists, needs approval link (if approved, IsAttributedClient=false)
    • "AlreadyLinkedToAnotherPartner" - Client already linked to different partner (cannot proceed)
  • 422 Unprocessable Entity - Business rule violation (field validation errors only, NOT partner matching failures)
  • 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")

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)

Request​

Responses​

Client created and fully onboarded (terms signed)