Manage Debtors

The Debtor resource owns identity, address, and contact data for the parties your client invoices. It is shared across invoices and enforcement actions, so using the same customerNumber for the same party matters.

Debtor types

The same real-world party is represented at a few different levels:

• Client debtor (Debtor, id prefix D.) - the debtor as registered under a single client, unique per client and customer number. This is the record you look up and update; it holds the client-specific identity, address, and contact data.
• System debtor (SystemDebtor) - the tenant-wide view of a debtor, keyed by identificationNumber across all clients. It carries the shared credit/insurance limits, segment, and SNI used for credit decisions, so the same party seen by two clients shares one system debtor.
• Invoice debtor (InvoiceDebtor) - the debtor snapshot captured on a specific invoice (name and addresses as stated at issue time). It is tied to that invoice and does not change if the client debtor is later edited.
• System debtor (internal) (SystemDebtorInternal) - an internal grouping that links a debtor’s records by an internal identification number; mostly used by Quiddly’s own processing and not something integrations create.

Lookup

curl -X POST "https://$HOST/debtors/search" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": { "identificationNumber": "199001011234" },
    "limit": 1
  }'

If the response contains a match, reuse its id.

Creating a debtor

There is no standalone “create debtor” endpoint. A debtor is created (or matched on the client and customerNumber) from the debtor object you embed when you create an invoice; the record is materialised when that invoice is activated. An identificationNumber that differs from the one on the matched debtor replaces it, and the same party sent under a new customerNumber becomes a second client debtor. Onboarding a new debtor therefore happens through its first invoice rather than a separate call.

Updating

PUT /debtors/{id} (requires UpdateDebtors) updates an existing debtor. To change individual fields without clobbering the rest, fetch the current state first, mutate, and PUT it back.