Integration Workflows

​

Common workflows

​

1. API key setup

1. Log in to the CaseXchange dashboard 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.

curl -X GET "https://api.casexchange.com/api/public/v1/firms/me" \
  -H "X-API-Key: cxp_ro_your_key_here"

• 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.

​

2. Sending a case referral

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).

# 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"
  }'

• 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.

​

3. Receiving and processing referrals

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

• 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.

​

4. Documents and messages

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.

# 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"

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

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."
  }'

• 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.

​

5. Routing rules

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.

# 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"

• 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.