Skip to Content
API reference

Leads and clients

Search, read, create, and update CRM records with an organization API key.

Set Leads and Clients permissions independently in Settings → Firm Settings → API → API keys. Read only allows GET. Read and write also allows POST and PATCH. Each request operates in the organization that issued the key.

Method and pathOperation
GET /api/v1/leadsList leads
GET /api/v1/leads/{leadId}Get a lead
POST /api/v1/leadsCreate a lead
PATCH /api/v1/leads/{leadId}Update a lead
GET /api/v1/clientsList clients
GET /api/v1/clients/{clientId}Get a client
POST /api/v1/clientsCreate a client
PATCH /api/v1/clients/{clientId}Update a client

Lists return { "items": [...], "nextCursor": "…" } in ascending record ID order. Use limit from 1 to 100 (default 25), and pass nextCursor as cursor with the same filters to continue. A null cursor marks the last page.

  • Both lists accept a case-insensitive substring search in q (up to 200 characters) and an exact source filter.
  • Lead search checks first name, last name, email, and company. Filter by status using new, contacted, qualified, proposal, negotiation, won, or lost.
  • Client search checks account and contact names and emails. Filter by record (person or company) and stage (qualified, opportunity, proposal, negotiation, won, or lost). Stage refers to the client record's stage value.
curl --fail-with-body 'https://your-app.example/api/v1/clients?stage=proposal&limit=25' \
  -H "X-API-Key: $API_KEY"

Create a record

Lead creation requires firstName, lastName, and email. Status defaults to new. Client creation requires name. The record type defaults to company; when stage is omitted, the client enters the organization's default client board stage. Both sources default to other.

curl --fail-with-body https://your-app.example/api/v1/leads \
  -H "X-API-Key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ad0ef229-d2bf-46c8-9473-f758032a34f0' \
  --data '{
    "firstName": "Avery",
    "lastName": "Smith",
    "email": "[email protected]",
    "source": "referral",
    "nextAction": "Schedule intake",
    "nextActionDueDate": "2026-12-01"
  }'

The first successful create returns 201, the record, and its relative URL in Location. For safe retries, generate a fresh optional Idempotency-Key per logical create and reuse it with the same payload if the result is uncertain. Use 16–128 letters, digits, underscores, or hyphens. An identical retry returns 200 with the current record. Reusing a key with different data, or replaying after the record was deleted, returns 409. Retry records are scoped by organization and resource and survive credential rotation.

Update fields

Send a JSON object containing at least one editable field. Omitted fields keep their values. Use null to clear nullable fields, such as assignedToId or a lead's nextActionDueDate. Successful updates return the record with 200. Requests that write the same field take effect in the order they commit.

  • Use the member's user ID (user.id from the member directory) for assignedToId.
  • Use a whole number from 0 to 2,147,483,647 for estimatedValue.
  • Lead follow-up dates use YYYY-MM-DD. Record timestamps use ISO 8601 UTC.
  • A converted lead can return a convertedClientId. Conversion and deletion are dashboard operations, along with editing client contacts, notes, tasks, and relationships.

See the OpenAPI specification for the complete fields, enums, and response schemas.

On this page