> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casexchange.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Workflows

> End-to-end flows for the CaseXchange Public API (/api/public/v1)

## Common workflows

This page maps real integration flows to the Public API endpoints under `/api/public/v1`. Each workflow references the autogenerated endpoint docs and links to example pages where available.

### 1. API key setup

Public API authentication uses long-lived API keys instead of JWT sessions.

1. Log in to the [CaseXchange dashboard](https://dashboard.casexchange.com) or call the Internal API `POST /api/v1/auth/login` to access your account.
2. Create a Public API key from **Settings > API Keys** in the dashboard, or programmatically via `POST /api/v1/public-api-keys`.
3. Include the key in the `X-API-Key` header for all subsequent Public API calls.
4. Verify connectivity and confirm your firm context with `GET /firms/me`.

```bash theme={null}
curl -X GET "https://api.casexchange.com/api/public/v1/firms/me" \
  -H "X-API-Key: cxp_ro_your_key_here"
```

Implementation tips:

* Call `GET /firms/me` immediately after key creation to verify the key is scoped to the expected firm.
* API keys are issued at three tiers (`read_only`, `standard`, `full`). Choose the minimum tier your integration needs.
* Store keys in a secrets manager -- never commit them to source control.

See [Firms examples](/api-reference/examples/firms) for response shapes.

***

### 2. Sending a case referral

This workflow covers creating a case, attaching it to a receiving firm, and monitoring progress.

1. `GET /case-types` and `GET /jurisdictions` to fetch reference data for building your case payload.
2. `GET /firms/available` to find a receiving firm that accepts the relevant case type and jurisdiction.
3. `POST /sent-cases` to create a draft case with claimant details, case type, and jurisdiction.
4. `POST /sent-cases/{id}/refer` to send the draft to the chosen receiving firm.
5. Monitor the referral with `GET /sent-cases` (list view) and `GET /sent-cases/{id}` (detail view).

```bash theme={null}
# Create a draft case
curl -X POST "https://api.casexchange.com/api/public/v1/sent-cases" \
  -H "X-API-Key: cxp_std_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Doe v. Smith - Auto Accident",
    "caseType": "Personal Injury",
    "jurisdiction": "NY",
    "clientFirstName": "Jane",
    "clientLastName": "Doe"
  }'

# Refer the draft to a firm
curl -X POST "https://api.casexchange.com/api/public/v1/sent-cases/{id}/refer" \
  -H "X-API-Key: cxp_std_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "referentFirmId": "b2c3d4e5-6789-0abc-def1-234567890abc"
  }'
```

Implementation tips:

* Treat lifecycle transitions (refer, close, reject) as separate action endpoints, not generic updates.
* Handle `403` (permission denied) and `409` (conflict / invalid state transition) on referral actions.
* Use query parameters on `GET /sent-cases` (`status`, `sort`, `order`) to build filtered dashboards.

See [Sent Cases examples](/api-reference/examples/sent-cases), [Reference Data examples](/api-reference/examples/reference-data), and [Firms examples](/api-reference/examples/firms).

***

### 3. Receiving and processing referrals

This workflow covers the receiver side -- accepting incoming referrals and moving them through the case lifecycle.

1. `GET /received-referrals` to list incoming referrals with pagination and filtering.
2. `GET /received-referrals/{id}` for full referral detail. PII fields are masked until the referral is acknowledged.
3. `POST /cases/{baseCaseId}/referrals/{id}/acknowledge` to accept the referral and unmask claimant PII.
4. `PATCH /received-referrals/{id}` to update editable fields such as `leadAttorneyName`, `phase`, `notes`, and custom metadata.
5. Use lifecycle action endpoints to advance the referral:
   * `POST /received-referrals/{id}/begin-investigating`
   * `POST /received-referrals/{id}/sign`
   * `POST /received-referrals/{id}/start-litigation`
   * `POST /received-referrals/{id}/close`
   * `POST /received-referrals/{id}/reject`

Implementation tips:

* PII masking is enforced at the API level -- you cannot read claimant details until you acknowledge.
* Expect permission differences between the sending and receiving firm on the same case.
* Poll `GET /received-referrals` with the `status` filter to drive intake queues.

See [Received Referrals examples](/api-reference/examples/received-referrals) and [Status Updates examples](/api-reference/examples/status-updates).

***

### 4. Documents and messages

Upload documents to a case and communicate with the partner firm on a referral.

**Documents:**

1. `POST /cases/{caseId}/documents` to upload a file (`multipart/form-data`).
2. `GET /cases/{caseId}/documents` to list all documents on a case.
3. `GET /cases/{caseId}/documents/{docId}/download` to retrieve a pre-signed download URL.

```bash theme={null}
# Upload a document
curl -X POST "https://api.casexchange.com/api/public/v1/cases/{caseId}/documents" \
  -H "X-API-Key: cxp_std_your_key_here" \
  -F "file=@medical-records.pdf"
```

**Messages:**

4. `POST /messages/send` to send a message to the partner firm on a referral. Optionally include a `requestedStatus` to prompt a status transition.

```bash theme={null}
curl -X POST "https://api.casexchange.com/api/public/v1/messages/send" \
  -H "X-API-Key: cxp_std_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "message": "Please provide an update on the client deposition."
  }'
```

Implementation tips:

* Use the pre-signed download URL from the response rather than constructing direct object storage paths.
* Document uploads support common file types (PDF, DOCX, JPEG, PNG). Check the `allowedMimeTypes` field on your firm profile for the full list.
* Messages trigger email notifications to the partner firm.

See [Documents examples](/api-reference/examples/documents) and [Messages examples](/api-reference/examples/messages).

***

### 5. Routing rules

View routing rules and evaluate routing for a given case profile.

1. `GET /routing/rules` to view the routing rules configured for your firm.
2. `GET /routing/evaluate` to test which firm a referral would route to for a given case type and jurisdiction combination, without actually creating a referral.

```bash theme={null}
# View routing rules
curl -X GET "https://api.casexchange.com/api/public/v1/routing/rules" \
  -H "X-API-Key: cxp_ro_your_key_here"

# Test routing evaluation
curl -X GET "https://api.casexchange.com/api/public/v1/routing/evaluate?caseType=Personal%20Injury&jurisdiction=NY" \
  -H "X-API-Key: cxp_ro_your_key_here"
```

Implementation tips:

* Use `GET /routing/evaluate` in dry-run or preview UIs before sending referrals.
* Rules can overlap -- the API evaluates them in priority order and returns the first match.

See [Routing examples](/api-reference/examples/routing).