--- title: "Create case as managing partner" method: POST path: "/managed-cases" tags: ["ManagedCases"] --- # Create case as managing partner `POST /managed-cases` 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. - `creditorCompanyName` string, required — 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 — Creditor country code (ISO 3166-1 alpha-2 format). Either this or CreditorCountry is required. - `creditorCountry` string, nullable — 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, required — 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 — 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 — 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 will be used regardless of lead agent matching rules. 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 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 "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 - `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 data (field validation errors) - `422` — Business rule violation (e.g., no partner available for jurisdiction) - `500` — Internal server error --- [API](https://skmtc.net/debitura/apis/debitura-collection-partner-api.md) · [All operations](https://skmtc.net/debitura/apis/debitura-collection-partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/debitura/debitura-collection-partner-api/revisions/d0dcc5024bd1/schema)