# CaseXchange Public API

## Docs

- [Cases by status drill-down](https://docs.casexchange.com/api-reference/analytics/cases-by-status-drill-down.md): Returns cases filtered by a given status and context (sent or received).
- [Export bundled analytics report](https://docs.casexchange.com/api-reference/analytics/export-bundled-analytics-report.md): Downloads a bundled analytics report as an Excel spreadsheet.
- [Export single analytics category](https://docs.casexchange.com/api-reference/analytics/export-single-analytics-category.md): Downloads a single analytics category as an Excel spreadsheet.
- [Get case analytics](https://docs.casexchange.com/api-reference/analytics/get-case-analytics.md): Returns case-level analytics with optional date range filtering.
- [Get dashboard analytics](https://docs.casexchange.com/api-reference/analytics/get-dashboard-analytics.md): Returns high-level referral analytics for the caller's firm.
- [Homepage period analytics](https://docs.casexchange.com/api-reference/analytics/homepage-period-analytics.md): Returns period counts (today/week/month) with previous-period comparisons for the caller's firm.
- [Received tracking analytics](https://docs.casexchange.com/api-reference/analytics/received-tracking-analytics.md): Returns analytics for referrals received by the caller's firm.
- [Referrals analytics](https://docs.casexchange.com/api-reference/analytics/referrals-analytics.md): Returns referral-level analytics for the caller's firm.
- [Revenue received analytics](https://docs.casexchange.com/api-reference/analytics/revenue-received-analytics.md): Returns revenue analytics for referrals received by the caller's firm.
- [Revenue sent analytics](https://docs.casexchange.com/api-reference/analytics/revenue-sent-analytics.md): Returns revenue analytics for referrals sent by the caller's firm.
- [Sent tracking analytics](https://docs.casexchange.com/api-reference/analytics/sent-tracking-analytics.md): Returns analytics for referrals sent by the caller's firm.
- [Delete a document](https://docs.casexchange.com/api-reference/documents/delete-a-document.md): Permanently deletes the specified document from the case and S3. Requires FULL tier.
- [Get document download URL](https://docs.casexchange.com/api-reference/documents/get-document-download-url.md): Returns a short-lived pre-signed S3 URL for downloading the specified document.
- [List documents for a case](https://docs.casexchange.com/api-reference/documents/list-documents-for-a-case.md): Returns all documents attached to the specified case.
- [Upload a document](https://docs.casexchange.com/api-reference/documents/upload-a-document.md): Uploads a file and attaches it to the specified case (multipart/form-data). Requires STANDARD tier. Maximum file size 50 MB.
- [Error Handling](https://docs.casexchange.com/api-reference/error-handling.md): Practical guidance for handling validation, auth, permission, and rate-limit errors in the CaseXchange Public API
- [Analytics](https://docs.casexchange.com/api-reference/examples/analytics.md): Dashboard and case analytics
- [Documents](https://docs.casexchange.com/api-reference/examples/documents.md): Document upload, download, and management
- [Firms](https://docs.casexchange.com/api-reference/examples/firms.md): Firm directory and profile management
- [Messages](https://docs.casexchange.com/api-reference/examples/messages.md): Send messages to partner firms on referrals
- [Network](https://docs.casexchange.com/api-reference/examples/network.md): Manage the firm's private referral network relationships
- [Received Referrals](https://docs.casexchange.com/api-reference/examples/received-referrals.md): Referrals received by your firm (receiver perspective)
- [Reference Data](https://docs.casexchange.com/api-reference/examples/reference-data.md): Case types, jurisdictions, and counties
- [Referrals](https://docs.casexchange.com/api-reference/examples/referrals.md): Referral sub-resources — lifecycle actions and management
- [Routing](https://docs.casexchange.com/api-reference/examples/routing.md): Referral routing rules and evaluation
- [Sent Cases](https://docs.casexchange.com/api-reference/examples/sent-cases.md): Cases created and sent by your firm (sender perspective)
- [Status Updates](https://docs.casexchange.com/api-reference/examples/status-updates.md): Query status updates across cases and referrals
- [Create a link between a referral and an external system record](https://docs.casexchange.com/api-reference/external-links/create-a-link-between-a-referral-and-an-external-system-record.md)
- [List all external links for the authenticated firm](https://docs.casexchange.com/api-reference/external-links/list-all-external-links-for-the-authenticated-firm.md): Returns a paginated list of all active external links filtered by external system. Each link includes referral metadata (current status, valid transitions). Uses INNER JOIN so orphaned links (referral deleted) are excluded from results and pagination counts.
- [Look up an external link by system + externalId](https://docs.casexchange.com/api-reference/external-links/look-up-an-external-link-by-system-+-externalid.md)
- [Replace an external link (soft-delete old, create new)](https://docs.casexchange.com/api-reference/external-links/replace-an-external-link-soft-delete-old-create-new.md)
- [Soft-delete an external link](https://docs.casexchange.com/api-reference/external-links/soft-delete-an-external-link.md)
- [Get firm by ID](https://docs.casexchange.com/api-reference/firms/get-firm-by-id.md): Returns a single firm by its UUID.
- [Get the caller's firm](https://docs.casexchange.com/api-reference/firms/get-the-callers-firm.md): Returns the firm associated with the API key making the request.
- [List available firms](https://docs.casexchange.com/api-reference/firms/list-available-firms.md): Returns firms the authenticated firm can send referrals to, from their private network and/or the public directory. Includes resolved case type display names and referral instructions.
- [List firms directory](https://docs.casexchange.com/api-reference/firms/list-firms-directory.md): Returns a directory of all active firms on the platform.
- [Update the caller's firm](https://docs.casexchange.com/api-reference/firms/update-the-callers-firm.md): Updates editable fields on the API key's own firm. Requires FULL tier.
- [Identity echo: firm + API key tier](https://docs.casexchange.com/api-reference/identity/identity-echo:-firm-+-api-key-tier.md): Returns the firm and API key tier currently authenticated. Used by the CloudLex browser extension during onboarding to verify a pasted key and surface the firm name + tier to the user. Open to any tier (read_only and above). Distinct from `/firms/me`, which returns the full firm record without the A…
- [Bulk import cases via CSV](https://docs.casexchange.com/api-reference/import/bulk-import-cases-via-csv.md): Creates or upserts cases from a CSV file upload. Requires FULL tier. Maximum file size 20 MB.
- [Bulk update cases via CSV](https://docs.casexchange.com/api-reference/import/bulk-update-cases-via-csv.md): Updates existing cases from a CSV file. Only existing cases are affected — no new records created. Requires FULL tier. Note: the 'notes' field has field-level RBAC — only the receiving (referent) firm can update it. The referring firm's requests to update 'notes' will be rejected per-row.
- [Integration Overview](https://docs.casexchange.com/api-reference/index.md): How to use the CaseXchange API reference and Postman collection
- [Accept a referral (provider-side)](https://docs.casexchange.com/api-reference/med-cases/accept-a-referral-provider-side.md): Transitions an UNDER_REVIEW referral to ACCEPTED. The firm is notified.
- [Acknowledge receipt of a referral (provider-side)](https://docs.casexchange.com/api-reference/med-cases/acknowledge-receipt-of-a-referral-provider-side.md): Transitions a SENT referral to UNDER_REVIEW. The firm is notified.
- [Close a referral (firm-side)](https://docs.casexchange.com/api-reference/med-cases/close-a-referral-firm-side.md): Closes a referral. Non-admin firm users can only close from `treatment_complete`. ADMIN can close from any non-terminal status. The provider is notified.
- [Create a med case](https://docs.casexchange.com/api-reference/med-cases/create-a-med-case.md): Creates a new Med Xchange case. All body fields are optional — a minimal create can be submitted with just `patientFirstName` and `patientLastName`. Requires STANDARD tier.
- [Create a referral on a med case](https://docs.casexchange.com/api-reference/med-cases/create-a-referral-on-a-med-case.md): Creates a new referral on the specified Med Xchange case. `providerId` is required. Requires STANDARD tier.
- [Delete a med case (not supported)](https://docs.casexchange.com/api-reference/med-cases/delete-a-med-case-not-supported.md): This endpoint intentionally returns 405. Deleting med cases is not supported. Set `isArchived` to `true` via PUT instead.
- [Get a referral on a med case](https://docs.casexchange.com/api-reference/med-cases/get-a-referral-on-a-med-case.md): Returns a single referral by UUID on the specified Med Xchange case.
- [Get med case by ID](https://docs.casexchange.com/api-reference/med-cases/get-med-case-by-id.md): Returns a single Med Xchange case by UUID.
- [List med cases](https://docs.casexchange.com/api-reference/med-cases/list-med-cases.md): Returns all Med Xchange cases visible to the caller's firm. Supports pagination, full-text search, and archived filtering.
- [List referrals on a med case](https://docs.casexchange.com/api-reference/med-cases/list-referrals-on-a-med-case.md): Returns all referrals attached to the specified Med Xchange case. The list is unpaginated.
- [Mark treatment as complete on a referral (provider-side)](https://docs.casexchange.com/api-reference/med-cases/mark-treatment-as-complete-on-a-referral-provider-side.md): Transitions an IN_TREATMENT referral to TREATMENT_COMPLETE. The firm is notified.
- [Mark treatment as started on a referral (provider-side)](https://docs.casexchange.com/api-reference/med-cases/mark-treatment-as-started-on-a-referral-provider-side.md): Transitions an ACCEPTED referral to IN_TREATMENT.
- [Reject a referral (provider-side)](https://docs.casexchange.com/api-reference/med-cases/reject-a-referral-provider-side.md): Transitions an UNDER_REVIEW referral to REJECTED with a reason. The firm is notified.
- [Update a med case](https://docs.casexchange.com/api-reference/med-cases/update-a-med-case.md): Updates an existing Med Xchange case. All body fields are optional. Requires STANDARD tier.
- [Update a referral on a med case](https://docs.casexchange.com/api-reference/med-cases/update-a-referral-on-a-med-case.md): Updates an existing referral on the specified Med Xchange case. All body fields are optional. Requires STANDARD tier.
- [Withdraw a referral (firm-side)](https://docs.casexchange.com/api-reference/med-cases/withdraw-a-referral-firm-side.md): Withdraws a referral from any non-terminal status. The provider is notified. Available to firm users on the case's handling firm.
- [Send a message on a referral](https://docs.casexchange.com/api-reference/messages/send-a-message-on-a-referral.md): Sends a message to the partner firm on a referral. Optionally requests a status change. Triggers an email notification to the opposite firm. When the identifier resolves to a base case, the message is sent on the most recent accessible referral.
- [Create or update outbound network relationship](https://docs.casexchange.com/api-reference/network/create-or-update-outbound-network-relationship.md): Creates a new outbound network relationship with the specified firm, or updates it if one already exists. Requires STANDARD tier.
- [Get inbound network firm detail](https://docs.casexchange.com/api-reference/network/get-inbound-network-firm-detail.md): Returns detailed information about a firm in the caller's inbound network, including relationship configuration and firm capabilities.
- [Get outbound network firm detail](https://docs.casexchange.com/api-reference/network/get-outbound-network-firm-detail.md): Returns detailed information about a firm in the caller's outbound network, including relationship configuration and firm capabilities.
- [List pending network relationships](https://docs.casexchange.com/api-reference/network/list-pending-network-relationships.md): Returns a list of pending network relationship requests, both inbound (firms requesting to refer to the caller) and outbound (firms the caller is waiting on).
- [Update existing outbound network relationship](https://docs.casexchange.com/api-reference/network/update-existing-outbound-network-relationship.md): Updates an existing outbound network relationship with the specified firm. Returns 404 if no relationship exists. Requires STANDARD tier.
- [Update inbound network relationship (accept/reject)](https://docs.casexchange.com/api-reference/network/update-inbound-network-relationship-acceptreject.md): Updates an existing inbound network relationship from the specified firm. Can be used to accept or reject a pending relationship, or update instructions. Requires STANDARD tier.
- [Add a notification email address](https://docs.casexchange.com/api-reference/notifications/add-a-notification-email-address.md): Adds an email address to the firm's notification list. Requires FULL tier.
- [Get notification preferences](https://docs.casexchange.com/api-reference/notifications/get-notification-preferences.md): Returns the notification preferences for the caller's firm.
- [List notification email addresses](https://docs.casexchange.com/api-reference/notifications/list-notification-email-addresses.md): Returns all notification email addresses configured for the caller's firm.
- [Update notification preferences](https://docs.casexchange.com/api-reference/notifications/update-notification-preferences.md): Updates the notification preferences for the caller's firm. Requires FULL tier.
- [List case types](https://docs.casexchange.com/api-reference/reference-data/list-case-types.md): Returns all active case types available for creating referrals.
- [List counties](https://docs.casexchange.com/api-reference/reference-data/list-counties.md): Returns counties, optionally filtered by one or more jurisdiction codes (comma-separated).
- [List custom field definitions for a case type](https://docs.casexchange.com/api-reference/reference-data/list-custom-field-definitions-for-a-case-type.md): Returns all active custom field definitions for a given case type, including metadata needed to render forms and validate input.
- [List jurisdictions](https://docs.casexchange.com/api-reference/reference-data/list-jurisdictions.md): Returns all jurisdictions (US states and territories) supported by the platform.
- [Acknowledge a referral](https://docs.casexchange.com/api-reference/referrals/acknowledge-a-referral.md): Transitions a SENT referral to RECEIVED, acknowledging it on behalf of the receiving firm. Only the referent firm may acknowledge. An optional `reason` may be provided. Tier: STANDARD.
- [Begin closing workflow for a referral](https://docs.casexchange.com/api-reference/referrals/begin-closing-workflow-for-a-referral.md): First step of the two-step close workflow. Transitions a referral from SIGNED or IN_LITIGATION to CLOSING. Only `closingStatus` is required. Optional `reason` is written to the status_updates row's message. Optional `closureReason` is written to the formal closure-reason column on the case (required…
- [Begin investigating a referral](https://docs.casexchange.com/api-reference/referrals/begin-investigating-a-referral.md): Transitions a RECEIVED referral to INVESTIGATING. Only the referent firm may call this action. An optional `reason` may be provided. Tier: STANDARD.
- [Delete a referral](https://docs.casexchange.com/api-reference/referrals/delete-a-referral.md): Permanently deletes a DRAFT referral. Only the referring firm may delete a referral. Active referrals (status other than DRAFT) cannot be deleted — use withdraw or reject instead. Tier: FULL.
- [Finalize closing — transition CLOSING to CLOSED](https://docs.casexchange.com/api-reference/referrals/finalize-closing-—-transition-closing-to-closed.md): Second step of the two-step close workflow. Transitions a referral from CLOSING to CLOSED. Required `closureReason` is written to the case's closureReason column. Optional `reason` is written to the status_updates row's message; when omitted, the message defaults to `"Case closed. Reason: ${closureR…
- [Get a referral](https://docs.casexchange.com/api-reference/referrals/get-a-referral.md): Returns a single referral by UUID. Accessible to both the referring and referent firm. Tier: READ_ONLY.
- [Get allowed next status transitions for a referral](https://docs.casexchange.com/api-reference/referrals/get-allowed-next-status-transitions-for-a-referral.md): Returns the allowed next status transitions for this referral, scoped to the calling firm's party (sender or receiver). The party is auto-detected from the calling firm — there is no need for the caller to specify it. Tier: READ_ONLY.
- [Get referral status history](https://docs.casexchange.com/api-reference/referrals/get-referral-status-history.md): Returns all historical status transitions for a referral. Accessible to both the referring and referent firm. Tier: READ_ONLY.
- [List referrals](https://docs.casexchange.com/api-reference/referrals/list-referrals.md): Returns all referrals where your firm is either the referring or referent party. Supports pagination, status filtering, and is scoped to your API key's firm. Tier: READ_ONLY.
- [Reject a referral](https://docs.casexchange.com/api-reference/referrals/reject-a-referral.md): Rejects an incoming referral. Can be called on SENT or RECEIVED referrals. Only the referent firm may reject. A `reason` explaining the rejection is required. Tier: STANDARD.
- [Send a referral](https://docs.casexchange.com/api-reference/referrals/send-a-referral.md): Transitions a DRAFT referral to SENT, dispatching it to the specified receiving firm. Only the referring firm may send. An optional `reason` and `notes` may be provided. Tier: STANDARD.
- [Sign a referral](https://docs.casexchange.com/api-reference/referrals/sign-a-referral.md): Marks a referral as signed by the client, transitioning it to SIGNED. Only the referent firm may call this action. An optional `reason` may be provided. Tier: STANDARD.
- [Start litigation on a referral](https://docs.casexchange.com/api-reference/referrals/start-litigation-on-a-referral.md): Transitions a SIGNED referral to IN_LITIGATION. Only the referent firm may call this action. An optional `reason` may be provided. Tier: STANDARD.
- [Update a referral](https://docs.casexchange.com/api-reference/referrals/update-a-referral.md): Updates mutable fields on a referral. The `notes` field has field-level RBAC — only the referent firm may update it. Financial estimates and dates may be updated by both parties. Tier: STANDARD.
- [Withdraw a referral](https://docs.casexchange.com/api-reference/referrals/withdraw-a-referral.md): Withdraws a SENT referral back to DRAFT status. Only the referring firm may withdraw. A `reason` explaining the withdrawal is required. Tier: STANDARD.
- [Response Format](https://docs.casexchange.com/api-reference/response-format.md): Response envelopes, pagination metadata, and error conventions used across the CaseXchange Public API
- [Create a routing rule](https://docs.casexchange.com/api-reference/routing/create-a-routing-rule.md): Creates a new referral routing rule for the firm. Requires FULL tier.
- [Delete a routing rule](https://docs.casexchange.com/api-reference/routing/delete-a-routing-rule.md): Deletes a routing rule. Requires FULL tier.
- [Evaluate re-referral routing for an existing case](https://docs.casexchange.com/api-reference/routing/evaluate-re-referral-routing-for-an-existing-case.md): Evaluates routing rules for an existing case as if it were being re-referred. Extracts the case profile (case type, jurisdiction, county, tier, category) from the existing case record and matches it against the caller's routing rules.
- [Evaluate routing rules for a case profile](https://docs.casexchange.com/api-reference/routing/evaluate-routing-rules-for-a-case-profile.md): Evaluates the caller's routing rules against a hypothetical case profile and returns the highest-priority matching rule along with its ordered list of firm assignments. Each assignment includes the target firm's ID, name, and any referral instructions (resolved from the firm relationship or the firm…
- [List routing rules](https://docs.casexchange.com/api-reference/routing/list-routing-rules.md): Returns the referral routing rules configured for the caller's firm.
- [Update a routing rule](https://docs.casexchange.com/api-reference/routing/update-a-routing-rule.md): Updates an existing routing rule. Requires FULL tier.
- [Create a sent case](https://docs.casexchange.com/api-reference/sent-cases/create-a-sent-case.md): Creates a new case from the sender perspective. The case starts in DRAFT status unless a referentFirmId is provided, in which case it is immediately sent. Requires STANDARD tier.
- [Get available statuses](https://docs.casexchange.com/api-reference/sent-cases/get-available-statuses.md): Returns the available next status transitions for a sent case, from the sender perspective. Accepts UUID, reference number, or Salesforce record ID.
- [Get sent case](https://docs.casexchange.com/api-reference/sent-cases/get-sent-case.md): Returns full detail for a sent case. Accepts UUID, reference number, or Salesforce record ID. Includes a nested referrals array summarising every referral on the case.
- [List sent cases](https://docs.casexchange.com/api-reference/sent-cases/list-sent-cases.md): Returns a paginated list of cases sent by the API key's firm (sender perspective). Lean response shape: id, referenceNumber, salesforceId, receivingFirmName, receivingFirmId, status, closingStatus, updatedAt.
- [Send or re-refer a case](https://docs.casexchange.com/api-reference/sent-cases/send-or-re-refer-a-case.md): Sends a DRAFT case to a receiving firm, or re-refers a previously rejected/withdrawn case. Creates a new referral targeting the specified firm. Requires STANDARD tier.
- [Update sent case](https://docs.casexchange.com/api-reference/sent-cases/update-sent-case.md): Partially updates sender-editable fields on a sent case. At least one field must be provided. Accepted fields: tier, source, salesforceId, salesforceObjectType. Accepts UUID, reference number, or Salesforce record ID.
- [List all status updates](https://docs.casexchange.com/api-reference/status-updates/list-all-status-updates.md): Returns all status updates across all cases and referrals the firm has access to. Paginated.
- [Look up status updates by flexible identifier](https://docs.casexchange.com/api-reference/status-updates/look-up-status-updates-by-flexible-identifier.md): Returns all status updates and messages for a case or referral identified by UUID, reference number, or CMS ID. When the identifier resolves to a base case, returns status updates across all accessible referrals.
- [Deactivate a user](https://docs.casexchange.com/api-reference/users/deactivate-a-user.md): Deactivates a user in the caller's firm. Sets the user to inactive, clears security tokens, and revokes all active sessions. Requires FULL tier.
- [Invite a user](https://docs.casexchange.com/api-reference/users/invite-a-user.md): Invites a new user to the caller's firm. Requires FULL tier.
- [List the caller's firm users](https://docs.casexchange.com/api-reference/users/list-the-callers-firm-users.md): Returns all users belonging to the API key's own firm.
- [Update a user](https://docs.casexchange.com/api-reference/users/update-a-user.md): Updates a user in the caller's firm. Requires FULL tier.
- [Integration Workflows](https://docs.casexchange.com/api-reference/workflows.md): End-to-end flows for the CaseXchange Public API (/api/public/v1)
- [JWT Authentication](https://docs.casexchange.com/auth/jwt.md): Authenticate directly with CaseXchange using username/password plus refresh cookies
- [Case Types](https://docs.casexchange.com/concepts/case-types.md): Standardized case-type classifications used in the CaseXchange Public API
- [Case Lifecycle](https://docs.casexchange.com/concepts/cases.md): Understand how the CaseXchange Public API models referrals, statuses, and ownership
- [Firms & Directory](https://docs.casexchange.com/concepts/firms.md): How the CaseXchange Public API represents law firms, your own firm profile, and the available-firms directory
- [Jurisdictions & Counties](https://docs.casexchange.com/concepts/jurisdictions.md): Reference data for state, territory, and county coverage
- [CaseXchange Public API](https://docs.casexchange.com/index.md): Everything you need to build with the CaseXchange platform
- [Quickstart](https://docs.casexchange.com/quickstart.md): Launch your CaseXchange integration in three steps

## OpenAPI Specs

- [openapi](https://docs.casexchange.com/api-reference/openapi.yml)