Routes
The body
clientCode must exactly match the path. The client reference ID is partner-supplied, opaque, case-sensitive, and stable for the life of the Matter.
parties[] holds every Party against whom recovery is instructed on this Matter — a sole liable person, joint owners of a rated property, or an organisation. Each entry’s required role records why that Party is linked to the Matter; Partner API v1 accepts debtor.
Exactly one entry sets isPrimaryLiable: true: the Party your source file identifies as liable. That flag records liability only; it does not select a correspondence recipient, and it does not make the other Parties less liable.
Joint liability never multiplies the obligation. Two liable Parties on a EUR 1,250 instruction is one Matter with one
debt.outstandingAmount of 1250.00 — not two Matters, and not EUR 2,500.Source representation
clientReferenceId is your system’s stable identifier for the source record, such as a database ID or account number. It is the path key; you may repeat it in the body, where it must match the path. matterType is the kind of legal work instructed: debt_recovery is the only supported value and the default. debt.type is optional: commercial_rates, rent_arrears, housing_loan or other.
A person uses type: person with name.givenName, optional name.middleNames[], name.familyName and an optional dateOfBirth.
An organisation uses type: organisation with one legalName, and optionally a companyNumber (for example a CRO number) and up to five tradingNames:
type and isPrimary; at most one entry in each collection may be primary, and the rest are secondary contacts. Email types are personal, work and other; phone types are mobile, landline, work and other. Phone numbers use E.164 format, with an optional extension of up to six digits. The same number may appear more than once with different extensions; staff see it once, with each type and extension beside it.
Placement minimum
A new Matter must include:- Between 1 and 10 entries in
parties[], exactly one withisPrimaryLiable: true - For every Party: a complete person name or nonblank organisation legal name
- For every Party:
roleset todebtor debt.outstandingAmountas fixed two-decimal Money and an allowed ISO 4217 currency- For every Party: exactly one address with
type: correspondence - For each of those addresses, either a valid Irish Eircode or
line1pluscityand/orstate
400 rather than creating a Matter with a Party that can never be written to.
A zero opening balance is valid, but the Matter is non-actionable until its balance becomes positive. Rated-property, registered, and site addresses may also be supplied; they do not satisfy the correspondence requirement.
Missing placement data returns 400 with no Matter created. Unknown fields and arbitrary metadata are rejected.
PUT or PATCH
The first successful PUT returns
201 Created. A materially different accepted PUT or PATCH returns 200, creates the next server-owned Source revision, and advances updatedAt.
Conditional writes
Every Matter write must carry a precondition, and CasePath IQ evaluates it atomically with authorization and the mutation itself.
Take the tag from the
ETag response header or the etag field of the representation; the sync list returns it for every Matter too.
If-Match: * is accepted and matches any current Matter (it returns 412 when none exists), but it gives up the stale-write protection of a specific tag. A closed Matter refuses PUT and PATCH with 409 matter_closed until it is reopened, whatever the precondition.
Free-text fields reject anything that looks like a payment card number (13–19 digits that pass the Luhn check) with 400 card_number_detected, and client reference IDs and payment IDs may not be . or ...
This is what makes a delayed request safe. If your request for content A is delayed behind a request for content B, A still carries the tag it was composed against, that tag is no longer current, and A is refused 412 instead of silently reverting the Matter.
After a lost response, GET and reconcile. Never reapply an old body under a freshly read tag — that is precisely the write the precondition exists to stop.
Payment observations and lifecycle commands do not take If-Match; they have their own preconditions, the external payment ID and predecessorLifecycleId.
Replacing parties
parties is always replaced as a whole collection. JSON Merge Patch replaces arrays wholesale, so there is no way to patch one Party in place: if you send parties, send every Party you intend the Matter to have, each one complete. Omit parties entirely to leave the collection untouched.
This rule prevents a new person or organisation from inheriting the previous Party’s correspondence details.
Balance updates
Use Matter PUT only to correct a mistaken opening balance or currency before CasePath IQ records recovery activity. After recovery activity begins:- PATCH cannot change
debt.outstandingAmountordebt.currency. - PUT cannot change currency.
- PUT must repeat the authoritative current outstanding balance.
- External payments, refunds, and reversals change balance through immutable Payment observations.
409 opening_balance_change_not_allowed. A stale balance assertion returns 409 balance_mismatch.
Responses and concurrency
Successful PUT, PATCH, and GET responses return the Source representation plus:matterIdsourceRevisionIdandlifecycleStateIdetag, also returned as theETagheaderstatusandintakeStatuscreatedAtandupdatedAt
etag as If-Match instead. Serialize writes per Matter. If different writes race, CasePath IQ accepts at most one; the loser returns 412 precondition_failed when its precondition was already superseded, or 409 source_write_conflict when two writes reach the lock together. Read the current Matter before deciding whether to retry.