> ## Documentation Index > Fetch the complete documentation index at: https://docs.casepathiq.com/llms.txt > Use this file to discover all available pages before exploring further. # Matter placement and updates > Create, replace, patch, and retrieve partner-owned Matter data. A Matter is the CasePath IQ-owned legal recovery file created or updated from an External legal instruction. The authenticated Source integration owns its Source representation; CasePath IQ owns its workflow, legal, and lifecycle state. ## Routes | Method | Path | Use | | - | - | - | | `PUT` | `/v1/clients/{clientCode}/matters/by-client-reference/{clientReferenceId}` | Create (`If-None-Match: *`) or fully replace (`If-Match`) partner-owned fields | | `PATCH` | Same path | Apply a JSON Merge Patch (`If-Match`) | | `GET` | Same path | Read by partner client reference ID | | `GET` | `/v1/matters/{matterId}` | Read by CasePath IQ Matter ID | 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. > [!NOTE] > > 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 ```json theme={null} { "clientCode": "SDCC", "clientReferenceId": "SDCC-2026-00482", "matterType": "debt_recovery", "parties": [ { "role": "debtor", "type": "person", "isPrimaryLiable": true, "name": { "givenName": "Aoife", "middleNames": ["Máire"], "familyName": "Murphy" }, "dateOfBirth": "1984-03-12", "customerNumber": "C-99102", "addresses": [ { "type": "correspondence", "line1": "12 Example Street", "city": "Tallaght", "state": "Dublin", "countryCode": "IE" } ], "emails": [ { "address": "aoife.murphy@example.com", "type": "personal", "isPrimary": true } ], "phones": [ { "number": "+353871234567", "type": "mobile", "isPrimary": true }, { "number": "+35314605000", "type": "landline", "extension": "204", "isPrimary": false } ] }, { "role": "debtor", "type": "person", "isPrimaryLiable": false, "name": { "givenName": "Cormac", "familyName": "Murphy" }, "addresses": [ { "type": "correspondence", "line1": "12 Example Street", "city": "Tallaght", "state": "Dublin", "countryCode": "IE" } ] } ], "debt": { "type": "commercial_rates", "currency": "EUR", "outstandingAmount": "1250.00" }, "instruction": { "summary": "Commercial rates arrears — instruct legal recovery", "historyNotes": "Reminders issued; last contact noted on file", "requestedAction": "letter_before_action" } } ``` `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`: ```json theme={null} { "role": "debtor", "type": "organisation", "isPrimaryLiable": true, "legalName": "Example Organisation Limited", "companyNumber": "123456", "tradingNames": ["Example Stores"] } ``` Do not split an organisation name into person-name fields. Email addresses and phone numbers are separate optional typed arrays of up to 10 entries each, so send every contact you hold. Every entry includes `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 with `isPrimaryLiable: true` * For every Party: a complete person name or nonblank organisation legal name * For every Party: `role` set to `debtor` * `debt.outstandingAmount` as 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 `line1` plus `city` and/or `state` The placement minimum is checked for every Party and fails the whole request. One unaddressable Party returns `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 | Behaviour | PUT | PATCH | | - | - | - | | Create a Matter | Yes | No; missing Matter returns `404` | | Update shape | Full Source replacement | JSON Merge Patch | | Content type | `application/json` | `application/merge-patch+json` | | Omitted fields | Removed if optional | Left unchanged | | Arrays | Send the complete desired array | Replaces the complete array when present | | Identical normalized retry | `200`, no new revision while that representation remains current | Same | | Required precondition | `If-None-Match: *` to create, `If-Match` to replace | `If-Match` | 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. | You are… | Send | If it no longer holds | | - | - | - | | Creating a Matter | `If-None-Match: *` | `412` — the Matter already exists; read it instead of replaying the create | | Updating a Matter | `If-Match: ""` from the representation you read | `412` — someone else wrote first; GET, reconcile, decide again | | Sending neither | — | `428 precondition_required`, nothing mutated | Take the tag from the `ETag` response header or the `etag` field of the representation; the [sync list](https://docs.casepathiq.com/synchronization.md) 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 `..`. > [!WARNING] > > The tag changes whenever **anything** partner-visible changes — Source facts, balance, lifecycle state or intake status — not only when `sourceRevisionId` advances. That is deliberate: it stops you overwriting Source facts while holding a stale view of the money or the lifecycle. 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. > [!WARNING] > > If a replacement changes any Party's canonical identity, that Party must also carry `addresses`, `emails`, and `phones` explicitly in the same request. Its address replacement must contain exactly one usable correspondence address. Omitted recipient collections return `400 recipient_rebind_required` with no mutation. 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.outstandingAmount` or `debt.currency`. * PUT cannot change currency. * PUT must repeat the authoritative current outstanding balance. * External payments, refunds, and reversals change balance through immutable [Payment observations](https://docs.casepathiq.com/payments-and-lifecycle.md#payment-observations). A disallowed opening-balance change returns `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: * `matterId` * `sourceRevisionId` and `lifecycleStateId` * `etag`, also returned as the `ETag` header * `status` and `intakeStatus` * `createdAt` and `updatedAt` Callers do not send revisions — send the `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. ## Next * [Synchronize changed state](https://docs.casepathiq.com/synchronization.md) * [Record payments and lifecycle commands](https://docs.casepathiq.com/payments-and-lifecycle.md) * [Handle conflicts and retries](https://docs.casepathiq.com/errors-and-retries.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.