⚖️

Matters API

Matters are the core entity in CaseHug — representing a legal case or engagement. Use this API to create matters, manage their lifecycle, and generate intake links for clients.

POST/api/v1/matters

Create a Matter

Creates a new matter for your firm. Returns the created matter object.

Authentication

Requires API key with matters:write scope.

Headers

Header	Value	Required
X-Api-Key	your-api-key	Yes
Content-Type	application/json	Yes

Request Body

Field	Type	Required	Description
title	string	Yes	Matter title
practice_area	string	Yes	e.g. personal_injury, estate_planning, family_law
client_id	string	No	ID of existing client to associate
description	string	No	Optional description
assigned_attorney	string	No	User ID of assigned attorney
intake_template_id	string	No	Template to use for intake form
custom_fields	object	No	Key-value custom field data
tags	string[]	No	Array of tag strings

Request Body Example

json

{
  "title": "Johnson v. Smith — Personal Injury",
  "practice_area": "personal_injury",
  "client_id": "cli_01HABC",
  "description": "Auto accident claim, downtown intersection",
  "assigned_attorney": "atty_01HDEF",
  "intake_template_id": "tmpl_01HGHI",
  "custom_fields": {
    "incident_date": "2024-01-10",
    "claim_value": 50000
  },
  "tags": ["auto", "priority"]
}

Response (201 Created)

json

{
  "data": {
    "id": "mat_01HXYZ",
    "title": "Johnson v. Smith — Personal Injury",
    "status": "active",
    "practice_area": "personal_injury",
    "client_id": "cli_01HABC",
    "assigned_attorney": "atty_01HDEF",
    "intake_template_id": "tmpl_01HGHI",
    "custom_fields": {
      "incident_date": "2024-01-10",
      "claim_value": 50000
    },
    "tags": ["auto", "priority"],
    "intake_link": null,
    "documents_count": 0,
    "created_at": "2024-03-07T14:00:00Z",
    "updated_at": "2024-03-07T14:00:00Z"
  }
}

Error Responses

Status	Code	Description
400	invalid_request	Missing required fields or invalid values
401	unauthorized	Missing or invalid API key
403	insufficient_scope	API key lacks matters:write scope
404	client_not_found	Provided client_id does not exist
422	duplicate_matter	A matter with this title already exists

Code Examples

curl -X POST https://api.calmintake.com/api/v1/matters \
  -H "X-Api-Key: ch_live_sk_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Johnson v. Smith — Personal Injury",
    "practice_area": "personal_injury",
    "client_id": "cli_01HABC"
  }'

GET/api/v1/matters

List Matters

Returns a paginated list of matters for your firm.

Authentication

Requires API key with matters:read scope.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Results per page (max 100)
status	string	all	Filter by status: active, archived
practice_area	string	-	Filter by practice area
client_id	string	-	Filter by client ID
search	string	-	Full-text search on title
sort	string	created_at	Sort field: created_at, updated_at, title
order	string	desc	Sort direction: asc, desc

Response (200)

json

{
  "data": [
    {
      "id": "mat_01HXYZ",
      "title": "Johnson v. Smith",
      "status": "active",
      "practice_area": "personal_injury",
      "client_id": "cli_01HABC",
      "documents_count": 3,
      "created_at": "2024-03-07T14:00:00Z"
    },
    {
      "id": "mat_01HAAA",
      "title": "Martinez Estate Planning",
      "status": "active",
      "practice_area": "estate_planning",
      "client_id": "cli_01HBBB",
      "documents_count": 0,
      "created_at": "2024-03-06T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 142,
    "has_more": true
  }
}

Code Examples

cURL

curl -X GET "https://api.calmintake.com/api/v1/matters?page=1&per_page=20&status=active" \
  -H "X-Api-Key: ch_live_sk_abc123xyz"

GET/api/v1/matters/:id

Get Matter

Retrieves full details for a single matter including client info and document counts.

Authentication

Requires matters:read scope.

Response (200)

json

{
  "data": {
    "id": "mat_01HXYZ",
    "title": "Johnson v. Smith — Personal Injury",
    "status": "active",
    "practice_area": "personal_injury",
    "description": "Auto accident claim, downtown intersection",
    "client": {
      "id": "cli_01HABC",
      "first_name": "David",
      "last_name": "Johnson",
      "email": "david.johnson@example.com"
    },
    "assigned_attorney": "atty_01HDEF",
    "custom_fields": {
      "incident_date": "2024-01-10",
      "claim_value": 50000
    },
    "tags": ["auto", "priority"],
    "intake_link": "https://intake.calmintake.com/i/abc123",
    "documents_count": 3,
    "documents_complete": 2,
    "created_at": "2024-03-07T14:00:00Z",
    "updated_at": "2024-03-07T15:30:00Z"
  }
}

Error Responses

Status	Code	Description
401	unauthorized	Missing or invalid API key
403	forbidden	Matter belongs to a different firm
404	matter_not_found	Matter with that ID does not exist

PATCH/api/v1/matters/:id

Update Matter

Update any fields on a matter. Only include the fields you want to change.

Authentication

Requires matters:write scope.

Request Body

json

{
  "title": "Johnson v. Smith — Auto Accident",
  "status": "active",
  "assigned_attorney": "atty_01HGGG",
  "custom_fields": {
    "claim_value": 75000
  },
  "tags": ["auto", "priority", "high-value"]
}

Returns the updated matter object (same schema as GET response) with status 200.

POST/api/v1/matters/:id/archive

Archive Matter

Archives a matter, removing it from active views. Archived matters can be restored. No request body required.

Authentication

Requires matters:write scope.

Response (200)

json

{
  "data": {
    "id": "mat_01HXYZ",
    "status": "archived",
    "archived_at": "2024-03-07T16:00:00Z"
  }
}

POST/api/v1/matters/:id/intake-link

Generate Intake Link

Generates a unique, shareable intake link for the client to complete their intake form and upload documents. Links expire after 30 days by default.

Authentication

Requires matters:write scope.

Request Body (optional)

Field	Type	Default	Description
expires_days	integer	30	Days until link expires (max 365)
force_new	boolean	false	Generate new link even if one exists

Response (200)

json

{
  "data": {
    "intake_link": "https://intake.calmintake.com/i/xk8abc123",
    "expires_at": "2024-04-07T14:00:00Z",
    "matter_id": "mat_01HXYZ"
  }
}

GET/api/v1/matters/:id/communications

List Matter Communications

Retrieve all SMS and email communications sent for a matter — intake link deliveries, automated reminders, and manual messages.

json

{
  "data": [
    {
      "id": "comm_01HXYZ",
      "channel": "sms",
      "direction": "outbound",
      "to": "+15551234567",
      "message": "Hi Alice, your intake link is ready: https://...",
      "status": "delivered",
      "sent_at": "2025-03-10T14:00:00.000Z"
    }
  ]
}

GET/api/v1/matters/:id/deadlines

List Matter Deadlines

Retrieve court dates, filing deadlines, and statute of limitations dates for a matter.

json

{
  "data": [
    {
      "id": "dl_01HXYZ",
      "title": "Answer Deadline",
      "due_date": "2025-04-15",
      "type": "filing",
      "notes": "30 days from service of process",
      "completed": false,
      "created_at": "2025-03-10T00:00:00.000Z"
    }
  ]
}

POST/api/v1/matters/:id/deadlines

Add a deadline to a matter.

Field	Type	Required	Description
title	string	Yes	Deadline description
due_date	string	Yes	ISO date (YYYY-MM-DD)
type	string	No	filing, hearing, statute, other
notes	string	No	Optional notes

POST/api/v1/matters/:id/send-link

Send Link to Client

Sends the intake link to a client via email or SMS. Automatically generates a link if one does not exist.

Authentication

Requires matters:write scope.

Request Body

json

{
  "channel": "email",
  "email": "david.johnson@example.com",
  "message": "Please complete your intake form at your earliest convenience."
}

Field	Type	Required	Description
channel	string	Yes	Delivery channel: email, sms
email	string	Cond.	Required when channel is email
phone	string	Cond.	Required when channel is sms
message	string	No	Custom message to include

Response (200)

json

{
  "data": {
    "sent": true,
    "channel": "email",
    "recipient": "david.johnson@example.com",
    "sent_at": "2024-03-07T14:05:00Z"
  }
}

Error Responses

Status	Code	Description
400	invalid_channel	Channel must be email or sms
400	missing_recipient	email or phone required for the channel
404	matter_not_found	Matter does not exist
422	send_failed	Delivery provider returned an error