---
title: "Create case as managing partner"
method: POST
path: "/managed-cases"
tags: ["ManagedCases"]
---

# Create case as managing partner

`POST /managed-cases`

## Request

- Base URL: `https://collectionpartner-api.debitura.com`
- URL: `https://collectionpartner-api.debitura.com/managed-cases`
- Auth: API key in header `XApiKey`

**Two ways to name the creditor — send one, never both:**
- **clientId (standard).** Create the client once with `POST /managed-clients`, then send its id as
  `clientId` on every case for that client. All of its cases land on the same client record.
- **creditorCompanyName + country (deprecated).** Still works, so existing integrations never break,
  but it creates a **new client record on every call**. Responses in this mode carry a
  `Deprecation: true` header. No removal date is set.

Sending `clientId` together with any creditor company field is rejected with a 400. A `clientId` that is
not one of your represented clients returns 404. With `clientId`, a CreditorReference already used on
that client is rejected as a duplicate. `clientId` replaces CreditorCompanyName and the creditor country
in the required fields below.

Creates a collection case on behalf of your client (or yourself) through the Debitura platform.

**Understanding the Creditor Field:**
The creditor is the party that the debtor owes money to. This can be:
- **Your client's company** - When you're submitting cases on behalf of clients you represent
- **Your own company** - When you're submitting your own debt collection cases

**How It Works:**
1. You provide the creditor's basic information (company name + country)
2. Debitura creates a creditor record (if one doesn't exist)
3. The collection case is created under that creditor
4. You are set as the managing partner
5. The case is automatically assigned to a collection partner based on jurisdiction

**Managing Partner Benefits:**
- Submit cases on behalf of your clients via API
- Maintain your client relationships
- Leverage Debitura's global partner network
- Monitor case progress through read-only access
- Provide full-service debt recovery to your clients

**Required Fields:**
- CreditorCompanyName - The company name of who the debtor owes money to
- CreditorCountryAlpha2 OR CreditorCountry - Creditor's country (provide either code or name)
- CurrencyCode - Case currency (e.g., 'USD', 'EUR', 'DKK')
- Date - Invoice issue date
- AmountToRecover - Claim amount
- Debtor - Complete debtor information with jurisdiction

**Debtor Rules:**
- debtor.type must be "Company" or "Private" (case-insensitive)
  - Company → debtor.name is mandatory (company name)
  - Private → debtor.name is mandatory (individual's full name)
- For Company debtors, debtor.contactPerson is required
- debtor.country (or debtor.countryAlpha2) is always required
- debtor.stateAlpha2 is **required for US cases** - provide the two-letter state code (e.g., "CA", "NY"). For non-US cases, this field is optional.
- debtor.state is a general-purpose region field (not used for US jurisdiction resolution)

**Optional Fields:**
- DueDate - Invoice due date
- AmountToRecoverOver6Months - Cumulative amount more than 6 months overdue (includes 12+ and 24+)
- AmountToRecoverOver12Months - Cumulative amount more than 12 months overdue (includes 24+)
- AmountToRecoverOver24Months - Cumulative amount more than 24 months overdue
- ClaimLines - The unpaid invoices making up the claim (see below)
- Comments - Additional notes
- ClaimDescription - Description of the claim
- CreditorReference - Your client's internal reference
- CollectionPartnerId - Override automatic partner matching
- IsTest - Mark as test case (excluded from production metrics)

**Submitting Claim Lines (recommended for multi-invoice claims):**
Instead of totalling the claim yourself, send the unpaid invoices and let us do the arithmetic:

```
"claimLines": [
  { "dueDate": "2024-01-15", "amount": 423.42, "reference": "INV-1001" },
  { "dueDate": "2025-05-02", "amount": 700.87, "reference": "INV-1042" }
]
```

- amount is the **outstanding balance** on that invoice — what the debtor still owes on it, already
  net of payments received and credit notes issued. It is not the invoice's original face value.
  Leave fully settled invoices out; every amount must be greater than zero, with at most 2 decimals.
- We derive AmountToRecover and all three age buckets from the lines, so send claimLines **instead of**
  AmountToRecover and the AmountToRecoverOver6/12/24Months fields. Sending both is a 400.
- Use claimLines whenever the debtor has already part-paid: it is the only way to express an honest
  age profile on a part-paid claim, because the buckets are then computed on the same outstanding
  balances the total is computed on.
- claimLines prices on exact age data. Sending a single DueDate instead is an approximation and can
  produce a different quote for the same claim.
- claimLines is a pricing input only. It is not stored and is not shown to the collecting partner —
  include a per-invoice breakdown in Comments if the partner needs to see one.
- Maximum 1000 lines. Per-line errors are returned keyed by index, e.g. `ClaimLines[2].DueDate`.
- If you omit the case-level DueDate, it is set to the oldest due date across your lines — so in that
  case Date must not be later than the earliest claimLines dueDate, or the request is rejected with a
  400 on Date. Send an explicit DueDate if you need a different case due date.

**Response:**
Returns the created case details including the case ID, reference number, and assignment information.

**Important Notes:**
- The 12+ and 24+ fields must be supplied together. The 6+ field is optional, but when supplied it requires both other buckets.
- Cumulative values must satisfy AmountToRecover ≥ 6+ ≥ 12+ ≥ 24+. DueDate may coexist with age buckets.
- Creditor records are created fresh each time (no duplicate detection)
- Contract requirements are automatically bypassed
- Production cases enter Debitura's internal verification before proceeding to the assigned collection partner
- Test cases bypass internal verification because delayed auto-validation is only scheduled for production cases
- Cases appear in your 'Managed Cases' list
- You have read-only access to monitor case progress

## Headers

- `Idempotency-Key` string

## Request body

- DebituraWebExternalApiContractsV1CasesRequestsCreateManagedCaseRequest: Request model for creating a case as a managing partner. The partner submits both creditor information and case details in a single request.
  - `clientId` string, uuid, nullable: The client this case belongs to. Create the client once with POST /managed-clients and send its id here; every case you submit for that client then lands on the same record. Send either ClientId or the creditor company fields below, never both.
  - `creditorCompanyName` string, nullable: Deprecated. Use ClientId: create the client once with POST /managed-clients. This mode still works and creates a new client record on every call. Creditor company name for this case. If you're submitting cases on behalf of your clients, use your client's company name. If you're submitting your own cases, use your own partner company name.
  - `creditorCountryAlpha2` string, nullable: Deprecated. Use ClientId: create the client once with POST /managed-clients. This mode still works and creates a new client record on every call. Creditor country code (ISO 3166-1 alpha-2 format). Either this or CreditorCountry is required.
  - `creditorCountry` string, nullable: Deprecated. Use ClientId: create the client once with POST /managed-clients. This mode still works and creates a new client record on every call. Creditor country name. Either this or CreditorCountryAlpha2 is required.
  - `currencyCode` string, required: Currency code for the case (ISO 4217 format)
  - `date` string, date-time, required: Invoice issue date. Provide date only without time component.
  - `dueDate` string, date-time, nullable: Invoice due date. Provide date only without time component.
  - `comments` string, nullable: Optional comments about the case. Use this to provide context about payment attempts, communication history, or other relevant information.
  - `claimDescription` string, nullable: Client provided description of the services or goods delivered
  - `creditorReference` string, nullable: Client's internal reference for the case (e.g., invoice number)
  - `debtor` DebituraWebExternalApiContractsV1CasesDebtorDto, required: 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 "Private" (case-insensitive)
    - `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)
  - `amountToRecover` number, double: Total amount to recover from debtor (in the specified currency). Required unless you send ClaimLines, in which case this must be omitted or 0 — the server derives the total by summing the outstanding balance of every claim line. Sending both a non-zero AmountToRecover and ClaimLines is rejected, because the two would disagree.
  - `amountToRecoverOver6Months` number, double, nullable: Optional cumulative portion of AmountToRecover that is more than 6 months overdue. Includes the 12+ and 24+ month amounts and must be supplied together with both fields.
  - `amountToRecoverOver12Months` number, double, nullable: Optional cumulative portion of AmountToRecover that is more than 12 months overdue. Includes the 24+ month amount and must be supplied together with AmountToRecoverOver24Months.
  - `amountToRecoverOver24Months` number, double, nullable: Optional cumulative portion of AmountToRecover that is more than 24 months overdue. Must be supplied together with AmountToRecoverOver12Months.
  - `claimLines` DebituraWebExternalApiContractsV1CasesRequestsClaimLineDto[], nullable: Optional: the unpaid invoices making up this claim, one line per invoice, each carrying its own outstanding balance and payment deadline. When supplied, the server derives AmountToRecover and all three cumulative age buckets from these lines, so send them instead of — never alongside — AmountToRecover and the AmountToRecoverOver6/12/24Months fields. Supplying both is rejected with a 400. Use this whenever the debtor has already part-paid the claim: the buckets are then computed on the same outstanding balances the total is computed on, so the age profile stays honest. Maximum 1000 lines. When DueDate is omitted on the case, it is derived as the oldest line due date.
    - `dueDate` string, date-time, nullable, required: Payment deadline of this invoice. Provide date only without time component. Must be on or after 2000-01-01 and must not be in the future.
    - `amount` number, double, required: The outstanding balance on this invoice in the case currency — what the debtor still owes on it, already net of any payments the debtor has made and net of any credit notes issued against it. This is not the invoice's original face value. Must be greater than zero with at most 2 decimal places; omit invoices that are fully settled.
    - `reference` string, nullable: Optional: your own invoice number for this line. Used only to make validation errors readable and to reject the same invoice being sent twice. It is not stored and not shown to anyone.
  - `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 is used instead of automatic partner matching. The partner must be active and have coverage for the debtor's jurisdiction.

## Response `200`

Case created successfully

- 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 Lifecycle/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 "Private" (case-insensitive)
    - `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: Deprecated: kept as a number and never removed, but not extended. Survey-generation cadence: 0 = Standard (rolling monthly survey), 1 = DecisionPointOnly (no rolling surveys). Your own cadence is available by name on GET /me.
  - `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. One of: "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` DebituraWebExternalApiContractsV1CasesCaseValidationLeanDto: Stable v1 validation summary used by ordinary and list mappings.
    - `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: Outstanding amount per bucket on the case: each bucket's total minus the payments allocated to it.
    - `principal` number, double
    - `interest` number, double
    - `reminderFees` number, double
    - `collectionFees` number, double

## Other responses

- `400`: Invalid request data (field validation errors)
- `404`: clientId is not one of your represented clients
- `409`: Conflict - an idempotent request with this key is still in progress
- `422`: Business rule violation (e.g., no partner available for jurisdiction)
- `500`: Internal server error

## Changes

- **2026-10-01** `460a861d7d9b`: 3 info
  - response property `collectionPartner/surveyCadenceMode` deprecated (media type: text/plain)
  - response property `collectionPartner/surveyCadenceMode` deprecated (media type: application/json)
  - response property `collectionPartner/surveyCadenceMode` deprecated (media type: text/json)
- **2026-09-20** `7a1c16414f83`: 1 breaking, 30 info
  - for the `header` request parameter `Idempotency-Key`, the minLength was increased from `0` to `1`
  - added the new optional request property `clientId` (media type: application/json-patch+json)
  - added the new optional request property `clientId` (media type: application/json)
  - added the new optional request property `clientId` (media type: text/json)
  - …27 more
- **2026-08-13** `db09d0fd5c94`: 8 breaking, 4 info
  - the request property `claimLines/items/amount` became required (media type: application/json-patch+json)
  - the request property `claimLines/items/amount` became required (media type: application/json)
  - the request property `claimLines/items/amount` became required (media type: text/json)
  - the request property `claimLines/items/amount` became required (media type: application/*+json)
  - …8 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/debitura/apis/debitura-collection-partner-api/changes/managed-cases/post.md)

---

[API](https://skmtc.dev/debitura/apis/debitura-collection-partner-api.md) - [All operations](https://skmtc.dev/debitura/apis/debitura-collection-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/debitura/apis/debitura-collection-partner-api/revisions/a7cf0ff022b6?raw)