Skip to main content
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.
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

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.

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