Import Existing Cases with Webhooks

Import cases you're already tracking and receive status updates via webhooks.

---

🎯 Overview

📌 TL;DR

You have cases already being handled by specific partner firms outside of Lexamica. Import them to track status updates and settlements through the platform, with real-time webhook notifications.

This guide is for you if:

• You have existing referral relationships you want to track in Lexamica

• You already know which firm is handling each case (no Relay matching needed)

• You want webhook notifications for status updates and settlements

What you'll build:

• A Case mapping for importing case data

• Import cases with specific handler firms

• Webhook subscriptions for updates and settlements

Key difference from other originator guides:

• Uses /case/{mapId}/create-existing instead of /case/{mapId}/send

• Skips the Relay Engine—you specify the handler directly

• No relay events (matched/rejected)—just updates and settlements

---

📖 Key Terms

Term	Definition
Existing Case	A case already being handled, imported for tracking purposes
Partner Firm ID	The Lexamica ID of the firm handling the case

---

⚙️ Architecture

Import Existing Cases (Webhooks)
────────────────────────────────

┌─────────────────┐                     ┌─────────────────┐
│   Your System   │                     │   Your System   │
│                 │                     │                 │
│ Import existing │                     │ Webhook Handler │
│ case with known │                     │                 │
│ handler firm    │                     │ • Updates       │
│                 │                     │ • Settlements   │
└────────┬────────┘                     └────────▲────────┘
         │                                       │
         │ POST /create-existing                 │ Webhooks
         ▼                                       │
┌─────────────────────────────────────────────────────────┐
│                   LEXAMICA                              │
│                                                         │
│  Case Created ───▶ Linked to Partner ───▶ Track Status │
│  (No Relay)           Firm                              │
│                                                         │
│  Events: Case Update Made, Case Settlement,            │
│          Case Stage Changed                            │
└─────────────────────────────────────────────────────────┘

---

📋 Prerequisites

Credentials:

• Organization ID, Public Key, and Private Key from Lexamica

• Partner Firm IDs for the firms handling your cases

Infrastructure:

• A publicly accessible HTTPS endpoint for webhooks

Foundational Docs:

• Organizations and Authentication — understand your API keys

• Mapping Engine — how field transformations work

• Inbound Webhooks — sending data to Lexamica

• Webhook Subscriptions — receiving events from Lexamica

💡 Tip: To get Partner Firm IDs, contact Lexamica support or use the platform to look them up.

---

💡 Step-by-Step Implementation

Step 1: Create Your Case Mapping

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/mapping/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Existing Case Import Mapping",
    "modelName": "Case",
    "fieldMappings": [
      { "lexamicaField": "_id", "foreignField": "lexamica_case_id", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "client.firstName", "foreignField": "client_first_name", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "client.lastName", "foreignField": "client_last_name", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "client.email", "foreignField": "client_email", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "client.phoneNumber", "foreignField": "client_phone", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "caseType", "foreignField": "practice_area", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "incident.date", "foreignField": "incident_date", "lexamicaFieldType": "Date", "foreignFieldType": "String" },
      { "lexamicaField": "incident.address.state", "foreignField": "incident_state", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "incident.synopsis", "foreignField": "description", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "customFields.original_case_id", "foreignField": "original_id", "lexamicaFieldType": "String", "foreignFieldType": "String" }
    ]
  }'

Step 2: Create Webhook Subscriptions

Subscribe to update and settlement events.

# Status updates from handler
curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/webhook-subscriptions/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Case Update Made",
    "url": "https://your-system.com/webhooks/lexamica",
    "secret": "your_webhook_secret",
    "mapping": "your_case_update_mapping_id",
    "description": "Receive status updates on imported cases",
    "active": true
  }'

# Stage changes
curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/webhook-subscriptions/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Case Stage Changed",
    "url": "https://your-system.com/webhooks/lexamica",
    "secret": "your_webhook_secret",
    "mapping": "your_case_mapping_id",
    "description": "Track case stage changes",
    "active": true
  }'

# Settlement info
curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/webhook-subscriptions/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Case Settlement",
    "url": "https://your-system.com/webhooks/lexamica",
    "secret": "your_webhook_secret",
    "mapping": "your_case_mapping_id",
    "description": "Track settlements",
    "active": true
  }'

Step 3: Import Cases with Partner Firm ID

Use the /create-existing endpoint with the partnerFirmId parameter.

Request:

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/inbound-webhooks/case/{mapId}/create-existing?Key=your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "client_first_name": "Jane",
    "client_last_name": "Smith",
    "client_email": "[email protected]",
    "client_phone": "555-123-4567",
    "practice_area": "Personal Injury",
    "incident_date": "2025-06-15",
    "incident_state": "CA",
    "description": "Motor vehicle accident - existing case being tracked.",
    "original_id": "CASE-2025-001",
    "partnerFirmId": "64f1a2b3c4d5e6f7a8b9c0f1"
  }'

Response:

{
  "lexamica_case_id": "64f1a2b3c4d5e6f7a8b9c0d3",
  "client_first_name": "Jane",
  "client_last_name": "Smith",
  "practice_area": "Personal Injury",
  "status": "existing",
  "created": "2026-01-15T10:30:00.000Z"
}

ℹ️ Note: If you omit partnerFirmId, Lexamica runs a projection analysis to suggest potential partners from your network but doesn't send invitations.

---

🔧 Complete Code Example

const express = require('express');
const crypto = require('crypto');
const axios = require('axios');

const app = express();
app.use(express.json({ verify: (req, res, buf) => { req.rawBody = buf; } }));

const config = {
  orgId: process.env.LEXAMICA_ORG_ID,
  publicKey: process.env.LEXAMICA_PUBLIC_KEY,
  privateKey: process.env.LEXAMICA_PRIVATE_KEY,
  webhookSecret: process.env.LEXAMICA_WEBHOOK_SECRET,
  mappingId: process.env.LEXAMICA_CASE_MAPPING_ID,
  baseUrl: 'https://integration.lexamica.com'
};

// Import an existing case
async function importExistingCase(caseData, partnerFirmId) {
  const payload = {
    ...caseData,
    partnerFirmId: partnerFirmId
  };

  const response = await axios.post(
    `${config.baseUrl}/organization/${config.orgId}/inbound-webhooks/case/${config.mappingId}/create-existing`,
    payload,
    {
      headers: { 'Content-Type': 'application/json' },
      params: { Key: config.publicKey }
    }
  );

  // Store the Lexamica ID
  await saveCaseMapping(caseData.original_id, response.data.lexamica_case_id);

  return response.data;
}

// Bulk import example
async function importCasesFromLegacySystem(cases) {
  const results = [];
  
  for (const legacyCase of cases) {
    try {
      const result = await importExistingCase({
        client_first_name: legacyCase.clientFirstName,
        client_last_name: legacyCase.clientLastName,
        client_email: legacyCase.clientEmail,
        client_phone: legacyCase.clientPhone,
        practice_area: legacyCase.caseType,
        incident_date: legacyCase.incidentDate,
        incident_state: legacyCase.state,
        description: legacyCase.description,
        original_id: legacyCase.id
      }, legacyCase.handlerFirmLexamicaId);
      
      results.push({ success: true, originalId: legacyCase.id, lexamicaId: result.lexamica_case_id });
    } catch (error) {
      results.push({ success: false, originalId: legacyCase.id, error: error.message });
    }
  }
  
  return results;
}

// Webhook handler
function verifySignature(rawBody, signature) {
  if (!signature) return false;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', config.webhookSecret)
    .update(rawBody)
    .digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch { return false; }
}

const webhookHandlers = {
  'Case Update Made': async (payload) => {
    console.log(`Update on case ${payload.case_id}: ${payload.title}`);
    await recordUpdate(payload.case_id, {
      title: payload.title,
      content: payload.content,
      date: new Date()
    });
  },
  
  'Case Stage Changed': async (payload) => {
    console.log(`Case ${payload.lexamica_case_id} stage: ${payload.stage}`);
    await updateCaseStage(payload.lexamica_case_id, payload.stage);
  },
  
  'Case Settlement': async (payload) => {
    console.log(`Settlement on case ${payload.lexamica_case_id}`);
    await markCaseSettling(payload.lexamica_case_id, {
      settlementDate: new Date(),
      // Settlement details in payload
    });
  }
};

app.post('/webhooks/lexamica', async (req, res) => {
  const signature = req.headers['x-lexamica-signature'];
  const eventType = req.headers['x-lexamica-event'];
  
  if (!verifySignature(req.rawBody, signature)) {
    return res.status(401).send('Invalid signature');
  }
  
  res.status(200).send('OK');
  
  const handler = webhookHandlers[eventType];
  if (handler) {
    try {
      await handler(req.body);
    } catch (error) {
      console.error(`Error processing ${eventType}:`, error);
    }
  }
});

// Placeholder functions
async function saveCaseMapping(originalId, lexamicaId) {
  console.log(`Mapped: ${originalId} -> ${lexamicaId}`);
}

async function recordUpdate(caseId, update) {
  console.log('Update:', caseId, update);
}

async function updateCaseStage(caseId, stage) {
  console.log('Stage:', caseId, stage);
}

async function markCaseSettling(caseId, details) {
  console.log('Settlement:', caseId, details);
}

app.listen(3000, () => console.log('Server running'));

---

📋 Events You'll Receive

Event	When It Fires	What It Contains
Case Update Made	Handler posts a status update	Update title, content, date
Case Stage Changed	Case moves to new stage	New stage label
Case Settlement	Settlement process starts	Settlement details

Note: You won't receive relay events since the case bypasses the Relay Engine.

---

❓ FAQ

❓ "Where do I get the Partner Firm ID?"

📝 Full Answer:

• From the Lexamica platform (firm profile page)

• Via the API (contact support for firm lookup endpoints)

• From previous integrations where you stored the firm ID

---

❓ "What if I don't specify a partner firm?"

📝 Full Answer: If you omit partnerFirmId, Lexamica:

1. Creates the case as a draft

2. Runs a projection analysis from your partner network

3. Does NOT send invitations

4. Suggests potential partners you can select in-platform

---

❓ "Can I import cases in bulk?"

📝 Full Answer: Yes. Loop through your cases and call the endpoint for each. Add delays (100-200ms) between calls to avoid rate limits. See the bulk import example in the code above.

---

➡️ Next Steps

• Can't receive webhooks? See Import Existing Cases with Polling

• Need to attach files? See File Operations

• Want Relay matching instead? See Originator: Full Integration with Webhooks

---

Last updated: January 2026