Inbound Webhooks

How to send data INTO Lexamica from your system.

---

Table of Contents

1. Overview

2. Key Terms

3. How It Works

4. Available Operations

5. Common Use Cases

6. FAQ

7. Technical Reference

---

🎯 Overview

📌 TL;DR

Inbound webhooks let you push data to Lexamica—create cases, respond to invitations, upload files, and more. Send requests using your field names, and the mapping engine transforms them automatically.

Inbound webhooks are endpoints where you send data TO Lexamica. They're the primary way to:

• Create new cases and send them to the Relay Engine for partner matching

• Accept or decline case invitations from other firms

• Upload documents and files to cases

• Post case updates and status changes

• Manage the invitation lifecycle

All inbound webhook endpoints use your Public Key for authentication and your Mapping ID to transform your data format to Lexamica's.

---

📖 Key Terms

Term	Definition
Inbound Webhook	An API endpoint that receives data from your system and processes it in Lexamica.
Relay Engine	Lexamica's automatic matching system that routes cases to appropriate partner firms.
Case Invitation	A request from one firm to another to handle a case. Can be accepted, declined, or evaluated.
Case Update	A status note or update posted to a case, typically required every 90 days.
Mapping ID	The identifier of the mapping configuration to use for transforming your data.

---

⚙️ How It Works

When you send data to an inbound webhook:

Inbound Webhook Flow
────────────────────

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your System   │────▶│  Integration    │────▶│    Lexamica     │
│                 │     │      API        │     │                 │
│ POST request    │     │                 │     │ Case created,   │
│ with your data  │     │ 1. Authenticate │     │ invitation      │
│ format          │     │ 2. Load mapping │     │ processed, etc. │
│                 │     │ 3. Transform    │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                │
                                ▼
                        ┌─────────────────┐
                        │    Response     │
                        │                 │
                        │ Transformed back│
                        │ to YOUR format  │
                        └─────────────────┘

Key points:

1. You send data using your field names (e.g., contact_first_name)

2. The mapping transforms it to Lexamica's fields (e.g., client.firstName)

3. Lexamica processes the request

4. The response is transformed back to your field names

🎯 Key Takeaway

Every inbound webhook URL includes your Mapping ID. The same endpoint can work differently depending on which mapping you use.

---

💡 Available Operations

Case Operations

Operation	Endpoint	Purpose
Send Case	/case/{mapId}/send	Create a case and send to Relay Engine for partner matching
Create Existing	/case/{mapId}/create-existing	Create a case that's already being handled by a known partner
Create Draft	/case/{mapId}/draft	Create a draft case without sending to Relay
Edit Case	/case/{mapId}/edit	Update client or incident details on an existing case
Create Update	/case/{mapId}/update	Post a status update or note to a case
Start Settlement	/case/{mapId}/settlement	Begin the settlement process for a case

Invitation Operations

Operation	Endpoint	Purpose	Who Can Use
Send	/case-invitation/{mapId}/send	Invite a specific firm to handle a case	Case originator
Accept	/case-invitation/{mapId}/accept	Accept an invitation you received	Invitee
Decline	/case-invitation/{mapId}/decline	Decline an invitation with a reason	Invitee
Evaluate	/case-invitation/{mapId}/evaluate	Mark invitation as under evaluation	Invitee
Contact Attempted	/case-invitation/{mapId}/contact-attempted	Mark that you attempted to contact the client	Invitee
Consult Complete	/case-invitation/{mapId}/consult-complete	Mark that consultation is complete	Invitee
Cancel	/case-invitation/{mapId}/cancel	Cancel an invitation you sent	Originator
Close	/case-invitation/{mapId}/close	Close an invitation you sent	Originator
Extend	/case-invitation/{mapId}/extend	Extend the expiration of an invitation	Originator

File Operations

Operation	Endpoint	Purpose
Upload File	/case/{mapId}/file/upload	Upload a file directly to a case
Stream File	/case/{mapId}/file/stream	Upload a file from a URL (for larger files)
Remove File	/case/{mapId}/file/remove	Delete a file from a case

---

📋 Common Use Cases

📗 Use Case: Sending a New Case to Relay

Goal	Create a case and have Lexamica find a matching partner firm
How	POST to the /case/{mapId}/send endpoint with case details
Result	Case enters the Relay Engine; you'll receive events when matched

Request:

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/inbound-webhooks/case/{mapId}/send?Key=your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_first_name": "Jane",
    "contact_last_name": "Smith",
    "contact_email": "[email protected]",
    "contact_phone": "555-123-4567",
    "practice_area": "Personal Injury",
    "incident_date": "2026-01-10",
    "incident_state": "CA",
    "case_description": "Rear-end collision on Highway 101. Client was stopped at red light.",
    "lead_source": "Website Form"
  }'

Response (in your field format):

{
  "case_id": "64f1a2b3c4d5e6f7a8b9c0d3",
  "contact_first_name": "Jane",
  "contact_last_name": "Smith",
  "contact_email": "[email protected]",
  "status": "pending_match",
  "created_at": "2026-01-15T10:30:00.000Z"
}

💡 Tip: Store the case_id in your system—you'll need it for future operations and to correlate webhook events.

📗 Use Case: Accepting an Invitation

Goal	Accept a case invitation that was sent to your firm
How	POST to /case-invitation/{mapId}/accept with the invitation ID
Result	You're now the handler for this case

Request:

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/inbound-webhooks/case-invitation/{mapId}/accept" \
  -H "Authorization: Bearer your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "invitation_id": "64f1a2b3c4d5e6f7a8b9c0d4"
  }'

Response:

{
  "invitation_id": "64f1a2b3c4d5e6f7a8b9c0d4",
  "case_id": "64f1a2b3c4d5e6f7a8b9c0d3",
  "status": "accepted",
  "accepted_at": "2026-01-15T14:22:00.000Z"
}

📗 Use Case: Posting a Case Update

Goal	Add a status update to a case (required every 90 days)
How	POST to /case/{mapId}/update with case ID and update content
Result	Update is recorded and visible to all parties

Request:

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/inbound-webhooks/case/{mapId}/update" \
  -H "Authorization: Bearer your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "case_id": "64f1a2b3c4d5e6f7a8b9c0d3",
    "update_title": "Discovery Phase Complete",
    "update_content": "All depositions completed. Moving to settlement negotiations.",
    "update_type": "status"
  }'

ℹ️ Note: The update_type field maps to Lexamica's type field. Use status for required status updates or note for general case notes.

📗 Use Case: Uploading a Case Document

Goal	Attach a document to an existing case
How	POST multipart form data to /case/{mapId}/file/upload
Result	File is stored and accessible to case participants

Request:

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/inbound-webhooks/case/{mapId}/file/upload" \
  -H "Authorization: Bearer your_public_key" \
  -F "caseId=64f1a2b3c4d5e6f7a8b9c0d3" \
  -F "file=@/path/to/document.pdf" \
  -F "fileName=medical_records.pdf"

📕 Use Case: Declining an Invitation

Goal	Decline a case invitation with an explanation
How	POST to /case-invitation/{mapId}/decline with reason
Result	Invitation marked as declined; originator is notified

Request:

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/inbound-webhooks/case-invitation/{mapId}/decline" \
  -H "Authorization: Bearer your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "invitation_id": "64f1a2b3c4d5e6f7a8b9c0d4",
    "decline_reason": "Conflict of interest - we represent the defendant."
  }'

---

❓ FAQ

❓ "What's the difference between Send and Create Existing?"

🔍 Quick Check:

• ✅ Need Lexamica to find a partner? Use Send (/case/{mapId}/send)

• ✅ Already know who's handling it? Use Create Existing (/case/{mapId}/create-existing)

📝 Full Answer:

• Send submits the case to the Relay Engine, which automatically matches it with partner firms based on practice area, location, and availability.

• Create Existing creates a case that you're already tracking with a known partner—it skips the matching process entirely.

---

❓ "How do I know if my case was matched?"

🔍 Quick Check:

• ✅ Set up a webhook subscription for Case Relay Matched events

• ✅ Or poll stored events if you can't receive webhooks

📝 Full Answer: After sending a case to Relay, you'll receive events as the matching process progresses:

• Case Relay Matched — A partner was found and invited

• Case Relay Rejected — No partners available for this case type/location

• Case Relay Missed — Partners were invited but none accepted

• Case Invitation Accepted — A partner accepted the case

See the Webhook Subscriptions guide for setting up event notifications.

---

❓ "What fields are required for sending a case?"

📝 Full Answer: For the /case/{mapId}/send endpoint, your mapping must resolve these required fields:

Lexamica Field	Description
client.firstName	Client's first name
client.lastName	Client's last name
client.phoneNumber	Client's phone number
caseType	Practice area (e.g., "Personal Injury")
incident.date	Date of the incident
incident.address.state	State where incident occurred
incident.synopsis	Description of what happened

All other fields are optional but recommended for better matching.

---

❓ "Can I use the same mapping for different operations?"

📝 Full Answer: It depends on the model type:

• Case mappings work with all case operations (send, edit, update, settlement)

• CaseInvitation mappings work with all invitation operations (accept, decline, etc.)

You can have multiple mappings of the same type for different purposes (e.g., a "full mapping" for new cases and a "minimal mapping" for updates).

---

❓ "What happens if my request fails?"

🔍 Quick Check:

• ✅ Check the error response for details

• ✅ Common issues: missing required fields, invalid mapping, authentication errors

📝 Full Answer: Error responses include details about what went wrong:

{
  "error": "Bad Request",
  "message": "Missing required field: client.phoneNumber",
  "details": {
    "missingFields": ["client.phoneNumber"]
  }
}

Common error causes:

• 400 Bad Request: Missing required fields or invalid data format

• 401 Unauthorized: Invalid or missing API key

• 404 Not Found: Invalid organization ID, mapping ID, or case/invitation ID

---

🔧 Technical Reference

Endpoint URL Pattern

All inbound webhook endpoints follow this pattern:

POST /organization/{orgId}/inbound-webhooks/{resource}/{mapId}/{action}

• {orgId} — Your organization ID

• {resource} — case, case-invitation, or file-related

• {mapId} — Your mapping ID

• {action} — The operation (send, accept, etc.)

Authentication

Use your Public Key via either:

• Query parameter: ?Key=your_public_key

• Header: Authorization: Bearer your_public_key

Required Fields by Operation

🔧 Technical Deep-Dive: Required Field Mappings

Each operation has specific field requirements. Your mapping must be able to resolve these fields from your request data.

Send Case (/case/{mapId}/send):

• client.firstName, client.lastName, client.phoneNumber

• caseType, incident.date, incident.address.state, incident.synopsis

Edit Case (/case/{mapId}/edit):

• _id (the case ID to edit)

Create Update (/case/{mapId}/update):

• referral (case ID), title, content, type

Invitation Operations:

• Most require just _id (invitation ID)

• Decline also requires declineReason

• Extend requires expires (new expiration date)

Get Available URLs

You can retrieve all inbound webhook URLs for your organization:

curl -X GET \
  "https://integration.lexamica.com/organization/{orgId}/inbound-webhooks/urls" \
  -H "Authorization: Bearer your_private_key"

This returns a list of all endpoints with your organization ID pre-populated.

---

Last updated: January 2026