Skip to main content

​
Start here

This tab is the reference for the CaseXchange Public API. Read this page and the three that follow it for the conventions every endpoint shares — the response envelope, the error codes, and the end-to-end flows — then open Endpoints in the sidebar for the operation-by-operation reference, which is generated from the OpenAPI schema and is the source of truth.

​
Postman Collection

The fastest way to explore and test the API is with the pre-built Postman collection. Every request includes automated test scripts that validate responses and chain environment variables (IDs, tokens) between requests.

Download Collection

All Public API endpoints with examples, tests, and variable chaining.

Download Environment

Production environment with pre-configured variables.

​
What is covered

  • The Public API (/api/public/v1) provides endpoints for sent cases, received referrals, firms, documents, routing rules, analytics, and network management — all authenticated via X-API-Key.
  • The Internal API (/api/v1) covers authentication, session management, and API key administration — authenticated via JWT bearer tokens.
  • Shared request/response schemas and standardized error envelopes across both API layers.

​
Base URLs

​
Authentication

Public API — include your API key in every request:
Internal API — use JWT bearer tokens (relative to /api/v1):
  1. POST /api/v1/auth/login
  2. GET /api/v1/auth/me
  3. POST /api/v1/auth/refresh-session (when the access token expires)
  4. Continue requests with Authorization: Bearer <accessToken>
See the JWT Guide for full details.

​
Response conventions

Public API responses use a consistent envelope with data, meta (requestId + timestamp), and optional pagination. Errors use error.code + error.message. See:

​
Rate limiting

Public API endpoints are rate limited per API key. Rate limit headers are included on every response: When you exceed the limit, you will receive a 429 Too Many Requests response. Implement exponential backoff and respect the X-RateLimit-Reset header before retrying.

​
Webhooks

CaseXchange can push referral lifecycle events — new referrals, acknowledgements, status changes, notes, documents — to an HTTPS endpoint you control, so you do not have to poll. Subscriptions are managed through POST /webhooks and its sibling endpoints with a standard-tier key; every delivery is signed with HMAC-SHA256 and retried on failure. Webhooks are a signal that something changed, not a synchronisation feed: keep reconciling against GET /status-updates and GET /received-referrals, which remain the source of truth. See the Webhooks tab for the setup guide, event catalog, signature verification, and delivery guarantees.

​
Versioning

The Public API is currently at v1. New fields may be added to response objects without a version bump — your client should ignore unknown fields. Breaking changes (removed fields, changed types, removed endpoints) will be communicated in advance and will result in a new version path (/v2).

​
OpenAPI spec

The full OpenAPI 3.0 spec is available for download to generate client libraries or import into tools:

​
How to navigate the endpoints

  • Open Endpoints in the sidebar and expand the group you need — the groups match the OpenAPI tags and stay collapsed until you click one.
  • Open any endpoint page to inspect required headers, path/query params, request body schema, and documented responses.
  • Use the Postman collection to run real requests against your environment with one click.

Examples

Representative cURL requests and success/error responses.

Error Handling

Troubleshooting patterns for validation, auth, permissions, and conflicts.

Response Format

Response envelope, pagination, and common schema conventions.

Workflows

End-to-end implementation flows across multiple endpoints.