Legal Hub Group — Partner API

Server-to-server API for LHG partners · base URL https://api.legalhubgroup.com · OpenAPI 3 spec

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:

HeaderValue
LHG-Key-IdYour key id
LHG-TimestampUnix seconds at signing time (accepted within ±300s of server time)
LHG-NonceA unique string per request, at most 64 characters (random hex is fine). Each nonce is accepted once.
LHG-SignatureLowercase 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

EndpointAuthWhat it does
GET /v1/healthnoneConnectivity check — proves DNS, TLS and routing before you write signing code
GET /v1/partnersignedReturns your partner name, environment, scopes, rate limit and IP allowlist — the first signed call to make
GET /v1/openapi.jsonnoneThis API as an OpenAPI 3 document
POST /v1/efile/handoffssigned · efileStart 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}/documentssigned · efileUpload a PDF as raw request bytes onto a draft (alternative to document URLs)
GET /v1/efile/filingssigned · efileList your filings, filterable by ?case_ref= / ?filing_ref=
GET /v1/efile/filings/{id}signed · efileOne filing: status, fees, every document's rejection reason, e-service delivery per person, documents with signed download URLs
GET /v1/efile/service-noticessigned · efileThe 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 URLDownload a filed or court-stamped PDF
POST /v1/serve/jobssigned · serveCreate a fully-priced process-serving job; the answer carries list, discount and net
POST /v1/serve/jobs/{id}/documentssigned · serveUpload a PDF as raw request bytes onto a job (alternative to document URLs)
GET /v1/serve/jobssigned · serveList your serve jobs, filterable by ?case_ref= / ?firm_ref= / ?status=
GET /v1/serve/jobs/{id}signed · serveOne job: status, every attempt's details, documents, proof status
GET /v1/serve/jobs/{id}/proofsigned or pre-signed URLDownload the released proof of service
POST /v1/serve/jobs/{id}/cancelsigned · serveCancel while unassigned or before the first attempt
GET /v1/serve/pricingsigned · servePublished 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:

  1. A firm clicks e-File in your product. Your backend calls POST /v1/efile/handoffs with the firm (keyed by firm.external_ref, your own id), the user, the case, the parties, the documents (public https URLs we fetch, or bytes you push afterwards), your case_ref/filing_ref, and a return_url.
  2. We answer with handoff.url — a one-time link, valid 15 minutes — and filing_id. Send the firm's browser there.
  3. 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.
  4. 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.
  5. The firm reviews the court's live fee quote and submits. Every page shows Return to you, which goes to your return_url with lhg_filing, lhg_status and filing_ref appended.
  6. 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:

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

EventSent when
efile.submittedThe court's filing system received the envelope
efile.acceptedThe clerk accepted the filing — documents[] carries signed download URLs for the court-stamped copies retrieved so far
efile.rejectedThe clerk rejected it — rejection.reason carries the court's reason and rejection.documents[] every document's own reason
efile.status_changedAny 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.servedOne 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.

  1. 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.
  2. POST /v1/serve/jobs with 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 (or self_represented), your refs and any notes to the server. The answer is the created job with its frozen price.
  3. Track by webhook: serve.assigned, serve.accepted, then a serve.attempt for every attempt — number, time, outcome, method, who took the papers — followed by serve.served or serve.non_serve. The server's identity is never included.
  4. When the signed proof of service is released, serve.proof_ready delivers a signed download URL (7 days; also available any time via GET /v1/serve/jobs/{id}/proof).
  5. Every two weeks we invoice you for the completed jobs at your net price, one line per job with your case_ref on it — serve.invoiced fires per job when the invoice goes out. Nothing is ever invoiced to your firms.
  6. Need to pull a job back? POST /v1/serve/jobs/{id}/cancel works 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

EventSent when
serve.createdA serve job was created through the API
serve.assignedA process server took the job
serve.acceptedThe server acknowledged the assignment
serve.attemptEvery attempt, successful or not — number, time, outcome, method, receiver details; never the server's identity
serve.servedService completed
serve.non_serveService could not be completed (due diligence done)
serve.cancelledThe job was cancelled — by your API call or by our operations team
serve.proof_readyThe signed proof of service was released — proof.download_url is a signed URL valid 7 days
serve.invoicedThe 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.

HTTPCodeMeaning
401missing_key / unknown_key / revoked_keyThe LHG-Key-Id header is absent, unknown, or the key was revoked
401invalid_timestampLHG-Timestamp malformed or outside the ±300s window — check clock skew
401invalid_signatureSignature mismatch — recheck the canonical string, especially the query string and body hash
401nonce_replayedThat nonce was already used with this key — generate a fresh one per request
403ip_not_allowedYour source IP is not on the key's allowlist
403partner_inactive / insufficient_scopeAccount inactive, or the key lacks the scope the endpoint needs
429rate_limitedOver the per-key limit — respect Retry-After
404not_foundNo 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": { … }
}
HeaderValue
LHG-Webhook-IdDelivery id (same as body id)
LHG-EventEvent type
LHG-Webhook-TimestampUnix seconds at send time
LHG-Webhook-SignatureHex 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