> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywise.de/llms.txt
> Use this file to discover all available pages before exploring further.

# List mandate correspondence

> Debtor correspondence of the case that the creditor may read: the same set the portal shows. `channel` is an open enumeration (`email` today). List rows omit `body` and `attachments`; read the item for both. Items become readable through a status or client-request publication; that moment counts as an update, so `updated_since` returns newly readable items.



## OpenAPI

````yaml /api-docs/case-management-api/openapi.json get /v2/mandates/{mandate_id}/correspondence/
openapi: 3.0.3
info:
  description: >-
    Submit orders and manage their complete lifecycle through the current API at
    the `/v2/` HTTP path.
  title: paywise Case Management API
  version: current
servers:
  - description: Production environment
    url: https://api.paywise.de
  - description: Sandbox environment
    url: https://api-sandbox.paywise.de
security: []
tags:
  - description: Submit orders and manage them until acceptance.
    name: Orders
  - description: Stable claim resources and their current relationships.
    name: Claims
  - description: 'Accepted cases: state, published history and documents.'
    name: Mandates
  - description: Debtor master data reused across orders.
    name: Debtors
  - description: Payments reported by you and booked by paywise.
    name: Payments
  - description: Files attached to claims and other resources.
    name: Documents
  - description: Collective statements (Sammelabrechnungen).
    name: Statements
  - description: Per-case statements (Aktenabrechnungen).
    name: Single mandate statements
  - description: Webhook endpoints and their signing secrets.
    name: Webhooks
  - description: Delivery log and redelivery of webhook events.
    name: Webhook deliveries
  - description: Ordered feed of the events webhooks deliver.
    name: Events
  - description: Reference catalog of legal forms.
    name: Legal forms
  - description: The authenticated credential and its context.
    name: Info
  - description: Rate-limit headroom of the credential.
    name: Usage
  - description: Availability of the API.
    name: Health
externalDocs:
  url: https://docs.paywise.de/api-docs/case-management-api/introduction
paths:
  /v2/mandates/{mandate_id}/correspondence/:
    get:
      tags:
        - Mandates
      summary: List mandate correspondence
      description: >-
        Debtor correspondence of the case that the creditor may read: the same
        set the portal shows. `channel` is an open enumeration (`email` today).
        List rows omit `body` and `attachments`; read the item for both. Items
        become readable through a status or client-request publication; that
        moment counts as an update, so `updated_since` returns newly readable
        items.
      operationId: list-mandate-correspondence
      parameters:
        - description: >-
            Required when a Partner key calls the Case Management API; rejected
            for direct Case keys. Contains the entitled paywise company UUID.
          in: header
          name: X-On-Behalf-Of-Company
          schema:
            format: uuid
            type: string
        - description: Only this channel. Unknown channels yield an empty page.
          in: query
          name: channel
          schema:
            type: string
        - description: >-
            Opaque continuation cursor for incremental synchronization, taken
            from the `next` URL of a previous page. Only valid together with
            `updated_since`: with `updated_since` set the list is ordered by
            change time and then id and pages by this cursor instead of
            `offset`, so a row that changes while you page is returned again
            later instead of pushing another row out of the result. Rows changed
            less than 60 seconds ago are held back until they are settled; use
            the largest `updated_at` you received as the next `updated_since`.
          in: query
          name: cursor
          schema:
            type: string
        - description: >-
            Only inbound (received from the debtor) or outbound (sent by
            paywise) items.
          in: query
          name: direction
          schema:
            enum:
              - inbound
              - outbound
            type: string
        - description: Number of results to return (maximum 100).
          in: query
          name: limit
          schema:
            default: 10
            maximum: 100
            minimum: 1
            type: integer
        - description: UUID of the parent accepted case in this request.
          in: path
          name: mandate_id
          required: true
          schema:
            format: uuid
            type: string
        - description: Zero-based result offset.
          in: query
          name: offset
          schema:
            default: 0
            minimum: 0
            type: integer
        - description: >-
            Return entries changed at or after this timezone-aware RFC 3339
            timestamp (inclusive). With it set, results are ordered by change
            time and then id instead of newest first, page by `cursor` instead
            of `offset`, and entries changed less than a minute ago are held
            back.
          in: query
          name: updated_since
          schema:
            format: date-time
            type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                correspondence-list:
                  value:
                    count: 123
                    next: http://api.example.org/accounts/?offset=400&limit=100
                    previous: http://api.example.org/accounts/?offset=200&limit=100
                    results:
                      - channel: email
                        direction: inbound
                        email:
                          cc: []
                          from: debtor@example.test
                          to:
                            - inkasso@paywise.de
                        history_entry_ids:
                          - f0000000-0000-4000-8000-000000000001
                        id: f3000000-0000-4000-8000-000000000001
                        occurred_at: '2026-08-27T10:58:00Z'
                        pdf_url: >-
                          https://api-sandbox.paywise.de/v2/mandates/50000000-0000-4000-8000-000000000001/correspondence/f3000000-0000-4000-8000-000000000001/pdf/
                        source_mandate:
                          id: 50000000-0000-4000-8000-000000000001
                          reference_number: PW-2026-000042
                          relation: main_case
                        subject: Ratenzahlung
                        updated_at: '2026-08-27T11:05:00Z'
                        url: >-
                          https://api-sandbox.paywise.de/v2/mandates/50000000-0000-4000-8000-000000000001/correspondence/f3000000-0000-4000-8000-000000000001/
              schema:
                $ref: '#/components/schemas/PaginatedCorrespondenceListList'
          description: ''
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '400':
          content:
            application/json:
              examples:
                validation-error:
                  value:
                    code: validation_error
                    detail: The request contains invalid data.
                    errors:
                      - code: invalid
                        field: claims[0].due_date
                        message: Due date must not precede the document date.
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '401':
          content:
            application/json:
              examples:
                authentication-error:
                  value:
                    code: not_authenticated
                    detail: Authentication credentials were not provided.
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '404':
          content:
            application/json:
              examples:
                not-found-error:
                  value:
                    code: not_found
                    detail: The requested resource was not found.
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            Retry-After:
              description: Integer seconds to wait before retrying a throttled request.
              schema:
                minimum: 1
                type: integer
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Standard error response.
          headers:
            Cache-Control:
              description: >-
                Cacheability directive. Authenticated responses use `private,
                no-store`; the legal-form catalog may use `private,
                max-age=86400`.
              schema:
                type: string
            X-Paywise-Environment:
              description: Environment that produced the response.
              schema:
                enum:
                  - production
                  - sandbox
                type: string
            X-Paywise-Request-Id:
              description: >-
                Fresh server-assigned correlation id for this response.
                Caller-provided request ids are ignored.
              schema:
                format: uuid
                type: string
      security:
        - caseBearerAuth: []
        - partnerBearerAuth: []
components:
  schemas:
    PaginatedCorrespondenceListList:
      properties:
        count:
          description: Total number of matching resources.
          example: 123
          type: integer
        next:
          description: >-
            URL for the next page, or null when this is the last page. With
            `updated_since` it carries an opaque `cursor`.
          example: http://api.example.org/accounts/?offset=400&limit=100
          format: uri
          nullable: true
          type: string
        previous:
          description: >-
            URL for the previous page, or null when this is the first page.
            Always null with `updated_since`.
          example: http://api.example.org/accounts/?offset=200&limit=100
          format: uri
          nullable: true
          type: string
        results:
          description: Resources returned for the requested page.
          items:
            $ref: '#/components/schemas/CorrespondenceList'
          type: array
      required:
        - count
        - results
      type: object
    Error:
      properties:
        code:
          description: Machine-readable error category.
          type: string
        detail:
          description: Short human-readable summary of the error.
          type: string
        errors:
          description: Field-level validation errors, when applicable.
          items:
            $ref: '#/components/schemas/ErrorItem'
          type: array
      required:
        - detail
        - code
      type: object
    CorrespondenceList:
      description: One correspondence item without body and attachments (list rows).
      properties:
        channel:
          description: >-
            Communication channel. Open enumeration: `email` today; clients must
            tolerate new values.
          readOnly: true
          type: string
        direction:
          allOf:
            - $ref: '#/components/schemas/DirectionEnum'
          description: Whether paywise received or sent the message.
          readOnly: true
        email:
          allOf:
            - $ref: '#/components/schemas/CorrespondenceEmailDetails'
          description: Email-channel details; present when `channel` is `email`.
          readOnly: true
        history_entry_ids:
          description: >-
            Published history entries that surface this message; empty for
            messages reachable only through a client request.
          items:
            format: uuid
            type: string
          readOnly: true
          type: array
        id:
          description: Stable identifier of the correspondence item.
          format: uuid
          readOnly: true
          type: string
        occurred_at:
          description: Time the message was received or sent.
          format: date-time
          readOnly: true
          type: string
        pdf_url:
          description: >-
            Authenticated URL of the message rendered as PDF (header block and
            plain text).
          format: uri
          readOnly: true
          type: string
        source_mandate:
          allOf:
            - $ref: '#/components/schemas/HistorySourceMandate'
          description: Main case or subcase the message belongs to.
          readOnly: true
        subject:
          description: Subject line, or null.
          nullable: true
          readOnly: true
          type: string
        updated_at:
          description: Latest change to this item; use for incremental synchronization.
          format: date-time
          readOnly: true
          type: string
        url:
          description: Authenticated API URL of this item.
          format: uri
          readOnly: true
          type: string
      required:
        - channel
        - direction
        - email
        - history_entry_ids
        - id
        - occurred_at
        - pdf_url
        - source_mandate
        - subject
        - updated_at
        - url
      type: object
    ErrorItem:
      properties:
        code:
          description: Machine-readable field error code.
          type: string
        field:
          description: >-
            Path to the field that caused the error, using dots for objects and
            brackets for list indexes, for example `claims[0].amount`; null for
            an error without a field path.
          nullable: true
          type: string
        message:
          description: Human-readable explanation of the field error.
          type: string
      required:
        - field
        - code
        - message
      type: object
    DirectionEnum:
      enum:
        - inbound
        - outbound
      type: string
    CorrespondenceEmailDetails:
      properties:
        cc:
          description: Carbon-copy addresses.
          items:
            type: string
          type: array
        from:
          description: Sender address.
          nullable: true
          type: string
        to:
          description: Recipient addresses.
          items:
            type: string
          type: array
      required:
        - cc
        - from
        - to
      type: object
    HistorySourceMandate:
      properties:
        id:
          description: Identifier of the case that produced the entry.
          format: uuid
          readOnly: true
          type: string
        reference_number:
          description: paywise reference number of the source case.
          readOnly: true
          type: string
        relation:
          allOf:
            - $ref: '#/components/schemas/RelationEnum'
          description: |-
            Main-case or subcase attribution.

            * `main_case` - main_case
            * `subcase` - subcase
          readOnly: true
      required:
        - id
        - reference_number
        - relation
      type: object
    RelationEnum:
      description: |-
        * `main_case` - main_case
        * `subcase` - subcase
      enum:
        - main_case
        - subcase
      type: string
  securitySchemes:
    caseBearerAuth:
      description: >-
        Company-bound Case Management API key — the standard credential for this
        API.
      scheme: bearer
      type: http
    partnerBearerAuth:
      description: >-
        Partner API key acting for one entitled company; every Case request must
        then also carry the X-On-Behalf-Of-Company header.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.