---
title: "Create collection case"
method: POST
path: "/cases"
tags: ["Cases"]
---

# Create collection case

`POST /cases`

Creates a new collection case for debt collection.

**Test Mode:**
- Set isTest=true to create a test case (case IS created in the database but marked as test data)
- Test cases are excluded from production metrics and can be easily filtered or deleted
- Use test mode for integration testing and development

**Debtor Rules:**
- debtor.type must be "Company" or "Private"
  - Company → debtor.name is mandatory (company name)
  - Private → debtor.name is mandatory (person's full name)

**Geographic Rules:**
- debtor.countryAlpha2 (ISO 3166-1 alpha-2) is always required
- debtor.state is a free-text region description
- For US debtors: debtor.stateAlpha2 (two-letter state code) is also required – debtor.state is ignored in that scenario

**Optional Parameters:**
- creditorDivisionId - Assign case to a specific division (for multi-division creditors)
- collectionPartnerId - Override automatic partner assignment with a specific collection partner
- skipDebituraVerification - Skip internal verification steps (advanced use)
- skipCreationEmails - Deprecated: accepted for backwards compatibility but ignored server-side. Creation emails are always suppressed in favour of the hourly CasesStarted digest
- allowPendingContracts - Accept cases with unsigned contracts in 'PendingContractSigning' status instead of returning 422

**Error Responses:**
- 400: Field validation errors (returns JSON object with field names as keys and error arrays as values)
- 422: Business rule violations (returns BusinessErrorResponseApiDTO with type, message, and solutionUrl)
- 500: Server errors

## Headers

- `Idempotency-Key` string

## Request body

- DebituraWebExternalApiContractsV1CasesRequestsCreateCollectionCaseRequestApiViewModel
  - `currencyCode` string, nullable, required
  - `date` string, date-time
  - `dueDate` string, date-time, nullable
  - `comments` string, nullable — Optional comments about the case, e.g. payment history or communication context.
  - `claimDescription` string, nullable — Client provided description of the claim
  - `creditorReference` string, 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 "Person"
    - `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)
  - `creditorDivisionId` string, uuid, nullable
  - `amountToRecover` number, double — The TOTAL amount to recover for this case. This represents the full principal amount across all invoices (if multiple invoices are bundled). For multi-invoice cases with different ages, you can optionally provide age breakdown fields (AmountToRecoverOver12Months and AmountToRecoverOver24Months) to enable blended age-based pricing. If age breakdown fields are omitted, age uplift will be calculated from the invoice due date (single-invoice pricing).
  - `amountToRecoverOver6Months` number, double, nullable — OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING (PRICING ZONE 180-DAY THRESHOLD) The portion of AmountToRecover that is more than 6 months (180 days) overdue. This includes amounts that are 12+ and 24+ months overdue. This field is optional and can only be provided alongside AmountToRecoverOver12Months and AmountToRecoverOver24Months. It enables precise pricing tier selection based on the 180-day threshold. When omitted, the system falls back to deriving the threshold from AmountToRecoverOver12Months. Validation rules: - Must be ≤ AmountToRecover - Must be ≥ AmountToRecoverOver12Months
  - `amountToRecoverOver12Months` number, double, nullable — OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING The portion of AmountToRecover that is more than 12 months overdue. This includes amounts that are 24+ months overdue. If provided, AmountToRecoverOver24Months must also be provided. Both fields must be provided together or both omitted. Used to calculate blended age uplift for multi-invoice cases: - Amount under 12 months = AmountToRecover - AmountToRecoverOver12Months - Amount 12-24 months = AmountToRecoverOver12Months - AmountToRecoverOver24Months - Amount over 24 months = AmountToRecoverOver24Months Blended uplift formula: ((A12-A24)×10 + A24×20) / AmountToRecover where A12 = AmountToRecoverOver12Months, A24 = AmountToRecoverOver24Months Validation rules: - Must be ≤ AmountToRecover - Must be ≥ AmountToRecoverOver24Months
  - `amountToRecoverOver24Months` number, double, nullable — OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING The portion of AmountToRecover that is more than 24 months overdue. If provided, AmountToRecoverOver12Months must also be provided. Both fields must be provided together or both omitted. Used to calculate blended age uplift for multi-invoice cases. See AmountToRecoverOver12Months for full details on the calculation. Validation rules: - Must be ≤ AmountToRecoverOver12Months - Must be ≤ AmountToRecover
  - `skipDebituraVerification` boolean — This skips the 'Pending verification' for Debitura and puts case straight to partner
  - `skipCreationEmails` boolean — Deprecated — this field is accepted for backwards compatibility but is ignored server-side. Creation emails are always suppressed; the hourly CasesStarted digest is the single notification channel for all entry points.
  - `allowPendingContracts` boolean — When true, cases with unsigned contracts (SDCA/POA) are accepted in 'PendingContractSigning' status instead of being rejected with 422. The case transitions automatically once contracts are signed. Default: false (unsigned contracts return 422).
  - `isTest` boolean — When true, creates a test case that IS persisted to the database but marked as test data. Test cases are excluded from production metrics and can be easily filtered or deleted. Use this for integration testing and development.
  - `tag` string, nullable — Optional tag for scoped test data grouping (e.g. "suite-run-{uuid}"). Use this to group test cases created by a single CI pipeline run so they can be bulk-deleted via DELETE /test/cases?tag={tag} without affecting parallel runs. Only meaningful when IsTest is true. Max 100 characters.
  - `collectionPartnerId` string, uuid, nullable — Optional: Specify a collection partner ID to handle this case. When provided, this partner will be used regardless of lead agent matching rules. The partner must be active and have coverage for the debtor's jurisdiction.
  - `assignedUserEmail` string, email, nullable — Optional: Email address of the creditor team member to assign as the case owner. When provided, email notifications for this case will be sent only to this user instead of all team members. Must correspond to an active member of your team.
  - `returnUrl` string, nullable — Optional: URL the creditor user should land on after completing any pending signing chain (SDCA upgrade / PoA / JPA / KYC) on the Debitura Creditors app. Embedded, URL-encoded, into `BusinessErrorResponseApiDTO.SigningHandoff.CombinedSigningUrl` (on 422 with pending signings) and `InvoiceDto.SigningHandoff.CombinedSigningUrl` (on 200 when `AllowPendingContracts=true` with signings remaining). Must be an absolute http(s) URL. Values that fail validation (relative URLs, non-http schemes, header-injection characters) are silently dropped — the combined URL is still emitted but without the returnUrl query parameter, and the Creditors app falls back to its own safe in-app default landing. Additive. Existing integrations that omit this field see the same behaviour as before.

## Response `200`

Case created

- DebituraWebExternalApiContractsV1CasesInvoiceDto — V1 Invoice DTO for external partner APIs
  - `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 Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto.Lifecycle/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto.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 "Person"
    - `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
  - `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. Returns the description of Debitura.Domain.Model.Receiveables.Invoices.Enums.ClaimDisputeStatus: "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` DebituraDomainServicesCaseValidationCaseValidationLeanDto
    - `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 — Additive external-API read model. Per-bucket outstanding on the debt ledger, produced by the payment allocation engine (bucket total minus Σ active stored allocations — never re-derived from a model). Mirrors the internal `Debitura.Domain.Model.Receiveables.InvoiceEconomics.EconomicalAllocationOutstanding` shape.
    - `principal` number, double
    - `interest` number, double
    - `reminderFees` number, double
    - `collectionFees` number, double

## Other responses

- `400` — Invalid request
- `422` — Business rule violation
- `500` — Server error

---

[API](https://skmtc.net/debitura/apis/debitura-customer-api.md) · [All operations](https://skmtc.net/debitura/apis/debitura-customer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/debitura/debitura-customer-api/versions/46478f2e476f/schema)