Debitura Tasks API

openapi: 3.2.0
info:
  title: Debitura Customer Tasks API
  description: Welcome to the Debitura Customer API, your gateway to seamlessly integrating your debt collection workflow with our platform.
  contact:
    name: Debitura Support
    url: https://www.debitura.com/integration/debt-collection-api
    email: contact@debitura.com
  version: v1
servers:
- url: https://customer-api.debitura.com
  description: Production
security:
- ApiKey: []
- Bearer: []
tags:
- name: Tasks
  description: Tasks
paths:
  /tasks:
    get:
      tags:
      - Tasks
      summary: List your open tasks
      description: 'Returns a paginated, account-wide list of every task (action-item) your account currently has — across ALL cases, not just one. Use GET /cases/{id}/tasks instead to scope this to a single case.


        **What is a task?**

        A task is something the platform needs YOU to do before a case can proceed — e.g. reply to a chat message, sign a contract, or assign a bank account for payouts. Tasks auto-resolve when the underlying condition clears (for example, once you reply to the case''s chat, the ReplyToChat task disappears on its own) — this is a live work queue, not an append-only log. Poll it, don''t assume a task you''ve seen before is still open.


        **Every task has a solutionUrl** — an absolute link, identical to the one used inside the Creditor app itself, that a human can open to resolve the task in one click, no matter the task type.


        **Some tasks also have an `action`** — a machine-readable hint pointing at the exact existing API call that resolves the task directly, with no human required. Today that''s the chat-driven cluster (ReplyToChat, ClientInputRequired, MoreInfoNeeded) — post a message via POST /cases/{caseId}/chats and the task resolves itself once the case leaves its needs-info state. Tasks without an action are `action: null` — resolve those via solutionUrl.


        **Filtering:**

        - status (default: Open) — Open or Solved

        - type (repeatable, e.g. ?type=ReplyToChat&type=SignContract) — restrict to specific task types


        **Pagination:**

        - Page (default: 1), PageSize (default: 10, max: 100)'
      parameters:
      - name: status
        in: query
        schema:
          type: string
          default: Open
      - name: type
        in: query
        schema:
          type: array
          items:
            type: string
      - name: Page
        in: query
        schema:
          type: integer
          format: int32
          default: 1
      - name: PageSize
        in: query
        schema:
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: Tasks returned
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskListDto'
            application/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskListDto'
            text/json:
              schema:
                $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskListDto'
        '400':
          description: Invalid status, type, or pagination parameters
          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'
      operationId: getTasks
      x-operation-id-source: derived
components:
  schemas:
    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.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.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.Tasks.TaskListDto:
      required:
      - page
      type: object
      properties:
        page:
          $ref: '#/components/schemas/Debitura.Domain.Model.Base.PageData'
        tasks:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Debitura.Web.ExternalApi.Contracts.V1.Tasks.TaskDto'
      additionalProperties: false
      description: Paged list of tasks, returned by `GET /tasks`.
    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.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 <i>specific</i> error (e.g., sign a contract).\n            \n\nPartners who want a <b>single URL</b> 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.
  securitySchemes:
    ApiKey:
      type: apiKey
      description: This is for clients who manage their own account. They can get the API key in the platform and set it as the 'XApiKey' in the 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