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

# Plan your integration

> Map local-authority workflows to the v1 API and review proposed contract changes.

> [!WARNING]
>
> Sandbox is available at [https://api.sandbox.casepathiq.com](https://api.sandbox.casepathiq.com). This page separates the current Phase 1 API from proposals for partner review. Proposed fields and headers are not part of the current OpenAPI reference; do not send them to a v1 implementation.

The intended flow is: a Local Authority or its Integration partner submits an External legal instruction; CasePath IQ validates and records the Matter; Firm staff review it before legal work; the partner retrieves permitted progress information. An API success records intake, not acceptance of the instruction or permission to send a letter.

## What the current v1 contract covers

| Partner needs to… | Current v1 contract | Limitation to resolve |
| - | - | - |
| Create an instructed Matter | [PUT by Client code and client reference ID](https://docs.casepathiq.com/matters.md) | Up to 10 debtor Parties and one debt; still not a general multi-role, multi-debt Matter payload |
| Correct source-owned details | PUT or JSON Merge PATCH under [`If-Match`](https://docs.casepathiq.com/matters#conditional-writes) | Recipient rebinding rules apply; `parties` replaces the whole collection |
| Report a payment, refund or reversal | [Immutable Payment observation](https://docs.casepathiq.com/payments-and-lifecycle.md#payment-observations) | Requires a stable payment ID and matching resulting balance; no multi-debt allocation contract |
| Stop or reconsider recovery | [Pause, clear-pause, close or reopen](https://docs.casepathiq.com/payments-and-lifecycle.md#lifecycle-operations) | Clearing the partner restriction never clears independent staff Holds or automatically resumes work |
| Refresh a Matter or catch up nightly | [GET one or paginated updatedSince list](https://docs.casepathiq.com/synchronization.md) | List returns current status, balance, lifecycle reason, Payment observation totals and `etag` — not an event history, a full payment history, or a next planned action |
| Send supporting documents or additional structured instructions | Not defined | Agree the required payloads and receipt semantics before implementation |

Use one stable client reference ID per instructed file. A customer number identifies source customer information; it does not authorize grouping every account for that customer into one Matter. The Source integration is authenticated by its key, and current grants authorize each Client code. The system operator, legal Client, creditor, instructing party and billing party may be different entities.

## Proposed contract changes

These are recommendations for agreement with the pilot partner, not amendments to the current wire contract. Each accepted change must update the canonical contract, OpenAPI, examples and runtime validation together. Until then, use only the existing [Matter representation](https://docs.casepathiq.com/matters.md#source-representation).

> [!NOTE]
>
> Four earlier proposals on this page are now part of the contract: multiple liable Parties (`parties[]`), conditional writes (`ETag` / `If-Match` / `If-None-Match`), a richer sync projection (`lifecycle`, `payments`, `etag`), and `matterType` with `debt.type`. They are documented in [Matters](https://docs.casepathiq.com/matters.md), [Synchronization](https://docs.casepathiq.com/synchronization.md) and the OpenAPI reference. What remains below is still proposal.

### Represent the instructed Matter accurately

`parties[]` now carries the instructed file's liable participants, with one flagged `isPrimaryLiable`. Still open:

| Proposed concept | Meaning and ownership |
| - | - |
| Roles beyond `debtor` | Guarantor, agent, occupier and similar participations, each with an explicit meaning |
| `debts[]` | Source debt references, currency, evidenced opening amount and links to liable participants |
| Instruction attribution | Issuer, recipient, requested work and date; CasePath IQ records acceptance separately |
| Additional typed fields | Only fields needed by the pilot, with documented types, limits and meaning; no arbitrary property bag |

One instruction with two liable participants and a single EUR 1,250 obligation is already expressible, and its total remains EUR 1,250. What is not yet expressible is one Matter with several distinct Debt items, or a participant whose role is not `debtor`.

Confirm whether the pilot needs multiple debts or non-debtor roles before choosing its supported subset. If deferred, document the supported subset and the staff intake route for unsupported files.

### Distinguish updates, payments and further instructions

Keep factual corrections in the source representation. Keep payments as immutable evidence with stable source identity; separate reported balance assertions from reasoned non-payment adjustments. For multiple debts, require explicit allocations or retain the evidence for staff reconciliation and hold demand progression; never guess an allocation or apply the same payment twice.

Propose a separately identifiable further Instruction for new legal authority, and a response tied to a specific Client decision request when the Firm asks whether to proceed. Define issuer authority, stable retry identity and the revision being decided before adding routes. Free-text history is context, not a payment, an approval or a command to resume work.

### Reject stale factual updates — implemented

Matter writes are now conditional: `If-None-Match: *` to create, `If-Match` to update, with `412` on a stale precondition and `428` on a missing one. The entity-tag covers the whole partner-facing representation, including balance and lifecycle state, so an internal Source revision alone can no longer stand in for it. Authorization, precondition and mutation are rechecked atomically. See [conditional writes](https://docs.casepathiq.com/matters.md#conditional-writes) and [RFC 9110 §13.1](https://www.rfc-editor.org/rfc/rfc9110.html#section-13.1) / [428](https://www.rfc-editor.org/rfc/rfc6585.html#section-3).

Still to agree with the pilot: the behaviour after a lost create or update response in their client — GET and reconcile, never reapply old content under a fresh tag — and whether payment-observation and lifecycle identity rules need any change once conditional writes are in use (they are deliberately left distinct).

### Return useful, permitted progress

Nightly catch-up and on-demand reads are retained, and the sync item now carries `lifecycle` (hold, reason, effective date), `payments` (observation totals and the last observation) and `etag`. Those are derived from facts this contract already defines.

Still proposed: a last completed action and date, and a next planned action and date (nullable when unknown). Both need an agreed Workflow Action vocabulary that does not exist in v1, and a planned action is not a promise of dispatch. Also still to define before any further financial exposure: receiving party and reconciliation status. A balance is not a payment history, and observation totals are not a reconciliation statement.

Only publish information approved for that Source integration and Client. Exclude staff notes, privileged advice and internal workflow identifiers. Every visible summary change must advance `updatedAt`; include paused and closed Matters so partners can reconcile them. Keep current-state sync distinct from a complete sequence of events.

The server-issued sync watermark proposed here is now implemented as `syncedThrough` on the final page of each run, held behind the snapshot boundary so commits in flight cannot be skipped, and returned even for an empty run. The client-clock overlap it replaced is gone from the [sync loop](https://docs.casepathiq.com/synchronization.md#recommended-sync-loop).

Still open for the pilot: a maximum lookback for a partner that has not synced in a long time — Salesforce caps its equivalent initial call at 30 days — so a six-month gap becomes a deliberate backfill rather than one very large accidental run. Add webhooks only when a partner needs prompt notifications; retain catch-up reads for missed notifications.

### Transfer documents separately

If the pilot needs statements, notices or other evidence, make document transfer a named deliverable. Propose: authorize a Matter-bound upload, issue a short-lived URL for one server-selected private object, validate the uploaded bytes, scan for malware, then expose an authorized document ID and processing status. Do not place file bytes in the Matter JSON.

Bind each upload to the Firm, Client, Source integration, Matter and stable partner document reference, with expected size/type/checksum and bounded expiry. Recheck current access for status and download; reject cross-scope references and caller-selected storage paths. Only the exact validated object version may become available; later replacement requires validation again. Failed, missing or inconclusive scans remain unavailable. Define duplicate upload, replacement, retention and deletion behavior with the document contract.

## Agree the pilot using concrete examples

Use synthetic examples for a new instruction, corrected recipient details, a payment, a stop instruction and a supporting document. CasePath IQ and the pilot partner should record the following decisions before starting a partner pilot:

| Decision | Required outcome |
| - | - |
| Supported files | Agreed Matter types, participant/debt cardinality, required fields and handling of unsupported files |
| Ownership | Field-by-field writable/read-only mapping; authority to instruct and permitted return information |
| Retries and ordering | Lost responses, duplicate IDs, stale writes and out-of-order financial evidence have documented outcomes |
| Synchronization | Nightly/on-demand cadence, initial boundary, pagination recovery and agreed progress fields |
| Security and access | Environment URLs, Client grants, key rotation/revocation, egress restrictions and support contact supplied during onboarding |
| Verification | Activated sandbox with synthetic data; cross-scope denial, retry/conflict, payment and stop-work checks against HTTP and persistence |

These decisions do not authorize production access. Publish the agreed contract revision and migration notes, update OpenAPI and workflow examples together, then prove the implemented sandbox behavior. Preserve an explicitly versioned contract for any already-integrated clients; never silently change required fields or write semantics. A passing documentation build is not runtime or deployment proof.

## Design references

These sources informed the proposals; their capabilities are not CasePath IQ functionality:

* [Clio Matters](https://docs.developers.clio.com/guides/clio-manage/matters/) documents client references, related contacts, status/stage and incremental reads. Retain our Matter-centred intake and stable partner reference.
* [Clio custom fields](https://docs.developers.clio.com/guides/clio-manage/custom-fields/) and [Actionstep custom data](https://docs.actionstep.com/custom-data-collections/) distinguish field definitions from values. Prefer a documented typed schema for actual pilot data.
* [Actionstep documents](https://docs.actionstep.com/uploading-and-downloading-documents/) separates file upload from association with a Matter. Keep document transfer separate from source facts.

## Next

* [Understand ownership and identifiers](https://docs.casepathiq.com/concepts.md)
* [Read the current v1 contract examples](https://docs.casepathiq.com/quickstart.md)
* [Check error and retry behavior](https://docs.casepathiq.com/errors-and-retries.md)


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