Environments
Every key belongs to one environment. Sandbox keys (lhg_sbx_…) exercise the full API with no real-world side effects: e-filing goes to the courts' test system, serve jobs are flagged sandbox and never dispatched, no email reaches a real person, no card is charged. Production keys (lhg_prd_…) do the real thing. Both environments live at this same base URL — the key decides.
Authentication — HMAC-SHA256 request signing
You hold a key id (public) and a secret (shown once when the key is issued — store it in your secret manager; we cannot show it again, only rotate it). Every request except GET /v1/health carries four headers:
| Header | Value |
|---|---|
LHG-Key-Id | Your key id |
LHG-Timestamp | Unix seconds at signing time (accepted within ±300s of server time) |
LHG-Nonce | A unique string per request, at most 64 characters (random hex is fine). Each nonce is accepted once. |
LHG-Signature | Lowercase hex HMAC-SHA256 of the canonical string, keyed by your secret |
The canonical string
Five lines joined by \n (a literal newline, no trailing newline):
METHOD uppercase — GET
PATH path incl. query string — /v1/partner
TIMESTAMP exactly as sent in LHG-Timestamp
NONCE exactly as sent in LHG-Nonce
SHA256(BODY) lowercase hex of the raw request body;
for GET / empty body use the empty hash:
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Worked example
Computed with the server's own signing code — reproduce these exact values and your implementation is correct. Request bodies, when you send one, must be JSON (Content-Type: application/json); hash the exact bytes you send.
key id: lhg_sbx_k_9f2c41d8a6b3e07f
secret: lhg_sbx_s_0000000000000000000000000000000000000000000000000000000000000000
request: GET https://api.legalhubgroup.com/v1/partner (no body)
timestamp: 1758400000
nonce: 5f2b9c0d7e4a13c6
canonical string (shown with \n visible):
GET\n
/v1/partner\n
1758400000\n
5f2b9c0d7e4a13c6\n
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
signature = HMAC_SHA256(secret, canonical) =
2c4fa8d0d3329eaaec62b0505030090101c84f2fc4dbec9b66e53734171ee165
// Node.js
const crypto = require('crypto');
function signedHeaders(keyId, secret, method, path, body) {
const ts = String(Math.floor(Date.now() / 1000));
const nonce = crypto.randomBytes(16).toString('hex');
const bodyHash = crypto.createHash('sha256').update(body || Buffer.alloc(0)).digest('hex');
const canonical = [method.toUpperCase(), path, ts, nonce, bodyHash].join('\n');
const signature = crypto.createHmac('sha256', secret).update(canonical).digest('hex');
return { 'LHG-Key-Id': keyId, 'LHG-Timestamp': ts, 'LHG-Nonce': nonce, 'LHG-Signature': signature };
}
// const res = await fetch('https://api.legalhubgroup.com/v1/partner',
// { headers: signedHeaders(KEY_ID, SECRET, 'GET', '/v1/partner') });
Endpoints
| Endpoint | Auth | What it does |
|---|---|---|
GET /v1/health | none | Connectivity check — proves DNS, TLS and routing before you write signing code |
GET /v1/partner | signed | Returns your partner name, environment, scopes, rate limit and IP allowlist — the first signed call to make |
GET /v1/openapi.json | none | This API as an OpenAPI 3 document |
POST /v1/efile/handoffs | signed · efile | Start an e-filing handoff: creates/matches the firm and user, pre-fills a draft, answers with a one-time portal URL |
POST /v1/efile/filings/{id}/documents | signed · efile | Upload a PDF as raw request bytes onto a draft (alternative to document URLs) |
GET /v1/efile/filings | signed · efile | List your filings, filterable by ?case_ref= / ?filing_ref= |
GET /v1/efile/filings/{id} | signed · efile | One filing: status, fees, every document's rejection reason, e-service delivery per person, documents with signed download URLs |
GET /v1/efile/service-notices | signed · efile | The court system's "you were e-served" notices for your firms, filterable by ?since= / ?case_number= |
GET /v1/efile/filings/{id}/documents/{docId} | signed or pre-signed URL | Download a filed or court-stamped PDF |
POST /v1/serve/jobs | signed · serve | Create a fully-priced process-serving job; the answer carries list, discount and net |
POST /v1/serve/jobs/{id}/documents | signed · serve | Upload a PDF as raw request bytes onto a job (alternative to document URLs) |
GET /v1/serve/jobs | signed · serve | List your serve jobs, filterable by ?case_ref= / ?firm_ref= / ?status= |
GET /v1/serve/jobs/{id} | signed · serve | One job: status, every attempt's details, documents, proof status |
GET /v1/serve/jobs/{id}/proof | signed or pre-signed URL | Download the released proof of service |
POST /v1/serve/jobs/{id}/cancel | signed · serve | Cancel while unassigned or before the first attempt |
GET /v1/serve/pricing | signed · serve | Published rates per state and service level, and your net price |
Scopes (efile, serve, concierge) gate endpoint groups; your key's granted scopes appear in GET /v1/partner. An efile or serve endpoint answers 403 insufficient_scope until that scope is on your key.
E-filing — the handoff flow
Your product owns the client relationship; the filing itself is finished on your own branded LHG portal. One round-trip:
- A firm clicks e-File in your product. Your backend calls
POST /v1/efile/handoffswith the firm (keyed byfirm.external_ref, your own id), the user, the case, the parties, the documents (public https URLs we fetch, or bytes you push afterwards), yourcase_ref/filing_ref, and areturn_url. - We answer with
handoff.url— a one-time link, valid 15 minutes — andfiling_id. Send the firm's browser there. - The link opens your branded portal, signs your user in (you are the identity provider — no LHG password exists), and lands on the draft with everything pre-filled. Court-specific choices your payload cannot know (the court's own case type, party type and filing codes, document confidentiality) are waiting with your words shown as hints; nothing is guessed.
- First time only, when the draft first reaches Review, the page asks the firm to set up its court-system account — registration with the court's filing system and a payment method (card details go to the court system's own hosted page, never to us or you) — and brings it straight back to the draft. The draft itself opens at once; from then on every handoff opens ready to file. The signed-in session lasts 8 hours, so setup never races the URL's 15 minutes.
- The firm reviews the court's live fee quote and submits. Every page shows Return to you, which goes to your
return_urlwithlhg_filing,lhg_statusandfiling_refappended. - Status flows back on your webhook (below). A rejection? POST a new handoff with the same
filing_ref: it opens a corrected draft with everything carried over and the court's reasons on top —rejection.documents[]carries every document's own reason, not just one.
E-service
Filing into an existing case, the portal's Serve step lets the firm pick who to e-serve — the people the court has on file for the case, the firm's own service contacts, and the court system's public directory — and the envelope goes out file-and-serve. E-service carries no charge. What comes back to you:
service.recipients[]onGET /v1/efile/filings/{id}and on everyefile.accepted/efile.status_changedpayload: each person served, per pleading, withstatussent,deliveredorfailedand the court system's note.nullwhen the filing served nobody.efile.status_changedwithevent: "service_failed"when the court system could not deliver to someone (service_failure.{name,email,reason}); the firm is emailed at the same time.efile.servedwhen one of your firms is itself e-served on a case — who served it, the case, the documents, and yourfirm_external_ref. Sent for live notices served within the last 3 days; older ones (and notices rebuilt from the court system's archive) are listed only, byGET /v1/efile/service-notices.
Worked handoff example
POST /v1/efile/handoffs
Content-Type: application/json
(+ the four signing headers over these exact body bytes)
{
"firm": {
"external_ref": "firm_8842",
"name": "Kim & Associates",
"address": "18375 Ventura Blvd, Tarzana, CA 91356",
"phone": "(818) 555-0140",
"email": "office@kimassociates.example",
"attorney": { "name": "Daniel Kim", "bar_number": "251804" }
},
"user": { "email": "daniel@kimassociates.example", "name": "Daniel Kim" },
"case": {
"court_code": "santacruz:cv",
"county": "Santa Cruz",
"category": "Civil — Unlimited",
"type": "Breach of Contract"
},
"parties": [
{ "role": "Plaintiff", "type": "person", "first_name": "Maria", "last_name": "Lopez" },
{ "role": "Defendant", "type": "organization", "org_name": "Acme Builders LLC" }
],
"documents": [
{ "url": "https://files.notyourlawyer.example/d/complaint.pdf", "title": "Complaint for Breach of Contract", "lead": true },
{ "url": "https://files.notyourlawyer.example/d/coversheet.pdf", "title": "Civil Case Cover Sheet" }
],
"case_ref": "case_5511",
"filing_ref": "filing_9020",
"return_url": "https://app.notyourlawyer.example/cases/5511/filings/9020/back"
}
→ 201
{
"handoff": {
"id": "pho_41",
"url": "https://nyl.legalhubgroup.com/partner/handoff/…one-time-token…",
"expires_at": "2026-09-21T18:15:00.000Z"
},
"filing_id": 118,
"firm": "created",
"user": "created"
}
Filing into an existing case: include case.case_number — the portal pre-fills the court's case search with it and the filer confirms the match (a case is never bound unseen). An unrecognised court_code or an unusable attorney comes back in warnings and is left to the filer.
E-filing webhook events
| Event | Sent when |
|---|---|
efile.submitted | The court's filing system received the envelope |
efile.accepted | The clerk accepted the filing — documents[] carries signed download URLs for the court-stamped copies retrieved so far |
efile.rejected | The clerk rejected it — rejection.reason carries the court's reason and rejection.documents[] every document's own reason |
efile.status_changed | Any other movement: partially_accepted, cancelled, event:"stamped_copy_ready" when a court-stamped copy arrives after acceptance, or event:"service_failed" when the court system could not deliver e-service to someone the filing served (service_failure.{name,email,reason}) |
efile.served | One of your firms was e-served — the notice (firm_external_ref, who served, case, documents); also listed by GET /v1/efile/service-notices |
Every payload's data is the same filing object GET /v1/efile/filings/{id} answers with: your case_ref/filing_ref, our filing_id, the court, the case number, timestamps, the fee lines as charged, and — on acceptance — documents[] with signed, expiring download URLs (7 days) for the court-stamped copies and receipts. Delivery is at-least-once: dedupe on the delivery id, and treat a repeated status as the no-op it is.
Sandbox
Run the whole flow with your lhg_sbx_… key first. Sandbox handoffs create sandbox firms — completely separate from any production firm with the same external_ref — whose portal is clearly banner-marked and whose filings go to the courts' test system: registration, payment setup (the test system's card page), fee quotes and clerk review all behave like the real thing, but no real filing exists, no real email is sent and nothing is charged. Production keys repeat the identical calls.
Process serving
Serving is server-to-server end to end — no portal, no handoff. Your backend creates a job, we dispatch a process server, and every movement comes back on your webhook. Your law firms never appear on our platform: your firm_ref and case_ref ride each job as data, the field server sees an ordinary job with the caption and your instructions, and everything reconciles back to your own records.
- Quote from
GET /v1/serve/pricing— the published list rate per state and service level, and your net (the exact number the job will carry). What you charge your own customer is yours. POST /v1/serve/jobswith the servee (person, or entity with its registered agent), the service address, the documents (public https URLs, or push bytes afterwards), the document type, the service level, the due date, the caption for the proof (court, case number, plaintiff, defendant), the attorney of record (orself_represented), your refs and any notes to the server. The answer is the created job with its frozen price.- Track by webhook:
serve.assigned,serve.accepted, then aserve.attemptfor every attempt — number, time, outcome, method, who took the papers — followed byserve.servedorserve.non_serve. The server's identity is never included. - When the signed proof of service is released,
serve.proof_readydelivers a signed download URL (7 days; also available any time viaGET /v1/serve/jobs/{id}/proof). - Every two weeks we invoice you for the completed jobs at your net price, one line per job with your
case_refon it —serve.invoicedfires per job when the invoice goes out. Nothing is ever invoiced to your firms. - Need to pull a job back?
POST /v1/serve/jobs/{id}/cancelworks while it is unassigned or before the first attempt; after that our operations team decides.
Worked serve example
POST /v1/serve/jobs
Content-Type: application/json
(+ the four signing headers over these exact body bytes)
{
"firm_ref": "firm_8842",
"case_ref": "case_5511",
"servee": { "first_name": "John", "last_name": "Roe" },
"service_address": {
"address": "1234 Pacific Ave", "address2": "Apt 2",
"city": "Santa Cruz", "county": "Santa Cruz", "state": "CA", "zip": "95060"
},
"documents": [
{ "url": "https://files.notyourlawyer.example/d/summons.pdf", "title": "Summons" },
{ "url": "https://files.notyourlawyer.example/d/complaint.pdf", "title": "Complaint" }
],
"document_type": "summons_complaint",
"service_level": "routine",
"due_date": "2026-10-15",
"case": {
"case_number": "26CV01234",
"plaintiff": "Maria Lopez",
"defendant": "John Roe",
"court_county": "Santa Cruz",
"court_branch": "Main Courthouse"
},
"attorney": {
"name": "Daniel Kim", "bar_number": "251804",
"firm_name": "Kim & Associates",
"address": "18375 Ventura Blvd, Tarzana, CA 91356",
"phone": "(818) 555-0140", "email": "office@kimassociates.example"
},
"notes": "Gate code 4415. Do not attempt before 8am."
}
→ 201
{
"job": {
"job_id": 512,
"status": "unassigned",
"service_level": "routine",
"partner_firm_ref": "firm_8842",
"partner_case_ref": "case_5511",
"price": { "list_cents": 15000, "discount_cents": 3000, "net_cents": 12000, "discount_percent": 20 },
"proof": { "status": null },
…
}
}
Serve webhook events
| Event | Sent when |
|---|---|
serve.created | A serve job was created through the API |
serve.assigned | A process server took the job |
serve.accepted | The server acknowledged the assignment |
serve.attempt | Every attempt, successful or not — number, time, outcome, method, receiver details; never the server's identity |
serve.served | Service completed |
serve.non_serve | Service could not be completed (due diligence done) |
serve.cancelled | The job was cancelled — by your API call or by our operations team |
serve.proof_ready | The signed proof of service was released — proof.download_url is a signed URL valid 7 days |
serve.invoiced | The job appeared on an invoice we sent you — invoice.{invoice_number, amount_cents, due_date} |
Every payload's data is the same job object GET /v1/serve/jobs/{id} answers with — your refs, our job_id, status, price and timestamps; attempt events carry attempts[], and serve.proof_ready carries proof.download_url.
Serve sandbox
Sandbox keys create sandbox jobs that never reach a real process server. Ask us to drive one through its lifecycle (assign → accept → attempts → served → proof released) and your receiver hears every serve.* event with realistic payloads, including a working signed proof URL. Production keys repeat the identical calls.
Rate limits
Per key, default 60 requests/minute (sliding window; configurable per key — ask us if you need more). Exceeding it returns 429 with a Retry-After header. Back off and retry; do not tight-loop.
Errors
Every failure is JSON: {"error":{"code":"…","message":"…"}}. The code is stable; branch on it, not on the message.
| HTTP | Code | Meaning |
|---|---|---|
| 401 | missing_key / unknown_key / revoked_key | The LHG-Key-Id header is absent, unknown, or the key was revoked |
| 401 | invalid_timestamp | LHG-Timestamp malformed or outside the ±300s window — check clock skew |
| 401 | invalid_signature | Signature mismatch — recheck the canonical string, especially the query string and body hash |
| 401 | nonce_replayed | That nonce was already used with this key — generate a fresh one per request |
| 403 | ip_not_allowed | Your source IP is not on the key's allowlist |
| 403 | partner_inactive / insufficient_scope | Account inactive, or the key lacks the scope the endpoint needs |
| 429 | rate_limited | Over the per-key limit — respect Retry-After |
| 404 | not_found | No such endpoint |
Webhooks
Each key can register one HTTPS webhook URL with its own signing secret (issued when the URL is set, shown once). We POST JSON events to it:
{
"id": "whd_123", // delivery id — dedupe on it; retries reuse it
"type": "test.ping", // event type
"environment": "sandbox", // sandbox events never mean real-world activity
"created_at": "2026-09-21T18:00:00.000Z",
"data": { … }
}
| Header | Value |
|---|---|
LHG-Webhook-Id | Delivery id (same as body id) |
LHG-Event | Event type |
LHG-Webhook-Timestamp | Unix seconds at send time |
LHG-Webhook-Signature | Hex HMAC-SHA256 of "<timestamp>.<raw body>" with your webhook secret |
Verify by recomputing the HMAC over the timestamp header, a dot, and the raw body bytes, then compare constant-time; reject timestamps older than a few minutes. Answer 2xx quickly (do slow work async). Non-2xx or a timeout is retried with exponential backoff (2, 4, 8… minutes, 8 attempts). Events: test.ping (from the LHG admin console) and the efile.* and serve.* families above; concierge events arrive with that phase.
Legal Hub Group · questions: info@legalhubgroup.com