Mapping Engine
How to transform data between your system and Lexamica using field mappings.
Table of Contents
🎯 Overview
📌 TL;DR
Mappings translate field names between your system and Lexamica. Your
client_first_namebecomes Lexamica'sclient.firstName, and vice versa. Create a mapping once, and all data flows through it automatically.
Your CRM, case management system, or database probably uses different field names than Lexamica. The Mapping Engine bridges this gap by defining how fields correspond between systems.
Mappings are bidirectional:
Inbound: When you send data to Lexamica, your fields are transformed to Lexamica's format
Outbound: When Lexamica sends data back (in responses or webhooks), it's transformed to your format
This means you can work entirely in your own field names—the mapping handles the translation.
📖 Key Terms
Mapping
A named configuration that defines how fields translate between your system and Lexamica.
Field Mapping
A single field-to-field correspondence within a mapping (e.g., client_email ↔ client.email).
Model
The type of Lexamica data the mapping applies to (Case, CaseInvitation, etc.).
Inbound Transformation
Converting your data format to Lexamica's format when sending data.
Outbound Transformation
Converting Lexamica's format to your format when receiving data.
Mapping ID
A unique identifier for a mapping, used in API endpoint URLs.
⚙️ How It Works
When data flows through the API, the Mapping Engine automatically transforms it:
🎯 Key Takeaway
You define the mapping once, and it works in both directions. Send data using your field names, receive data in your field names.
💡 Key Concepts
Supported Models
Each mapping is tied to a specific data model. Choose the model based on what data you're working with:
Case
Case/matter data, client info, incidents
client.firstName, client.email, caseType, incident.date
CaseInvitation
Invitation status and lifecycle
accepted, declined, expires, referral._id
CaseUpdate
Case notes and status updates
title, content, referral._id
LawFirm
Firm information
name, _id
LawFirmUser
User/attorney information
givenName, familyName, email
Attachment
File metadata
filename, mimetype, size, url
Field Types
Each field mapping specifies data types to ensure proper conversion:
String
Text values
Names, emails, descriptions
Number
Numeric values
Fees, percentages, amounts
Date
Date/time values
Incident dates, deadlines
Boolean
True/false values
Flags, toggles
Constant
Fixed values that don't come from your data
Always set status to "active"
Nested Field Syntax
Lexamica uses dot notation for nested objects. Your fields can be flat or nested—the mapping handles the translation:
Custom Fields
For data that doesn't fit Lexamica's standard fields, use customFields:
Custom fields are stored with the case and returned in webhooks, preserving your data through the round trip.
Example: Your system tracks lead_source and marketing_campaign:
📋 Common Use Cases
📗 Use Case: Creating a Basic Case Mapping
Goal
Map your CRM's case fields to Lexamica's Case model
How
Create a mapping with field correspondences
Result
A Mapping ID you'll use for all case-related operations
Request:
Response:
💡 Tip: Save the
_idfrom the response—this is your Mapping ID that you'll use in inbound webhook URLs.
📗 Use Case: Mapping with Custom Fields
Goal
Include CRM-specific data that Lexamica doesn't have standard fields for
How
Map to customFields.* paths
Result
Your custom data flows through and returns in webhooks
Adding custom fields to your mapping:
📗 Use Case: Using Constant Values
Goal
Always send a fixed value for a field
How
Set the field type to Constant and specify the value
Result
The constant is included in every request
Example: Always set update frequency to 90 days:
❓ FAQ
❓ "Do I need separate mappings for inbound and outbound?"
📝 Full Answer: No. Each mapping works bidirectionally. When you send data (inbound), your fields are transformed to Lexamica fields. When you receive data (outbound), Lexamica fields are transformed back to your fields. One mapping handles both directions.
❓ "How do I map fields that don't exist in Lexamica?"
🔍 Quick Check:
✅ Use
customFields.*for additional data you want to preserve✅ Custom fields are stored and returned in webhooks
📝 Full Answer: Use the customFields namespace. For example, if your CRM has a referral_source field, map it to customFields.referral_source. This data will be stored with the case and included when Lexamica sends data back to you via webhooks or API responses.
❓ "Can I have multiple mappings for the same model?"
📝 Full Answer: Yes. You might want different mappings for different use cases. For example:
A "Full Case Mapping" with all fields for new case creation
A "Basic Case Mapping" with just client info for updates
Each mapping gets its own ID, and you choose which to use in each API call.
❓ "What happens if a field is missing from my request?"
📝 Full Answer: Missing fields are simply not included in the transformed data. Lexamica will use defaults or leave optional fields empty. For required fields (like client.email or client.phoneNumber), you'll receive a validation error if they're missing.
❓ "How do I update an existing mapping?"
🔍 Quick Check:
✅ Use the
/mapping/{mapId}/updateendpoint✅ Include the complete
fieldMappingsarray (it replaces the existing one)
📝 Full Answer: Send a POST request to update with your Mapping ID:
🔧 Technical Reference
Available Lexamica Fields
You can retrieve all available fields for mapping via the API:
Case Model Fields
_id
String
Case ID (for updates to existing cases)
client.firstName
String
Client's first name
client.lastName
String
Client's last name
client.email
String
Client's email (required if no phone)
client.phoneNumber
String
Client's phone (required if no email)
client.address.line1
String
Client address line 1
client.address.line2
String
Client address line 2
client.address.city
String
Client city
client.address.state
String
Client state
client.address.zipCode
String
Client ZIP code
caseType
String
Practice area/case type
incident.date
Date
Date of incident
incident.synopsis
String
Description of incident
incident.address.*
String
Incident location fields
payment.feeType
String
percentage or custom
payment.percentage
Number
Fee percentage
payment.custom
String
Custom fee amount
updates.frequency
Number
Update frequency (30, 60, 90, or 120 days)
customFields.*
Any
Your custom data
CaseInvitation Model Fields
_id
String
Invitation ID
referral._id
String
Associated case ID
accepted
Date
When invitation was accepted
declined
Date
When invitation was declined
evaluated
Date
When invitation was marked as evaluating
expires
Date
Invitation expiration
declineReason
String
Reason for decline
CaseUpdate Model Fields
_id
String
Update ID
referral._id
String
Associated case ID
title
String
Update title
content
String
Update content/notes
overdue
Boolean
Whether update was overdue
🔧 Technical Deep-Dive: Field Mapping Structure
Each field mapping in the
fieldMappingsarray follows this structure:
lexamicaField: The dot-notation path in Lexamica's data structure
foreignField: Your system's field name
*FieldType: One ofString,Number,Date,Boolean,Constant
constantValue/Type: Used when one side is a fixed value
subMappings: For nested object transformations
Last updated: January 2026
Last updated