What the current v1 contract covers
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.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, Synchronization 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:
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 and RFC 9110 §13.1 / 428.
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 carrieslifecycle (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.
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:
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 documents client references, related contacts, status/stage and incremental reads. Retain our Matter-centred intake and stable partner reference.
- Clio custom fields and Actionstep custom data distinguish field definitions from values. Prefer a documented typed schema for actual pilot data.
- Actionstep documents separates file upload from association with a Matter. Keep document transfer separate from source facts.