Two perspectives
The Public API exposes every case through the lens of the firm holding the API key:
- Sent Cases — cases your firm created and sent to another firm (sender perspective).
- Received Referrals — referrals another firm sent to you (receiver perspective).
Both perspectives share the same underlying data, but each returns only the fields and actions relevant to that role. See the endpoint examples for full request/response details:
Objects
- Case — Primary record containing title, jurisdiction, case type, and client details.
- Referral — A case handoff from a sending firm to a receiving firm. A single case can have multiple referrals (re-referrals), each with its own status and lifecycle.
- Base Case — The canonical case shared across all of its referrals.
Statuses
Every referral progresses through a defined set of statuses. The full enum is:
| Status | Description |
|---|
draft | Case created but not yet sent to a receiving firm. |
sent | Referral dispatched to the receiving firm. |
received | Receiving firm has acknowledged the referral. |
under_evaluation | Receiving firm is evaluating the case. |
investigating | Active investigation is underway. |
signed | Client retainer has been signed. |
in_litigation | Case is in active litigation. |
closing | Case is in the closing process. |
won | Case resolved with a favorable outcome. |
lost | Case resolved with an unfavorable outcome. |
rejected | Receiving firm declined the referral. |
withdrawn | Sending firm withdrew the referral. |
closed | Case is fully closed. |
Closing status
When a referral reaches a terminal state through the close action, a closingStatus is required:
| Closing Status | Meaning |
|---|
won_settled | Case was won or settled. |
lost | Case was lost. |
no_longer_pursuing | Firm elected to stop pursuing the case. |
Status flow
draft -> sent -> received -> under_evaluation -> investigating -> signed -> in_litigation -> closing -> closed
\-> won
\-> lost
sent -> rejected (by receiving firm)
sent -> withdrawn (by sending firm)
Use the GET /sent-cases/{id}/available-statuses or GET /received-referrals/{id}/available-statuses endpoint to discover which transitions are valid for the current state before attempting a status change.
Permissions
- Sending firm — Owns initial case creation. Can edit sender-owned fields (
tier, source) after the case is sent. Can withdraw a referral.
- Receiving firm — Can update notes, financial estimates, phase, lead attorney, and other referral fields after acknowledgment. Can reject, advance, or close a referral.
- Both firms — Can read case details and referral status history through their respective perspective endpoints.
Refer and re-refer logic
A referral is created when a sending firm sends a draft case to a receiving firm.
POST /sent-cases/{id}/refer sends a draft case to a receiving firm or creates a new referral on an existing case (re-refer). Each new referral receives an incremented sequenceNumber.- Only the sending firm (owner of the base case) can refer or re-refer.
- An active network relationship between the sending and receiving firms is required.
- The referrals sub-resource (
/cases/{baseCaseId}/referrals) provides granular lifecycle actions on individual referrals: acknowledge, begin-investigating, sign, start-litigation, close, reject, and withdraw.
# Create a case as a draft
POST /sent-cases
# Send it to a receiving firm (initial refer)
POST /sent-cases/{id}/refer
{ "referentFirmId": "...", "notes": "..." }
# Later, re-refer the same case to a different firm
POST /sent-cases/{id}/refer
{ "referentFirmId": "<different-firm-id>", "notes": "..." }
Common field glossary
Fields that appear across case and referral responses:
| Field | Type | Description |
|---|
cmsId | string | null | External case management system ID — the first non-null value from integrations (Dear Legal, Neos, Clio, SmartAdvocate, Salesforce). Used for flexible ID resolution alongside UUID and reference number. |
tier | integer | null | Case priority tier (1-5). Set by the sending firm. Higher values indicate higher priority. |
ratedTier | integer | null | Tier rating assigned by the receiving firm after evaluation. |
source | string | null | Origin of the case (e.g., “Website Lead”, “Attorney Referral”, “Advertisement”). Free-text field set by the sending firm. |
isRetainerSigned | boolean | Whether the client retainer agreement has been signed. Set to true automatically by the sign lifecycle action, or can be set on case creation. |
requiresUpdate | boolean | System flag indicating the case has pending actions or stale data that the firm should review. |
sequenceNumber | integer | The referral’s position in the chain (starts at 1 for the first referral, increments on re-refer). |
clientFeeAgreementPercentage | number | null | Fee agreement percentage expressed as a decimal between 0 and 1 (e.g., 0.33 = 33%). |
sendingFirmPercentage | number | null | Sending firm’s share expressed as a whole number between 0 and 100 (e.g., 25 = 25%). |
clientFeeAgreementPercentage uses a 0-1 scale while sendingFirmPercentage uses a 0-100 scale. This matches the OpenAPI spec constraints.
Error handling
All error responses follow a consistent envelope with error.code, error.message, and meta.requestId. See Error Handling for the full error code reference table, status code guide, and troubleshooting patterns.
