> ## 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.

# Core concepts

> Understand Matter identity, ownership, lifecycle, payments, and synchronization before integrating.

The Partner API is easier to implement once its ownership rules are clear. Read this page before the workflow guides.

## Integration scope

One partner key authenticates one Source integration. Current grants then authorize the Client codes that integration may access.

```text theme={null}
Partner system → Source integration → Client code → Matter
```

Authentication proves which integration is calling. The Client grant decides which records it may reach.

## Matter

A **Matter** is the CasePath IQ-owned legal recovery file created or updated from an External legal instruction. It combines:

* The Party, its Matter-specific role, and correspondence details
* The current outstanding debt
* The requested legal-recovery instruction
* CasePath IQ-owned status, intake state, and lifecycle state

Use **Matter**, not Case, in CasePath IQ integrations.

## Partner and CasePath IQ identifiers

| Identifier | Owner | Use |
| - | - | - |
| `clientReferenceId` | Partner | Stable, case-sensitive key in the request URL |
| `matterId` | CasePath IQ | Stable CasePath IQ identifier returned in responses |

A client reference ID is unique within the authenticated Source integration and Client. Keep it stable for the life of the Matter, and do not put names, account numbers, or other personal data in URL identifiers.

## Source representation

The authenticated Source integration owns the **Source representation**: `parties`, `debt`, and `instruction`. CasePath IQ owns workflow and legal state, including:

* `matterId`
* `status` and `intakeStatus`
* `sourceRevisionId`
* `lifecycleStateId`
* `etag`, the precondition for your next write
* Staff, audit, readiness, and workflow history

Matter PUT and PATCH requests never contain a caller revision. Instead they carry an HTTP precondition — `If-None-Match: *` to create, `If-Match` to update — and a materially different accepted write creates the next server-owned Source revision and a new `etag`. See [conditional writes](https://docs.casepathiq.com/matters.md#conditional-writes).

## Party identity, role, and correspondence

A **Party** is the neutral person or organisation linked to a Matter. A Matter carries a `parties[]` collection, because an instructed file may name several liable Parties — joint owners of a rated property, or joint tenants. The required `role` explains why each Party is involved; Partner API v1 accepts `role: debtor`, meaning recovery is instructed against that Party.

Exactly one entry sets `isPrimaryLiable: true`, recording which Party the source file identifies as liable. Joint liability does not multiply the obligation: the Matter keeps one `debt.outstandingAmount`.

A person Party has a structured `name` with `givenName`, optional `middleNames[]`, and `familyName`. An organisation Party has one `legalName`.

Every Party on a new Matter needs exactly one usable `correspondence` address, because each Party is separately addressable. Rated-property, registered, and site addresses may also be supplied, but they do not select the correspondence recipient. Email addresses and phone numbers are optional typed collections.

> [!WARNING]
>
> Changing Party identity with PATCH also requires explicit replacement of `addresses`, `emails`, and `phones` in the same request. This prevents a new Party from inheriting the previous Party's recipient data.

## Balance and payment evidence

The Matter carries the opening outstanding balance. Once recovery activity begins, payment, refund, and reversal evidence is recorded as immutable **Payment observations**.

Do not rewrite an accepted observation. Correct it with a reversal observation followed by the corrected observation. An opening-balance mistake may be corrected by Matter PUT only before CasePath IQ records recovery activity.

## Lifecycle state

Pause, close, clear-pause, and reopen form one linear lifecycle chain. Every Matter response includes the current `lifecycleStateId`. Send that value as `predecessorLifecycleId` with the next lifecycle command.

An accepted lifecycle command applies immediately. `effectiveOn` records the partner's claimed business date (from 2000-01-01 to 31 days ahead); it does not schedule a future transition. Clearing a pause or reopening a Matter does not automatically resume legal work or outbound communication.

## Incremental synchronization

`GET /v1/matters` returns a minimized current-state projection, not an event stream. `updatedSince` is required, inclusive, and combined with opaque page tokens for paging.

Sync items exclude Party identity, addresses, contacts, instructions, and internal workflow data. Use GET one when you need the full partner-facing Matter representation.

## Continue

* [Create your first Matter](https://docs.casepathiq.com/quickstart.md)
* [Place and update Matters](https://docs.casepathiq.com/matters.md)
* [Synchronize current state](https://docs.casepathiq.com/synchronization.md)
* [Record payments and lifecycle changes](https://docs.casepathiq.com/payments-and-lifecycle.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.