Skip to content

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 de-duplication on identificationNumber matters.

Debtor types

Section titled “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

Section titled “Lookup”
Terminal window
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

Section titled “Creating a debtor”

There is no standalone “create debtor” endpoint. A debtor is created (or matched on identificationNumber) from the debtor object you embed when you create an invoice; the record is materialised when that invoice is activated. Onboarding a new debtor therefore happens through its first invoice rather than a separate call.

Updating

Section titled “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.