🏢

Firms API

Manage your firm's account settings, view usage statistics, and administer users. These endpoints require admin-level API keys.

GET/api/v1/firms

Get Firm Details

Returns your firm's profile and settings. Each API key belongs to exactly one firm.

Authentication

Requires firms:read scope.

Response (200)

json

{
  "data": {
    "id": "firm_01HFFF",
    "name": "Campbell & Associates",
    "slug": "campbell-associates",
    "email": "admin@campbelllegal.com",
    "phone": "+15121234567",
    "website": "https://campbelllegal.com",
    "address": {
      "line1": "500 Congress Ave",
      "suite": "Ste 200",
      "city": "Austin",
      "state": "TX",
      "zip": "78701"
    },
    "plan": "pro",
    "timezone": "America/Chicago",
    "logo_url": "https://storage.calmintake.com/firms/firm_01HFFF/logo.png",
    "settings": {
      "intake_branding": true,
      "custom_domain": null,
      "default_intake_template": "tmpl_01HGHI",
      "email_notifications": true,
      "sms_notifications": false
    },
    "created_at": "2023-09-01T10:00:00Z"
  }
}

Code Example

cURL

curl -X GET https://api.calmintake.com/api/v1/firms \
  -H "X-Api-Key: ch_live_sk_abc123xyz"

PATCH/api/v1/firms/settings

Update Firm Settings

Update firm profile and configuration settings. Only include fields you want to change.

Authentication

Requires firms:write scope.

Updateable Fields

Field	Type	Description
name	string	Firm display name
phone	string	Firm phone number (E.164 format)
website	string	Firm website URL
timezone	string	IANA timezone identifier
address	object	Firm address object
settings.email_notifications	boolean	Enable email event notifications
settings.sms_notifications	boolean	Enable SMS event notifications
settings.default_intake_template	string	Default template ID for new matters
settings.intake_branding	boolean	Show firm branding on intake portal
settings.custom_domain	string	Custom domain for intake portal

Request Body

json

{
  "name": "Campbell & Associates Law Group",
  "phone": "+15129999999",
  "timezone": "America/Chicago",
  "settings": {
    "email_notifications": true,
    "sms_notifications": true,
    "default_intake_template": "tmpl_01HGHI",
    "intake_branding": true,
    "custom_domain": "intake.campbelllegal.com"
  }
}

Response (200)

json

{
  "data": {
    "id": "firm_01HFFF",
    "name": "Campbell & Associates Law Group",
    "phone": "+15129999999",
    "timezone": "America/Chicago",
    "settings": {
      "email_notifications": true,
      "sms_notifications": true,
      "default_intake_template": "tmpl_01HGHI",
      "intake_branding": true,
      "custom_domain": "intake.campbelllegal.com"
    },
    "updated_at": "2024-03-07T14:30:00Z"
  }
}

Code Example

cURL

curl -X PATCH https://api.calmintake.com/api/v1/firms/settings \
  -H "X-Api-Key: ch_live_sk_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campbell & Associates Law Group",
    "settings": {
      "sms_notifications": true
    }
  }'

GET/api/v1/firms/usage

Get Usage Statistics

Returns usage metrics for the current billing period, including matter counts, storage, API request usage, and plan limits.

Authentication

Requires firms:read scope.

Response (200)

json

{
  "data": {
    "plan": "pro",
    "billing_period": {
      "start": "2024-03-01T00:00:00Z",
      "end": "2024-03-31T23:59:59Z"
    },
    "usage": {
      "matters": {
        "total": 142,
        "active": 87,
        "archived": 55
      },
      "clients": {
        "total": 201
      },
      "documents": {
        "uploaded_this_period": 438,
        "storage_used_gb": 2.7
      },
      "api_requests": {
        "this_period": 8420,
        "limit": 50000
      },
      "intake_links_sent": {
        "this_period": 63
      }
    },
    "limits": {
      "matters": null,
      "storage_gb": 50,
      "api_requests_per_period": 50000,
      "users": 10
    }
  }
}

GET/api/v1/firms/users

List Firm Users

Returns all users and pending invitations for your firm.

Authentication

Requires firms:read scope.

Query Parameters

Parameter	Type	Description
status	string	Filter: active, pending, suspended
role	string	Filter by role: admin, attorney, staff
page	integer	Page number (default 1)
per_page	integer	Results per page (default 20)

Response (200)

json

{
  "data": [
    {
      "id": "usr_01HAAA",
      "email": "kevin@campbelllegal.com",
      "first_name": "Kevin",
      "last_name": "Campbell",
      "role": "admin",
      "status": "active",
      "last_sign_in": "2024-03-07T08:00:00Z",
      "created_at": "2023-09-01T10:00:00Z"
    },
    {
      "id": "usr_01HBBB",
      "email": "sarah@campbelllegal.com",
      "first_name": "Sarah",
      "last_name": "Mitchell",
      "role": "attorney",
      "status": "active",
      "last_sign_in": "2024-03-06T17:30:00Z",
      "created_at": "2023-10-15T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 4,
    "has_more": false
  }
}

POST/api/v1/firms/users

Invite User

Sends an email invitation to a new user to join your firm. The invitation expires after 7 days.

Authentication

Requires firms:write scope.

Request Body

json

{
  "email": "newattorney@campbelllegal.com",
  "first_name": "James",
  "last_name": "Rivera",
  "role": "attorney"
}

Available Roles

Role	Description
admin	Full access — can manage firm settings, users, and all data
attorney	Can create/manage matters, view all clients
staff	Can view and update assigned matters only
paralegal	Can manage documents and intake forms

Response (201)

json

{
  "data": {
    "id": "inv_01HCCC",
    "email": "newattorney@campbelllegal.com",
    "first_name": "James",
    "last_name": "Rivera",
    "role": "attorney",
    "status": "pending",
    "invite_sent_at": "2024-03-07T14:00:00Z",
    "expires_at": "2024-03-14T14:00:00Z"
  }
}

Error Responses

Status	Code	Description
400	invalid_request	Missing required fields or invalid role
403	insufficient_scope	API key lacks firms:write scope
409	user_already_exists	Email is already a member of this firm
422	user_limit_reached	Plan user limit reached — upgrade to add more

Code Examples

curl -X POST https://api.calmintake.com/api/v1/firms/users \
  -H "X-Api-Key: ch_live_sk_abc123xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newattorney@campbelllegal.com",
    "first_name": "James",
    "last_name": "Rivera",
    "role": "attorney"
  }'

GET/api/v1/firms/notifications

Get Notification Preferences

Retrieve the firm's notification preferences — which event types trigger SMS and email alerts, and to which recipients.

json

{
  "data": {
    "document_uploaded": { "email": true, "sms": false },
    "intake_completed": { "email": true, "sms": true },
    "deadline_approaching": { "email": true, "sms": true },
    "intake_link_expired": { "email": true, "sms": false }
  }
}

PATCH/api/v1/firms/notifications

Update notification preferences. Pass only the keys you want to change.

GET/api/v1/firms/onboarding

Get Onboarding State

Retrieve the firm's onboarding completion status. Used to drive the onboarding wizard in the dashboard.

json

{
  "data": {
    "completed": false,
    "current_step": 3,
    "steps": {
      "welcome": true,
      "practice_areas": true,
      "doc_templates": false,
      "notifications": false,
      "invite_team": false,
      "ready": false
    },
    "practice_areas": ["family_law", "personal_injury"],
    "completed_at": null
  }
}

POST/api/v1/firms/onboarding

Save onboarding step data and advance the wizard. Pass the step number and any data collected in that step.

Field	Type	Required	Description
step	number	Yes	Step number (1–6)
data	object	No	Step-specific data (practice_areas, notification_prefs, invites, etc.)
complete	boolean	No	Set true to mark onboarding as fully complete