> ## 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.

# Create mandate message

> Messages exchanged with paywise about one order or one case.



## OpenAPI

````yaml /api-docs/case-management-api/openapi.json post /v2/mandates/{mandate_id}/messages/
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}/messages/:
    post:
      tags:
        - Mandates
      summary: Create mandate message
      description: Messages exchanged with paywise about one order or one case.
      operationId: create-mandate-message
      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: UUID of the parent accepted case in this request.
          in: path
          name: mandate_id
          required: true
          schema:
            format: uuid
            type: string
        - description: >-
            Required client-supplied command key scoped to the selected Case
            company or Partner owner, method, operation and path. An exact retry
            replays the original response while it is retained, including after
            credential rotation or replacement. Current permissions are
            required.
          in: header
          name: Idempotency-Key
          required: true
          schema:
            maxLength: 255
            type: string
      requestBody:
        content:
          application/json:
            examples:
              message-create:
                value:
                  body: The customer provided an updated invoice address.
                  documents: []
                  title: Updated invoice address
            schema:
              $ref: '#/components/schemas/MessageCreateRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageRead'
          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
        '409':
          content:
            application/json:
              examples:
                conflict-error:
                  value:
                    code: conflict
                    detail: The resource changed state and cannot accept this command.
              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:
    MessageCreateRequest:
      description: >-
        Unknown and read-only request fields are rejected with a validation
        error instead of being silently ignored.
      properties:
        body:
          description: >-
            Message content sent to paywise; supported HTML is sanitized and the
            content must not be empty after sanitization.
          maxLength: 262144
          minLength: 1
          type: string
        documents:
          description: >-
            Documents attached to the message. At most 20 documents and 50 MiB
            of decoded document content per command. Each file is limited to 10
            MiB and each PDF to 100 pages. Exceeding a limit rejects the command
            with 400.
          items:
            $ref: '#/components/schemas/InlineDocumentCreateRequest'
          maxItems: 20
          type: array
        title:
          description: Short subject of the message.
          maxLength: 200
          minLength: 1
          type: string
      required:
        - body
        - title
      type: object
    MessageRead:
      description: Resource representation with a native UUID `id`.
      properties:
        author:
          allOf:
            - $ref: '#/components/schemas/MessageAuthor'
          description: Channel through which the message was authored.
          readOnly: true
        body:
          description: Message content exchanged with paywise.
          nullable: true
          readOnly: true
          type: string
        created_at:
          description: Time at which the message was created.
          format: date-time
          readOnly: true
          type: string
        documents:
          description: Documents attached to the message.
          items:
            $ref: '#/components/schemas/DocumentRead'
          readOnly: true
          type: array
        editable:
          description: >-
            Whether this message can be edited through the API. True only for a
            client message created through current Case Management API for the
            calling company while it is under review and no review task has
            started.
          readOnly: true
          type: boolean
        href:
          description: API URL of this message.
          format: uri
          readOnly: true
          type: string
        id:
          description: Stable identifier for this resource.
          format: uuid
          readOnly: true
          type: string
        parent:
          allOf:
            - $ref: '#/components/schemas/MessageParent'
          description: Order or accepted case to which the message belongs.
          readOnly: true
        response_to:
          description: Message to which this message responds, when applicable.
          format: uuid
          nullable: true
          readOnly: true
          type: string
        sender:
          allOf:
            - $ref: '#/components/schemas/SenderEnum'
          description: Party that sent the message.
          readOnly: true
        state:
          allOf:
            - $ref: '#/components/schemas/StateEnum'
          description: >-
            Review/publication state: `under_review` for a client message
            awaiting review, `handled` after handling, or `published` for a
            published message. Check `editable` before offering edits.
          readOnly: true
        title:
          description: Short subject of the message.
          nullable: true
          readOnly: true
          type: string
        updated_at:
          description: Time at which the message was last updated.
          format: date-time
          readOnly: true
          type: string
      required:
        - author
        - body
        - created_at
        - documents
        - editable
        - href
        - id
        - parent
        - response_to
        - sender
        - state
        - title
        - updated_at
      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
    InlineDocumentCreateRequest:
      additionalProperties: false
      description: Document embedded inline in a claim, message, or answer payload.
      properties:
        base64:
          description: >-
            Required base64-encoded PDF, JPEG, or PNG content. Maximum decoded
            file size: 10 MiB (10,485,760 bytes); maximum PDF length: 100 pages.
            Across the entire command, at most 20 documents and 50 MiB of
            decoded content are allowed, including documents nested under other
            parents. Exceeding a limit returns 400; too many PDF pages uses
            page_limit_exceeded.
          maxLength: 15029589
          minLength: 1
          type: string
        filename:
          description: >-
            Original filename shown to users. Path components and control
            characters are removed and the extension always follows the detected
            content type.
          maxLength: 255
          minLength: 1
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/CaseDocumentTypeEnum'
          description: |-
            Business purpose of the document.

            * `bank_statement` - bank_statement
            * `claim_statement` - claim_statement
            * `correspondence` - correspondence
            * `enforceable_title` - enforceable_title
            * `invoice` - invoice
            * `other` - other
            * `payment_proof` - payment_proof
            * `reminder` - reminder
            * `rental_agreement` - rental_agreement
      required:
        - base64
        - type
      type: object
    MessageAuthor:
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/MessageAuthorTypeEnum'
          description: >-
            Authorship channel: `api` for a client message created through
            current Case Management API, `user` for another client-authored
            message, or `paywise` for a message sent by paywise.
          readOnly: true
      required:
        - type
      type: object
    DocumentRead:
      description: Resource representation with a native UUID `id`.
      properties:
        created_at:
          description: Time at which the document was submitted.
          format: date-time
          readOnly: true
          type: string
        download_url:
          description: >-
            Authenticated API URL for downloading the document; null while its
            status is not `ready`.
          format: uri
          nullable: true
          readOnly: true
          type: string
        failure_reason:
          allOf:
            - $ref: '#/components/schemas/DocumentFailureReasonEnum'
          description: >-
            Why processing failed when status is `failed`; `null` otherwise.
            `page_limit_exceeded`: PDF above the 100-page ceiling; `encrypted`:
            password-protected PDF; `corrupt`: bytes could not be parsed;
            `unsupported`: content type not accepted; `processing_failed`: any
            other processing error.
          nullable: true
          readOnly: true
        filename:
          description: Original filename shown to users.
          readOnly: true
          type: string
        id:
          description: Stable identifier for this resource.
          format: uuid
          readOnly: true
          type: string
        mime_type:
          description: Detected media type of the document.
          nullable: true
          readOnly: true
          type: string
        parent:
          allOf:
            - $ref: '#/components/schemas/DocumentParent'
          description: Resource that owns the document.
          readOnly: true
        status:
          allOf:
            - $ref: '#/components/schemas/CaseDocumentStatusEnum'
          description: >-
            Document availability: `pending` while scanning or processing is
            incomplete; `ready` when processing permits download; `failed` when
            scanning or processing failed; `rejected` when the malware check
            rejected the file.
          readOnly: true
        type:
          allOf:
            - $ref: '#/components/schemas/CaseDocumentTypeEnum'
          description: Business purpose of the document.
          readOnly: true
        updated_at:
          description: Time at which document processing last changed.
          format: date-time
          readOnly: true
          type: string
      required:
        - created_at
        - download_url
        - failure_reason
        - filename
        - id
        - mime_type
        - parent
        - status
        - type
        - updated_at
      type: object
    MessageParent:
      properties:
        id:
          description: Identifier of the order or accepted case owning the message.
          format: uuid
          readOnly: true
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/MessageParentTypeEnum'
          description: >-
            Whether the message belongs to an order (`order`) or an accepted
            case (`mandate`).
          readOnly: true
      required:
        - id
        - type
      type: object
    SenderEnum:
      enum:
        - client
        - paywise
      type: string
    StateEnum:
      enum:
        - under_review
        - handled
        - published
      type: string
    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
    CaseDocumentTypeEnum:
      description: |-
        * `bank_statement` - bank_statement
        * `claim_statement` - claim_statement
        * `correspondence` - correspondence
        * `enforceable_title` - enforceable_title
        * `invoice` - invoice
        * `other` - other
        * `payment_proof` - payment_proof
        * `reminder` - reminder
        * `rental_agreement` - rental_agreement
      enum:
        - bank_statement
        - claim_statement
        - correspondence
        - enforceable_title
        - invoice
        - other
        - payment_proof
        - reminder
        - rental_agreement
      type: string
    MessageAuthorTypeEnum:
      description: |-
        * `api` - api
        * `user` - user
        * `paywise` - paywise
      enum:
        - api
        - user
        - paywise
      type: string
    DocumentFailureReasonEnum:
      enum:
        - page_limit_exceeded
        - encrypted
        - corrupt
        - unsupported
        - processing_failed
      type: string
    DocumentParent:
      properties:
        id:
          description: Identifier of the resource that owns the document.
          format: uuid
          readOnly: true
          type: string
        type:
          allOf:
            - $ref: '#/components/schemas/DocumentParentTypeEnum'
          description: |-
            Kind of resource that owns the document.

            * `claim` - claim
            * `message` - message
            * `request_to_client_answer` - request_to_client_answer
            * `rental_agreement` - rental_agreement
            * `enforceable_title` - enforceable_title
          readOnly: true
      required:
        - id
        - type
      type: object
    CaseDocumentStatusEnum:
      enum:
        - pending
        - ready
        - failed
        - rejected
      type: string
    MessageParentTypeEnum:
      description: |-
        * `order` - order
        * `mandate` - mandate
      enum:
        - order
        - mandate
      type: string
    DocumentParentTypeEnum:
      description: |-
        * `claim` - claim
        * `message` - message
        * `request_to_client_answer` - request_to_client_answer
        * `rental_agreement` - rental_agreement
        * `enforceable_title` - enforceable_title
      enum:
        - claim
        - message
        - request_to_client_answer
        - rental_agreement
        - enforceable_title
      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.