Create and onboard a new client

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 an expiration window configured per-partner (ApprovalTtlDays, default 7 days, clamped 1–30)
   • Existing client must approve the referral partner link via OnboardingLinks.Url
   • If approved, IsAttributedClient will be FALSE (revenue only on partner-referred cases)
   • 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.
   • 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)

{
  "externalTenantId": "tenant-12345",
  "client": {
    "name": "Acme Corp",
    "registrationNumber": "12345678",
    "address": "123 Business Street",
    "zipCode": "1000",
    "city": "Lisbon",
    "state": "Lisbon",
    "country": "Portugal",
    "supportEmail": "billing@acme-corp.com",
    "supportPhone": "+351 123 456 789"
  },
  "users": [
    {
      "name": "John Doe",
      "email": "john.doe@acme-corp.com",
      "isOnboardingUser": true
    }
  ],
  "cases": [
    {
      "currencyCode": "EUR",
      "amountToRecover": 4000,
      "date": "2026-02-22",
      "dueDate": "2026-03-02",
      "claimDescription": "Custom mobile app development services",
      "comments": "Outstanding invoice INV 2024 00789 for custom mobile app development delivered 15 Nov 2024; payment 60 days overdue despite two reminders.",
      "creditorReference": "INV‑2024‑00789",
      "isTest": false,
      "debtor": {
        "type": "Company",
        "name": "Acme Corp",
        "contactPerson": "John Doe",
        "companyRegistrationNumber": "12345678",
        "address": "123 Business Street",
        "zipCode": "1000",
        "city": "Lisbon",
        "state": "Lisbon",
        "countryAlpha2": "PT",
        "email": "billing@acme‑corp.com",
        "phone": "+351 123 456 789"
      }
    }
  ]
}

{
  "caseResults": {
    "successfulCases": [
      {
        "debtor": {
          "type": "Company",
          "name": "Pacific Trading LLC",
          "contactPerson": "John Smith",
          "companyRegistrationNumber": "47-1234567",
          "address": "123 Market Street, Suite 400",
          "zipCode": "94105",
          "city": "San Francisco",
          "state": "California",
          "stateAlpha2": "CA",
          "countryAlpha2": "US",
          "country": "United States",
          "email": "accounts@pacifictrading.com",
          "phone": "+1 415 555 0123"
        }
      }
    ]
  }
}