Mistral AI Lead Intake for Clio Legal Client Onboarding

Capture new client leads via web chat and documents, detect duplicates, and automatically create contacts and matters in Clio through its REST API.

mistral lead-intake clio legal-tech nextjs hybrid-rag langfuse qdrant duplicate-detection document-processing

The problem

Small law firms using Clio still manually copy lead info from web forms and emails, often duplicating contacts and losing track of follow‑ups, which slows client onboarding.

Built from

Intro

In this tutorial, you’ll build a legal lead intake system powered by Mistral AI that integrates with Clio’s REST API. Your app will run a conversational chat session that asks intake questions, extracts structured lead fields from the conversation, detects duplicate leads using hybrid vector + BM25 retrieval, handles document uploads (PDFs and images), and pushes qualified leads to Clio as contacts and matters. By the end, you’ll have a working Next.js app with a chat API, document upload endpoint, duplicate warnings, qualification scoring, and Clio OAuth2 sync — all instrumented with Langfuse observability.

Prerequisites

Node.js >= 22 and pnpm 10.x (the project uses pnpm@10.0.0)
A Mistral AI API key for the conversational model
An OpenAI API key for text embeddings (used by the REAA hybrid-rag stack)
A Langfuse account for observability (public + secret keys, host URL)
A Qdrant instance URL for vector storage (used by duplicate detection)
Clio OAuth2 client credentials (client ID, client secret, redirect URI)
Familiarity with TypeScript and Next.js App Router conventions

Step 1: Scaffold the project and install dependencies

Create the Next.js project and install all the dependencies you’ll need. The project uses the App Router (app/ directory) and pnpm as its package manager.

terminal

npx create-next-app@latest mistral-lead-intake --typescript

Example artifact

A complete, working implementation of this recipe — downloadable as a zip or browsable file by file. Generated by our build pipeline; tested with full coverage before publishing.

Download example (zip)Browse files

171 kB·115 tests·100.0% coverage·vitest passing

SHA-2566abbbd0cc26e8f11aeb3627b99806667a9f3d52ac470bf3dc5edd0ee2a923349

Book a conversation All solutions

Comments

Loading comments…

Intro

Prerequisites

Node.js >= 22 and pnpm 10.x (the project uses pnpm@10.0.0)
A Mistral AI API key for the conversational model
An OpenAI API key for text embeddings (used by the REAA hybrid-rag stack)
A Langfuse account for observability (public + secret keys, host URL)
A Qdrant instance URL for vector storage (used by duplicate detection)
Clio OAuth2 client credentials (client ID, client secret, redirect URI)
Familiarity with TypeScript and Next.js App Router conventions

Step 1: Scaffold the project and install dependencies

Create the Next.js project and install all the dependencies you’ll need. The project uses the App Router (app/ directory) and pnpm as its package manager.

terminal

npx create-next-app@latest mistral-lead-intake --typescript

import { z } from "zod"; export interface LeadIntake { id: string; name: string; email: string; phone?: string; description: string; caseType: string; firmName?: string; priority?: number; status: string; createdAt: string; } export interface LeadIntakeResult { lead: LeadIntake; duplicateOf: string | null; matchScore: number; fields: Record<string, string>; } export interface DedupResult { isDuplicate: boolean; matchedLeadId: string | null; similarityScore: number; matchedChunks: string[]; } export interface ChatMessage { role: "user" | "assistant"; content: string; timestamp?: string; } export interface ChatSession { id: string; messages: ChatMessage[]; leadData: Partial<LeadIntake>; metadata: Record<string, unknown>; } export interface DocumentUploadResult { documentId: string; extractedText: string; fields: Partial<LeadIntake>; } export interface ClioContact { id: string; first_name: string; last_name: string; email: string; phone_number?: string; type: string; } export interface ClioMatter { id: string; display_number: string; description: string; client_id: string; status: string; } export interface ClioToken { accessToken: string; refreshToken: string; expiresAt: number; } export class ClioApiError extends Error { statusCode: number; body: string; constructor(message: string, statusCode: number, body: string) { super(message); this.name = "ClioApiError"; this.statusCode = statusCode; this.body = body; } } export const LeadIntakeSchema = z.object({ id: z.string(), name: z.string(), email: z.email(), phone: z.string().optional(), description: z.string(), caseType: z.string(), firmName: z.string().optional(), priority: z.number().int().min(1).max(5).optional(), status: z.string(), createdAt: z.string(), }).strict(); export const ChatMessageSchema = z.object({ messages: z.array(z.object({ role: z.enum(["user", "assistant"]), content: z.string(), })), }); export const DedupRequestSchema = z.object({ text: z.string().min(1), threshold: z.number().min(0).max(1).optional(), });

import { HybridRetriever } from "@reaatech/hybrid-rag-retrieval"; import { type Chunk } from "@reaatech/hybrid-rag"; export class DedupService { private retriever: HybridRetriever; private ready = false; constructor() { const qdrantUrl = process.env.QDRANT_URL ?? ""; const collectionName = process.env.QDRANT_COLLECTION_NAME ?? "leads"; const apiKey = process.env.OPENAI_API_KEY ?? ""; this.retriever = new HybridRetriever({ vector: { qdrant: { url: qdrantUrl, collectionName, }, embedding: { provider: "openai", model: "text-embedding-3-small", apiKey, }, topK: 20, }, bm25: { k1: 1.2, b: 0.75, topK: 20, }, fusion: { strategy: "rrf", }, topK: 10, }); } async initialize(): Promise<void> { try { await this.retriever.initialize(); this.ready = true; } catch { this.ready = false; } } async indexLeads(chunks: Chunk[]): Promise<void> { if (!this.ready) { return; } await this.retriever.indexChunks(chunks); } async checkDuplicate( leadText: string, threshold = 0.85, ): Promise<{ isDuplicate: boolean; matchedLeadId: string | null; similarityScore: number; matchedChunks: string[]; }> { if (!this.ready) { return { isDuplicate: false, matchedLeadId: null, similarityScore: 0, matchedChunks: [], }; } const results = await this.retriever.retrieve(leadText, { topK: 5, retrievalMode: "hybrid", }); if (results.length === 0) { return { isDuplicate: false, matchedLeadId: null, similarityScore: 0, matchedChunks: [], }; } const best = results[0]; if (best.score >= threshold) { return { isDuplicate: true, matchedLeadId: best.documentId, similarityScore: best.score, matchedChunks: results .filter((r) => r.score >= threshold) .map((r) => r.content), }; } return { isDuplicate: false, matchedLeadId: null, similarityScore: best.score, matchedChunks: [], }; } }

import { createWorker } from "tesseract.js"; import { extractText, getDocumentProxy } from "unpdf"; import { DocumentValidator, TextPreprocessor, chunkDocument, UnsupportedFormatError, FileSizeExceededError, } from "@reaatech/hybrid-rag-ingestion"; import { type Chunk, ChunkingStrategy } from "@reaatech/hybrid-rag"; export class IngestionService { async processPdf( buffer: ArrayBuffer, ): Promise<{ totalPages: number; text: string }> { const pdf = await getDocumentProxy(new Uint8Array(buffer)); const result = await extractText(pdf, { mergePages: true }); return { totalPages: result.totalPages, text: result.text, }; } async ocrImage(buffer: Buffer): Promise<string> { const worker = await createWorker("eng"); const ret = await worker.recognize(buffer); const text = ret.data.text; await worker.terminate(); return text; } async chunkDocument( content: string, docId: string, ): Promise<Chunk[]> { const preprocessor = new TextPreprocessor(); const processed = preprocessor.preprocess(content); return chunkDocument(processed.content, docId, { strategy: ChunkingStrategy.SEMANTIC, chunkSize: 512, overlap: 50, similarityThreshold: 0.5, }); } async processUpload( buffer: ArrayBuffer, originalName: string, ): Promise<{ text: string; chunks: Chunk[] }> { const ext = originalName.split(".").pop()?.toLowerCase() ?? ""; const supportedFormats = ["pdf", "md", "html", "txt", "png", "jpg", "jpeg", "gif", "bmp"]; if (!supportedFormats.includes(ext)) { throw new UnsupportedFormatError(`Format .${ext} is not supported`); } const validator = new DocumentValidator({ maxFileSize: 10 * 1024 * 1024, }); const docId = `upload-${String(Date.now())}`; let content: string; if (ext === "pdf") { const extracted = await this.processPdf(buffer); content = extracted.text; } else { content = await this.ocrImage(Buffer.from(buffer)); } const doc = { id: docId, content, source: originalName, metadata: {}, }; const validation = validator.validate(doc); if (!validation.isValid) { if (validation.errors.some((e) => e.toLowerCase().includes("size"))) { throw new FileSizeExceededError(buffer.byteLength, 10 * 1024 * 1024); } throw new Error(`Document validation failed: ${validation.errors.join(", ")}`); } const chunks = await this.chunkDocument(content, docId); return { text: content, chunks }; } }

Mistral AI Lead Intake for Clio Legal Client Onboarding

The problem

Built from

Intro

Prerequisites

Step 1: Scaffold the project and install dependencies

Example artifact

Comments

Intro

Prerequisites

Step 1: Scaffold the project and install dependencies

Step 2: Configure environment variables

Step 3: Define the domain types and Zod schemas

Step 4: Create the AGENTS.md configuration loader

Step 5: Build the Mistral AI chat service

Step 6: Build the embedding and duplicate-detection services

Step 7: Build the document ingestion service

Step 8: Build the Clio REST API integration

Step 9: Wire up Langfuse observability

Step 10: Create the API route handlers

Step 11: Create the barrel exports

Step 12: Run the tests

Next steps