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

# Update debtor

> Update a debtor. Only send the fields you change; `addresses` and `communication_channels` **replace** all
existing entries.

`customer_id` relinks the debtor to another of your customers **in the same organisation** (`400` for a
customer in another organisation; partner keys: `403` for a customer of another partner, `400` for `null`).

On a debtor that is a person, a `company` block turns it into a company only together with
`company.company_name` (otherwise `400`); a block of nulls only (e.g. `company: { uid: null }`) is ignored.




## OpenAPI

````yaml patch /openapi/debtors/{id}
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/debtors/{id}:
    patch:
      tags:
        - Debtors
      summary: Update debtor
      description: >
        Update a debtor. Only send the fields you change; `addresses` and
        `communication_channels` **replace** all

        existing entries.


        `customer_id` relinks the debtor to another of your customers **in the
        same organisation** (`400` for a

        customer in another organisation; partner keys: `403` for a customer of
        another partner, `400` for `null`).


        On a debtor that is a person, a `company` block turns it into a company
        only together with

        `company.company_name` (otherwise `400`); a block of nulls only (e.g.
        `company: { uid: null }`) is ignored.
      operationId: updateDebtor
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDebtorInput'
            examples:
              updatePerson:
                summary: Update person details
                value:
                  person:
                    first_name: Jane
                    last_name: Smith
                    birth_date: '1985-03-15'
              updateAddress:
                summary: Replace the addresses
                value:
                  addresses:
                    - street: Main Street 123
                      zip: '1010'
                      city: Wien
                      country: AT
                      is_primary: true
              updateCompany:
                summary: Update company debtor
                value:
                  acting_as: company
                  company:
                    company_name: Tech Solutions GmbH
                    firmenbuchnummer: FN 123456x
                  iban: DE89370400440532013000
                  bic: COBADEFFXXX
      responses:
        '200':
          description: Debtor updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseDebtor'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    UpdateDebtorInput:
      type: object
      description: Only send the fields you change.
      properties:
        acting_as:
          type: string
          enum:
            - person
            - company
        debtor_type:
          type: string
          enum:
            - privateperson
            - protocolled_company
            - unprotocolled_company
        customer_id:
          type: string
          format: uuid
          nullable: true
          description: Relink the debtor to another customer in the same organisation.
        iban:
          type: string
          minLength: 15
          maxLength: 34
        bic:
          type: string
          minLength: 8
          maxLength: 11
        person:
          type: object
          properties:
            salutation:
              type: string
              enum:
                - mr
                - mrs
                - diverse
                - ''
              description: Same spellings as on create; '' removes the salutation
            gender:
              type: string
              enum:
                - mr
                - mrs
                - diverse
                - ''
              nullable: true
              description: >-
                Alias of salutation, read only when salutation is absent, null
                or empty; an unrecognised gender is ignored
            first_name:
              type: string
            last_name:
              type: string
            birth_date:
              type: string
        company:
          type: object
          properties:
            company_name:
              type: string
            firmenbuchnummer:
              type: string
            not_protocolled:
              type: boolean
            uid:
              type: string
              maxLength: 40
              nullable: true
              description: EU VAT ID; null clears it
        partner_client_reference:
          type: string
          maxLength: 255
          nullable: true
          description: Your own customer number for this debtor; null clears it
        legal_representative:
          nullable: true
          description: Replaces the debtor's guardian or attorney; `null` removes it.
          allOf:
            - $ref: '#/components/schemas/DebtorLegalRepresentative'
        addresses:
          type: array
          description: Replaces all addresses.
          items:
            $ref: '#/components/schemas/AddressUpdateInput'
        communication_channels:
          type: array
          description: Replaces all channels.
          items:
            $ref: '#/components/schemas/CommunicationChannelUpdateInput'
    ApiResponseDebtor:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/DebtorWithKeys'
    DebtorLegalRepresentative:
      type: object
      description: >
        The debtor's legal guardian (Betreuer, Vormund) or attorney
        (Bevollmächtigter), where one exists. Send it only

        then — a debtor without one is sent without this object.
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - guardian
            - attorney
            - other
        name:
          type: string
          minLength: 1
          maxLength: 200
        address:
          type: object
          required:
            - street
            - zip
            - city
            - country
          properties:
            street:
              type: string
            zip:
              type: string
            city:
              type: string
            country:
              $ref: '#/components/schemas/CountryCode'
        email:
          type: string
          format: email
        phone:
          type: string
          maxLength: 50
    AddressUpdateInput:
      type: object
      required:
        - street
        - zip
        - city
        - country
      properties:
        id:
          type: string
          format: uuid
          description: An existing address to keep
        street:
          type: string
        zip:
          type: string
        city:
          type: string
        country:
          $ref: '#/components/schemas/CountryCode'
        is_primary:
          type: boolean
    CommunicationChannelUpdateInput:
      type: object
      required:
        - type
        - value
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - email
            - phone
        value:
          type: string
        is_primary:
          type: boolean
    DebtorWithKeys:
      description: >-
        A debtor as the `/openapi/debtors` endpoints return it — with your keys
        for it.
      allOf:
        - $ref: '#/components/schemas/Debtor'
        - type: object
          properties:
            company:
              nullable: true
              allOf:
                - $ref: '#/components/schemas/DebtorCompany'
                - type: object
                  properties:
                    uid:
                      type: string
                      nullable: true
                      description: EU VAT ID (UID) of the business, normalised
            partner_client_reference:
              type: string
              nullable: true
              description: Your own customer number for this debtor
            legal_representative:
              nullable: true
              description: >-
                The debtor's legal guardian or attorney as you sent it; `null`
                when none.
              allOf:
                - $ref: '#/components/schemas/DebtorLegalRepresentative'
    CountryCode:
      type: string
      description: Country (ISO 3166-1 alpha-2)
      enum:
        - AF
        - AL
        - DZ
        - AD
        - AO
        - AG
        - AR
        - AM
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BT
        - BO
        - BA
        - BW
        - BR
        - BN
        - BG
        - BF
        - BI
        - KH
        - CM
        - CA
        - CV
        - CF
        - TD
        - CL
        - CN
        - CO
        - KM
        - CG
        - CD
        - CR
        - HR
        - CU
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - ET
        - FJ
        - FI
        - FR
        - GA
        - GM
        - GE
        - DE
        - GH
        - GR
        - GD
        - GT
        - GN
        - GW
        - GY
        - HT
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IL
        - IT
        - CI
        - JM
        - JP
        - JO
        - KZ
        - KE
        - KI
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MK
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MR
        - MU
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - NZ
        - NI
        - NE
        - NG
        - KP
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PL
        - PT
        - QA
        - RO
        - RU
        - RW
        - KN
        - LC
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SK
        - SI
        - SB
        - SO
        - ZA
        - KR
        - SS
        - ES
        - LK
        - SD
        - SR
        - SZ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TO
        - TT
        - TN
        - TR
        - TM
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UY
        - UZ
        - VU
        - VA
        - VE
        - VN
        - YE
        - ZM
        - ZW
    Debtor:
      type: object
      properties:
        id:
          type: string
          format: uuid
        customer_id:
          type: string
          format: uuid
          nullable: true
        acting_as:
          type: string
          enum:
            - person
            - company
        debtor_type:
          type: string
          enum:
            - privateperson
            - protocolled_company
            - unprotocolled_company
        person:
          type: object
          nullable: true
          properties:
            salutation:
              type: string
              enum:
                - mr
                - mrs
                - diverse
              nullable: true
            first_name:
              type: string
            last_name:
              type: string
            birth_date:
              type: string
              nullable: true
        company:
          $ref: '#/components/schemas/DebtorCompany'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        communication_channels:
          type: array
          items:
            $ref: '#/components/schemas/CommunicationChannel'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DebtorCompany:
      type: object
      nullable: true
      properties:
        company_name:
          type: string
        firmenbuchnummer:
          type: string
          nullable: true
        not_protocolled:
          type: boolean
    Address:
      type: object
      properties:
        id:
          type: string
          format: uuid
        street:
          type: string
        zip:
          type: string
        city:
          type: string
        country:
          $ref: '#/components/schemas/CountryCode'
        is_primary:
          type: boolean
    CommunicationChannel:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - email
            - phone
        value:
          type: string
        is_primary:
          type: boolean
  responses:
    BadRequest:
      description: >
        The request is invalid. A body that fails validation answers `error:
        VALIDATION_ERROR` with one entry per

        problem in `details` (`path` — the field, as a list of keys and indexes;
        `message`; `code`). Other `400`s carry

        only `message`.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: VALIDATION_ERROR
              message:
                type: string
                example: Validation failed
              details:
                type: array
                items:
                  type: object
                  properties:
                    path:
                      type: array
                      items:
                        oneOf:
                          - type: string
                          - type: integer
                    message:
                      type: string
                    code:
                      type: string
                      example: invalid_type
          examples:
            validationError:
              value:
                success: false
                error: VALIDATION_ERROR
                message: Validation failed
                details:
                  - code: invalid_type
                    expected: string
                    received: undefined
                    path:
                      - invoice_number
                    message: Required
            businessRule:
              value:
                success: false
                message: >-
                  Payment invoice number must match an active collection letter
                  or cost invoice. Active document numbers: ICO-2026-000123
    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.
    Forbidden:
      description: >-
        The key may not do this — for example a `customer_id` of another
        partner.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: Forbidden
              message:
                type: string
                example: This customer does not belong to your partner account.
    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.