File Operations

Upload, download, and manage case files through the API.

---

🎯 Overview

📌 TL;DR

Upload files directly or via URL, remove files when needed, and get notified when files are uploaded to cases you're involved with. This appendix works with any integration pattern.

This guide covers:

• Uploading files directly to cases

• Uploading files via URL (for larger files)

• Removing files from cases

• Receiving notifications when files are uploaded

Use this with:

• Any originator or handler integration

• Both webhook and polling patterns

---

📖 Key Terms

Term	Definition
Attachment	A file associated with a case
Direct Upload	Upload file content directly via multipart form
Stream Upload	Upload file from a URL (Lexamica fetches it)

---

📋 Prerequisites

Credentials:

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

Foundational Docs:

• Organizations and Authentication — understand your API keys

• Mapping Engine — how field transformations work

• Inbound Webhooks — sending data to Lexamica

For file upload notifications (optional):

• Webhook Subscriptions — if receiving notifications via webhooks

• Event Storage and Polling — if polling for notifications

---

💡 Uploading Files

Method 1: Direct Upload

Best for smaller files uploaded directly from your server.

Endpoint: POST /organization/{orgId}/inbound-webhooks/case/{mapId}/file/upload

Request (multipart/form-data):

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

Response:

{
  "attachment_id": "64f1a2b3c4d5e6f7a8b9c0e1",
  "filename": "medical_records.pdf",
  "size": 245678,
  "mimetype": "application/pdf",
  "url": "https://storage.lexamica.com/files/64f1a2b3c4d5e6f7a8b9c0e1"
}

Node.js Example:

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

async function uploadFile(caseId, filePath, fileName) {
  const form = new FormData();
  form.append('caseId', caseId);
  form.append('file', fs.createReadStream(filePath));
  form.append('fileName', fileName || path.basename(filePath));
  
  const response = await axios.post(
    `${BASE_URL}/organization/${ORG_ID}/inbound-webhooks/case/${MAPPING_ID}/file/upload`,
    form,
    {
      params: { Key: PUBLIC_KEY },
      headers: form.getHeaders()
    }
  );
  
  return response.data;
}

// Usage
const attachment = await uploadFile(
  '64f1a2b3c4d5e6f7a8b9c0d3',
  './documents/intake_form.pdf',
  'Client Intake Form.pdf'
);

Method 2: Stream Upload (URL-based)

Best for larger files or files already hosted elsewhere. Lexamica fetches the file from the URL you provide.

Endpoint: POST /organization/{orgId}/inbound-webhooks/case/{mapId}/file/stream

Request:

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/inbound-webhooks/case/{mapId}/file/stream?Key=your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "caseId": "64f1a2b3c4d5e6f7a8b9c0d3",
    "url": "https://your-storage.com/files/document.pdf",
    "filename": "accident_photos.pdf",
    "mimetype": "application/pdf",
    "size": 1245678
  }'

Node.js Example:

async function uploadFileFromUrl(caseId, fileUrl, filename, mimetype, size) {
  const response = await axios.post(
    `${BASE_URL}/organization/${ORG_ID}/inbound-webhooks/case/${MAPPING_ID}/file/stream`,
    {
      caseId,
      url: fileUrl,
      filename,
      mimetype,
      size
    },
    {
      params: { Key: PUBLIC_KEY },
      headers: { 'Content-Type': 'application/json' }
    }
  );
  
  return response.data;
}

// Usage
const attachment = await uploadFileFromUrl(
  '64f1a2b3c4d5e6f7a8b9c0d3',
  'https://mybucket.s3.amazonaws.com/docs/report.pdf',
  'Police Report.pdf',
  'application/pdf',
  524288
);

💡 Tip: Stream upload is useful when your files are in cloud storage (S3, GCS, etc.) and you want to avoid downloading them to your server first.

---

💡 Removing Files

Endpoint: POST /organization/{orgId}/inbound-webhooks/case/{mapId}/file/remove

Request:

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/inbound-webhooks/case/{mapId}/file/remove?Key=your_public_key" \
  -H "Content-Type: application/json" \
  -d '{
    "caseId": "64f1a2b3c4d5e6f7a8b9c0d3",
    "attachmentId": "64f1a2b3c4d5e6f7a8b9c0e1"
  }'

Node.js Example:

async function removeFile(caseId, attachmentId) {
  const response = await axios.post(
    `${BASE_URL}/organization/${ORG_ID}/inbound-webhooks/case/${MAPPING_ID}/file/remove`,
    { caseId, attachmentId },
    {
      params: { Key: PUBLIC_KEY },
      headers: { 'Content-Type': 'application/json' }
    }
  );
  
  return response.data;
}

---

💡 Receiving File Upload Notifications

Get notified when files are uploaded to cases you're involved with.

Via Webhooks

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 File Uploaded",
    "url": "https://your-system.com/webhooks/lexamica",
    "secret": "your_webhook_secret",
    "mapping": "your_attachment_mapping_id",
    "description": "File upload notifications",
    "active": true
  }'

Sample webhook payload:

{
  "case_id": "64f1a2b3c4d5e6f7a8b9c0d3",
  "attachment_id": "64f1a2b3c4d5e6f7a8b9c0e1",
  "filename": "medical_records.pdf",
  "mimetype": "application/pdf",
  "size": 245678,
  "url": "https://storage.lexamica.com/files/64f1a2b3c4d5e6f7a8b9c0e1",
  "uploaded_at": "2026-01-15T10:30:00.000Z"
}

Via Polling

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/stored-event-subscriptions/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Case File Uploaded",
    "mapping": "your_attachment_mapping_id",
    "description": "Store file upload events for polling",
    "active": true
  }'

---

💡 Downloading Files

Files include a url field that you can use to download the content.

Example:

async function downloadFile(fileUrl, savePath) {
  const response = await axios.get(fileUrl, {
    responseType: 'stream'
  });
  
  const writer = fs.createWriteStream(savePath);
  response.data.pipe(writer);
  
  return new Promise((resolve, reject) => {
    writer.on('finish', resolve);
    writer.on('error', reject);
  });
}

// In your webhook/polling handler:
async function handleFileUploaded(payload) {
  // Download the file
  await downloadFile(
    payload.url,
    `./downloads/${payload.filename}`
  );
  
  // Or store the URL for later access
  await db.caseFiles.create({
    caseId: payload.case_id,
    filename: payload.filename,
    downloadUrl: payload.url,
    size: payload.size,
    mimetype: payload.mimetype
  });
}

---

🔧 Attachment Mapping

Create an Attachment mapping for file-related events:

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/mapping/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Attachment Mapping",
    "modelName": "Attachment",
    "fieldMappings": [
      { "lexamicaField": "_id", "foreignField": "attachment_id", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "caseId", "foreignField": "case_id", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "filename", "foreignField": "filename", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "mimetype", "foreignField": "mimetype", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "size", "foreignField": "size", "lexamicaFieldType": "Number", "foreignFieldType": "Number" },
      { "lexamicaField": "url", "foreignField": "download_url", "lexamicaFieldType": "String", "foreignFieldType": "String" }
    ]
  }'

---

🔧 Complete Example: File Sync Service

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const path = require('path');

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

class FileService {
  // Upload file directly
  async uploadFile(caseId, filePath, fileName) {
    const form = new FormData();
    form.append('caseId', caseId);
    form.append('file', fs.createReadStream(filePath));
    form.append('fileName', fileName || path.basename(filePath));
    
    const response = await axios.post(
      `${config.baseUrl}/organization/${config.orgId}/inbound-webhooks/case/${config.attachmentMappingId}/file/upload`,
      form,
      {
        params: { Key: config.publicKey },
        headers: form.getHeaders()
      }
    );
    
    return response.data;
  }

  // Upload file from URL
  async uploadFromUrl(caseId, fileUrl, filename, mimetype, size) {
    const response = await axios.post(
      `${config.baseUrl}/organization/${config.orgId}/inbound-webhooks/case/${config.attachmentMappingId}/file/stream`,
      { caseId, url: fileUrl, filename, mimetype, size },
      {
        params: { Key: config.publicKey },
        headers: { 'Content-Type': 'application/json' }
      }
    );
    
    return response.data;
  }

  // Remove file
  async removeFile(caseId, attachmentId) {
    const response = await axios.post(
      `${config.baseUrl}/organization/${config.orgId}/inbound-webhooks/case/${config.attachmentMappingId}/file/remove`,
      { caseId, attachmentId },
      {
        params: { Key: config.publicKey },
        headers: { 'Content-Type': 'application/json' }
      }
    );
    
    return response.data;
  }

  // Download file
  async downloadFile(fileUrl, savePath) {
    const response = await axios.get(fileUrl, { responseType: 'stream' });
    const writer = fs.createWriteStream(savePath);
    response.data.pipe(writer);
    
    return new Promise((resolve, reject) => {
      writer.on('finish', resolve);
      writer.on('error', reject);
    });
  }

  // Bulk upload
  async uploadMultiple(caseId, files) {
    const results = [];
    for (const file of files) {
      try {
        const result = await this.uploadFile(caseId, file.path, file.name);
        results.push({ success: true, ...result });
      } catch (error) {
        results.push({ success: false, file: file.name, error: error.message });
      }
    }
    return results;
  }
}

module.exports = new FileService();

---

❓ FAQ

❓ "What file types are supported?"

Most common file types are supported: PDF, images (JPG, PNG), documents (DOC, DOCX), and more. Contact support for specific format questions.

---

❓ "What's the maximum file size?"

Direct upload has practical limits based on timeout. For large files (>50MB), use stream upload with a hosted URL. The stream upload will automatically handle file size limits and will retry the upload if it fails.

---

❓ "Are files visible to all case participants?"

Yes, files uploaded to a case are visible to all firms who are confirmed as a participant in the case (originator and handler).

---

❓ "How long are file URLs valid?"

File URLs are typically short-lived and expire after a few hours. Store files in your own system if you need guaranteed permanent access.

---

🔧 Troubleshooting

"File upload returns 400"

• Check that caseId is valid and you have access to the case

• Verify the mapping ID is for the Attachment model

• For direct upload, ensure the file field is named file

"Stream upload fails"

• Ensure the source URL is publicly accessible

• Verify the file exists at the URL

• Check that mimetype matches the actual file

---

Last updated: January 2026