Forem: kathan

Extracting Structured Data from Images Using AI: Why GPT-4o Beats Traditional OCR for Real-World Documents

kathan — Fri, 01 May 2026 11:42:34 +0000

I've built traditional OCR pipelines using LEAD Tools, Tesseract, and ABBYY. They work — until they don't. A slightly rotated scan, a different font weight, a handwritten field in the margin, or a table with merged cells, and the accuracy collapses. You end up with brittle regex patterns, endless exception handling, and a maintenance burden that grows with every new document format the client sends.

Then I started using AI vision models for document extraction. The difference is significant enough that I've replaced traditional OCR with AI-based extraction on every new project since. This post explains the approach, shows the C# implementation, and covers when it works best and where to be careful.

Why Traditional OCR Fails on Real-World Documents
Traditional OCR engines convert image pixels to text. They do this well when documents are clean, consistently formatted, and machine-printed. Real-world documents are none of these things:

Invoices come from hundreds of different vendors with different layouts, fonts, and field positions.
Legal documents have handwritten annotations, stamps, and signatures that break character recognition.
Medical forms mix printed and handwritten content in the same field.
Scanned contracts are often skewed, noisy, or have watermarks.

Writing code to handle all of this — column detection, bounding box logic, field mapping, layout parsing — is a significant engineering effort. And every new document type breaks something.

The AI Approach: Describe What You Want, Get It
Modern vision models like GPT-4o from OpenAI (available through Azure OpenAI) understand document context the same way a human does. You send an image and a prompt describing exactly what data you want extracted and in what format. The model reads the document, understands its structure, and returns the data.

No layout parsing. No bounding boxes. No regex. No column detection. Just a prompt and a JSON response.

Real Example: Extracting Invoice Data
Let's say you receive vendor invoices as scanned PDFs or photos. You need to extract: invoice number, vendor name, invoice date, due date, line items (description, quantity, unit price, total), subtotal, tax, and grand total. Here's the complete implementation in C# using Azure OpenAI.

Step 1: Set Up Azure OpenAI Client

// Install: dotnet add package Azure.AI.OpenAI
// Install: dotnet add package Microsoft.Extensions.AI

// appsettings.json
{
  "AzureOpenAI": {
    "Endpoint": "https://your-resource.openai.azure.com/",
    "ApiKey":   "your-api-key",
    "Model":    "gpt-4o"
  }
}

// Program.cs
builder.Services.AddSingleton(sp =>
{
    var config   = sp.GetRequiredService<IConfiguration>();
    var endpoint = new Uri(config["AzureOpenAI:Endpoint"]!);
    var cred     = new AzureKeyCredential(config["AzureOpenAI:ApiKey"]!);
    return new AzureOpenAIClient(endpoint, cred);
});

builder.Services.AddScoped<IDocumentExtractionService, DocumentExtractionService>();

Step 2: Define Your Output Model
The key to reliable extraction is telling the AI exactly what JSON structure to return. Define a C# model first, then instruct the AI to match it.

public class InvoiceData
{
    public string?       InvoiceNumber { get; set; }
    public string?       VendorName    { get; set; }
    public string?       VendorAddress { get; set; }
    public DateTime?     InvoiceDate   { get; set; }
    public DateTime?     DueDate       { get; set; }
    public List<LineItem> LineItems    { get; set; } = [];
    public decimal?      Subtotal      { get; set; }
    public decimal?      TaxAmount     { get; set; }
    public decimal?      GrandTotal    { get; set; }
    public string?       Currency      { get; set; }
    public string?       PaymentTerms  { get; set; }
    public float         Confidence    { get; set; }
    public string?       Notes         { get; set; }
}

public class LineItem
{
    public string?  Description { get; set; }
    public decimal? Quantity    { get; set; }
    public decimal? UnitPrice   { get; set; }
    public decimal? Total       { get; set; }
}

Step 3: The Extraction Service

public class DocumentExtractionService : IDocumentExtractionService
{
    private readonly AzureOpenAIClient _client;
    private readonly IConfiguration    _config;

    public DocumentExtractionService(
        AzureOpenAIClient client,
        IConfiguration config)
    {
        _client = client;
        _config = config;
    }

    public async Task<InvoiceData?> ExtractInvoiceAsync(
        byte[] imageBytes,
        string mimeType = "image/jpeg")
    {
        var chatClient = _client.GetChatClient(_config["AzureOpenAI:Model"]);

        // Convert image to base64 data URI
        var base64 = Convert.ToBase64String(imageBytes);
        var dataUri = $"data:{mimeType};base64,{base64}";

        var prompt = """
            You are a precise document data extraction assistant.
            Extract all invoice data from this image and return it as JSON.

            Return ONLY valid JSON with this exact structure — no markdown, no explanation:
            {
              "invoiceNumber": "string or null",
              "vendorName":    "string or null",
              "vendorAddress": "string or null",
              "invoiceDate":   "YYYY-MM-DD or null",
              "dueDate":       "YYYY-MM-DD or null",
              "lineItems": [
                {
                  "description": "string",
                  "quantity":    number,
                  "unitPrice":   number,
                  "total":       number
                }
              ],
              "subtotal":    number or null,
              "taxAmount":   number or null,
              "grandTotal":  number or null,
              "currency":    "USD / GBP / AED / INR / etc.",
              "paymentTerms": "string or null",
              "confidence":   0.0 to 1.0,
              "notes": "any unusual observations about the document"
            }

            Rules:
            - Extract numbers as numeric values, not strings
            - If a field is not visible, return null
            - confidence = your estimate of extraction accuracy
            - Do not invent or guess values you cannot clearly read
            """;

        var messages = new List<ChatMessage>
        {
            new UserChatMessage(
                ChatMessageContentPart.CreateTextPart(prompt),
                ChatMessageContentPart.CreateImagePart(
                    new Uri(dataUri), null))
        };

        var response = await chatClient.CompleteChatAsync(
            messages,
            new ChatCompletionOptions
            {
                MaxOutputTokenCount = 2000,
                Temperature         = 0.1f  // Low temp = more deterministic output
            });

        var json = response.Value.Content[0].Text;

        // Strip markdown fences if the model adds them despite instructions
        json = json
            .Replace("```
{% endraw %}
json", "")
            .Replace("
{% raw %}
```",     "")
            .Trim();

        return JsonSerializer.Deserialize<InvoiceData>(json,
            new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            });
    }
}

Processing Multiple Document Types with One Service
The real power is how easily you adapt the same pattern for different document types. Just change the prompt. Here's how we handle different document formats with a single extraction service by varying the prompt and output model.

// Generic extraction method — pass any prompt and expected output type
public async Task<T?> ExtractAsync<T>(
    byte[] imageBytes,
    string extractionPrompt,
    string mimeType = "image/jpeg") where T : class
{
    var chatClient = _client.GetChatClient(_config["AzureOpenAI:Model"]);
    var base64     = Convert.ToBase64String(imageBytes);
    var dataUri    = $"data:{mimeType};base64,{base64}";

    var schema = GenerateJsonSchema<T>(); // Use reflection or hard-coded schema

    var systemPrompt = $"""
        You are a precise document data extraction AI.
        Extract the requested data and return ONLY valid JSON.
        Schema to follow: {schema}
        If a field is not found in the document, set it to null.
        Do not return markdown, explanations, or commentary.
        """;

    var messages = new List<ChatMessage>
    {
        new SystemChatMessage(systemPrompt),
        new UserChatMessage(
            ChatMessageContentPart.CreateTextPart(extractionPrompt),
            ChatMessageContentPart.CreateImagePart(new Uri(dataUri), null))
    };

    var response = await chatClient.CompleteChatAsync(messages,
        new ChatCompletionOptions { Temperature = 0.1f });

    var json = response.Value.Content[0].Text.Trim()
        .TrimStart('`').TrimEnd('`')
        .Replace("json\n", "");

    return JsonSerializer.Deserialize<T>(json,
        new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
}

// Usage examples:

// Extract business card data
var card = await _extractor.ExtractAsync<BusinessCardData>(
    imageBytes,
    "Extract all contact information from this business card.");

// Extract medical form data
var form = await _extractor.ExtractAsync<MedicalFormData>(
    imageBytes,
    "Extract patient name, DOB, medications listed, and doctor name from this form.");

// Extract receipt data
var receipt = await _extractor.ExtractAsync<ReceiptData>(
    imageBytes,
    "Extract store name, date, all items purchased with prices, and total amount.");

Using It in a Blazor File Upload Flow
Here is how to wire this into a Blazor Server component where users upload an invoice image and see the extracted data instantly.

@page "/invoice-upload"
@inject IDocumentExtractionService Extractor

<h2>Upload Invoice</h2>

<InputFile OnChange="HandleFileSelected" accept="image/*,.pdf" />

@if (_loading)
{
    <p>Extracting data...</p>
}

@if (_invoice is not null)
{
    <div class="invoice-preview">
        <h3>@_invoice.VendorName — @_invoice.InvoiceNumber</h3>
        <p>Date: @_invoice.InvoiceDate?.ToString("d")</p>
        <p>Total: @_invoice.GrandTotal?.ToString("C") (@_invoice.Currency)</p>
        <p>Confidence: @(_invoice.Confidence * 100)%</p>

        <table>
            @foreach (var item in _invoice.LineItems)
            {
                <tr>
                    <td>@item.Description</td>
                    <td>@item.Quantity</td>
                    <td>@item.UnitPrice?.ToString("C")</td>
                    <td>@item.Total?.ToString("C")</td>
                </tr>
            }
        </table>
    </div>
}

@code {
    private bool        _loading = false;
    private InvoiceData? _invoice = null;

    private async Task HandleFileSelected(InputFileChangeEventArgs e)
    {
        _loading = true;
        _invoice = null;

        try
        {
            var file   = e.File;
            var buffer = new byte[file.Size];

            await using var stream = file.OpenReadStream(maxAllowedSize: 10 * 1024 * 1024);
            await stream.ReadExactlyAsync(buffer);

            _invoice = await Extractor.ExtractInvoiceAsync(
                buffer, file.ContentType);
        }
        catch (Exception ex)
        {
            Console.Error.WriteLine($"Extraction failed: {ex.Message}");
        }
        finally
        {
            _loading = false;
        }
    }
}

Handling PDFs — Converting Pages to Images First
The vision API accepts images, not PDFs. For multi-page PDF invoices, convert each page to a JPEG first, then process each page separately. We use the open-source PDFium library for this in .NET.

// Install: dotnet add package PdfiumViewer.Native.x86_64.v8-xfa
// Install: dotnet add package PdfiumViewer

public async Task<List<InvoiceData?>> ExtractFromPdfAsync(byte[] pdfBytes)
{
    var results = new List<InvoiceData?>();

    using var stream    = new MemoryStream(pdfBytes);
    using var document  = PdfDocument.Load(stream);

    for (int page = 0; page < document.PageCount; page++)
    {
        // Render at 200 DPI for good quality
        using var image  = document.Render(page, 200, 200, false);
        using var ms     = new MemoryStream();
        image.Save(ms, System.Drawing.Imaging.ImageFormat.Jpeg);

        var pageBytes = ms.ToArray();
        var result    = await ExtractInvoiceAsync(pageBytes, "image/jpeg");

        if (result is not null)
            results.Add(result);
    }

    return results;
}

Accuracy, Cost, and When to Use AI vs Traditional OCR
AI extraction is not free. GPT-4o charges per token and image tokens are significant. Here's a practical breakdown to help you decide:

Use AI extraction when:
• Documents come in many formats from different sources (invoices, contracts, forms)
• Accuracy is critical and manual correction is expensive
• Documents contain handwriting, stamps, or non-standard layouts
• You need structured data, not just raw text
• Volume is moderate (hundreds per day, not millions)

Use traditional OCR when:
• Documents are always the same template (your own forms)
• Volume is very high (millions per day) and cost matters at scale
• You only need raw text extraction, not structured fields
• Latency is critical (OCR is faster than an API call)

For typical business document processing — invoices, medical records, legal forms, receipts — AI extraction saves significant development time and delivers higher accuracy than any traditional pipeline I've built. The prompt is your only maintenance surface. When a new document layout appears, you adjust the prompt — not the code.

Tips for Production Reliability

Always validate the output — check that numeric totals add up, required fields are non-null, and dates are valid before saving to your database.
Use temperature 0.1 — lower temperature makes the model more deterministic and consistent. High temperature introduces unnecessary variation in data extraction.
Include a confidence score in the prompt — instruct the model to rate its own confidence. Flag anything below 0.85 for human review rather than auto-processing.
Log the raw response — always log the raw JSON string from the model before parsing. This makes debugging extraction failures much easier.
Handle rate limits — Azure OpenAI has tokens-per-minute limits. For batch processing, add a retry with exponential backoff using Polly.

// Polly retry policy for rate limiting
services.AddHttpClient<IDocumentExtractionService>()
    .AddResilienceHandler("openai-retry", builder =>
    {
        builder.AddRetry(new HttpRetryStrategyOptions
        {
            MaxRetryAttempts = 4,
            Delay            = TimeSpan.FromSeconds(2),
            BackoffType      = DelayBackoffType.Exponential,
            UseJitter        = true,
            ShouldHandle     = args => args.Outcome.Result?.StatusCode
                               == System.Net.HttpStatusCode.TooManyRequests
                               ? PredicateResult.True()
                               : PredicateResult.False()
        });
    });

Building a Legal Tech Automation System: Syncing Clio, Lawmatics, Zoom & Box Using .NET Hangfire

kathan — Thu, 30 Apr 2026 11:44:59 +0000

Law firms run on data — contacts, matters, call recordings, transcripts, documents. The problem is that data lives in four different platforms that don't talk to each other. Clio and Lawmatics handle case management. Zoom handles calls. Box handles document storage. Every day, staff manually copy contacts, chase recordings, and create folders. That's exactly the workflow we automated.

This post documents the full architecture we built for a US-based law firm — North City Law — using ASP.NET Core, Hangfire, and the REST APIs of all four platforms. If you're building legal tech integrations or any multi-platform sync system, the patterns here apply directly.

The Problem — Four Platforms, Zero Sync
Here's what the firm's manual workflow looked like before automation:

A new client is added to Lawmatics (their CRM)
Staff manually add the same contact to Zoom's external contacts
A call happens — Zoom generates a recording, AI summary, and transcript
Staff download the transcript and paste it as a note in Clio
A new matter opens in Clio — staff manually create a Box folder and upload documents

This process consumed 2–3 hours of admin work daily and introduced errors at every manual step. Our goal: make all of it happen automatically, on a schedule, without human intervention.

Architecture Overview
The system is built on Blazor Server + ASP.NET Core + Hangfire, hosted on Azure App Service. Each integration is a Hangfire recurring job that runs on a configurable schedule. OAuth 2.0 tokens for each platform are stored encrypted in a SQL Server database and refreshed automatically.

The four core jobs are:

Job 1: Sync contacts from Clio/Lawmatics → Zoom External Contacts (every 6 hours)
Job 2: Pull Zoom call recordings, AI summaries, and transcripts → post as notes in Clio/Lawmatics (daily at 7 AM)
Job 3: Monitor new matters in Clio → create corresponding Box folder structure (triggered on schedule every 15 minutes)
Job 4: Upload matter documents from Clio → Box folder (daily at 6 AM)

Setting Up Hangfire with SQL Server
Hangfire is the backbone of the scheduling system. It stores job state in SQL Server, handles retries automatically, and provides a dashboard to monitor every job run.

// Program.cs
builder.Services.AddHangfire(config => config
    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
    .UseSimpleAssemblyNameTypeSerializer()
    .UseRecommendedSerializerSettings()
    .UseSqlServerStorage(builder.Configuration.GetConnectionString("HangfireDb"),
        new SqlServerStorageOptions
        {
            CommandBatchMaxTimeout       = TimeSpan.FromMinutes(5),
            SlidingInvisibilityTimeout   = TimeSpan.FromMinutes(5),
            QueuePollInterval            = TimeSpan.Zero,
            UseRecommendedIsolationLevel = true,
            DisableGlobalLocks           = true
        }));

builder.Services.AddHangfireServer(options =>
{
    options.WorkerCount    = 5;
    options.Queues         = new[] { "critical", "default", "low" };
});

// Register recurring jobs after app builds
var app = builder.Build();

using (var scope = app.Services.CreateScope())
{
    var recurringJobs = scope.ServiceProvider
        .GetRequiredService<IRecurringJobManager>();

    // Every 6 hours — sync contacts to Zoom
    recurringJobs.AddOrUpdate<ContactSyncJob>(
        "sync-contacts-to-zoom",
        job => job.ExecuteAsync(),
        "0 */6 * * *");

    // Daily at 7 AM UTC — sync Zoom recordings to Clio notes
    recurringJobs.AddOrUpdate<ZoomRecordingSyncJob>(
        "sync-zoom-recordings-to-clio",
        job => job.ExecuteAsync(),
        "0 7 * * *");

    // Every 15 minutes — check for new Clio matters
    recurringJobs.AddOrUpdate<NewMatterBoxJob>(
        "create-box-folders-for-new-matters",
        job => job.ExecuteAsync(),
        "*/15 * * * *");
}

Job 1: Syncing Contacts from Clio/Lawmatics to Zoom
The Clio API returns contacts with full contact details. We map these to Zoom's External Contact format and use the Zoom API to upsert them. The key challenge is matching contacts that already exist in Zoom — we match on phone number since names can differ between systems.

public class ContactSyncJob
{
    private readonly IClioService    _clio;
    private readonly IZoomService    _zoom;
    private readonly ILogger<ContactSyncJob> _logger;

    public ContactSyncJob(
        IClioService clio,
        IZoomService zoom,
        ILogger<ContactSyncJob> logger)
    {
        _clio   = clio;
        _zoom   = zoom;
        _logger = logger;
    }

    public async Task ExecuteAsync()
    {
        _logger.LogInformation("Starting contact sync at {Time}", DateTime.UtcNow);

        // Fetch all contacts from Clio (paginated)
        var clioContacts = await _clio.GetAllContactsAsync();

        // Fetch existing Zoom external contacts for deduplication
        var zoomContacts = await _zoom.GetExternalContactsAsync();
        var zoomByPhone  = zoomContacts
            .Where(z => !string.IsNullOrEmpty(z.Phone))
            .ToDictionary(z => z.Phone!.NormalizePhone(), z => z);

        int created = 0, updated = 0, skipped = 0;

        foreach (var contact in clioContacts)
        {
            try
            {
                var normalized = contact.PrimaryPhone?.NormalizePhone();

                if (string.IsNullOrEmpty(normalized))
                {
                    skipped++;
                    continue;
                }

                if (zoomByPhone.TryGetValue(normalized, out var existing))
                {
                    // Update if name changed
                    if (existing.DisplayName != contact.DisplayName)
                    {
                        await _zoom.UpdateExternalContactAsync(existing.Id, new ZoomContactRequest
                        {
                            DisplayName = contact.DisplayName,
                            Email       = contact.Email,
                            Phone       = contact.PrimaryPhone
                        });
                        updated++;
                    }
                }
                else
                {
                    await _zoom.CreateExternalContactAsync(new ZoomContactRequest
                    {
                        DisplayName = contact.DisplayName,
                        Email       = contact.Email,
                        Phone       = contact.PrimaryPhone
                    });
                    created++;
                }
            }
            catch (Exception ex)
            {
                _logger.LogError(ex,
                    "Failed to sync contact {Name}", contact.DisplayName);
            }
        }

        _logger.LogInformation(
            "Contact sync complete. Created: {C}, Updated: {U}, Skipped: {S}",
            created, updated, skipped);
    }
}

Job 2: Syncing Zoom Recordings and AI Summaries to Clio Notes
This is the most valuable part of the automation. Zoom's API provides three assets per meeting: the recording file URL, an AI-generated summary, and a full transcript. We download all three and post them as a structured note in Clio against the matching contact.

public class ZoomRecordingSyncJob
{
    private readonly IZoomService       _zoom;
    private readonly IClioService       _clio;
    private readonly ISyncStateService  _state;
    private readonly ILogger<ZoomRecordingSyncJob> _logger;

    public async Task ExecuteAsync()
    {
        // Only fetch recordings since last successful sync
        var lastSync = await _state.GetLastSyncTimeAsync("zoom-recordings");
        var fromDate = lastSync ?? DateTime.UtcNow.AddDays(-1);

        _logger.LogInformation("Fetching Zoom recordings since {From}", fromDate);

        var meetings = await _zoom.GetCloudRecordingsAsync(
            from: fromDate,
            to:   DateTime.UtcNow);

        foreach (var meeting in meetings)
        {
            try
            {
                // Try to match the meeting host/participant to a Clio contact
                var clioContact = await _clio
                    .FindContactByEmailAsync(meeting.HostEmail);

                if (clioContact is null)
                {
                    _logger.LogWarning(
                        "No Clio contact found for {Email}",
                        meeting.HostEmail);
                    continue;
                }

                // Build a rich note from all three Zoom assets
                var noteBody = BuildNoteContent(meeting);

                await _clio.CreateNoteAsync(new ClioNoteRequest
                {
                    Subject  = $"Zoom Call — {meeting.Topic} ({meeting.StartTime:MMM dd, yyyy})",
                    Body     = noteBody,
                    ContactId = clioContact.Id,
                    Date     = meeting.StartTime
                });

                _logger.LogInformation(
                    "Posted note for meeting {Topic} to contact {Name}",
                    meeting.Topic, clioContact.DisplayName);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex,
                    "Failed to sync meeting {Id}", meeting.Id);
            }
        }

        await _state.SetLastSyncTimeAsync("zoom-recordings", DateTime.UtcNow);
    }

    private static string BuildNoteContent(ZoomMeeting meeting)
    {
        var sb = new StringBuilder();

        sb.AppendLine($"**Meeting:** {meeting.Topic}");
        sb.AppendLine($"**Date:** {meeting.StartTime:f}");
        sb.AppendLine($"**Duration:** {meeting.Duration} minutes");
        sb.AppendLine($"**Host:** {meeting.HostEmail}");
        sb.AppendLine();

        if (!string.IsNullOrEmpty(meeting.AiSummary))
        {
            sb.AppendLine("## AI Summary");
            sb.AppendLine(meeting.AiSummary);
            sb.AppendLine();
        }

        if (!string.IsNullOrEmpty(meeting.Transcript))
        {
            sb.AppendLine("## Call Transcript");
            // Truncate to 5000 chars — Clio notes have limits
            var transcript = meeting.Transcript.Length > 5000
                ? meeting.Transcript[..5000] + "\n\n[Transcript truncated — see Zoom for full version]"
                : meeting.Transcript;
            sb.AppendLine(transcript);
        }

        if (!string.IsNullOrEmpty(meeting.RecordingUrl))
        {
            sb.AppendLine();
            sb.AppendLine($"[View Full Recording]({meeting.RecordingUrl})");
        }

        return sb.ToString();
    }
}

Job 3: Auto-Creating Box Folders When a New Matter Opens
When a lawyer opens a new matter in Clio, the firm needs a Box folder created immediately with the correct naming convention and subfolder structure. We poll Clio's matters API every 15 minutes looking for matters created since the last check, then create the Box folder hierarchy.

public class NewMatterBoxJob
{
    private readonly IClioService      _clio;
    private readonly IBoxService       _box;
    private readonly ISyncStateService _state;
    private readonly ILogger<NewMatterBoxJob> _logger;

    // The root Box folder ID where all matter folders live
    private const string ROOT_FOLDER_ID = "your-root-box-folder-id";

    public async Task ExecuteAsync()
    {
        var lastCheck = await _state.GetLastSyncTimeAsync("new-matters")
                        ?? DateTime.UtcNow.AddMinutes(-15);

        var newMatters = await _clio.GetMattersCreatedAfterAsync(lastCheck);

        foreach (var matter in newMatters)
        {
            try
            {
                // Check if folder already exists (idempotency guard)
                var folderName  = BuildFolderName(matter);
                var existingId  = await _box.FindFolderByNameAsync(
                    ROOT_FOLDER_ID, folderName);

                if (existingId is not null)
                {
                    _logger.LogInformation(
                        "Box folder already exists for matter {Id}", matter.Id);
                    continue;
                }

                // Create parent matter folder
                var matterFolderId = await _box.CreateFolderAsync(
                    parentId: ROOT_FOLDER_ID,
                    name:     folderName);

                // Create standard subfolder structure
                var subfolders = new[]
                {
                    "Correspondence",
                    "Pleadings",
                    "Discovery",
                    "Contracts",
                    "Research",
                    "Billing"
                };

                foreach (var sub in subfolders)
                {
                    await _box.CreateFolderAsync(
                        parentId: matterFolderId,
                        name:     sub);
                }

                // Store Box folder ID back in Clio custom field
                await _clio.UpdateMatterCustomFieldAsync(
                    matterId:    matter.Id,
                    fieldName:   "box_folder_id",
                    fieldValue:  matterFolderId);

                _logger.LogInformation(
                    "Created Box folder structure for matter: {Name}",
                    matter.DisplayNumber);
            }
            catch (Exception ex)
            {
                _logger.LogError(ex,
                    "Failed to create Box folder for matter {Id}", matter.Id);
            }
        }

        await _state.SetLastSyncTimeAsync("new-matters", DateTime.UtcNow);
    }

    private static string BuildFolderName(ClioMatter matter)
    {
        // Format: "2025-001 — Smith v Jones"
        var sanitized = Regex.Replace(
            matter.DisplayNumber + " — " + matter.Description,
            @"[\\/:*?""<>|]", "_");
        return sanitized[..Math.Min(sanitized.Length, 100)];
    }
}

OAuth 2.0 Token Management — The Part Everyone Gets Wrong
All three APIs (Clio, Lawmatics, Zoom) use OAuth 2.0. Tokens expire. If your Hangfire job runs at 3 AM and the access token expired at 2 AM, the job fails silently. The solution is a dedicated token service that automatically refreshes before every API call.

public class TokenService : ITokenService
{
    private readonly AppDbContext _db;
    private readonly IHttpClientFactory _http;

    public async Task<string> GetValidTokenAsync(string platform)
    {
        var stored = await _db.OAuthTokens
            .FirstOrDefaultAsync(t => t.Platform == platform)
            ?? throw new InvalidOperationException(
                $"No token found for {platform}. Re-authenticate.");

        // Refresh if token expires within the next 5 minutes
        if (stored.ExpiresAt <= DateTime.UtcNow.AddMinutes(5))
        {
            stored = await RefreshTokenAsync(stored);
        }

        return Decrypt(stored.AccessTokenEncrypted);
    }

    private async Task<OAuthToken> RefreshTokenAsync(OAuthToken token)
    {
        var client   = _http.CreateClient();
        var platform = GetPlatformConfig(token.Platform);

        var response = await client.PostAsync(
            platform.TokenEndpoint,
            new FormUrlEncodedContent(new Dictionary<string, string>
            {
                ["grant_type"]    = "refresh_token",
                ["refresh_token"] = Decrypt(token.RefreshTokenEncrypted),
                ["client_id"]     = platform.ClientId,
                ["client_secret"] = platform.ClientSecret
            }));

        response.EnsureSuccessStatusCode();

        var result = await response.Content
            .ReadFromJsonAsync<OAuthTokenResponse>();

        token.AccessTokenEncrypted  = Encrypt(result!.AccessToken);
        token.ExpiresAt             = DateTime.UtcNow
                                        .AddSeconds(result.ExpiresIn - 60);

        if (!string.IsNullOrEmpty(result.RefreshToken))
            token.RefreshTokenEncrypted = Encrypt(result.RefreshToken);

        _db.OAuthTokens.Update(token);
        await _db.SaveChangesAsync();

        return token;
    }

    // AES-256 encryption for stored tokens
    private string Encrypt(string plainText) { /* AES-256-CBC impl */ }
    private string Decrypt(string cipherText) { /* AES-256-CBC impl */ }
}

Results and What This Saved
After deploying this system, the results were immediate. The firm eliminated approximately 2–3 hours of daily admin work, removed all manual copy-paste errors between systems, and ensured every Zoom call automatically appeared as a structured note in Clio within hours — without anyone touching a keyboard.

The Hangfire dashboard gave the firm's operations lead full visibility into every job run, every failure, and every retry — so when Zoom's API had a 20-minute outage one morning, the jobs simply queued and completed automatically when the service came back online.

Key Takeaways
If you're building similar multi-platform integrations in .NET, these are the principles that saved us the most time:

1. Store sync state — always record the last successful sync timestamp. Never re-process everything from the beginning.
2. Match on stable identifiers — phone numbers and emails are more reliable than names across systems.
3. Make jobs idempotent — running a job twice should produce the same result as running it once.
4. Encrypt tokens at rest — OAuth tokens are credentials. Treat them like passwords.
5. Use Hangfire's dashboard — give your client visibility into the automation. It builds trust and surfaces issues before they become problems.