API Reference

The CaseLumen API lets a law firm’s own systems send data into its CaseLumen account. Today it does one thing: it opens a new intake from a lead, for example when someone fills in the contact form on the firm’s website.

Every request goes to https://caselumen.com/api/v1, sends and receives JSON, and should include Accept: application/json and Content-Type: application/json.

Requests are signed with an API key. A firm’s Owner or Admin creates keys in CaseLumen under Settings → API. Each key belongs to one firm, can do only what it was allowed to do when it was made, and is shown once, when it’s created. Keys start with caselumen_.

Send the key as a bearer token:

Authorization: Bearer caselumen_…

Keep the key on your server. Never put it in a web page, browser JavaScript or a mobile app, where anyone can read it. A website form should post to your own server, and your server calls CaseLumen. If a key may have leaked, revoke it in Settings → API and create a new one.

POST https://caselumen.com/api/v1/intakes  ·  needs a key that can Create intakes.

Opens a new intake, with the person as a new potential-client contact. Send any of these fields:

The intake starts as New, with the firm’s default practice area and case type, and the firm’s usual new-intake email goes out. The contact is always a new one, even when the email matches someone already in CaseLumen: staff check conflicts and merge duplicates themselves.

Example:

curl https://caselumen.com/api/v1/intakes \
  -H "Authorization: Bearer $CASELUMEN_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: website-lead-8812" \
  -d '{
    "name": "Maria L. Gonzalez",
    "email": "maria@example.com",
    "phone": "(555) 201-4477",
    "incident_date": "2026-09-14",
    "description": "My surgeon left a sponge inside me during my gallbladder surgery.",
    "is_urgent": true,
    "source": "Google / Organic Search",
    "referral_notes": "How did you hear about us: Internet search"
  }'

A new intake answers 201 Created:

{
  "data": {
    "id": 1482,
    "status": "new",
    "url": "https://app.example.com/intakes/1482",
    "created_at": "2026-10-19T17:04:12+00:00"
  }
}

url opens the intake in CaseLumen, for staff who are signed in.

Networks fail, so your server should retry a request that timed out or got a 5xx answer. To make retrying safe, send an Idempotency-Key header: any unique string up to 255 characters, such as a UUID made once per form submission and reused on every retry of it.

A request repeating a key CaseLumen has already seen doesn’t open a second intake. It answers 200 OK with the intake the first request opened. A retry that arrives while the first request is still running waits for it; if that takes too long, it answers 409 Conflict, and you can retry again shortly. Keys are remembered for 90 days.

Every error has a message. A 422 looks like this:

{
  "message": "Send an email or a phone number, so the firm can reach the person.",
  "errors": {
    "email": ["Send an email or a phone number, so the firm can reach the person."],
    "phone": ["Send an email or a phone number, so the firm can reach the person."]
  }
}

If a lead can’t be delivered, keep your own copy (or email it to the firm) so it isn’t lost.

Each key may make 60 requests a minute. Past that, CaseLumen answers 429 Too Many Requests with a Retry-After header giving the seconds to wait.

The firm’s Owners and Admins can see every request made with the firm’s keys under Settings → API: when it came in, which key made it, what it sent, and what CaseLumen answered. Requests are kept for 90 days. When an integration misbehaves, start there.

This is version 1, under /api/v1. Version 1 may gain new optional fields and new fields in its answers, so ignore fields you don’t know. Anything that would break an existing integration will come as a new version.