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

# Download document

> The file itself, with its original filename in `Content-Disposition`.



## OpenAPI

````yaml get /openapi/documents/{id}/download
openapi: 3.0.3
info:
  title: incaseof.law Partner API
  version: 1.0.0
  description: >
    The incaseof.law partner API (`/openapi/*`): create claims and debtors,
    attach invoices and documents, record

    payments, follow a claim through collection and take the judicial-step
    decision.


    This document is the contract the API is tested against: every path, request
    body and response field here is

    compared with the implementation on each change. A field that is not listed
    here is not part of the API.


    ## Authentication


    Every `/openapi` request carries `Authorization: Bearer <api key>`. API keys
    are opaque strings starting with

    `ico_live_` (not JWTs). Request a key at https://app.incaseof.law/openapi;
    incaseof.law reviews the request and

    sends the key by e-mail.


    - **Organisation keys** act for one creditor organisation.

    - **Partner keys** act for a partner (software vendor, reseller) and its
    customers. Requests that create a claim
      or a debtor name the customer with `customer_id`; reads and updates reach every object of the partner's own
      customers without it. A `customer_id` that does not exist answers `400`, one of another partner `403`.

    ## Errors


    Every error answers `{ "success": false, "message": "…" }`, some with an
    `error` code. Validation errors list the

    failed fields in `details` (see `BadRequest`). Every response carries the
    rate-limit headers (see

    `TooManyRequests`).


    ## Partner intake rules


    Some partner agreements require more than the API's own required fields, and
    some prohibit data. They apply to

    partner keys only, are set per partner account by incaseof.law, and are
    checked **before anything is stored** — a

    refused request leaves no claim, invoice, PDF, payment, document or customer
    behind.


    - **Required fields.** The fields marked *optional unless your partner
    agreement requires it* exist for every
      caller. When your agreement requires one, a request without it answers `400` naming each missing field
      (`"message": "default_date required"`, one `details` entry per field). They are checked on creation only: on
      `POST /openapi/claims` (`creditor_confirmation`), both invoice endpoints (`default_date`,
      `creditor_reminder_dates` — not with `default_basis: bgb_286_3` —, `contract_date`, `subject`),
      `POST /openapi/debtors` (`legal_representative`) and `POST /openapi/customers` (`legal_form`,
      `legal_representative` — `owner` for a sole trader —, `billing_email`, `payout_account`, `vat_deductible`).
    - **Prohibited data (health data).** When your agreement prohibits health
    data, these free-text fields are checked:
      invoice `subject` (on the PDF upload also `description`), `invoice_issuer`, `invoice_recipient`; payment `notes`;
      document `description`; customer `metadata`. A value that looks like a health insurance number (KVNR: a capital
      letter and nine digits), an institution code (IK: a nine-digit number on its own), the word `PZN`, `Pflegegrad`,
      `Diagnose`, the word `ICD` or an ICD code with its dot (`F32.1`) answers `400` with
      `"error": "PROHIBITED_DATA"` and the field in `details` (the value is never echoed). Use neutral wording, e.g.
      "Privatärztliche Leistung vom 01.09.2026".

    ## Webhooks


    incaseof.law can push events to a partner-controlled HTTPS endpoint whenever
    a claim's lifecycle changes:

    `claim.collection_stage_changed` and `claim.status_changed`. See the
    **Webhooks** section at the bottom of this

    document for the payload shape, header reference, signature scheme and retry
    policy.
servers:
  - url: https://service.incaseof.law
    description: Production API
  - url: https://sandbox.incaseof.law
    description: Partner sandbox (test data only, sandbox keys — see "Partner sandbox")
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Service availability
  - name: Claims
    description: Claims, their status and the judicial-step decision
  - name: Debtors
    description: Debtors of your claims
  - name: Invoices
    description: The invoices a claim is based on
  - name: Payments
    description: Payments the debtor made
  - name: Documents
    description: Supporting documents of a claim
  - name: Customers
    description: A partner's customers (the creditors it works for)
paths:
  /openapi/documents/{id}/download:
    get:
      tags:
        - Documents
      summary: Download document
      description: The file itself, with its original filename in `Content-Disposition`.
      operationId: downloadDocument
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Unauthorized:
      description: The `Authorization` header is missing, or the key is invalid or expired.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: Unauthorized
              message:
                type: string
                example: >-
                  Invalid API token. Please check your token or request a new
                  one.
    NotFound:
      description: The object does not exist or is not reachable with this key.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Claim not found
    TooManyRequests:
      description: >
        The key's hourly limit is used up — every `/openapi` request can answer
        this. Requests are counted per key and

        clock hour (UTC); the limit is agreed per key (default 1 000 per hour).
        Retry after `Retry-After` seconds.

        Every answer — not only this one — carries `X-RateLimit-Limit`,
        `X-RateLimit-Remaining` and `X-RateLimit-Reset`.
      headers:
        Retry-After:
          description: Seconds until the next hour starts and requests are admitted again.
          schema:
            type: integer
            example: 1260
        X-RateLimit-Limit:
          description: Requests allowed per hour for this key.
          schema:
            type: integer
            example: 1000
        X-RateLimit-Remaining:
          description: Requests left in the current hour (0 here).
          schema:
            type: integer
            example: 0
        X-RateLimit-Reset:
          description: Unix time (seconds) at which the count starts again.
          schema:
            type: integer
            example: 1790002800
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: Too Many Requests
              message:
                type: string
                example: >-
                  Rate limit exceeded. Your limit is 1000 requests per hour.
                  Please try again later.
              details:
                type: object
                properties:
                  limit:
                    type: integer
                    example: 1000
                  window:
                    type: string
                    example: 1 hour
                  resets_at:
                    type: string
                    format: date-time
    InternalServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              message:
                type: string
                example: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key (`ico_live_…`), sent as `Authorization: Bearer <key>`. Not a
        JWT.

````

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