openapi: 3.2.0 info: title: Debitura Cases API version: v1 description: 'Operations tagged Cases across 3 of this provider''s published API definitions: debitura-collection-partner-api.json, debitura-customer-api.json, debitura-referral-partner-api.json. Each path carries the servers of the definition it was published in.' servers: - url: https://collectionpartner-api.debitura.com description: Production - url: https://customer-api.debitura.com description: Production - url: https://referral-api.debitura.com description: Production tags: - name: Cases description: Cases paths: /cases: get: tags: - Cases summary: List collection cases. description: "Returns a paginated list of cases where you are the **collection partner** (actively collecting the debt).\n\n**What is a Collection Partner?**\nA collection partner is an agency or law firm that performs the actual debt recovery work. When you appear as the collection partner on a case, you are responsible for:\n- Contacting the debtor and attempting recovery\n- Managing the case lifecycle and status updates\n- Recording payments and fees\n- Uploading documents and evidence\n- Communicating with the creditor through the case chat\n\n**Note:** This endpoint shows cases where you are collecting. For cases you submitted on behalf of your own clients (where you are the managing partner), use the `/managed-cases` endpoint instead.\n\n**Pagination:**\n- page (default: 1) - Page number, starting from 1\n- pageSize (default: 10, max: 100) - Number of results per page\n\n**Filters:**\n- statuses - Filter by case lifecycle status (comma-separated list)\n Valid values: PendingVerification, NeedsAdditionalDetails, Leads, LeadsQuoteGiven, Active, Paused, Closed\n **Note:** Partner-specific statuses only. Internal platform statuses like 'PendingContractSigning' or 'PendingVerificationInternal' are not available here — cases in those stages are hidden from every collection-partner-facing endpoint until Debitura's internal verification clears, regardless of assignment.\n- divisionIds - Filter by creditor division IDs (comma-separated GUIDs)\n- debtorIds - Filter by specific debtor IDs (comma-separated GUIDs)\n- ids - Filter by specific case IDs (comma-separated GUIDs)\n- includeTestCases - When true, includes test/demo cases owned by the caller. Defaults to false.\n\n**Sorting:**\n- sort - Sort field and direction (format: 'field:direction')\n Examples: 'date:desc', 'amount:asc', 'debtorName:asc'\n\n**Response:**\n- Returns InvoiceListApiDTO with page metadata and cases array\n- Page metadata includes: totalResults, currentPage, skipped, pageSize" parameters: - name: Page in: query schema: type: integer format: int32 - name: PageSize in: query schema: type: integer format: int32 - name: DebtorIds in: query schema: type: array items: type: string format: uuid - name: Ids in: query schema: type: array items: type: string format: uuid - name: Statuses in: query description: 'Filter by case lifecycle status. Valid values: PendingContractSigning, PendingVerificationInternal, PendingVerification, NeedsAdditionalDetails, Leads, LeadsQuoteGiven, Active, Paused, Closed, Merged (case-insensitive; both name and description forms accepted).' schema: type: array items: type: string - name: DivisionIds in: query description: Optional list of division IDs to filter by schema: type: array items: type: string format: uuid - name: Sort in: query description: 'Optional sorting string "Field[:asc|desc][,Field2[:asc|desc]]…". Valid sort fields: DateCreated, DateUpdated, DateFinished, DateCollectionStarted, DueDate, Date, GrossAmount, Remainder, InterestFees, CollectionFees, ReminderFees, Lifecycle, CloseCode. Examples: ''DateCreated:desc'', ''DueDate:asc''. Unknown fields are silently ignored.' schema: type: string - name: includeTestCases in: query description: "When true, includes test/demo cases where the caller is the owner (either as collection partner\nor as managing partner). Defaults to false.\n \nImplementation note: the spec sets CollectionPartnerIds = [callerPartnerId] as an AND filter.\nSelf-managed test cases are still returned because routing isolation guarantees\nCollectionPartnerId == ManagedByPartnerId for cases submitted by the managing partner to themselves.\nTestCaseOwnerManagedByPartnerId provides the OR-leg for non-self-routed test cases." schema: type: boolean default: false responses: '200': description: List returned content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceListDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceListDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceListDto' '400': description: Invalid query parameters (returns specific validation errors) content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] post: tags: - Cases summary: Create collection case description: "Creates a new collection case for debt collection.\n\n**Test Mode:**\n- Set isTest=true to create a test case (case IS created in the database but marked as test data)\n- Test cases are excluded from production metrics and can be easily filtered or deleted\n- Use test mode for integration testing and development\n\n**Debtor Rules:**\n- debtor.type must be \"Company\" or \"Private\"\n - Company → debtor.name is mandatory (company name)\n - Private → debtor.name is mandatory (person's full name)\n\n**Geographic Rules:**\n- debtor.countryAlpha2 (ISO 3166-1 alpha-2) is always required\n- debtor.state is a free-text region description\n- For US debtors: debtor.stateAlpha2 (two-letter state code) is also required – debtor.state is ignored in that scenario\n\n**Optional Parameters:**\n- creditorDivisionId - Assign case to a specific division (for multi-division creditors)\n- collectionPartnerId - Override automatic partner assignment with a specific collection partner\n- skipDebituraVerification - Skip internal verification steps (advanced use)\n- skipCreationEmails - Deprecated: accepted for backwards compatibility but ignored server-side. Creation emails are always suppressed in favour of the hourly CasesStarted digest\n- allowPendingContracts - Accept cases with unsigned contracts in 'PendingContractSigning' status instead of returning 422\n\n**Error Responses:**\n- 400: Field validation errors (returns JSON object with field names as keys and error arrays as values)\n- 422: Business rule violations (returns BusinessErrorResponseApiDTO with type, message, and solutionUrl)\n- 500: Server errors" parameters: - name: Idempotency-Key in: header description: 'Optional idempotency key (max 255 characters) for safely retrying this request. If a previous request used the same key with an identical body, the original terminal response is replayed verbatim. Reusing the key with a different body returns 422 with `Type: "IdempotencyConflict"`. Field-level 400 validation errors are not stored, so you may fix the request and retry with the same key.' schema: maxLength: 255 type: string requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.CreateCollectionCaseRequestApiViewModel' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.CreateCollectionCaseRequestApiViewModel' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.CreateCollectionCaseRequestApiViewModel' application/*+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.CreateCollectionCaseRequestApiViewModel' responses: '200': description: Case created content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' '400': description: Invalid request content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '422': description: Business rule violation content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorResponseApiDTO' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorResponseApiDTO' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorResponseApiDTO' '500': description: Server error content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}: get: tags: - Cases summary: Fetch case by ID description: 'Returns detailed case information for a specific case ID (GUID). **Access Control:** Only returns cases where you are the collection partner, or test/demo cases where you are the managing partner. For managed production cases, use `/managed-cases/{id}` instead. **Response Includes:** - Case details (reference, amount, currency, status, lifecycle stage) - Debtor information (name, address, contact details, company/private type) - Creditor information - Collection partner assignment details - Financial breakdown (principal, interest, fees) - Important dates (creation, assignment, due dates) - Geographic information (jurisdiction, country)' parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Case found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' '400': description: ID missing, empty, or ID is not a collection case content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found, deleted, or not assigned to you as collection partner content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/case-reference/{caseReference}: get: tags: - Cases summary: Fetch case by reference description: 'Returns detailed case information using the Debitura case reference (e.g., ''Q8OAXF3W''). **Use Case:** Use this endpoint when you have the Debitura case reference (visible in the partner portal and emails) but not the GUID. This is helpful for customer service integrations or when referencing cases in communications. **Access Control:** Only returns cases where you are the collection partner, or test/demo cases where you are the managing partner. For managed production cases, use `/managed-cases/case-reference/{reference}`.' parameters: - name: caseReference in: path required: true schema: type: string responses: '200': description: Case found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' '400': description: Reference missing or reference is not a collection case content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Reference not found or not assigned to you as collection partner content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/by-partner-reference/{reference}: get: tags: - Cases summary: Fetch a single case by the collection partner's own reference ID. description: 'Returns detailed case information using the collection partner''s own reference (the `CollectionPartnerReference` field set during case activation). **Use Case:** Use this endpoint when you have your own internal case reference and want to look up the corresponding Debitura case. This is useful for integrating your case management system with Debitura. **Matching:** Exact string match only. Combined references like ''112179442 & 112179443'' must be queried with the full combined string. **Access Control:** Only returns cases where you are the collection partner and the case is a production collection case.' parameters: - name: reference in: path required: true schema: type: string responses: '200': description: Case found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' '400': description: Reference missing or empty content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: No case found with this partner reference content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/by-partner-reference: get: tags: - Cases summary: Batch lookup of cases by the collection partner's own reference IDs. description: 'Returns a dictionary mapping each partner reference to its corresponding case details. **Use Case:** Use this endpoint to look up multiple cases at once using your own internal reference IDs. This is more efficient than making individual calls for each reference. **Parameters:** - references (required) - Comma-separated list of partner reference strings (max 100) **Matching:** Exact string match only. References not found or not assigned to you are omitted from the response (no error). **Response:** A dictionary where keys are the partner reference strings and values are the case details. Missing references are silently omitted.' parameters: - name: references in: query schema: type: string responses: '200': description: Dictionary of reference to case content: text/plain: schema: type: object additionalProperties: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' text/json: schema: type: object additionalProperties: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' '400': description: References parameter missing, empty, or exceeds maximum content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/by-creditor-reference: get: tags: - Cases summary: Fetch a single case by creditor reference, scoped to a specific creditor and partner. description: 'Returns detailed case information using the creditor''s own reference (`CreditorReference`) scoped to a specific creditor. **Use Case:** Use this endpoint when you have the creditor''s reference (e.g. from an invoice file or payment import) and need to look up the corresponding Debitura case. Because `CreditorReference` is only unique within a single creditor, you must also supply `creditorId` to make the lookup unambiguous. **Matching:** Exact string match on `CreditorReference`. The case must also belong to the specified creditor and be assigned to the calling partner. **Access Control:** Only returns production collection cases where you are the collection partner. The `creditorId` parameter scopes the lookup to a specific creditor — you can only retrieve cases for creditors whose cases are assigned to you.' parameters: - name: reference in: query schema: type: string - name: creditorId in: query schema: type: string format: uuid responses: '200': description: Case found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' '400': description: Reference or creditorId missing or empty content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: No case found for this reference + creditor combination, or not assigned to you content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/timeline: get: tags: - Cases summary: Fetch case timeline description: 'Returns the complete chronological event history for a case along with the current engagement phase. **Timeline Events Include:** - Case assignment to collection partner - Status changes and lifecycle transitions - Payment recordings - Document uploads - Communication events - Fee additions - Manual updates and notes - System-generated events **Response shape:** - `items` — chronological list of timeline events - `currentEngagementPhase` — current phase of the active engagement: "Pre-legal", "Legal", or "Enforcement". Null when no active engagement exists. **Use Case:** Use this to track case progress, understand case history, audit actions, or display activity to users. Timeline events are ordered chronologically and include timestamps, event types, titles, and descriptions. **Note:** Timeline is filtered to show partner-relevant events only.' parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Timeline returned content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CaseTimelineResponse' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CaseTimelineResponse' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CaseTimelineResponse' '400': description: Case ID missing or empty content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to you as collection partner content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/chats: get: tags: - Cases summary: Fetch case chats description: 'Returns all chat messages for a case in chronological order. **Chat Participants:** - Collection partner (you) - Messages from your team - Creditor - Messages from the client who owns the debt - Debitura support - System notifications and support messages - Managing partner (if applicable) - Messages from the partner who submitted the case **Message Details Include:** - Message content and timestamp - Sender information (name, role) - Message type (text, system notification, file attachment reference) - Read status and delivery information **Use Case:** Use this endpoint to build case communication interfaces, retrieve conversation history, or integrate case discussions into your systems. Perfect for customer service tools or partner portals. **Note:** If the case has no thread or messages, an empty array is returned.' parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Chats returned (empty array if no messages) content: text/plain: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Chats.ChatDto' application/json: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Chats.ChatDto' text/json: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Chats.ChatDto' '400': description: Case ID missing or empty content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to you as collection partner content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] post: tags: - Cases summary: Send a chat message on a case description: 'Posts a new chat message on a case, visible to both the collection partner and the creditor. **Message Details:** - The message is attributed to the team member identified by `userId` - The creditor will receive an email notification about the new message - A task is created in the Debitura platform for the creditor to review the message - Messages appear in the case chat timeline in chronological order **Prerequisites:** - The case must exist and be assigned to you as collection partner - The `userId` must be a valid user ID from `GET /users` belonging to your team **Use Case:** Use this endpoint to communicate with creditors about case progress, request additional information, or provide status updates. Messages sent via this endpoint are equivalent to messages sent through the partner portal chat.' parameters: - name: id in: path required: true schema: type: string format: uuid - name: Idempotency-Key in: header description: Optional idempotency key (max 255 characters). If the same key is reused with an identical message body within 24 hours, the originally created chat message is returned instead of posting a duplicate. The key is scoped per partner, case, and message body — reusing it with a different body posts a new message rather than returning a conflict. schema: maxLength: 255 type: string requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Chats.SendChatRequest' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Chats.SendChatRequest' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Chats.SendChatRequest' application/*+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Chats.SendChatRequest' responses: '200': description: Chat message sent successfully (or duplicate idempotency key — existing response returned) content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Chats.ChatDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Chats.ChatDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Chats.ChatDto' '400': description: Validation error — missing fields, invalid userId, or invalid request body content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to this collection partner content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Internal server error content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/payments: get: tags: - Cases summary: Fetch case payments description: 'Returns all payments recorded on a specific case. **Payment Information Includes:** - Payment amount and currency - Payment date (when received) - Payment type (full payment, partial payment, settlement) - Payment method (bank transfer, card, cash, etc.) - Payment status (pending, confirmed, reconciled) - Reference information - Allocation breakdown (principal, interest, fees) **Use Case:** Use this endpoint to: - Track payment history for a case - Reconcile payments with your records - Display payment status to users - Calculate outstanding balances - Generate financial reports **Note:** Only payments associated with this specific case are returned. All payments are returned in reverse chronological order (newest first).' parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Payments returned (may be empty array) content: text/plain: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto' application/json: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto' text/json: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto' '400': description: Case ID missing or empty content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to you as collection partner content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] post: tags: - Cases summary: Create a payment on a case description: "Records a payment received for a collection case.\n\n**Use Case:**\nUse this endpoint when you receive a payment from the debtor. Provide the payment amount and, in the normal case, nothing else for the split — **omit both PayoutCreditor and PayoutCollectionPartner** and Debitura computes the creditor/partner split server-side from the case's pricing terms (success fee). This is the default and recommended usage for almost every integration.\n\n**Advanced override — PayoutCreditor / PayoutCollectionPartner:**\nSupplying both fields lets you dictate the split explicitly instead of using the computed one. This is an **advanced, opt-in override** for legitimate edge cases (e.g. a negotiated split where the collection partner already holds funds) — it is not the normal path and most integrations should never set it. When supplied:\n- Both fields are required together, and MUST sum to PaymentAmount (within 0.01 tolerance).\n- The response's `Warnings` array surfaces (without blocking the request) if the split allocates zero to the creditor, or if the case had no outstanding balance before this payment — both are signs of a misconfigured or duplicate payment and should be reviewed.\n\n**Currency:** Payment must be in the same currency as the invoice. The currency is automatically determined from the case.\n\n**PaymentRecipient Options:**\n- **Creditor** - Payment was received by the creditor (your client). When using this option, you MUST also specify CommissionPaymentStatus.\n- **CollectionPartner** - Payment was received by you (the collection partner). Commission is automatically marked as Paid since you already have the funds.\n\n**CommissionPaymentStatus:**\nThis field tracks whether the collection partner's commission has been paid. It's only required when PaymentRecipient is 'Creditor'.\n- **Paid** - The creditor has already paid your commission\n- **Unpaid** - The creditor has not yet paid your commission\n\nNote: When PaymentRecipient is 'CollectionPartner', this field is automatically set to 'Paid' since you already have the money.\n\n**Critical Validation:**\n- PayoutCreditor and PayoutCollectionPartner are optional but must be supplied together. When supplied, they MUST equal PaymentAmount (within 0.01 tolerance). When omitted (recommended), the split is computed from the case terms.\n- An explicit split that zeroes the creditor, or that is supplied on an already-settled (zero-remainder) case, is accepted but surfaced as a warning in the response — not blocked.\n- CommissionPaymentStatus is required only if PaymentRecipient is 'Creditor'\n\n**Payment Flow:**\n1. Full Payment (payment >= outstanding):\n - If CloseCase=true → closes case with 'Paid' status\n - If CloseCase=false → case remains open\n\n2. Partial Payment (payment < outstanding):\n - The payment is recorded regardless of CloseCase. The case is NOT closed (CloseCase is honoured only when the payment fully settles the balance) and no error is returned.\n - To close on a partial payment, use the close endpoint with the PartiallyPaid close code." parameters: - name: id in: path required: true schema: type: string format: uuid - name: Idempotency-Key in: header description: 'Optional idempotency key (max 255 characters) for safely retrying this request. If a previous request used the same key with an identical body, the original terminal response is replayed verbatim. Reusing the key with a different body returns 422 with `Type: "IdempotencyConflict"`. Field-level 400 validation errors are not stored, so you may fix the request and retry with the same key.' schema: maxLength: 255 type: string requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.CreatePaymentRequest' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.CreatePaymentRequest' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.CreatePaymentRequest' application/*+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.CreatePaymentRequest' responses: '200': description: Payment created successfully (or duplicate Idempotency-Key — the original response is replayed). Check the Warnings array for non-blocking advisory notices (e.g. about an explicit payout-split override). content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.CreatePaymentResponse' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.CreatePaymentResponse' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.CreatePaymentResponse' '400': description: Invalid request (validation errors) content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to you content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '409': description: A request with this Idempotency-Key is already in progress. Retry after the indicated delay. content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '422': description: The Idempotency-Key has already been used with a different request body. content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Server error occurred content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/files: get: tags: - Cases summary: Get case files description: 'Returns all documents and files attached to a case. **File Types Include:** - OriginalInvoice - The initial invoice/claim document - ProofOfDelivery - Delivery confirmations - Contract - Agreements and contracts - Correspondence - Email and letter communications - PaymentProof - Payment receipts and confirmations - CourtDocuments - Legal filings and court papers - Other - Miscellaneous supporting documents **File Information Includes:** - File ID and case ID - File name and description/label - Document type classification - Upload timestamps (created, updated) - Download URL (temporary, signed link) - File metadata **Use Case:** Use this endpoint to: - Retrieve evidence and supporting documents - Display case files in partner portals - Download documents for offline review - Build document management interfaces - Audit document completeness **Note:** File URLs are temporary signed links that expire after a period. Generate new URLs by calling this endpoint again if links expire.' parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Files retrieved successfully (may be empty array) content: text/plain: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Files.CaseFileDto' application/json: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Files.CaseFileDto' text/json: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Files.CaseFileDto' '400': description: Case ID missing or empty content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to you as collection partner content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Server error occurred while retrieving files content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] post: tags: - Cases summary: Upload a file to a case description: 'Uploads a file and attaches it to a case. Mirrors the file upload action available in the Partner portal. **Access:** Collection partners only. Managing partners are rejected. **Status gate:** Allowed on all non-Merged statuses, including Closed. Only Merged cases are rejected. **File requirements:** - Maximum size: 25 MB - Allowed extensions: `.pdf` `.doc` `.docx` `.xls` `.xlsx` `.jpg` `.jpeg` `.png` `.txt` `.zip` `.csv` `.eml` **DocumentType (optional):** - `OriginalInvoice` — the original invoice document - `DebtorDocuments` — documents provided by the debtor - `CreditorDocuments` — documents provided by the creditor - `PartnerDocuments` — documents provided by the collection partner - `DemandLetter` — formal demand letter - `Miscellaneous` — other supporting documents The file is immediately visible to the creditor.' parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: multipart/form-data: schema: type: object properties: File: type: string description: 'The file to upload. Required. Allowed extensions: .pdf .doc .docx .xls .xlsx .jpg .jpeg .png .txt .zip .csv .eml Maximum size: 25 MB.' format: binary DocumentType: type: string description: 'Optional document type / category. Omit (or pass null) to leave uncategorised. Valid values: DebtorDocuments, CreditorDocuments, PartnerDocuments, OriginalInvoice, DemandLetter, Miscellaneous.' Description: type: string description: Optional free-text description / label for the file (max 500 characters). encoding: File: style: form DocumentType: style: form Description: style: form responses: '200': description: File uploaded successfully content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Files.CaseFileDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Files.CaseFileDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Files.CaseFileDto' '400': description: Invalid request — missing file, unsupported extension, or request validation error content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to this collection partner content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '409': description: Case is Merged and cannot accept new files content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '413': description: File exceeds the 25 MB size limit content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '415': description: Unsupported file extension content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Internal server error content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/notes: post: tags: - Cases summary: Create a note on a case description: 'Creates a new note/comment on a collection case. **Use Case:** Use this endpoint to document activities, record conversations, add reminders, or log any relevant information about the case. Notes are automatically shared with the creditor. **Validation:** - Description is required (max 10000 characters) - EventDate must not be in the future (if provided) **EventDate:** Supply EventDate to back-date the note to the time the event actually occurred. For example, if a phone call happened three days ago, pass that date so the timeline reflects the real event order. Omit for real-time notes.' parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Notes.CreateNoteRequest' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Notes.CreateNoteRequest' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Notes.CreateNoteRequest' application/*+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Notes.CreateNoteRequest' responses: '200': description: Note created successfully content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Notes.NoteDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Notes.NoteDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Notes.NoteDto' '400': description: Invalid request (missing required fields, EventDate in the future, or validation errors) content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to you content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Server error occurred content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/payments/{paymentId}: put: tags: - Cases summary: Edit a payment on a case description: 'Edits an existing payment on a collection case. Mirrors the payout-split semantics of the create-payment endpoint. **Payout Split:** supply both PayoutCreditor and PayoutCollectionPartner to set the split explicitly (they must sum to PaymentAmount), or omit both to have it recomputed from the case''s pricing terms. **Invoiced payments are frozen:** a payment whose payout has already been invoiced (Stripe/QBO) cannot be edited and returns **422 Unprocessable Entity**. This protects the issued accounting entry from silent drift. **Reopen consent:** if the edit lowers the payment so a previously closed (Paid) case is left with a positive outstanding balance, the case must be reopened. By default this returns **409 Conflict**; resend with `reopenCaseIfNeeded: true` to confirm — the case is reopened to Active and a `case.updated` webhook fires.' parameters: - name: id in: path required: true schema: type: string format: uuid - name: paymentId in: path required: true schema: type: string format: uuid requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.UpdatePaymentRequest' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.UpdatePaymentRequest' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.UpdatePaymentRequest' application/*+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.UpdatePaymentRequest' responses: '200': description: Payment updated successfully content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto' '400': description: Invalid request (validation errors) content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case or payment not found / not assigned to you content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '409': description: Edit would reopen the case; resend with reopenCaseIfNeeded=true content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '422': description: Payment has already been invoiced and cannot be edited content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Server error occurred content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] delete: tags: - Cases summary: Delete a payment on a case description: 'Deletes a payment from a collection case, reverting its effect on the case balance and cascading the payout deletion. A durable audit record of the deletion is retained. **Invoiced payments are frozen:** a payment whose payout has already been invoiced (Stripe/QBO) cannot be deleted and returns **422 Unprocessable Entity**. **Reopen consent:** if deleting the payment leaves a previously closed (Paid) case with a positive outstanding balance, the case must be reopened. By default this returns **409 Conflict**; resend with `reopenCaseIfNeeded=true` to confirm — the case is reopened to Active and a `case.updated` webhook fires.' parameters: - name: id in: path required: true schema: type: string format: uuid - name: paymentId in: path required: true schema: type: string format: uuid - name: reopenCaseIfNeeded in: query schema: type: boolean default: false responses: '204': description: Payment deleted successfully '400': description: Invalid request content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case or payment not found / not assigned to you content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '409': description: Deletion would reopen the case; resend with reopenCaseIfNeeded=true content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '422': description: Payment has already been invoiced and cannot be deleted content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Server error occurred content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/close: post: tags: - Cases summary: Close a case description: 'Closes a collection case with a specified close code. **Use Case:** Use this endpoint to formally close a case when collection is complete or cannot continue. The close code determines the reason and impacts reporting. **Close Code Validation:** - **Paid**: Requires at least one payment AND total payments >= outstanding amount - **PartiallyPaid**: Requires at least one payment AND total payments < outstanding amount - **All other codes**: No payment requirements **Valid Close Codes:** - **Paid** - Full payment received from debtor - **PartiallyPaid** - Some payment received but not full amount - **DebtorInsolventBankrupt** - Debtor declared bankruptcy or insolvent - **DebtorUntraceable** - Unable to locate or contact debtor - **DisputedLegalActionDeclinedByClient** - Debt disputed, creditor declined legal action - **WithdrawnByClient** - Creditor requested case withdrawal - **PreLegalExhaustedNoPayment** - All pre-legal attempts exhausted without payment - **StatuteOfLimitationsExpired** - Legal time limit to collect has passed - **SettlementRejectedByClient** - Proposed settlement rejected by creditor - **UnresponsiveClient** - Creditor not responding to collection partner - **Other** - Other reason (please provide comment)' parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.CloseCaseRequest' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.CloseCaseRequest' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.CloseCaseRequest' application/*+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.CloseCaseRequest' responses: '200': description: Case closed successfully content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CloseCaseResponse' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CloseCaseResponse' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CloseCaseResponse' '400': description: Invalid request (validation errors) content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to you content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Server error occurred content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/start: post: tags: - Cases summary: Activate a case from PendingVerification description: 'Transitions a case from `PendingVerification` → `Active`, officially accepting it for debt collection. **Prerequisites:** - The case must be in `PendingVerification` status (returns 400 otherwise) - The case must not require custom terms (non-standard agreement). Cases outside the standard pre-legal scope — where the claim type is not an unpaid invoice or loan repayment, or where a dispute exists — require negotiation in the partner portal and cannot be activated via this API (returns 400 with a descriptive error). - The `userId` must be a valid user ID from `GET /users` belonging to your team (returns 400 if not found) - The `assignedUserId`, if provided, must also be a valid user ID from `GET /users` belonging to your team (returns 400 if not found) **What happens on activation:** 1. Case lifecycle transitions to Active 2. A welcome message is sent to the creditor via email notification, attributed to the user identified by `userId` 3. The welcome message is posted as a chat message in the case thread, attributed to the user identified by `userId` 4. Any pending verification tasks are automatically resolved **Fee fields:** The `interestFees`, `reminderFees`, and `collectionFees` fields update the corresponding fee amounts on the case, in the case currency. Default to 0.00 if not provided. **userId vs assignedUserId:** `userId` is required and identifies who is sending the welcome message (the actor). `assignedUserId` is optional and identifies who the case is assigned to for ongoing handling. They can be the same person or different team members. Use `GET /users` to retrieve valid user IDs.' parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.StartCaseRequest' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.StartCaseRequest' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.StartCaseRequest' application/*+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.StartCaseRequest' responses: '200': description: Case activated successfully content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.StartCaseResponse' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.StartCaseResponse' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.StartCaseResponse' '400': description: Validation error — case not in PendingVerification, requires custom terms, invalid assignedUserId, or invalid request body content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to this collection partner content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Internal server error content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/fees: put: tags: - Cases summary: Update case fees and/or principal description: 'Updates the interest, reminder, and collection fees — and optionally the principal (GrossAmount) — on a case. All provided values replace the current values. The `grossAmount` field is optional and backward-compatible: omitting it leaves the principal unchanged. Fees typically change over time as collection activity progresses — for example due to legal costs, attorney fees, investigation charges, or other events. **When `grossAmount` is supplied:** - Both increases and decreases are allowed (no restriction on direction) - The pre-legal success fee (commission) is silently recalculated and returned in the response - The outstanding remainder is recalculated to reflect the new principal - A timeline audit event is written recording the change (From/To principal and fees) **Prerequisites:** - The case must be assigned to this collection partner - The case must **not** be Closed or Merged (returns 400 otherwise) - All amounts must be ≥ 0 (negative values rejected)' parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.UpdateCaseFeesRequest' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.UpdateCaseFeesRequest' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.UpdateCaseFeesRequest' application/*+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.UpdateCaseFeesRequest' responses: '200': description: Fees updated successfully content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.UpdateCaseFeesResponse' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.UpdateCaseFeesResponse' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.UpdateCaseFeesResponse' '400': description: Validation error — invalid values, case is Closed or Merged, or confirmPriceChange=true was sent on a deliberately-set rate (accepted quote / manual override), which is preserve-only on this API — resubmit with keepIntentionalRate=true instead. content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not assigned to this collection partner content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '409': description: 'Price-change confirmation required — the principal edit would move the success fee by >0.1%. For a standard rate, resubmit with confirmPriceChange=true to re-price. For a deliberately-set rate (accepted quote / manual override) the rate is preserve-only: resubmit with keepIntentionalRate=true to apply the edit and keep the special rate — partners cannot override it (sending confirmPriceChange=true on such a case is rejected with 400).' content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.PriceChangeConfirmationResponse' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.PriceChangeConfirmationResponse' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.PriceChangeConfirmationResponse' '500': description: Internal server error content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/exclusive-period: get: tags: - Cases summary: Get exclusive collection period chain description: Returns the full exclusive collection period chain for a case, including the initial period and any extensions triggered by debtor actions (promise to pay, payment agreement, or actual payment). parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Chain returned content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.ExclusivePeriodDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.ExclusivePeriodDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.ExclusivePeriodDto' '400': description: ID missing, empty, or ID is not a collection case content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found, not assigned to you, or no collection period exists content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/{id}/validation: get: tags: - Cases summary: Get full validation detail for a case description: 'Returns the full creditor-facing validation status for a case, including the resolution area and description for each outstanding item. **When to call:** Check `validation.needsInfo` on `GET /cases/{id}`. If `true`, call this endpoint to retrieve the item-level breakdown of what must be supplied. **Access Control:** Same as `GET /cases/{id}` — only accessible when you are the collection partner (or managing partner on test cases). **Safety:** Only creditor-facing resolution areas are returned. Internal areas (InternalReview, AdminReview) and sensitive fields (Rationale, Confidence) are never exposed.' parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Full validation status returned content: text/plain: schema: $ref: '#/components/schemas/Debitura.Domain.Services.CaseValidation.CaseValidationStatusDto' application/json: schema: $ref: '#/components/schemas/Debitura.Domain.Services.CaseValidation.CaseValidationStatusDto' text/json: schema: $ref: '#/components/schemas/Debitura.Domain.Services.CaseValidation.CaseValidationStatusDto' '400': description: ID missing, empty, or not a collection case content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found or not accessible content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://collectionpartner-api.debitura.com description: Production /cases/preview: post: tags: - Cases summary: Preview case eligibility and requirements description: "Preview what would happen if you submitted a case, without actually creating it.\n\n**What This Endpoint Returns:**\n- IsEligible - Whether the case can be submitted (partner available)\n- PartnerAssignment - Which collection partner would handle the case\n- RequiredActions - What contracts/documents need to be signed before submission\n - Standard Debt Collection Agreement (SDCA)\n - Power of Attorney (PoA) for the assigned partner\n- PricingPreview - Estimated success fee with age-based surcharges\n- Jurisdiction - Geographic details\n\n**Use This To:**\n1. Check if a jurisdiction is supported before submitting\n2. Determine which documents need signing before case creation\n3. Get signing URLs to guide users through required actions\n4. Estimate pricing including age surcharges\n\n**Required Fields:**\n- AmountToRecover - Total principal amount\n- CurrencyCode - ISO 4217 currency code (e.g., 'DKK', 'EUR', 'USD')\n- Debtor.Type - 'Company' or 'Private'\n- Debtor.CountryAlpha2 - ISO 3166-1 alpha-2 country code\n- Debtor.StateAlpha2 - Required for US cases only (e.g., 'CA', 'NY')\n\n**Optional Fields (Multi-Invoice Age Pricing):**\n- AmountToRecoverOver12Months - Portion over 12 months overdue\n- AmountToRecoverOver24Months - Portion over 24 months overdue\n(Both must be provided together if used)\n- AmountToRecoverOver6Months - Portion over 6 months overdue (optional, improves pricing tier accuracy at the 180-day threshold; requires Over12/Over24)\n\n**Solution URLs Are Context-Aware:**\n- Bearer token (referral partner) → referral onboarding URLs\n- XApiKey (creditor) → standard creditor app URLs\n\n**Important Notes:**\n- This endpoint does NOT create a case - it only previews what would happen\n- The preview uses the same eligibility logic as POST /cases\n- If multiple partners match (system limitation), the first match is returned\n- All required actions must be completed before calling POST /cases\n\n**Example Workflow:**\n```\n1. POST /cases/preview → Check eligibility and get signing URLs\n2. User completes required actions (signs SDCA, signs PoA)\n3. POST /cases → Create the actual case\n```" requestBody: content: application/json-patch+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.PreviewCaseRequestApiViewModel' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.PreviewCaseRequestApiViewModel' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.PreviewCaseRequestApiViewModel' application/*+json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.PreviewCaseRequestApiViewModel' responses: '200': description: Preview completed content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.PreviewCaseResponseApiViewModel' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.PreviewCaseResponseApiViewModel' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.PreviewCaseResponseApiViewModel' '400': description: Invalid request (validation errors) content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Internal server error content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] - Bearer: [] servers: - url: https://customer-api.debitura.com description: Production /cases/by-creditor-reference/{creditorReference}: get: tags: - Cases summary: Fetch case by creditor reference description: Returns case details for the provided creditor reference. The creditor reference is your own unique identifier for the case, as provided when the case was created. parameters: - name: creditorReference in: path required: true schema: type: string responses: '200': description: Case found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' '400': description: Creditor reference missing or empty content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: No case found with this creditor reference content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] - Bearer: [] servers: - url: https://customer-api.debitura.com description: Production /cases/{id}/contract-status: get: tags: - Cases summary: Get contract signing status for a case description: 'Returns the signing status of the SDCA (Standard Debt Collection Agreement), PoA (Power of Attorney), and Jurisdiction Pricing Appendix for a case. **Use case:** When a case is stuck in PendingContractSigning, use this endpoint to determine which contract is missing and get the signing URL. **Response:** - sdca: Always present — shows whether the debt collection agreement is signed - poa: Present only if a collection partner is assigned — shows whether the power of attorney is signed for that partner - NeedsPoaSigning: true when the case is blocked because a required PoA or Jurisdiction Pricing Appendix has not been signed - Each contract item includes a solutionUrl if signing or re-signing is needed - The solutionUrl is context-aware: referral partner bearer tokens get referral onboarding URLs, API keys get creditor app URLs' parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Contract status returned content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CaseContractStatusApiDTO' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CaseContractStatusApiDTO' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CaseContractStatusApiDTO' '400': description: ID missing, empty, or not a collection case content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found, deleted, or does not belong to your account content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] - Bearer: [] servers: - url: https://customer-api.debitura.com description: Production /cases/{id}/quote-requests: get: tags: - Cases summary: List quote requests for a case description: Returns all quote requests for the specified case. Multiple quote requests can exist per case. parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Quote requests returned content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadListDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadListDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadListDto' '400': description: Invalid case ID content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] - Bearer: [] servers: - url: https://customer-api.debitura.com description: Production /cases/{id}/quote-requests/{quoteRequestId}: get: tags: - Cases summary: Get quote request details description: Returns detailed information for a specific quote request including computed properties. parameters: - name: id in: path required: true schema: type: string format: uuid - name: quoteRequestId in: path required: true schema: type: string format: uuid responses: '200': description: Quote request found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadDetailDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadDetailDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadDetailDto' '400': description: Invalid ID content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Quote request or case not found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] - Bearer: [] servers: - url: https://customer-api.debitura.com description: Production /cases/{id}/quote-requests/{quoteRequestId}/quotes: get: tags: - Cases summary: List quotes for a quote request description: Returns all partner quotes received for the specified quote request. parameters: - name: id in: path required: true schema: type: string format: uuid - name: quoteRequestId in: path required: true schema: type: string format: uuid responses: '200': description: Quotes returned content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuoteListDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuoteListDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuoteListDto' '400': description: Invalid ID content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Quote request or case not found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] - Bearer: [] servers: - url: https://customer-api.debitura.com description: Production /cases/{id}/quote-requests/{quoteRequestId}/quotes/{quoteId}: get: tags: - Cases summary: Get quote details description: Returns complete details for a specific quote including full pricing breakdown. parameters: - name: id in: path required: true schema: type: string format: uuid - name: quoteRequestId in: path required: true schema: type: string format: uuid - name: quoteId in: path required: true schema: type: string format: uuid responses: '200': description: Quote found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuoteDetailDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuoteDetailDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuoteDetailDto' '400': description: Invalid ID content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Quote, quote request, or case not found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Internal server error content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] - Bearer: [] servers: - url: https://customer-api.debitura.com description: Production /cases/{id}/tasks: get: tags: - Cases summary: List tasks for a case description: 'Returns every open task (action-item) attached to this specific case. Same data as GET /tasks, scoped to one case — use this when you''re already working a specific case and want just its outstanding tasks. **Note:** account-level tasks that aren''t tied to a single case (e.g. SignContract, AssignBankAccount — these block your whole account, not one case) never appear here; call GET /tasks to see those. **Filtering:** - status (default: Open) — Open or Solved - type (repeatable, e.g. ?type=ReplyToChat) — restrict to specific task types No pagination — a single case has few tasks.' parameters: - name: id in: path required: true schema: type: string format: uuid - name: status in: query schema: type: string default: Open - name: type in: query schema: type: array items: type: string responses: '200': description: Tasks returned content: text/plain: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskDto' application/json: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskDto' text/json: schema: type: array items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskDto' '400': description: ID missing, or invalid status/type filter content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] - Bearer: [] servers: - url: https://customer-api.debitura.com description: Production /cases/{caseId}/files: post: tags: - Cases summary: Upload a file to a case. Optionally posts a system chat message to notify the collection partner. description: 'Uploads a file and associates it with a case owned by one of the referral partner''s clients. File requirements: - Maximum file size: 25 MB - Allowed types: PDF, Excel (.xls, .xlsx), CSV, Text (.txt), Images (.jpg, .jpeg, .png, .gif) When sendChatNotification is true (default), a system message is posted on the case chat to notify the collection partner that a new file was uploaded.' parameters: - name: caseId in: path required: true schema: type: string format: uuid - name: sendChatNotification in: query schema: type: boolean default: true - name: Idempotency-Key in: header description: 'Optional idempotency key (max 255 characters) for safely retrying this request. If a previous request used the same key with an identical body, the original terminal response is replayed verbatim. Reusing the key with a different body returns 422 with `Type: "IdempotencyConflict"`. Field-level 400 validation errors are not stored, so you may fix the request and retry with the same key.' schema: maxLength: 255 type: string requestBody: content: multipart/form-data: schema: type: object properties: file: type: string format: binary encoding: file: style: form responses: '200': description: File uploaded successfully '400': description: Validation error content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '404': description: Case not found content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '413': description: File too large content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '415': description: Unsupported file type content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' '500': description: Internal server error content: text/plain: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' application/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' text/json: schema: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto' security: - ApiKey: [] servers: - url: https://referral-api.debitura.com description: Production components: schemas: Debitura.Web.ExternalApi.Contracts.V1.Users.UserRelationDto: required: - email type: object properties: id: type: integer format: int32 dateCreated: type: - string - 'null' format: date-time dateUpdated: type: - string - 'null' format: date-time firstName: type: - string - 'null' lastName: type: - string - 'null' email: type: - string - 'null' additionalProperties: false Debitura.Web.ExternalApi.Contracts.V1.Cases.ExclusivePeriodDto: type: object properties: engagementStartDate: type: string description: Start date of the initial exclusivity engagement. format: date-time currentEndDate: type: string description: Current end date of the exclusive period (after any extensions). format: date-time daysRemaining: type: integer description: 'Days remaining until the period ends. Negative when the period has naturally expired. Zero when the engagement was terminated early (partner change or withdrawal), regardless of the original end date.' format: int32 status: type: - string - 'null' description: 'Current status of the exclusive period: Active, Expired, or Terminated. Active — partner has exclusive rights. Expired — period ended naturally (time elapsed or case resolved). Terminated — period was ended early (partner change, withdrawal, etc.).' extensions: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.ExclusivePeriodExtensionDto' description: 'Each extension event that occurred within the current engagement, in chronological order. Empty for cases that have never had an extension triggered.' additionalProperties: false description: 'Full exclusive collection period chain for a case. Returned by GET /cases/{id}/exclusive-period.' Debitura.Web.ExternalApi.Contracts.V1.Cases.TimelineActorDto: required: - type type: object properties: type: type: - string - 'null' description: 'The type of actor. One of: "System", "Creditor user", "Partner user".' name: type: - string - 'null' description: Display name of the actor, if available. additionalProperties: false description: Represents the actor (person or system) that performed a timeline action. Debitura.Web.ExternalApi.Contracts.V1.Cases.PriceChangeConfirmationResponse: type: object properties: caseId: type: string description: The case ID. format: uuid confirmationRequired: type: boolean description: 'Always `true` on this response. Lets clients branch on the response shape without inspecting the HTTP status code.' isIntentionalRate: type: boolean description: 'True when the rate is a deliberately-set rate (accepted quote or manual override) rather than a plain bracket crossing. When true the client resolves the 409 with `KeepIntentionalRate = true` only (the rate is preserve-only; `ConfirmPriceChange = true` is rejected with 400). When false only `ConfirmPriceChange = true` applies (re-price). Lets the consumer branch without parsing Debitura.Web.ExternalApi.Contracts.V1.Cases.PriceChangeConfirmationResponse.Message.' currentSuccessFee: type: - number - 'null' description: The success fee percentage currently on the case (before the edit). format: double proposedSuccessFee: type: number description: The success fee percentage that would apply if the edit is confirmed. format: double warning: type: - string - 'null' description: 'Optional warning surfaced alongside the confirmation — e.g. when the principal is lowered on a case that already has payments (partner-rules.md suggests registering a payment instead). Null when there is no warning.' message: type: - string - 'null' description: Human-readable explanation of why confirmation is required. additionalProperties: false description: 'Returned with HTTP 409 when a principal edit would move the case success fee by more than the allowed threshold (>0.1 percentage points), or would affect a deliberately-set rate. The edit is NOT applied; the partner reviews the proposed rate change and resubmits the same request to resolve it. For a plain bracket crossing (Debitura.Web.ExternalApi.Contracts.V1.Cases.PriceChangeConfirmationResponse.IsIntentionalRate false) resubmit with `ConfirmPriceChange = true` to re-price. For a deliberately-set rate (Debitura.Web.ExternalApi.Contracts.V1.Cases.PriceChangeConfirmationResponse.IsIntentionalRate true) the rate is preserve-only: resubmit with `KeepIntentionalRate = true` to apply the edit and keep it — partners cannot override it, and sending `ConfirmPriceChange = true` on such a case is rejected with HTTP 400 (DEB-4765 (b)). See partner-rules.md (price-change confirmation) and DEB-4759.' Debitura.Domain.Model.CommunicationCenter.Chats.ChatRole: enum: - 0 - 1 - 2 type: integer format: int32 Debitura.Web.ExternalApi.Contracts.V1.Files.CaseFileDto: type: object properties: id: type: string format: uuid dateCreated: type: string format: date-time dateUpdated: type: string format: date-time caseId: type: string format: uuid entityType: type: - string - 'null' entityId: type: string format: uuid fileName: type: - string - 'null' url: type: - string - 'null' description: type: - string - 'null' documentType: type: - string - 'null' additionalProperties: false Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.CloseCaseRequest: required: - closeCode type: object properties: closeCode: minLength: 1 type: string description: "Close code/reason for closing the case.\n \n**Valid close codes:**\n- **Paid**: Full payment received from debtor\n- **PartiallyPaid**: Some payment received but not full amount\n- **DebtorInsolventBankrupt**: Debtor declared bankruptcy or insolvent\n- **DebtorUntraceable**: Unable to locate or contact debtor\n- **DisputedLegalActionDeclinedByClient**: Debt disputed, creditor declined legal action\n- **WithdrawnByClient**: Creditor requested case withdrawal\n- **PreLegalExhaustedNoPayment**: All pre-legal attempts exhausted without payment\n- **StatuteOfLimitationsExpired**: Legal time limit to collect has passed\n- **SettlementRejectedByClient**: Proposed settlement rejected by creditor\n- **UnresponsiveClient**: Creditor not responding to collection partner\n- **UneconomicalToPursue**: Recovery cost exceeds claim value\n- **Other**: Other reason (please provide comment)" example: Paid comment: maxLength: 2000 minLength: 0 type: - string - 'null' description: Optional comment explaining the closure (recommended for 'Other' close code) example: Case closed after full payment received via bank transfer on 2025-11-19 additionalProperties: false description: Request to close a case Debitura.Web.ExternalApi.Contracts.V1.Cases.ClosedByDto: required: - userName type: object properties: userId: type: integer format: int32 userName: type: - string - 'null' additionalProperties: false Debitura.Web.ExternalApi.Contracts.V1.Cases.SigningHandoffDto: type: object properties: combinedSigningUrl: type: - string - 'null' description: '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.' additionalProperties: false description: "Partner-facing handoff metadata for a creditor's pending signing chain.\nReturned on POST /cases responses (422 with pending-signing errors,\nor 200 with AllowPendingContracts=true when signings remain).\n \nDesigned as an envelope so future fields (expiration, suggested email\ncopy, etc.) can be added without polluting the parent DTO." Debitura.Web.ExternalApi.Contracts.V1.Cases.CollectionPartnerDto: type: object properties: name: type: - string - 'null' officeEmail: type: - string - 'null' officePhone: type: - string - 'null' publicSite: type: - string - 'null' surveyCadenceMode: $ref: '#/components/schemas/Debitura.Domain.Model.CollectionPartnerLogics.CollectionPartners.SurveyCadenceMode' additionalProperties: false description: V1 Collection Partner DTO for external partner APIs Debitura.Web.ExternalApi.Contracts.V1.Payments.CreatePaymentResponse: required: - caseReference - commissionPaymentStatus - paymentRecipient type: object properties: paymentId: type: string format: uuid caseReference: type: - string - 'null' date: type: string format: date-time paymentAmount: type: number format: double payoutCreditor: type: number format: double payoutCollectionPartner: type: number format: double paymentRecipient: type: - string - 'null' commissionPaymentStatus: type: - string - 'null' closeCase: type: boolean caseClosed: type: boolean closeCode: type: - string - 'null' remainingAmount: type: number format: double warnings: type: - array - 'null' items: type: string description: 'Non-blocking warnings about this payment. Always present (empty when there is nothing to flag). Currently populated only when an explicit PayoutCreditor/PayoutCollectionPartner override was supplied and (a) it allocates zero to the creditor, or (b) the case already had no outstanding balance before this payment — both are signs of a misconfigured or duplicate payment. The payment is still recorded; these are advisory only, not errors. Review and resolve out of band if unexpected (e.g. via the case''s Payments view in the Partner Portal, or by contacting Debitura support).' additionalProperties: false description: Response after creating a payment Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentRelatedInvoiceDto: required: - reference - status type: object properties: status: type: - string - 'null' reference: type: - string - 'null' invoiceId: type: string format: uuid additionalProperties: false Debitura.Web.ExternalApi.Contracts.V1.Cases.AssignedUserDto: type: object properties: email: type: - string - 'null' description: The assigned user's email address. name: type: - string - 'null' description: The assigned user's full name. additionalProperties: false description: Represents the creditor team member assigned to a case. Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.UpdateCaseFeesRequest: type: object properties: grossAmount: maximum: 1.7976931348623157e+308 minimum: 0 type: - number - 'null' description: 'Principal claim amount (gross amount) in the case currency. Optional — omit to leave the principal unchanged (fees-only update, backward-compatible). Both increases and decreases are allowed; must be ≥ 0.' format: double example: 1000.0 interestFees: maximum: 1.7976931348623157e+308 minimum: 0 type: number description: Interest fees on this case, in the case currency. format: double example: 25.5 reminderFees: maximum: 1.7976931348623157e+308 minimum: 0 type: number description: Reminder fees on this case, in the case currency. format: double example: 10.0 collectionFees: maximum: 1.7976931348623157e+308 minimum: 0 type: number description: Collection fees on this case, in the case currency. format: double example: 50.0 confirmPriceChange: type: boolean description: "The \"Change to standard\" resolution. When a principal edit on a standard-rate case would\nmove the success fee by more than 0.1 percentage points (a bracket crossing), the first request\nreturns HTTP 409 with the proposed old/new rate instead of applying the change. Resubmit the same\nrequest with this set to `true` to confirm and apply the re-price. Leaving it `false`\n(the default) on an unaffected edit has no effect. See partner-rules.md (price change confirmation\nrequired if the success fee changes by >0.1%).\n \nIMPORTANT (DEB-4765 (b)): on a case with a deliberately-set rate (an accepted quote or a manual\noverride), partners can never override a special agreement via this API. Sending this flag on such a\ncase is REJECTED with HTTP 400 — resubmit with Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.UpdateCaseFeesRequest.KeepIntentionalRate=`true` to apply\nthe edit and keep the special rate. Only the admin (internal) surface can change a special rate." example: false keepIntentionalRate: type: boolean description: 'The "Keep special rate" resolution. When the case carries a deliberately-set rate (an accepted quote or a manual override) that the edit would otherwise prompt about, resubmit with this set to `true` to apply the edit while preserving the existing rate. On this external Partner API a special rate is preserve-only: this is the ONLY way to apply an edit to such a case — sending Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.UpdateCaseFeesRequest.ConfirmPriceChange instead is rejected with HTTP 400. Ignored for a plain bracket crossing on a non-intentional rate (use Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.UpdateCaseFeesRequest.ConfirmPriceChange there).' example: false additionalProperties: false description: Request to update the fee amounts (and optionally the principal) on an active case. Debitura.Web.ExternalApi.Contracts.V1.Notes.CreateNoteRequest: required: - description type: object properties: description: maxLength: 10000 minLength: 0 type: string description: Note content example: Called debtor on 2025-11-19. They acknowledged the debt and promised to pay within 7 days. Will follow up on 2025-11-26. eventDate: type: - string - 'null' description: 'The date when the event actually occurred. Must not be in the future. When provided, the note will appear at this date in the timeline instead of the upload time. This is useful for importing historical events (e.g. a phone call that happened last week). Omit or set to null to use the current time (default behaviour).' format: date-time example: '2025-11-14T09:30:00Z' additionalProperties: false description: Request to create a new note on a case Debitura.Web.ExternalApi.Contracts.V1.Notes.NoteDto: required: - caseReference - title - visibility type: object properties: id: type: string format: uuid caseReference: type: - string - 'null' title: type: - string - 'null' description: type: - string - 'null' visibility: type: - string - 'null' createdAt: type: string format: date-time eventDate: type: - string - 'null' description: 'The event date provided at creation time. Null if no EventDate was supplied, meaning the note was recorded in real-time (CreatedAt reflects the actual event time).' format: date-time createdBy: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Notes.NoteCreatedByDto' additionalProperties: false description: Note details response Debitura.Web.ExternalApi.Contracts.V1.Cases.CreditorDivisionDto: type: object properties: id: type: string description: Unique identifier for the division format: uuid name: type: - string - 'null' description: Name of the division additionalProperties: false description: 'Creditor division information for external partner APIs. Represents a specific division or department within a creditor organization.' Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto: type: object properties: error: type: - string - 'null' description: Short human-readable error label (legacy field — preserved for backward compatibility). message: type: - string - 'null' description: Human-readable error description (legacy field — preserved for backward compatibility). businessErrors: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorApiDTO' description: Canonical structured error array. Consumers should migrate to reading this field. additionalProperties: false description: "Generic structured error response for API endpoints.\n \nDual-write design: existing fields (Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto.Error / Debitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto.Message etc.)\nare preserved for backward compatibility alongside the canonical\nDebitura.Web.ExternalApi.Contracts.V1.Errors.ApiErrorResponseDto.BusinessErrors array, allowing consumers to migrate at their own pace." Debitura.Web.ExternalApi.Contracts.V1.Cases.BankAccountDto: type: object properties: id: type: integer description: Bank account identifier format: int32 label: type: - string - 'null' description: User-friendly label (e.g., "Main EUR Account") scheme: type: - string - 'null' description: 'Account scheme: IBAN, SWIFT, or LOCAL' currencyCode: type: - string - 'null' description: Currency code (ISO 4217) bankCountryCode: type: - string - 'null' description: Bank country code (ISO Alpha-2) accountHolderName: type: - string - 'null' description: Account holder name (beneficiary) iban: type: - string - 'null' description: IBAN (for IBAN scheme accounts) bic: type: - string - 'null' description: BIC/SWIFT code (for IBAN and SWIFT scheme accounts) accountNumber: type: - string - 'null' description: Account number (for SWIFT and LOCAL scheme accounts) localIdentifier: type: - string - 'null' description: Local identifier (for LOCAL scheme accounts, e.g., sort code + account number) localIdentifierType: type: - string - 'null' description: Type of local identifier (e.g., "Sort Code", "Routing Number") bankName: type: - string - 'null' description: Bank name (optional) bankAddress: type: - string - 'null' description: Bank address (optional) bankCity: type: - string - 'null' description: Bank city (optional) bankZipCode: type: - string - 'null' description: Bank zip/postal code (optional) bankState: type: - string - 'null' description: Bank state/region (optional) additionalProperties: false description: '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)' Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceAllocationOutstandingDto: type: object properties: principal: type: number format: double interest: type: number format: double reminderFees: type: number format: double collectionFees: type: number format: double additionalProperties: false description: '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.' Debitura.Web.ExternalApi.Contracts.V1.Payments.CreatePaymentRequest: required: - date - paymentAmount - paymentRecipient type: object properties: date: type: string description: Payment date (when payment was received). Provide date only without time component. format: date-time example: '2025-11-19' paymentAmount: maximum: 1.7976931348623157e+308 minimum: 0.01 type: number description: "Total payment amount received.\n \nWhen both PayoutCreditor and PayoutCollectionPartner are supplied they must sum to this amount.\nWhen both are omitted, the split is computed server-side from the case's pricing terms." format: double example: 5000.0 payoutCreditor: maximum: 1.7976931348623157e+308 minimum: 0 type: - number - 'null' description: "Amount to be paid out to creditor. **Optional — omit by default.**\n \nNormal usage is to leave this (and PayoutCollectionPartner) unset: the split is then computed\nserver-side from the case's pricing terms (success fee), which is correct for almost every\nintegration. Setting this is an **advanced, opt-in override** for legitimate edge cases (e.g. a\nnegotiated split where the collection partner already holds funds) — most callers should never\nneed it. When supplied, PayoutCollectionPartner must also be supplied and the two must sum to\nPaymentAmount. A zero value here (entire payment routed to the partner), or an explicit split\nsupplied on a case that already has no outstanding balance, is accepted but surfaced as a\nwarning in the response (`CreatePaymentResponse.Warnings`) rather than rejected — review\nthese warnings, as they are signs of a misconfigured or duplicate payment." format: double example: 4000.0 payoutCollectionPartner: maximum: 1.7976931348623157e+308 minimum: 0 type: - number - 'null' description: "Amount to be kept by collection partner (commission). **Optional — omit by default.**\n \nNormal usage is to leave this (and PayoutCreditor) unset: the split is then computed\nserver-side from the case's pricing terms (success fee), which is correct for almost every\nintegration. Setting this is an **advanced, opt-in override** for legitimate edge cases (e.g. a\nnegotiated split where the collection partner already holds funds) — most callers should never\nneed it. When supplied, PayoutCreditor must also be supplied and the two must sum to\nPaymentAmount. See PayoutCreditor (above) for the soft-guard warnings this can trigger." format: double example: 1000.0 paymentRecipient: minLength: 1 type: string description: "Who received the payment.\n \n**Valid values:**\n- **Creditor**: Payment was received by the creditor (client). When used, you must also specify CommissionPaymentStatus.\n- **Platform**: Payment was received by Debitura platform. Commission is automatically marked as paid.\n- **CollectionPartner**: Payment was received by the collection partner. Commission is automatically marked as paid." example: Creditor commissionPaymentStatus: type: - string - 'null' description: "Commission payment status. **Required only if PaymentRecipient is Creditor.**\n \nWhen PaymentRecipient is CollectionPartner or Platform, this field is ignored and commission is automatically marked as Paid.\n \n**Valid values:**\n- **Paid**: Commission has been paid to collection partner\n- **Unpaid**: Commission has not yet been paid to collection partner" example: Paid closeCase: type: boolean createUnpaidCommissionFollowUp: type: boolean description: "Whether to run the unpaid-commission follow-up chain when this payment leaves the\ncollection partner's commission Unpaid (PaymentRecipient = Creditor, CommissionPaymentStatus = Unpaid).\nThe chain is: stamp the payout reminder date, email the partner, and create the\nUnpaidCommissionInvoiceClient follow-up task — which the reminder robot then drives.\n \nDefaults to `true`, preserving the standard API / UI behaviour. Set to `false`\nto opt this source out of the entire chain (no stamp, email, task, reminders or escalation);\nthe Payment and Payout are still created normally. Used by ingestion partners (e.g. ASTOP)\nthat already report commission settlement out of band and must not trigger the chase." example: true additionalProperties: false description: "Request to create a payment on a case.\n \n**Currency:** Payment must be in the same currency as the invoice. Currency is automatically determined from the case and cannot be specified in the request." example: date: '2026-07-21' paymentAmount: 5000 payoutCreditor: 4000 payoutCollectionPartner: 1000 paymentRecipient: Creditor commissionPaymentStatus: Paid closeCase: false Debitura.Domain.Services.CaseValidation.CaseValidationStatusDto: type: object properties: needsInfo: type: boolean creditorRespondedAt: type: - string - 'null' format: date-time items: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Domain.Services.CaseValidation.CaseValidationItemDto' additionalProperties: false Debitura.Web.ExternalApi.Contracts.V1.Chats.ChatDto: type: object properties: id: type: string format: uuid dateCreated: type: string format: date-time dateUpdated: type: - string - 'null' format: date-time role: $ref: '#/components/schemas/Debitura.Domain.Model.CommunicationCenter.Chats.ChatRole' roleLabel: type: - string - 'null' description: 'Human-readable label for the role (e.g., "Partner", "Creditor", "Managed by partner"). Companion to Debitura.Web.ExternalApi.Contracts.V1.Chats.ChatDto.Role — always present when Role is set.' message: type: - string - 'null' isSeen: type: boolean user: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Users.UserRelationDto' additionalProperties: false Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.StartCaseRequest: required: - welcomeMessage type: object properties: welcomeMessage: maxLength: 5000 minLength: 0 type: string description: 'Welcome message sent to the creditor upon case activation. This message is included in the email notification sent to the creditor and posted in the case chat.' example: We have received your case and will begin collection proceedings. You will receive regular updates on progress. userId: type: - string - 'null' description: 'ID of the team member who is sending this welcome message and activating the case. Used to attribute the chat message and email communication. Must be a valid user ID from GET /users. Returns 400 if the user is not found in your team. Deprecated: use UserEmail instead. At least one of UserId or UserEmail must be provided.' format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 deprecated: true userEmail: type: - string - 'null' description: 'Email address of the team member who is sending this welcome message and activating the case. Must correspond to an active member of your team. Preferred over UserId. At least one of UserEmail or UserId must be provided.' format: email example: john.doe@example.com collectionPartnerReference: maxLength: 128 minLength: 0 type: - string - 'null' description: 'Your internal reference number for this case (optional). Stored on the case and visible in the partner portal.' example: GET-2025-0042 assignedUserId: type: - string - 'null' description: 'ID of the team member to assign as the case handler (optional). Can be the same as UserId or a different team member. Must be a valid user ID from GET /users. Returns 400 if the user is not found in your team. Deprecated: use AssignedUserEmail instead.' format: uuid deprecated: true assignedUserEmail: type: - string - 'null' description: 'Email address of the team member to assign as the case handler (optional). Must correspond to an active member of your team. Preferred over AssignedUserId.' format: email example: jane.smith@example.com interestFees: maximum: 1.7976931348623157e+308 minimum: 0 type: number description: Interest fees on this case, in the case currency. Defaults to 0.00 if not provided. format: double example: 0.0 reminderFees: maximum: 1.7976931348623157e+308 minimum: 0 type: number description: Reminder fees on this case, in the case currency. Defaults to 0.00 if not provided. format: double example: 100.0 collectionFees: maximum: 1.7976931348623157e+308 minimum: 0 type: number description: Collection fees on this case, in the case currency. Defaults to 0.00 if not provided. format: double example: 0.0 additionalProperties: false description: Request to activate a case from PendingVerification to Active status. example: userId: 3fa85f64-5717-4562-b3fc-2c963f66afa6 welcomeMessage: We have received your case and will begin collection proceedings. You will receive regular updates on progress. collectionPartnerReference: GET-2025-0042 assignedUserId: null interestFees: 0 reminderFees: 100 collectionFees: 0 Debitura.Web.ExternalApi.Contracts.V1.Cases.CaseTimelineResponse: required: - items type: object properties: items: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.TimelineItemDto' description: Chronological list of events on the case. currentEngagementPhase: type: - string - 'null' description: 'The current engagement phase of the case, sourced from CaseEngagement.CurrentPhase. Possible values: "Pre-legal", "Legal", "Enforcement". Null when no active engagement exists (e.g. case not yet assigned to a partner).' additionalProperties: false description: 'Response envelope for GET /cases/{id}/timeline. Wraps the chronological event list with case-level context that cannot be expressed as a single timeline entry.' Debitura.Web.ExternalApi.Contracts.V1.Cases.CloseCaseResponse: required: - caseReference - closeCode - closeCodeDescription type: object properties: caseReference: type: - string - 'null' closeCode: type: - string - 'null' closeCodeDescription: type: - string - 'null' comment: type: - string - 'null' closedAt: type: string format: date-time closedBy: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.ClosedByDto' finalOutstandingAmount: type: number format: double totalPayments: type: number format: double totalRecovered: type: number format: double additionalProperties: false description: Response after closing a case Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorApiDTO: type: object properties: type: type: - string - 'null' description: The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable"). message: type: - string - 'null' description: A human-readable description of the error. solutionUrl: type: - string - 'null' description: "A URL where the user can resolve this specific error (e.g., sign a contract).\n \n\nPartners who want a single URL that walks the user through every pending\nsigning in one chain — instead of forwarding one URL per\n`BusinessErrorApiDTO` — should use\nDebitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorResponseApiDTO.SigningHandoff's `CombinedSigningUrl`.\nThe two are complementary: `SolutionUrl` is granular per-error;\n`CombinedSigningUrl` is the chain-walking alternative for signing-related errors." additionalProperties: false description: Represents a business error in the API response. Debitura.Web.ExternalApi.Contracts.V1.Payments.UpdatePaymentRequest: required: - date - paymentAmount - paymentRecipient type: object properties: date: type: string description: Payment date (when payment was received). Provide date only without time component. format: date-time example: '2025-11-19' paymentAmount: maximum: 1.7976931348623157e+308 minimum: 0.01 type: number description: "Total payment amount received.\n \nWhen both PayoutCreditor and PayoutCollectionPartner are supplied they must sum to this amount.\nWhen both are omitted, the split is computed server-side from the case's pricing terms." format: double example: 5000.0 payoutCreditor: maximum: 1.7976931348623157e+308 minimum: 0 type: - number - 'null' description: "Amount to be paid out to creditor. **Optional.**\n \nWhen omitted (along with PayoutCollectionPartner), the split is computed server-side from the\ncase's pricing terms (success fee). When supplied, PayoutCollectionPartner must also be supplied\nand the two must sum to PaymentAmount." format: double example: 4000.0 payoutCollectionPartner: maximum: 1.7976931348623157e+308 minimum: 0 type: - number - 'null' description: "Amount to be kept by collection partner (commission). **Optional.**\n \nWhen omitted (along with PayoutCreditor), the split is computed server-side from the\ncase's pricing terms (success fee). When supplied, PayoutCreditor must also be supplied\nand the two must sum to PaymentAmount." format: double example: 1000.0 paymentRecipient: minLength: 1 type: string description: "Who received the payment.\n \n**Valid values:**\n- **Creditor**: Payment was received by the creditor (client). When used, you must also specify CommissionPaymentStatus.\n- **CollectionPartner**: Payment was received by the collection partner. Commission is automatically marked as paid." example: Creditor commissionPaymentStatus: type: - string - 'null' description: "Commission payment status. **Required only if PaymentRecipient is Creditor.**\n \nWhen PaymentRecipient is CollectionPartner, this field is ignored and commission is automatically marked as Paid.\n \n**Valid values:** Paid, Unpaid." example: Paid reopenCaseIfNeeded: type: boolean description: "Consent to reopen the case if this edit lowers the payment so a previously closed (Paid)\ncase is left with a positive outstanding balance.\n \nWhen the edit would reopen the case and this flag is `false` (default), the request is\nrejected with HTTP 409 Conflict. Resend with `true` to confirm the reopen — the case is\nreopened to Active and a `case.updated` webhook fires." example: false additionalProperties: false description: "Request to edit an existing payment on a case. Mirrors the payout-split semantics of\nDebitura.Web.ExternalApi.Contracts.V1.Payments.CreatePaymentRequest.\n \n**Currency:** A payment's currency cannot be changed — it is fixed to the case currency.\n \n**Invoiced payments are frozen:** a payment whose payout has already been invoiced\n(Stripe/QBO) cannot be edited and returns HTTP 422." Debitura.Web.ExternalApi.Contracts.V1.Cases.DebtorDto: required: - name - type type: object properties: type: minLength: 1 type: string description: 'Debtor type. Valid values: "Company" or "Person"' example: Company name: minLength: 1 type: string description: Debtor name (company name or person's full name) example: Pacific Trading LLC contactPerson: type: - string - 'null' description: Contact person at the company (required for companies, not used for persons) example: John Smith companyRegistrationNumber: type: - string - 'null' description: Company registration number (VAT number, CVR, org number, etc.) example: 47-1234567 address: type: - string - 'null' description: Street address example: 123 Market Street, Suite 400 zipCode: type: - string - 'null' description: Postal/ZIP code example: '94105' city: type: - string - 'null' description: City name example: San Francisco state: type: - string - 'null' description: State/region/province name example: California stateAlpha2: type: - string - 'null' description: 'US state: two-letter code (e.g., "CA"), ISO 3166-2 format (e.g., "US-CA"), or full name (e.g., "California")' example: CA countryAlpha2: type: - string - 'null' description: Country code (ISO 3166-1 alpha-2 format) example: US country: type: - string - 'null' description: Country name example: United States email: type: - string - 'null' description: Email address for debtor contact example: accounts@pacifictrading.com phone: type: - string - 'null' description: Phone number (include country code) example: +1 415 555 0123 additionalProperties: false description: 'V1 Debtor DTO for external partner APIs. The debtor is the party that owes the debt.' Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto: type: object properties: id: type: string format: uuid dateCreated: type: string format: date-time dateUpdated: type: - string - 'null' format: date-time reference: type: - string - 'null' creditorReference: type: - string - 'null' creditorComments: type: - string - 'null' claimDescription: type: - string - 'null' grossAmount: type: number format: double remainder: type: number format: double interestFees: type: number format: double reminderFees: type: number format: double collectionFees: type: number format: double totalAddedFees: type: number format: double currency: type: - string - 'null' isTestCase: type: boolean lifecycle: type: - string - 'null' dueDate: type: string format: date-time date: type: string format: date-time dateFinished: type: - string - 'null' format: date-time dateCollectionStarted: type: - string - 'null' format: date-time closeCode: type: - string - 'null' currentEngagementPhase: type: - string - 'null' description: "The current phase of the case's engagement: \"Pre-legal\", \"Legal\", or \"Enforcement\".\nA different axis from Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto.Lifecycle/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto.CloseCode — an Active case can be\nin any of the three phases.\n \nNull means \"no active engagement\" (e.g. lead / quoting / pre-contract-signing / unassigned, or\na data-consistency gap) — this is a distinct third state, NOT a synonym for Pre-legal. Most\ncases legitimately read Pre-legal; phase only leaves Pre-legal on legal/enforcement quote flows.\n \nNot guaranteed to be monotonic: an admin correction can move phase backwards (e.g. Legal back\nto Pre-legal).\n \nPersists after case closure — reflects the case's last-known engagement phase, not the current\nLifecycle. Note: this is a different field from a lead quote's own offered phase (the phase a\npartner's quote proposes to work the case at, if this case ever went through a quote flow) —\nthis field is the case-level phase of its actual engagement, not a quote's terms." claimType: type: - string - 'null' description: 'The type of claim for this case (e.g. "Unpaid Invoice", "Loan Repayment", "Breach of Contract"). Null if not set.' creditorDivisionId: type: - string - 'null' format: uuid debtor: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.DebtorDto' collectionPartner: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CollectionPartnerDto' creditor: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CreditorDto' bankAccount: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BankAccountDto' blendedAgeUpliftPoints: type: - number - 'null' description: '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).' format: double preLegalSuccessFee: type: - number - 'null' description: '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.' format: double solutionUrl: type: - string - 'null' description: '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.' deprecated: true signingHandoff: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.SigningHandoffDto' exclusivePeriodEndDate: type: - string - 'null' description: '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.' format: date-time disputeStatus: type: - string - 'null' description: '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: $ref: '#/components/schemas/Debitura.Domain.Services.CaseValidation.CaseValidationLeanDto' assignedUser: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.AssignedUserDto' allocationOutstanding: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceAllocationOutstandingDto' additionalProperties: false description: V1 Invoice DTO for external partner APIs Debitura.Web.ExternalApi.Contracts.V1.Cases.TimelineItemDto: required: - description - title - type type: object properties: date: type: string format: date-time type: type: - string - 'null' title: type: - string - 'null' description: type: - string - 'null' actor: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.TimelineActorDto' additionalProperties: false Debitura.Web.ExternalApi.Contracts.V1.Cases.StartCaseResponse: type: object properties: caseId: type: string description: The case ID. format: uuid caseReference: type: - string - 'null' description: The Debitura case reference (e.g. 'Q8OAXF3W'). status: type: - string - 'null' description: The new lifecycle status of the case. activatedAt: type: string description: UTC timestamp when the case was activated. format: date-time collectionPartnerReference: type: - string - 'null' description: Your internal reference number for this case, if provided. additionalProperties: false description: Response returned when a case is successfully activated. Debitura.Web.ExternalApi.Contracts.V1.Cases.CreditorDto: type: object properties: id: type: string description: Unique identifier for the creditor format: uuid companyName: type: - string - 'null' description: Company name of the creditor companyRegistrationNumber: type: - string - 'null' description: Company registration number (CVR, VAT number, etc.) officeEmail: type: - string - 'null' description: Primary office email address officePhone: type: - string - 'null' description: Primary office phone number address: type: - string - 'null' description: Street address city: type: - string - 'null' description: City zipCode: type: - string - 'null' description: Postal/ZIP code state: type: - string - 'null' description: State or region (if applicable) country: type: - string - 'null' description: Country name division: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.CreditorDivisionDto' additionalProperties: false description: 'Creditor (client) information for external partner APIs. Represents the party that the debtor owes money to.' Debitura.Web.ExternalApi.Contracts.V1.Cases.UpdateCaseFeesResponse: type: object properties: caseId: type: string description: The case ID. format: uuid grossAmount: type: number description: Updated principal claim amount (gross amount), in the case currency. format: double interestFees: type: number description: Updated interest fees, in the case currency. format: double reminderFees: type: number description: Updated reminder fees, in the case currency. format: double collectionFees: type: number description: Updated collection fees, in the case currency. format: double totalAddedFees: type: number description: Sum of all fee types. format: double recalculatedSuccessFee: type: - number - 'null' description: 'Recalculated success fee after the principal update. Null if no collection partner is assigned or if the principal was not changed.' format: double remainder: type: number description: Outstanding remainder after the update (principal + fees − payments). format: double additionalProperties: false description: Response returned when case fees (and optionally the principal) are successfully updated. Debitura.Web.ExternalApi.Contracts.V1.Notes.NoteCreatedByDto: required: - userName type: object properties: userId: type: integer format: int32 userName: type: - string - 'null' additionalProperties: false Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentDto: required: - currency - invoice - method - recipient type: object properties: id: type: string format: uuid dateCreated: type: string format: date-time dateUpdated: type: - string - 'null' format: date-time date: type: string format: date-time grossAmount: type: number format: double recipient: type: - string - 'null' method: type: - string - 'null' currency: type: - string - 'null' invoice: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Payments.PaymentRelatedInvoiceDto' additionalProperties: false Debitura.Domain.Services.CaseValidation.CaseValidationItemDto: type: object properties: resolutionArea: type: - string - 'null' description: type: - string - 'null' additionalProperties: false Debitura.Domain.Model.Base.PageData: type: object properties: totalResults: type: integer format: int32 pageSize: type: integer format: int32 currentPage: type: integer format: int32 responseCount: type: integer format: int32 totalPages: type: integer format: int32 readOnly: true additionalProperties: false Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceListDto: required: - page type: object properties: page: $ref: '#/components/schemas/Debitura.Domain.Model.Base.PageData' cases: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.InvoiceDto' additionalProperties: false Debitura.Domain.Model.CollectionPartnerLogics.CollectionPartners.SurveyCadenceMode: enum: - 0 - 1 type: integer format: int32 Debitura.Domain.Services.CaseValidation.CaseValidationLeanDto: type: object properties: needsInfo: type: boolean additionalProperties: false Debitura.Web.ExternalApi.Contracts.V1.Chats.SendChatRequest: required: - message type: object properties: message: maxLength: 10000 minLength: 0 type: string description: The chat message content to send. example: Please provide the signed contract for this case. userId: type: - string - 'null' description: 'ID of the team member sending this message. Must be a valid user ID from GET /users belonging to your team. Deprecated: use UserEmail instead. At least one of UserId or UserEmail must be provided.' format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 deprecated: true userEmail: type: - string - 'null' description: 'Email address of the team member sending this message. Must correspond to an active member of your team (same account as the API key). Preferred over UserId. At least one of UserEmail or UserId must be provided.' format: email example: john.doe@example.com additionalProperties: false description: Request to send a chat message on a case. Debitura.Web.ExternalApi.Contracts.V1.Cases.ExclusivePeriodExtensionDto: type: object properties: type: type: - string - 'null' description: 'What triggered this extension: PromiseToPay, PaymentAgreement, Payment, or Manual.' eventDate: type: string description: When the extension period started (i.e. when the trigger event occurred). format: date-time newEndDate: type: string description: The new period end date after this extension was applied. format: date-time additionalProperties: false description: A single extension event in the exclusive period chain. Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.PreviewCaseRequestApiViewModel: required: - amountToRecover - currencyCode - debtor type: object properties: amountToRecover: type: number description: "The TOTAL amount to recover for this case.\nThis represents the full principal amount across all invoices (if multiple invoices are bundled).\n \nFor multi-invoice cases with different ages, you can optionally provide age breakdown fields\n(AmountToRecoverOver12Months and AmountToRecoverOver24Months) to enable blended age-based pricing.\n \nIf age breakdown fields are omitted, the preview will show base pricing without age surcharge calculation." format: double currencyCode: maxLength: 3 minLength: 3 type: string description: ISO 4217 currency code for the amount (e.g., "DKK", "EUR", "USD") debtor: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.PreviewDebtorDto' amountToRecoverOver6Months: type: - number - 'null' description: "OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING (PRICING ZONE 180-DAY THRESHOLD)\n \nThe portion of AmountToRecover that is more than 6 months (180 days) overdue.\nThis includes amounts that are 12+ and 24+ months overdue.\n \nThis field is optional and can only be provided alongside AmountToRecoverOver12Months\nand AmountToRecoverOver24Months. It enables precise pricing tier selection based on\nthe 180-day threshold. When omitted, the system falls back to deriving the threshold\nfrom AmountToRecoverOver12Months.\n \nValidation rules:\n- Must be ≤ AmountToRecover\n- Must be ≥ AmountToRecoverOver12Months" format: double amountToRecoverOver12Months: type: - number - 'null' description: "OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING\n \nThe portion of AmountToRecover that is more than 12 months overdue.\nThis includes amounts that are 24+ months overdue.\n \nIf provided, AmountToRecoverOver24Months must also be provided.\nBoth fields must be provided together or both omitted.\n \nUsed to calculate blended age uplift for multi-invoice cases:\n- Amount under 12 months = AmountToRecover - AmountToRecoverOver12Months\n- Amount 12-24 months = AmountToRecoverOver12Months - AmountToRecoverOver24Months\n- Amount over 24 months = AmountToRecoverOver24Months\n \nBlended uplift formula: ((A12-A24)×10 + A24×20) / AmountToRecover\nwhere A12 = AmountToRecoverOver12Months, A24 = AmountToRecoverOver24Months\n \nValidation rules:\n- Must be ≤ AmountToRecover\n- Must be ≥ AmountToRecoverOver24Months" format: double amountToRecoverOver24Months: type: - number - 'null' description: "OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING\n \nThe portion of AmountToRecover that is more than 24 months overdue.\n \nIf provided, AmountToRecoverOver12Months must also be provided.\nBoth fields must be provided together or both omitted.\n \nUsed to calculate blended age uplift for multi-invoice cases.\nSee AmountToRecoverOver12Months for full details on the calculation.\n \nValidation rules:\n- Must be ≤ AmountToRecoverOver12Months\n- Must be ≤ AmountToRecover" format: double dueDate: type: - string - 'null' description: 'Optional invoice due date. Mutually exclusive with age bucket fields. If provided, Debitura computes the age surcharge internally — no need to calculate age buckets. Cannot be a future date.' format: date-time returnUrl: maxLength: 2048 type: - string - 'null' description: "Optional: URL the creditor user should land on after completing any\npending signing chain (SDCA upgrade / PoA / JPA / KYC) on the\nDebitura Creditors app. Embedded, URL-encoded, into\n`PreviewCaseResponseApiViewModel.Result.SigningHandoff.CombinedSigningUrl`\n(when at least one signing-related required action is present) and into\n`BusinessErrorResponseApiDTO.SigningHandoff.CombinedSigningUrl` /\n`InvoiceDto.SigningHandoff.CombinedSigningUrl` on POST `/cases`.\n \nMust be an absolute http(s) URL. Values that fail validation\n(relative URLs, non-http schemes, header-injection characters) are\nsilently dropped — the combined URL is still emitted but without\nthe returnUrl query parameter, and the Creditors app falls back to\nits own safe in-app default landing.\n \nAdditive. Existing integrations\nthat omit this field see the same behaviour as before." additionalProperties: false description: "Request model for previewing case eligibility, partner assignment, and required actions\nbefore actually creating a collection case.\n \nThis endpoint allows you to check:\n- Whether a case would be eligible for collection (partner coverage available)\n- Which partner would be assigned\n- What documents need to be signed (SDCA, Power of Attorney)\n- Estimated pricing with age-based surcharges\n \nUse this to guide users through document signing before final case submission." example: amountToRecover: 50000 currencyCode: USD amountToRecoverOver12Months: 30000 amountToRecoverOver24Months: 15000 debtor: type: Company countryAlpha2: US stateAlpha2: CA Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuoteDto: required: - agreementType - currency - partnerName - status type: object properties: quoteId: type: string format: uuid quoteRequestId: type: string format: uuid partnerId: type: string format: uuid partnerName: type: - string - 'null' status: type: - string - 'null' agreementType: type: - string - 'null' hourlyRate: type: - number - 'null' format: double hourlyEstimated: type: - number - 'null' format: double flatFeeEstimate: type: - number - 'null' format: double successFee: type: - number - 'null' format: double hybridEstimate: type: - number - 'null' format: double proposedSolution: type: - string - 'null' partnerWhyUsSection: type: - string - 'null' phase: type: - string - 'null' description: The case phase this quote offers to work in (Pre-legal / Legal / Enforcement). Null = unspecified. offerNature: type: - string - 'null' description: 'Whether declining stops the case (Recommendation / Required). v1: display only. Null = unspecified.' currency: type: - string - 'null' dateCreated: type: string format: date-time additionalProperties: false description: V1 Lead Quote DTO for external customer APIs (summary view) Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuoteListDto: required: - quotes type: object properties: quotes: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuoteDto' additionalProperties: false description: V1 Lead Quote list response for external customer APIs Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuotePricingDto: type: object properties: hourlyRate: type: - number - 'null' format: double hourlyEstimated: type: - number - 'null' format: double flatFeeEstimate: type: - number - 'null' format: double successFeeFee: type: - number - 'null' format: double hybridEstimate: type: - number - 'null' format: double costProcessMisc: type: number format: double additionalProperties: false description: Nested pricing details for a lead quote Debitura.Web.ExternalApi.Contracts.V1.Cases.RequiredActionDto: type: object properties: type: type: - string - 'null' description: 'The type of action required. Common values: "MissingDebtCollectionContract", "MissingPowerOfAttorney"' message: type: - string - 'null' description: Human-readable description of what is required. solutionUrl: type: - string - 'null' description: "URL where the user can complete this specific action (e.g., contract signing page).\nThe URL is context-aware: referral partner tokens get referral onboarding URLs,\nregular API keys get standard creditor app URLs.\n \n\nPartners who want a single URL that walks the user through every pending\naction in one chain — instead of forwarding one URL per `RequiredActionDto` —\nshould use Debitura.Web.ExternalApi.Contracts.V1.Cases.PreviewResultDto.SigningHandoff's\n`CombinedSigningUrl`. The two are complementary: `SolutionUrl` is granular\nper-action; `CombinedSigningUrl` is the chain-walking alternative for\nsigning-related actions." isBlocking: type: boolean description: 'Whether this action must be completed before case submission. Currently all returned actions are blocking (true).' additionalProperties: false description: An action required before the case can be submitted (e.g., signing a contract). Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.CreateCollectionCaseRequestApiViewModel: required: - currencyCode type: object properties: currencyCode: type: - string - 'null' date: type: string format: date-time dueDate: type: - string - 'null' format: date-time comments: maxLength: 4000 type: - string - 'null' description: Optional comments about the case, e.g. payment history or communication context. claimDescription: maxLength: 4000 type: - string - 'null' description: Client provided description of the claim creditorReference: maxLength: 50 type: - string - 'null' debtor: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.DebtorDto' creditorDivisionId: type: - string - 'null' format: uuid amountToRecover: type: number description: "The TOTAL amount to recover for this case.\nThis represents the full principal amount across all invoices (if multiple invoices are bundled).\n \nFor multi-invoice cases with different ages, you can optionally provide age breakdown fields\n(AmountToRecoverOver12Months and AmountToRecoverOver24Months) to enable blended age-based pricing.\n \nIf age breakdown fields are omitted, age uplift will be calculated from the invoice due date (single-invoice pricing)." format: double amountToRecoverOver6Months: type: - number - 'null' description: "OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING (PRICING ZONE 180-DAY THRESHOLD)\n \nThe portion of AmountToRecover that is more than 6 months (180 days) overdue.\nThis includes amounts that are 12+ and 24+ months overdue.\n \nThis field is optional and can only be provided alongside AmountToRecoverOver12Months\nand AmountToRecoverOver24Months. It enables precise pricing tier selection based on\nthe 180-day threshold. When omitted, the system falls back to deriving the threshold\nfrom AmountToRecoverOver12Months.\n \nValidation rules:\n- Must be ≤ AmountToRecover\n- Must be ≥ AmountToRecoverOver12Months" format: double amountToRecoverOver12Months: type: - number - 'null' description: "OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING\n \nThe portion of AmountToRecover that is more than 12 months overdue.\nThis includes amounts that are 24+ months overdue.\n \nIf provided, AmountToRecoverOver24Months must also be provided.\nBoth fields must be provided together or both omitted.\n \nUsed to calculate blended age uplift for multi-invoice cases:\n- Amount under 12 months = AmountToRecover - AmountToRecoverOver12Months\n- Amount 12-24 months = AmountToRecoverOver12Months - AmountToRecoverOver24Months\n- Amount over 24 months = AmountToRecoverOver24Months\n \nBlended uplift formula: ((A12-A24)×10 + A24×20) / AmountToRecover\nwhere A12 = AmountToRecoverOver12Months, A24 = AmountToRecoverOver24Months\n \nValidation rules:\n- Must be ≤ AmountToRecover\n- Must be ≥ AmountToRecoverOver24Months" format: double amountToRecoverOver24Months: type: - number - 'null' description: "OPTIONAL - MULTI-INVOICE AGE BUCKET PRICING\n \nThe portion of AmountToRecover that is more than 24 months overdue.\n \nIf provided, AmountToRecoverOver12Months must also be provided.\nBoth fields must be provided together or both omitted.\n \nUsed to calculate blended age uplift for multi-invoice cases.\nSee AmountToRecoverOver12Months for full details on the calculation.\n \nValidation rules:\n- Must be ≤ AmountToRecoverOver12Months\n- Must be ≤ AmountToRecover" format: double skipDebituraVerification: type: boolean description: This skips the 'Pending verification' for Debitura and puts case straight to partner skipCreationEmails: type: boolean description: '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.' deprecated: true allowPendingContracts: type: boolean description: '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: type: boolean description: '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: maxLength: 100 type: - string - 'null' description: '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: type: - string - 'null' description: '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.' format: uuid assignedUserEmail: maxLength: 320 type: - string - 'null' description: '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.' format: email example: john.doe@example.com returnUrl: maxLength: 2048 type: - string - 'null' description: "Optional: URL the creditor user should land on after completing any\npending signing chain (SDCA upgrade / PoA / JPA / KYC) on the\nDebitura Creditors app. Embedded, URL-encoded, into\n`BusinessErrorResponseApiDTO.SigningHandoff.CombinedSigningUrl`\n(on 422 with pending signings) and\n`InvoiceDto.SigningHandoff.CombinedSigningUrl` (on 200 when\n`AllowPendingContracts=true` with signings remaining).\n \nMust be an absolute http(s) URL. Values that fail validation\n(relative URLs, non-http schemes, header-injection characters) are\nsilently dropped — the combined URL is still emitted but without\nthe returnUrl query parameter, and the Creditors app falls back to\nits own safe in-app default landing.\n \nAdditive. Existing integrations\nthat omit this field see the same behaviour as before." additionalProperties: false example: 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: true 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 Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadDetailDto: required: - leadFlowStatus - quoteType - status type: object properties: quoteRequestId: type: string format: uuid caseId: type: string format: uuid status: type: - string - 'null' leadFlowStatus: type: - string - 'null' quoteType: type: - string - 'null' maxQuotes: type: integer format: int32 currentQuotesCount: type: integer format: int32 isMaxBidCountReached: type: boolean outcome: type: - string - 'null' request: type: - string - 'null' existingFees: type: - string - 'null' dateCreated: type: string format: date-time dateQualified: type: - string - 'null' format: date-time leadsDoneOffered: type: - string - 'null' format: date-time dateReminderSent: type: - string - 'null' format: date-time dateReminderTwoSent: type: - string - 'null' format: date-time dateOutcomeSelected: type: - string - 'null' format: date-time additionalProperties: false description: V1 Lead detail DTO for external customer APIs (detailed view) Debitura.Web.ExternalApi.Contracts.V1.Cases.JurisdictionDto: type: object properties: id: type: integer description: Internal jurisdiction identifier. format: int32 name: type: - string - 'null' description: Display name of the jurisdiction (e.g., "Denmark", "United States - California"). countryAlpha2: type: - string - 'null' description: ISO 3166-1 alpha-2 country code. stateAlpha2: type: - string - 'null' description: ISO 3166-2 state/region code (only for countries with state-level routing like the US). additionalProperties: false description: Geographic jurisdiction information for the case. Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadListDto: required: - quoteRequests type: object properties: quoteRequests: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadDto' additionalProperties: false description: V1 Lead list response for external customer APIs Debitura.Web.ExternalApi.Contracts.V1.Cases.Requests.PreviewDebtorDto: required: - countryAlpha2 - type type: object properties: type: minLength: 1 type: string description: 'Debtor type. Valid values: "Company" or "Private" This affects partner selection as different partners may specialize in B2B vs B2C collection.' countryAlpha2: maxLength: 2 minLength: 2 type: string description: 'Country code (ISO 3166-1 alpha-2 format, e.g., "DK", "US", "PL") Used to determine jurisdiction and available collection partners.' stateAlpha2: maxLength: 2 minLength: 2 type: - string - 'null' description: 'US state code (e.g., "CA", "NY") REQUIRED for United States cases only, as US partner coverage is state-specific. Optional for other countries.' additionalProperties: false description: 'Simplified debtor information for case preview. Only includes the minimum fields required for partner routing and eligibility checking.' Debitura.Web.ExternalApi.Contracts.V1.Cases.PreviewResultDto: type: object properties: isEligible: type: boolean description: 'Whether the case is eligible for collection (i.e., a collection partner is available). If false, check IneligibilityReason for details.' ineligibilityReason: type: - string - 'null' description: 'Explanation of why the case is not eligible (only present when IsEligible = false). Common reasons: "We don''t have an exclusive pre-legal partner in the provided jurisdiction."' partnerAssignment: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.PartnerAssignmentDto' requiredActions: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.RequiredActionDto' description: 'List of actions required before the case can be submitted (e.g., sign contracts). Empty if no actions are required. Each action includes a solution URL to complete the requirement.' jurisdiction: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.JurisdictionDto' pricingPreview: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.PricingPreviewDto' requiresKycVerification: type: boolean description: 'Whether the resolved collection partner requires KYC verification before cases can be submitted. When true, the creditor must complete KYC verification before case creation will succeed.' hasKycOnFile: type: boolean description: 'Whether the creditor already has KYC verification on file with Debitura. When RequiresKycVerification is true and HasKycOnFile is false, a MissingKycVerification required action will be present in the RequiredActions list.' signingHandoff: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.SigningHandoffDto' additionalProperties: false description: Detailed preview result for a case submission. Debitura.Web.ExternalApi.Contracts.V1.Cases.PricingPreviewDto: type: object properties: baseSuccessFeePercentage: type: number description: 'Base success fee percentage before age surcharges. This is the standard rate for cases under 12 months overdue.' format: double ageSurchargePercentage: type: number description: 'Additional percentage points added for aged invoices. Calculated based on invoice age: - 12-24 months overdue: +8 percentage points - 24+ months overdue: +15 percentage points - Multi-invoice with mixed ages: blended rate (0-15 percentage points)' format: double totalSuccessFeePercentage: type: number description: 'Total success fee percentage (base + age surcharge). This is the percentage of the recovered amount that will be charged as a success fee.' format: double currencyCode: type: - string - 'null' description: ISO 4217 currency code for the case. pricingSource: type: - string - 'null' description: 'Which pricing rule determined the fee. Possible values: "Standard agreement", "Creditor custom pricing", "Managing partner custom pricing", "Jurisdiction custom pricing", "Partner custom pricing", "Accepted quote".' pricingSourceDescription: type: - string - 'null' description: 'Human-readable explanation of why this pricing was applied. Example: "9.5% success fee — BD Legal custom collection rates (EU zone, $1,000–$7,999 tier)"' additionalProperties: false description: Estimated pricing for the case, including age-based surcharges. Debitura.Web.ExternalApi.Contracts.V1.Cases.PartnerAssignmentDto: type: object properties: collectionPartnerId: type: string description: Unique identifier for the collection partner. format: uuid partnerName: type: - string - 'null' description: Display name of the collection partner company. partnerCountry: type: - string - 'null' description: ISO 3166-1 alpha-2 country code for the partner's primary country. additionalProperties: false description: Information about the collection partner assigned to this case. Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskActionDto: type: object properties: method: type: - string - 'null' description: HTTP method to use, e.g. `"POST"`. path: type: - string - 'null' description: 'Path template for the resolving call, e.g. `"/cases/{caseId}/chats"`. Relative to the API''s base URL.' additionalProperties: false description: "A machine-readable hint pointing at the existing API call that resolves a task, e.g.\n`{ \"method\": \"POST\", \"path\": \"/cases/{caseId}/chats\" }` for a chat-driven task.\n \nPath uses the same `{param}` placeholder style as this API's own\ndocumented routes — substitute in the real IDs before calling." Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorResponseApiDTO: type: object properties: businessErrors: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.BusinessErrorApiDTO' description: List of business errors that must be resolved before the case can be created. signingHandoff: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.SigningHandoffDto' additionalProperties: false description: Response returned when business rule violations prevent case creation. Debitura.Web.ExternalApi.Contracts.V1.Cases.PreviewCaseResponseApiViewModel: type: object properties: result: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.PreviewResultDto' additionalProperties: false description: 'Response from previewing a case, showing eligibility, partner assignment, required actions, and pricing estimates.' Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskDto: type: object properties: id: type: string description: The task's unique ID. format: uuid type: type: - string - 'null' description: 'Stable string code for the task type (e.g. `"ReplyToChat"`). This is the public, additive-safe contract — it does NOT track the internal integer enum used in storage.' typeLabel: type: - string - 'null' description: Human-readable label for Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskDto.Type (e.g. "Reply to chat"). title: type: - string - 'null' description: Short task title, as shown in the Creditor app. description: type: - string - 'null' description: Optional longer description of what the task requires. status: type: - string - 'null' description: Either `"Open"` or `"Solved"`. caseId: type: - string - 'null' description: 'The case (collection case / invoice) this task belongs to, when applicable. Null for account-level tasks not tied to a single case (e.g. SignContract, AssignBankAccount).' format: uuid caseReference: type: - string - 'null' description: Your reference for Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskDto.CaseId, if any. leadId: type: - string - 'null' description: The lead this task belongs to (e.g. SelectQuoteWinner), if applicable. format: uuid deadline: type: - string - 'null' description: When this task is due, if a deadline is set. format: date-time dateCreated: type: string description: When the task was created. format: date-time dateSolved: type: - string - 'null' description: When the task was resolved, if it has been. format: date-time solutionUrl: type: - string - 'null' description: 'Absolute URL — identical to the one the Creditor app itself links to — where a human can resolve this task. Always present, regardless of whether Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskDto.Action is populated.' action: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskActionDto' additionalProperties: false description: "A creditor-facing action item (\"task\") — something the platform needs the client to do\nbefore a case can proceed (e.g. reply to a chat, sign a contract, assign a bank account).\n \nEvery task carries a Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskDto.SolutionUrl — an absolute link identical to the one used\ninside the Creditor app — so a human can resolve any task in one click, even task types that\nare not yet directly API-actionable. Tasks that ARE directly API-actionable additionally carry\na non-null Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskDto.Action pointing at the exact API call that resolves them." Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuoteDetailDto: required: - agreementType - currency - partnerName - pricing - status type: object properties: quoteId: type: string format: uuid quoteRequestId: type: string format: uuid partnerId: type: string format: uuid partnerName: type: - string - 'null' status: type: - string - 'null' agreementType: type: - string - 'null' pricing: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadQuotePricingDto' currency: type: - string - 'null' proposedSolution: type: - string - 'null' feeComments: type: - string - 'null' partnerWhyUsSection: type: - string - 'null' fullQuoteLink: type: - string - 'null' dateCreated: type: string format: date-time dateUpdated: type: - string - 'null' format: date-time additionalProperties: false description: V1 Lead Quote detail DTO for external customer APIs (detailed view) Debitura.Web.ExternalApi.Contracts.V1.Leads.LeadDto: required: - leadFlowStatus - quoteType - status type: object properties: quoteRequestId: type: string format: uuid caseId: type: string format: uuid status: type: - string - 'null' leadFlowStatus: type: - string - 'null' quoteType: type: - string - 'null' maxQuotes: type: integer format: int32 currentQuotesCount: type: integer format: int32 outcome: type: - string - 'null' purpose: type: - string - 'null' description: 'Why this lead exists: PhaseChange (legal/enforcement escalation that advances the case phase) or AdditionalService (in-phase add-on). Null for legacy leads created before the field existed.' dateCreated: type: string format: date-time dateQualified: type: - string - 'null' format: date-time leadsDoneOffered: type: - string - 'null' format: date-time dateReminderSent: type: - string - 'null' format: date-time dateReminderTwoSent: type: - string - 'null' format: date-time dateOutcomeSelected: type: - string - 'null' format: date-time additionalProperties: false description: V1 Lead DTO for external customer APIs (summary view) Debitura.Web.ExternalApi.Contracts.V1.Cases.CaseContractStatusApiDTO: type: object properties: sdca: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.ContractItemDto' poa: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.ContractItemDto' pricingAppendix: $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Cases.ContractItemDto' collectionPartnerName: type: - string - 'null' description: Name of the assigned collection partner, if any. needsPoaSigning: type: boolean description: 'Whether the creditor needs to sign (or re-sign) a Power of Attorney. True when: POA is missing or stale, OR the debtor''s country has an active jurisdiction pricing zone and the Jurisdiction Pricing Appendix (presented as POA) is missing or stale.' additionalProperties: false description: Contract signing status for a case, showing SDCA and PoA status with signing URLs. Debitura.Web.ExternalApi.Contracts.V1.Cases.ContractItemDto: type: object properties: signed: type: boolean description: Whether the contract has been signed. requiresResigning: type: boolean description: Whether the contract needs to be re-signed (e.g., due to contract template updates). solutionUrl: type: - string - 'null' description: 'URL where the creditor can sign or re-sign the contract. Null if the contract is signed and current. The URL is context-aware: referral partner tokens get referral onboarding URLs, regular API keys get standard creditor app URLs.' additionalProperties: false description: Status of an individual contract (SDCA, PoA, or Pricing Appendix). Debitura.Domain.Services.CaseValidation.CaseValidationStatusDto_2: type: object properties: needsInfo: type: boolean description: 'True when the latest validation run requires creditor action. Reads Debitura.Domain.Model.Receiveables.Invoices.Invoice.ValidationNeedsInfo directly — do not re-derive from items.' creditorRespondedAt: type: - string - 'null' description: 'When the creditor (or managing partner) last explicitly responded to a needs-info request. Null when the creditor has not yet responded, or after the case passes validation.' format: date-time items: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Domain.Services.CaseValidation.CaseValidationItemDto_2' description: 'Creditor-facing action items from the latest validation run. Empty when Debitura.Domain.Services.CaseValidation.CaseValidationStatusDto.NeedsInfo is false or no run exists.' additionalProperties: false description: 'Sanitized, creditor-safe projection of a case''s current validation status. Safe to expose on any external surface — never contains Rationale, InternalValidationComment, InternalReview/AdminReview areas, Confidence, or EvaluationMethod.' Debitura.Web.ReferralPartnerApi.Models.Cases.ContactUser: type: object properties: email: type: - string - 'null' name: type: - string - 'null' additionalProperties: false description: A user contact associated with a creditor. Debitura.Web.ReferralPartnerApi.Models.Cases.ClientContacts: type: object properties: onboardingUser: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.ContactUser' officeEmail: type: - string - 'null' description: The creditor's office email address (company-level contact). otherUsers: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.ContactUser' description: Other users linked to this creditor account (excludes the onboarding user). additionalProperties: false description: 'Contact information for a client, including the original onboarding user, the company office email, and all other users linked to the creditor.' Debitura.Domain.Services.CaseValidation.CaseValidationItemDto_2: type: object properties: resolutionArea: type: - string - 'null' description: 'Enum name of the resolution area (e.g. "ProvideDocuments", "CorrectDebtorAddress"). Always a Debitura.Domain.Services.CaseValidation.CaseValidationHelpers.CreditorFacingAreas member — never "InternalReview" or "AdminReview".' description: type: - string - 'null' description: 'Creditor-safe description of what needs to be fixed. Source: Debitura.Domain.Model.Receiveables.CaseValidation.CaseValidationRuleResult.CuratedDescription — scoring stripped.' additionalProperties: false description: A single creditor-facing action item within Debitura.Domain.Services.CaseValidation.CaseValidationStatusDto. Debitura.Web.ReferralPartnerApi.Models.Cases.CasePotentialRevenue: type: object properties: grossAmountUsd: type: number description: Case gross amount converted to USD. format: double successFeePercentage: type: number description: Success fee percentage charged by the collection partner (e.g. 9.5). format: double collectionPartnerRevenueUsd: type: number description: GrossAmountUsd * SuccessFeePercentage / 100. format: double platformRevenueSharePercentage: type: number description: Debitura's revenue share percentage of the collection fee (e.g. 40.0). format: double platformRevenueUsd: type: number description: CollectionPartnerRevenueUsd * PlatformRevenueSharePercentage / 100. format: double referralFeePercentage: type: number description: Referral partner's share percentage of platform revenue (e.g. 50.0). format: double referralRevenueUsd: type: number description: PlatformRevenueUsd * ReferralFeePercentage / 100. format: double additionalProperties: false description: 'Breakdown of potential revenue if the full case amount is collected. All amounts are in USD; percentages are displayed as whole numbers (e.g. 9.5 = 9.5%).' Debitura.Web.ReferralPartnerApi.Models.Cases.GetCasesResponse: type: object properties: page: $ref: '#/components/schemas/Debitura.Domain.Model.Base.PageData_2' cases: type: - array - 'null' items: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.CaseItem' summary: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.CasesSummary' additionalProperties: false description: Response model for listing cases linked to a referral partner Debitura.Domain.Model.Base.PageData_2: type: object properties: totalResults: type: integer description: Total number of records for the query (filtered or all as applicable). format: int32 pageSize: type: integer description: How many records are returned per page. format: int32 currentPage: type: integer description: Which page number is being shown, calculated from the number of skipped items. format: int32 responseCount: type: integer description: How many records are present in the current page. format: int32 totalPages: type: integer description: Total number of pages available given Debitura.Domain.Model.Base.PageData.TotalResults and Debitura.Domain.Model.Base.PageData.PageSize. format: int32 readOnly: true additionalProperties: false description: Paging metadata describing a paged result set. Debitura.Web.ReferralPartnerApi.Models.Cases.CaseItem: type: object properties: id: type: string format: uuid reference: type: - string - 'null' creditorReference: type: - string - 'null' client: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.CaseClientInfo' debtor: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.CaseDebtorInfo' grossAmount: type: number format: double remainder: type: number format: double currency: type: - string - 'null' lifecycle: type: - string - 'null' description: 'Lifecycle status as human-readable description (e.g. "Active", "Closed", "Pending Verification"). Same format as InvoiceDto.Lifecycle in the external API contracts.' closeCode: type: - string - 'null' description: Close code description if the case is closed (e.g. "Paid", "Withdrawn by Client"), null otherwise. currentEngagementPhase: type: - string - 'null' description: "The current phase of the case's engagement: \"Pre-legal\", \"Legal\", or \"Enforcement\". A\ndifferent axis from Debitura.Web.ReferralPartnerApi.Models.Cases.CaseItem.Lifecycle/Debitura.Web.ReferralPartnerApi.Models.Cases.CaseItem.CloseCode — an Active case can be\nin any of the three phases.\n \nNull means \"no active engagement\" (e.g. lead / quoting / pre-contract-signing / unassigned,\nor a data-consistency gap) — a distinct third state, NOT a synonym for Pre-legal. Most cases\nlegitimately read Pre-legal; phase only leaves Pre-legal on legal/enforcement quote flows.\n \nNot guaranteed to be monotonic (an admin correction can move phase backwards). Persists\nafter case closure — reflects the case's last-known engagement phase, not the current\nLifecycle." dateCreated: type: string format: date-time dueDate: type: string format: date-time dateCollectionStarted: type: - string - 'null' format: date-time dateFinished: type: - string - 'null' format: date-time validation: $ref: '#/components/schemas/Debitura.Domain.Services.CaseValidation.CaseValidationStatusDto_2' collectionPartner: type: - string - 'null' description: 'Display name of the collection partner handling this case (e.g. "Oriel Collections"). Null if no collection partner has been assigned yet.' expectedReferralRatePercentage: type: - number - 'null' description: 'The expected referral fee rate as a percentage (e.g. 70.0 = 70%). For cases with a collection partner that has a per-assignment override, the override is used. Otherwise falls back to the referral link''s snapshotted rate (frozen at link creation time). Null when no collection partner has been assigned yet — a rate can only be determined once routing is complete. For realised payouts with frozen rates, see `referralFeePercentageSnapshot` on the transactions endpoint.' format: double additionalProperties: false description: 'A debt collection case as seen by a referral partner. Follows the same field conventions as InvoiceDto (ExternalApi.Contracts) but scoped to what referral partners need, with ExternalTenantId on Client.' Debitura.Web.ReferralPartnerApi.Models.Cases.CasesSummary: type: object properties: totalCases: type: integer format: int32 casesThisMonth: type: integer format: int32 byLifecycle: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.LifecycleBreakdown' additionalProperties: false Debitura.Web.ReferralPartnerApi.Models.Cases.LifecycleBreakdown: type: object properties: active: type: integer format: int32 pending: type: integer format: int32 closed: type: integer format: int32 paused: type: integer format: int32 additionalProperties: false Debitura.Web.ReferralPartnerApi.Models.Cases.CaseClientInfo: type: object properties: externalTenantId: type: - string - 'null' description: Your external tenant ID for this client (the identifier you provided when linking). creditorId: type: string format: uuid companyName: type: - string - 'null' contacts: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.ClientContacts' additionalProperties: false description: Client (creditor) info with referral-partner-specific ExternalTenantId. Debitura.Web.ReferralPartnerApi.Models.Cases.CaseDebtorInfo: type: object properties: name: type: - string - 'null' description: Debtor display name (company name, or person name if individual). country: type: - string - 'null' description: Debtor's country (full name, e.g. "United Kingdom", "Denmark"). additionalProperties: false description: Debtor info for the case. Debitura.Web.ReferralPartnerApi.Models.Cases.GetCaseDetailResponse: type: object properties: id: type: string format: uuid reference: type: - string - 'null' creditorReference: type: - string - 'null' client: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.CaseClientInfo' debtor: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.CaseDebtorInfo' grossAmount: type: number format: double remainder: type: number format: double currency: type: - string - 'null' lifecycle: type: - string - 'null' closeCode: type: - string - 'null' currentEngagementPhase: type: - string - 'null' description: 'The current phase of the case''s engagement: "Pre-legal", "Legal", or "Enforcement". Null means no active engagement — see Debitura.Web.ReferralPartnerApi.Models.Cases.CaseItem.CurrentEngagementPhase for full semantics (not monotonic, persists after case closure).' dateCreated: type: string format: date-time dueDate: type: string format: date-time dateCollectionStarted: type: - string - 'null' format: date-time dateFinished: type: - string - 'null' format: date-time validation: $ref: '#/components/schemas/Debitura.Domain.Services.CaseValidation.CaseValidationStatusDto_2' collectionPartner: type: - string - 'null' description: 'Display name of the collection partner handling this case (e.g. "Oriel Collections"). Null if no collection partner has been assigned yet.' expectedReferralRatePercentage: type: - number - 'null' description: 'The expected referral fee rate as a percentage (e.g. 70.0 = 70%). Uses the per-assignment override when set, otherwise the referral link''s snapshotted rate (frozen at link creation time). Null when no collection partner has been assigned yet.' format: double potentialRevenue: $ref: '#/components/schemas/Debitura.Web.ReferralPartnerApi.Models.Cases.CasePotentialRevenue' additionalProperties: false description: 'Response model for retrieving a single case with potential revenue breakdown. Extends CaseItem fields with revenue data for referral partners.' securitySchemes: ApiKey: type: apiKey description: Collection Partner API Key (use XApiKey header) name: XApiKey in: header Bearer: type: http description: This is for referral partners, who are sending in clients to the platform. They get the bearer token from the referral partner Api and can be inserted here. scheme: bearer bearerFormat: JWT externalDocs: description: Debitura developer documentation url: https://docs.debitura.com x-refined-from: - debitura-collection-partner-api.json - debitura-customer-api.json - debitura-referral-partner-api.json