Skip to main content
A debtor is the person or organization from whom you are seeking payment. The debtor record describes that party; the 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. 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 to find the requirements for the selected form. For how liable parties appear in an accepted case, see 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: The format checks behind that table answer 400 validation_error with a field path and a stable code: 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 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 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 to bring a correction concerning an accepted case to paywise’s attention. 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: To put these records to use, follow Submit an order.