👤

Clients API

Clients represent the people your firm represents. Each matter is associated with a client. Use this API to create and manage client records.

POST/api/v1/clients

Create a Client

Creates a new client record for your firm. At minimum, first name and last name are required.

Authentication

Requires clients:write scope.

Headers

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

Request Body Fields

Field	Type	Required	Description
first_name	string	Yes	Client first name
last_name	string	Yes	Client last name
email	string	No	Client email address
phone	string	No	E.164 format phone number
date_of_birth	string	No	ISO 8601 date (YYYY-MM-DD)
address	object	No	Address object with line1, line2, city, state, zip
notes	string	No	Internal notes (not visible to client)
custom_fields	object	No	Key-value custom field data

Request Body Example

json

{
  "first_name": "David",
  "last_name": "Johnson",
  "email": "david.johnson@example.com",
  "phone": "+15551234567",
  "date_of_birth": "1985-06-15",
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "Austin",
    "state": "TX",
    "zip": "78701"
  },
  "notes": "Referred by Martinez Law",
  "custom_fields": {
    "referral_source": "existing_client",
    "language": "en"
  }
}

Response (201 Created)

json

{
  "data": {
    "id": "cli_01HABC",
    "first_name": "David",
    "last_name": "Johnson",
    "email": "david.johnson@example.com",
    "phone": "+15551234567",
    "date_of_birth": "1985-06-15",
    "address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "Austin",
      "state": "TX",
      "zip": "78701"
    },
    "notes": "Referred by Martinez Law",
    "custom_fields": {
      "referral_source": "existing_client",
      "language": "en"
    },
    "matters_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
401	unauthorized	Missing or invalid API key
403	insufficient_scope	API key lacks clients:write scope
409	duplicate_email	Client with this email already exists

Code Examples

curl -X POST https://api.calmintake.com/api/v1/clients \
  -H "X-Api-Key: ch_live_sk_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "David",
    "last_name": "Johnson",
    "email": "david.johnson@example.com",
    "phone": "+15551234567"
  }'

GET/api/v1/clients

List Clients

Returns a paginated list of clients for your firm.

Authentication

Requires clients:read scope.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
per_page	integer	20	Results per page (max 100)
search	string	-	Search by name or email
sort	string	created_at	Sort field: created_at, last_name
order	string	desc	Sort order: asc, desc

Response (200)

json

{
  "data": [
    {
      "id": "cli_01HABC",
      "first_name": "David",
      "last_name": "Johnson",
      "email": "david.johnson@example.com",
      "phone": "+15551234567",
      "matters_count": 2,
      "created_at": "2024-03-07T14:00:00Z"
    },
    {
      "id": "cli_01HBBB",
      "first_name": "Maria",
      "last_name": "Martinez",
      "email": "maria.m@example.com",
      "phone": "+15559876543",
      "matters_count": 1,
      "created_at": "2024-03-05T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 87,
    "has_more": true
  }
}

GET/api/v1/clients/:id

Get Client

Returns full details for a single client, including their associated matters.

Authentication

Requires clients:read scope.

Response (200)

json

{
  "data": {
    "id": "cli_01HABC",
    "first_name": "David",
    "last_name": "Johnson",
    "email": "david.johnson@example.com",
    "phone": "+15551234567",
    "date_of_birth": "1985-06-15",
    "address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "Austin",
      "state": "TX",
      "zip": "78701"
    },
    "notes": "Referred by Martinez Law",
    "custom_fields": {
      "referral_source": "existing_client",
      "language": "en"
    },
    "matters": [
      {
        "id": "mat_01HXYZ",
        "title": "Johnson v. Smith",
        "status": "active",
        "practice_area": "personal_injury"
      }
    ],
    "matters_count": 1,
    "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	Client belongs to a different firm
404	client_not_found	Client with that ID does not exist

PATCH/api/v1/clients/:id

Update Client

Updates client fields. Only include the fields you want to change — all other fields remain unchanged.

Authentication

Requires clients:write scope.

Request Body Example

json

{
  "phone": "+15550001111",
  "address": {
    "line1": "456 Oak Ave",
    "city": "Austin",
    "state": "TX",
    "zip": "78702"
  },
  "notes": "Moved to new address. Preferred contact: phone."
}

Returns the updated client object with status 200. Same schema as the GET response.

Error Responses

Status	Code	Description
400	invalid_request	Invalid field values
401	unauthorized	Missing or invalid API key
403	insufficient_scope	API key lacks clients:write scope
404	client_not_found	Client does not exist
409	duplicate_email	New email already belongs to another client