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 path | Operation |
|---|---|
GET /api/v1/leads | List leads |
GET /api/v1/leads/{leadId} | Get a lead |
POST /api/v1/leads | Create a lead |
PATCH /api/v1/leads/{leadId} | Update a lead |
GET /api/v1/clients | List clients |
GET /api/v1/clients/{clientId} | Get a client |
POST /api/v1/clients | Create a client |
PATCH /api/v1/clients/{clientId} | Update a client |
List and search
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 exactsourcefilter. - Lead search checks first name, last name, email, and company. Filter by
statususingnew,contacted,qualified,proposal,negotiation,won, orlost. - Client search checks account and contact names and emails. Filter by
record(personorcompany) andstage(qualified,opportunity,proposal,negotiation,won, orlost). 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.idfrom the member directory) forassignedToId. - 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.