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

  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)