Lukhoo Attorney API Integration Guide

See the complete connection

A webhook announces that something changed. Your software then uses its API key to fetch the current permitted record and can write an authorized response back to Lukhoo.

SOURCE TO TARGET TO SOURCE

1. Client uses LukhooAn incident, permission, conversation, or message changes.

2. Lukhoo sends noticeA signed webhook delivers an event type and resource reference.

3. Firm receivesYour HTTPS endpoint stores the event and returns a 2xx response.

4. Firm fetches or repliesYour software uses its API key to read the resource or send a message.

5. Lukhoo stays currentThe client, Attorney Portal, API Console, and API reflect the same backend record.

Keep the roles separate

The API key authorizes API requests. The webhook signing secret proves that a webhook came from Lukhoo. They are different secrets and are never interchangeable.

Make your first successful request

Start with a read. This confirms membership, API-key authentication, attorney identity, and connectivity without changing client data.

ABOUT 5 MINUTES

Sign in to the API Console. Portal + API Integration Access must be active.
Open Connection. Create a key named for the system using it, such as Case management production.
Select only required permissions. For the complete messaging test, select incidents:read, messages:read, messages:write, and engagements:write.
Store the key immediately. It begins with lk_live_ and is displayed once. Put it in the firm's secret manager or Postman local secret value.
Call the conversations endpoint. A 200 response proves the API connection is authenticated.

Postman or terminal

First read

GET /conversations?after=0&limit=100
Authorization: Bearer lk_live_YOUR_KEY

curl -sS "https://lukhoo.com/api/attorney/v1/conversations?after=0&limit=100" \
  -H "Authorization: Bearer $LUKHOO_API_KEY"

Expected

HTTP 200 with an items array. An empty array means the key worked but this attorney currently has no permitted conversations.

Configure event delivery

Webhooks are the primary near-real-time notification channel. They tell the firm what changed without placing private incident or message content in the notification.

LUKHOO TO FIRM

Connection check

Test without firm software

In Connection, select Create test receiver.
On the Lukhoo test receiver, select Send test.
Open Activity and find test.delivery.
Confirm delivered, HTTP 200, and signature verified.

What this test proves

It proves event creation, HMAC signing, HTTP delivery, signature verification, and acknowledgement. It uses synthetic data only. It does not fetch a client record or send a client message.

Firm endpoint

Receive live event references

Provide a public HTTPS URL on port 443 that your firm controls.
Select the event types the firm needs and save the endpoint.
Store the one-time whsec_ signing secret securely.
Send a test. Live events begin only after the endpoint returns a successful response.
Persist each event before returning a 2xx response.

Do not use public request-capture sites with real clients

Use a receiver controlled by the firm or a designated Lukhoo test environment. Even reference identifiers should be treated as protected integration data.

What the firm receives

{
  "spec_version": "1.0",
  "event_id": "b38d0a60-2367-4c67-a6ad-bb9d83243a12",
  "sequence": "125",
  "event_type": "message.created",
  "created_at": "2026-09-08T18:00:00.000Z",
  "data": {
    "resource_type": "message",
    "resource_id": "456",
    "resource_url": "/api/attorney/v1/messages/456"
  }
}

VerifyRead Lukhoo-Signature, extract the timestamp, and calculate HMAC-SHA256 over the exact bytes of timestamp + "." + raw_request_body. RejectReject an invalid signature or a timestamp more than five minutes from the receiver's server clock. StoreDeduplicate with event_id. Deliveries are at least once and may arrive again or out of order. FetchCall data.resource_url with the Bearer API key to obtain the current authorized resource.

Test a complete message round trip

Use one designated test client and one test attorney. These steps create real Lukhoo messages so both sides can verify the same conversation.

CLIENT TO FIRM TO CLIENT

Source: Lukhoo client

Client sends the first message

Open or resume a permitted conversation for the designated test client.
From the client side of Lukhoo, send a recognizable message such as Round-trip test 001.
Lukhoo detects the new message, normally within about 10 seconds plus processing time.
The verified firm endpoint receives message.created with a message resource URL.

Target: firm software or Postman

Firm fetches and replies

Fetch the webhook's resource_url with the API key.
Read conversation_id from the authorized message response.
POST the attorney reply to that conversation with a unique idempotency key.
Confirm the client sees the reply in Lukhoo and that the API Console and Attorney Portal show the same conversation.

POST /conversations/123/messages
Authorization: Bearer lk_live_YOUR_KEY
Content-Type: application/json
Idempotency-Key: roundtrip-test-001

{
  "body": "Attorney API round-trip test reply."
}

Expected

Lukhoo returns HTTP 200 with message_id and created_at. The client receives the attorney message through the same Lukhoo conversation, notification, and checkpoint records used by the Attorney Portal.

Retry rule

If the response is uncertain, retry with the same Idempotency-Key and exactly the same body. Use a new key for a new message. Reusing a key with different content returns 409.

Know what each event means

Event notifications are instructions to fetch or reconcile current state. They are not permanent copies of client records.

EVENT CONTRACT

Event	Meaning	Firm action
`incident.created`	A permitted incident became visible.	Fetch the incident and create or update the local view.
`incident.updated`	Incident data, evidence availability, permission, or scoring changed.	Fetch the incident again and replace cached current state.
`incident.removed`	The incident is no longer available to this attorney.	Remove private details from active firm views.
`conversation.updated`	Contact-window, unread, or hiring state changed.	Fetch the conversation and update workflow status.
`message.created`	A client or attorney message was created.	Fetch the message, deduplicate it, and update the conversation.
`message.updated`	A currently visible message changed.	Fetch it again and reconcile the local copy.

Use GET /events?after=125&limit=100 with the last saved sequence for recovery. Webhooks are near real time; the event cursor is the recovery path when a receiver was unavailable.

Access and security rules

Every read, write, artifact download, and webhook delivery is checked against current membership and current client permission.

ALWAYS ENFORCED

Membership

Portal AccessThe attorney uses the Lukhoo Portal. API reads, writes, downloads, keys, and webhook delivery are unavailable. Portal + APIThe portal and authorized firm software can use the same currently permitted records. API inactivePortal Access can continue while active, but API requests and new webhook deliveries stop.

Client permission

SummaryThe attorney sees only the permitted summary until contact and detail rules are satisfied. UnlockedDetails and evidence remain available only while membership, contact, and sharing rules permit them. RemovedThe firm must stop displaying private details when access is removed or a fetch returns 403 or 404.

API keys are restricted credentials. Rotate or revoke them in Connection. Webhook signing secrets must be stored separately. Never place either secret in browser code, source control, support tickets, screenshots, or application logs.

Understand common responses

The response code tells the firm whether to fix the request, refresh permission, or retry later.

OPERATIONS

Response	Meaning	Next action
`200 / 201`	The request completed.	Store the returned identifier or cursor.
`400`	The request, paging value, or idempotency key is invalid.	Correct the request before retrying.
`401 console_sign_in_required`	No Bearer Authorization header reached the API.	Set Postman to Bearer Token or restore the missing header.
`401 invalid_api_key`	The Bearer key is malformed, invalid, expired, or revoked.	Check the key value or rotate the key.
`403 scope_required`	The key lacks the required permission.	Create or use a key with the required scope.
`403 api_membership_required`	Portal + API Integration Access is not active.	Review membership before retrying.
`404`	The resource does not exist or is no longer visible.	Remove cached private details from the active view.
`409`	An idempotency key was reused for different content or the requested state conflicts.	Do not blindly retry; reconcile the original action.
`429`	A request limit was reached.	Honor the rate-limit headers and retry with backoff.
`503`	A required Lukhoo source could not be verified.	Retry later with exponential backoff.

Connect Lukhoo to your firm software