crm.leads.notes & crm.leads.activities
#
Manage internal notes and read activity audit events (stage movements, assignments, edits) on any lead.
TypeScript Signatures #
typescript
// Notes API
crm.leads.notes.add(leadId: number, content: string): Promise<Note>;
crm.leads.notes.list(leadId: number): Promise<Note[]>;
// Activities API
crm.leads.activities.list(
leadId: number,
options?: { page?: number; limit?: number }
): Promise<PaginatedResult<Activity>>;Method Details #
crm.leads.notes.add(leadId, content)
#
Appends a new internal note entry to the timeline of the specified lead.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
leadId | number | Yes | The ID of the lead to attach the note to. |
content | string | Yes | Plain text note body (maximum 10,000 characters). |
crm.leads.notes.list(leadId)
#
Retrieves all internal notes attached to a lead ordered chronologically.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
leadId | number | Yes | The ID of the lead whose notes to fetch. |
crm.leads.activities.list(leadId, options?)
#
Queries the audit timeline of activities performed on a lead (e.g. stage movements, assignments, status updates).
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
leadId | number | Yes | — | The ID of the lead whose activities to query. |
options.page | number | No | 1 | Page number for pagination. |
options.limit | number | No | 20 | Max number of activity entries to retrieve (max 100). |
Models & Interfaces #
typescript
interface Note {
id: number;
content: string;
userId: number;
createdAt: string;
}
interface Activity {
id: number;
type: string;
title: string | null;
description: string | null;
userId: number | null;
createdAt: string;
}
interface PaginatedResult<T> {
rows: T[];
total: number;
page: number;
limit: number;
}Minimal Example #
typescript
async function run(context: Context, dolfin: DolfinApi): Promise<void> {
const { lead } = context;
const crm = await dolfin.crm.module(lead.moduleId);
// Add internal audit note
await crm.leads.notes.add(
lead.id,
"Payment received via Stripe Webhook. Ready for onboarding."
);
}Production Recipe: Auditing Stage Velocity #
Calculates how many days elapsed between lead creation and the current stage transition, recording the metrics to metadata and appending an audit note:
typescript
async function run(context: Context, dolfin: DolfinApi): Promise<void> {
const { lead } = context;
const crm = await dolfin.crm.module(lead.moduleId);
// Fetch recent activities
const timeline = await crm.leads.activities.list(lead.id, { limit: 20 });
const createdAtTime = new Date(lead.createdAt).getTime();
const now = Date.now();
const totalDays = Math.max(1, Math.round((now - createdAtTime) / (1000 * 60 * 60 * 24)));
console.log(`Lead lifecycle duration: ${totalDays} days across ${timeline.total} activities`);
await crm.leads.update(lead.id, {
meta: {
days_to_current_stage: totalDays,
total_activity_count: timeline.total
}
});
await crm.leads.notes.add(
lead.id,
`📊 Stage velocity calculation: ${totalDays} days in pipeline (${timeline.total} historical events logged).`
);
}Error Handling & Limits #
| Scenario | Thrown Error | Resolution |
|---|---|---|
content length > 10,000 chars | Note content exceeds 10000 characters | Truncate or summarize long note strings before saving. |
Invalid / deleted leadId | Lead not found | Verify leadId exists in the active tenant module before calling. |
Empty / whitespace content | Note content cannot be empty | Ensure content.trim().length > 0. |
💡
Tip
Use crm.leads.notes.add within your stage transition triggers to maintain clear operational trails without cluttering primary lead fields.