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

# Debtors

> Identify the right party, reuse debtor records, and submit or read debtor metadata and events alongside identity data.

A **debtor** is the person or organization from whom you are seeking payment.
The debtor record describes that party; the [claims](/api-docs/case-management-api/concepts/claims)
describe what they owe. Keeping these separate lets you submit several claims
or later orders against the same party without creating a new debtor each time.
Debtors are independently writable resources. Always create or reuse the
debtor before creating the order; an order accepts the primary UUID as
`debtor_id` and other liable parties as `additional_debtor_ids`, not embedded
debtor write objects.

## Identify the right party

Start with the party that incurred the obligation. Whether someone owes money
privately or in a business capacity determines how you describe them.

| Situation | How to represent the debtor |
| - | - |
| A private individual owes money from a personal transaction. | Use a consumer record with the person's identity. |
| A sole proprietor owes money from their business activity. | Use a business record with the proprietor's personal identity and a business legal form when known. A trading name alone is not enough. |
| A company or partnership owes money. | Use a business record with the organization's name and a legal form when known. |

Use the actual contracting party's details from your customer records and
supporting documents. A billing contact or a person who placed an order is not
necessarily the party against whom you have the claim.

A consumer's new `person` object requires `first_name` and `last_name`.
`salutation` is optional: omit it or send `null` or `""` when unknown.
Business persons and legal representatives still require a salutation.
`birth_date` is optional. A new `organization` object requires `name`.
Business debtor `legal_form` is optional; omit it or send `null` or `""` when
unknown. Without a legal form, supply exactly one `person` or `organization`
identity. A supplied catalog code still determines the permitted identity.
When updating an existing person or organization with PATCH, you can send only
the fields that changed; omitted fields keep their current values. Sending
`null` or `""` clears a consumer salutation or business debtor legal form.

### Representatives and additional debtors

Representation and liability describe different relationships. A
representative acts for the debtor; an additional debtor is another party
liable for the order's claims. A person can have both roles, so record the
actual relationship rather than treating every contact as another debtor.

Every additional debtor is jointly and severally liable (Gesamtschuldner) with
the primary debtor for every claim of the order; claims with a different set
of liable debtors are submitted as separate orders.

For minor members or customers, submit the minor as the primary consumer
debtor (`debtor_id`) and include their `person.birth_date`. Create or reuse a
separate consumer debtor record for the adult legal guardian and reference
their UUID in the order's `additional_debtor_ids`. Make sure your contracts
establish the guardian's personal liability for the claims you submit;
guardianship alone does not establish that liability. paywise does not provide
a legal opinion on whether your contracts establish personal liability.

A supplied legal form determines which representative roles are appropriate and
whether representative details are needed before submission. Use the
[legal-form catalog](/api-docs/case-management-api/reference/legal-forms/list-legal-forms)
to find the requirements for the selected form. For how liable parties appear
in an accepted case, see
[Mandates](/api-docs/case-management-api/concepts/mandates).

## Debtor validation rules

Validation helps catch information that would make a claim difficult to
identify, review, or communicate about. Focus on the underlying customer data
when resolving a problem:

| Area | What to check and why it matters |
| - | - |
| Identity | The person's or organization's name, consumer or business capacity, and legal form must fit together. This helps paywise identify the party your claim concerns. |
| Postal address | Provide a complete address with the correct country and one primary address. Postal-code checks catch inconsistencies; a clear primary address avoids ambiguity about where correspondence should go. |
| Contact details | Supply the debtor's known email addresses and phone numbers. Format checks catch common entry mistakes; paywise's own email addresses cannot be used as debtor contact details. |
| Representation and age | Record the correct representative and role for the debtor's legal form. Age information can affect whether the party can be submitted in that role and whether further handling is needed. |
| Supporting information | Use accurate dates of birth, register details, and known bank details. Plausibility and format checks help catch typos; repeated addresses, contact channels, bank accounts, and representatives are rejected within the record. |

The format checks behind that table answer `400 validation_error` with a
field path and a stable code:

| Field | Rule |
| - | - |
| `acting_as` | Every debtor reads back `consumer` or `business`, never blank. `GET /v2/debtors/?acting_as=` accepts exactly those two values, case-sensitively; anything else is `400` on `acting_as` with code `invalid_parameter`. |
| `person.salutation` | Use `mr`, `ms`, or `mx` when supplied. Consumer debtors may omit it or send `null` or `""`; business persons and representatives require it. The value `unspecified` is rejected with code `invalid_choice`, including for legal representatives. Existing records without a supported salutation read back `null`. |
| `addresses[].postal_code` | ASCII digits only. A visually identical non-ASCII digit is `400` with code `invalid` before the country pattern is consulted. |
| `person.birth_date` | `YYYY-MM-DD` in ASCII digits; any other spelling is `400` with code `invalid`. |
| `bank_accounts[].iban` | Non-ASCII characters are `400` with code `invalid_iban`. |
| E-mail addresses | paywise's own domains are refused with code `own_domain_email`, including IDNA and NFKC look-alike spellings; a spelling the format check refuses first answers `invalid_email`. |
| `legal_representatives[i].legal_representatives[]` | A representative listed twice under the same representative is `400` on `legal_representatives[i].legal_representatives[j]` with code `duplicate`. |
| Collection items on `PATCH` | Each item of a replaced `addresses`, `communication_channels`, `bank_accounts`, or `legal_representatives` array must be complete. A missing required field is `400` on `…[i].<field>` with code `required`. |
| `legal_representatives[]` on `PATCH` | Echoing a stored representative with its current `role` keeps that role and its stored liability decision. An item that carries the `id` of a stored representative whose role has no public code — it reads back as `other` — and sends `role: "other"` is `400` on `legal_representatives` with code `unsupported_role`; send a concrete role. Changing a representative to a person clears its `legal_form` and nested representatives. Stored representatives are re-checked against the legal form (`invalid_for_legal_form`) only when `acting_as`, `legal_form`, or the person/organization kind changes. |

Fix inaccurate data in your source system as well as in paywise, so the same
problem does not return with the next order. A valid format does not establish
that an address is deliverable, an account belongs to the debtor, or the claim
is justified.

### Saving a record is different from submitting an order

You can save a debtor before all information needed for collection is
complete. When you finalize an order, paywise also checks submission
readiness, including a complete primary postal address for each debtor and
any representative details required by the legal form. Email addresses,
phone numbers, and bank accounts are not universally required debtor fields.

Age-related cases need particular care. The API rejects underage
representatives and sole proprietors. A minor consumer's record can be saved,
but the order needs additional handling before submission; recording a
guardian relationship alone does not satisfy the current order-readiness
requirements. Follow the
[order readiness guidance](/api-docs/case-management-api/concepts/orders#draft-and-finalization)
for these cases.

If readiness checks fail, the order remains a draft that you can correct.
Successful submission then starts paywise's review; it is not yet acceptance
of the collection case.

## Metadata and events

Create a debtor with optional `metadata` and `events` arrays through
`POST /v2/debtors/`, then reference the returned UUID from orders. Metadata is
a list of `{type, value}` objects and permits repeated types; a debtor-specific
example is `{"type": "user:reference", "value": "CUSTOMER-1001"}`.

Debtor events use the resource's allowed types, such as `registration`, and
the v1 fields `type`, `title`, `occurence`, `your_reference`, `description`,
and `location`. The last three are optional and nullable. The historical
`occurence` spelling is part of the contract. See the
[context format](/api-docs/case-management-api/concepts/claims#metadata-and-events)
and the debtor reference for its exact type enums.

The full debtor read returns its stored context, including values submitted
through the earlier API. Existing debtor UUIDs remain valid in the same company
and environment. Do not recreate the debtor or resubmit its context.
Explicit context changes through `PATCH` are rejected; unrelated changes
preserve metadata and events.

## Reuse and editing

Store the debtor's paywise identifier alongside your own customer reference.
Reuse the record for later orders concerning the same party in the same
capacity. Duplicate checks within a record or order do not replace matching
customers across your own system.

The primary `debtor_id` must not also appear in `additional_debtor_ids`, and an
additional UUID may appear only once. A malformed reference is reported on
`debtor_id` or `additional_debtor_ids[i]`; an unknown or other-company UUID is
a neutral `404`. A duplicate additional party is reported on the list-level
`additional_debtor_ids` with code `duplicate`.

While any linked order is under review, the debtor record is temporarily
locked so the information being reviewed stays consistent: every write,
including a no-op `PATCH {}`, answers `409`. Editing resumes when no linked
order remains in that review phase. Only an order that still holds a claim
under review locks the record; a finished order whose claims were all removed
(or that became a merge husk) does not.

Accepted mandates keep their own debtor snapshot. Updating the reusable
record afterward — its representatives included — supports future orders; it
does not rewrite an existing case, and reusing the record for a new order does
not carry over the co-debtors of an earlier case. The snapshot is not a debtor
resource: mandates and statement rows embed it as a `MandateDebtor` without an
`id`, `GET /v2/debtors/` does not list it (with or without `updated_since`),
`GET` and `PATCH /v2/debtors/{id}/` answer `404` for it, and `debtor_id` or
`additional_debtor_ids` naming it answer `404`
(`No debtor found for the given reference.`). Use the
[case communication workflow](/api-docs/case-management-api/workflows/messages-and-client-requests)
to bring a correction concerning an accepted case to paywise's attention.

<span id="debtor-summaries-on-orders" />

Orders include a compact debtor summary so you can recognize the parties
without retrieving every detail. The summary includes metadata and events.
Open the full debtor record when you need addresses, contact details, bank
accounts, or representatives.

## Implementation reference

For exact fields, formats, limits, and request examples, use the API reference:

* Create a debtor: [POST `/v2/debtors/`](/api-docs/case-management-api/reference/debtors/create-debtor)
* Read the full record: [GET `/v2/debtors/{id}/`](/api-docs/case-management-api/reference/debtors/get-debtor)
* Update a debtor: [PATCH `/v2/debtors/{id}/`](/api-docs/case-management-api/reference/debtors/update-debtor)
* Browse legal forms: [GET `/v2/legal-forms/`](/api-docs/case-management-api/reference/legal-forms/list-legal-forms) — the catalog carries a strong `ETag`; send it back as `If-None-Match` to receive `304 Not Modified` while it is unchanged

To put these records to use, follow
[Submit an order](/api-docs/case-management-api/workflows/submit-an-order).


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