Lawmatics Developer Documentation
Technical reference for the CaseHug–Lawmatics integration. API endpoints, data models, webhook events, pipeline stage mapping, and OAuth 2.0 authentication flow.
Authentication Flow
CaseHug uses Lawmatics' OAuth 2.0 Authorization Code Grant flow. Firms must have developer settings enabled (contact support@lawmatics.com).
1. User clicks "Connect to Lawmatics"
2. CaseHug generates CSRF state, stores in oauth_states table
3. Redirect → https://app.lawmatics.com/oauth/authorize
?response_type=code
&client_id={LAWMATICS_CLIENT_ID}
&redirect_uri={callback_url}
&scope=read write
&state={csrf_state}
4. User authorizes in Lawmatics
5. Lawmatics redirects → /api/v1/integrations/lawmatics/callback?code=xxx&state=xxx
6. CaseHug validates CSRF state
7. POST https://app.lawmatics.com/oauth/token
grant_type=authorization_code
&code={code}
&client_id={LAWMATICS_CLIENT_ID}
&client_secret={LAWMATICS_CLIENT_SECRET}
&redirect_uri={callback_url}
8. Store access_token + refresh_token in firm_integrations
9. Redirect to dashboard with success message⚠️ Token refresh: Access tokens expire. CaseHug automatically refreshes tokens 5 minutes before expiration using the refresh_token grant type. If refresh fails, the firm must reconnect.
API Endpoints
/api/v1/integrations/lawmatics/connectInitiates OAuth flow. Generates CSRF state, stores in DB, redirects to Lawmatics authorize URL.
302 Redirect to Lawmatics/api/v1/integrations/lawmatics/callbackOAuth callback. Validates CSRF state, exchanges authorization code for tokens, stores in firm_integrations, redirects to dashboard.
302 Redirect to dashboard/api/v1/integrations/lawmatics/disconnectRevokes Lawmatics OAuth access, removes tokens from DB, deactivates integration.
{ "success": true }/api/v1/integrations/lawmatics/statusReturns connection status, sync settings, and last sync time.
{ "connected": true, "settings": {...}, "last_sync": {...} }/api/v1/integrations/lawmatics/statusUpdate integration settings (auto-sync toggles, case type mappings).
{ "success": true, "settings": {...} }/api/v1/integrations/lawmatics/syncSync a specific matter to Lawmatics. Body: { "matter_id": "uuid", "action": "sync_matter" | "pull_matters" }
{ "success": true, "lawmatics_matter_id": 12345 }/api/v1/integrations/lawmatics/syncGet sync history for the firm. Query: ?matter_id=xxx&limit=20
{ "logs": [...], "total": 20 }/api/v1/integrations/lawmatics/webhooksReceives webhook events from Lawmatics. Validates signature, processes events, stores in audit log.
{ "received": true }Data Models
firm_integrations
| Column | Type | Description |
|---|---|---|
| firm_id | UUID | Foreign key to firms table |
| platform | TEXT | "lawmatics" |
| access_token | TEXT | OAuth access token (encrypted) |
| refresh_token | TEXT | OAuth refresh token |
| token_expires_at | TIMESTAMPTZ | Token expiration time |
| is_active | BOOLEAN | Connection active status |
| webhook_secret | TEXT | HMAC secret for webhook verification |
| settings | JSONB | Auto-sync toggles, case type mappings |
| connected_at | TIMESTAMPTZ | When the connection was established |
matters (Lawmatics columns)
| Column | Type | Description |
|---|---|---|
| lawmatics_matter_id | BIGINT | Lawmatics matter ID (indexed) |
| lawmatics_synced_at | TIMESTAMPTZ | Last sync timestamp |
lawmatics_webhook_events
| Column | Type | Description |
|---|---|---|
| id | UUID | Primary key |
| firm_id | UUID | Foreign key to firms |
| event_type | TEXT | e.g. contact.created, matter.stage_changed |
| resource_id | BIGINT | Lawmatics resource ID |
| payload | JSONB | Raw webhook payload |
| processed | BOOLEAN | Whether event has been processed |
| processed_at | TIMESTAMPTZ | Processing timestamp |
| error_message | TEXT | Error details if processing failed |
Webhook Events
| Event | Description | CaseHug Action |
|---|---|---|
| contact.created | New contact added in Lawmatics | Logged for future import |
| matter.stage_changed | Matter moved to different pipeline stage | Updates linked CaseHug matter status |
| form.submitted | Form submission received in Lawmatics | Logged for audit |
| envelope.completed | E-signature envelope completed | Logged for audit |
Example webhook payload:
{
"event": "matter.stage_changed",
"data": {
"id": 12345,
"name": "Smith Divorce",
"stage": "Retained",
"previous_stage": "Consultation"
},
"timestamp": "2026-04-07T04:30:00Z"
}Default Stage Mappings
CaseHug maps case types to Lawmatics pipeline stages. Firms can override in Settings → Integrations.
| CaseHug Case Type | Lawmatics Stage | Practice Area |
|---|---|---|
| divorce_standard | Family Law Intake | Family Law |
| custody_only | Family Law Intake | Family Law |
| immigration_asylum | Immigration Intake | Immigration |
| personal_injury_auto | PI Intake | Personal Injury |
| estate_planning_will | Estate Planning Intake | Estate Planning |
| estate_planning_probate | Probate Intake | Probate |
Error Codes
| Status | Meaning |
|---|---|
| 400 | Bad Request — Missing required fields or invalid payload |
| 401 | Unauthorized — Invalid or expired access token |
| 403 | Forbidden — Insufficient permissions or wrong role |
| 404 | Not Found — Matter or integration record doesn't exist |
| 429 | Rate Limited — Too many requests. Retry with exponential backoff |
| 500 | Internal Error — Check sync logs for details |
| 503 | Service Unavailable — Lawmatics credentials not configured |
Environment Variables
# Lawmatics OAuth credentials (obtain from Lawmatics Developer App) LAWMATICS_CLIENT_ID=your_client_id LAWMATICS_CLIENT_SECRET=your_client_secret LAWMATICS_REDIRECT_URI=https://calmintake.com/api/v1/integrations/lawmatics/callback # Note: Firms must contact support@lawmatics.com to enable developer settings # before they can authorize OAuth connections.