crm.leads.create
#
Programmatically creates a new lead within the scoped module. Allows setting initial pipeline and stage placements, assigning ownership, and attaching custom metadata fields during creation.
TypeScript Signature #
typescript
crm.leads.create(data: {
name: string;
email?: string | null;
phone?: string | null;
countryCode?: string | null;
assignedTo?: number;
teamId?: number;
pipelineSlug?: string;
stageSlug?: string;
meta?: Record<string, unknown>;
}): Promise<Lead>;
Parameters Reference #
| Parameter | Type | Required | Description |
|---|---|---|---|
data.name | string | Yes | Full name or company title for the lead. |
data.email | string | null | Optional | Primary email address. |
data.phone | string | null | Optional | Primary phone number string. |
data.countryCode | string | null | Optional | E.164 country dial code (e.g. "+1", "+91"). |
data.assignedTo | number | Optional | Numerical ID of the assigned user. |
data.teamId | number | Optional | Numerical ID of the assigned team. |
data.pipelineSlug | string | Optional* | Pipeline slug for initial placement (requires stageSlug). |
data.stageSlug | string | Optional* | Stage slug for initial placement (requires pipelineSlug). |
data.meta | Record<string, unknown> | Optional | Custom module attributes configured in Module Builder. |
*If pipelineSlug or stageSlug is provided, both must be supplied together.
Minimal Quickstart Example #
typescript
async function run(context: Context, dolfin: DolfinApi): Promise<void> {
const { lead } = context;
const crm = await dolfin.crm.module(lead.moduleId);
const newProspect = await crm.leads.create({
name: "Acme Industrial Expansion",
email: "procurement@acme-industrial.com",
pipelineSlug: "default_pipeline",
stageSlug: "new_lead",
meta: {
source: "Partner Referral"
}
});
console.log(`Created new lead ID: ${newProspect.id}`);
}
Production Recipe: Creating Follow-up Expansion Deals #
When a primary deal moves to closed_won, this recipe automatically creates an expansion account lead linked to the parent lead and logs an audit trail.
typescript
async function run(context: Context, dolfin: DolfinApi): Promise<void> {
const { lead } = context;
const crm = await dolfin.crm.module(lead.moduleId);
console.log(`Evaluating deal closure for lead #${lead.id} (${lead.name})`);
try {
// Only trigger if contract value is high
const contractValue = Number(lead.meta?.deal_value || 0);
if (contractValue >= 25000) {
console.log(`High-value contract detected ($${contractValue}). Creating Year 2 Expansion lead.`);
const expansionLead = await crm.leads.create({
name: `${lead.name} — Year 2 Renewal & Expansion`,
email: lead.email,
phone: lead.phone,
countryCode: lead.countryCode,
pipelineSlug: "default_pipeline",
stageSlug: "new_lead",
assignedTo: lead.assignedTo || undefined,
teamId: lead.teamId || undefined,
meta: {
parent_lead_id: lead.id,
initial_contract_value: contractValue,
deal_type: "Expansion Opportunity"
}
});
// Link parent lead to expansion lead
await crm.leads.notes.add(
lead.id,
`📦 Automated Expansion: Created child opportunity "${expansionLead.name}" (ID: ${expansionLead.id}).`
);
console.log(`Successfully spawned expansion lead ID #${expansionLead.id}.`);
}
} catch (error: any) {
console.error(`Failed to create expansion lead: ${error.message}`);
throw error;
}
}
Common Errors & Troubleshooting #
| Error Message | Cause | Resolution |
|---|---|---|
Lead name is required | data.name was omitted, empty, or not a string. | Provide a non-empty name string. |
Pipeline with slug "..." not found in this module. | Passed an invalid pipelineSlug. | Verify pipeline slug using crm.pipelines.list(). |
Stage with slug "..." not found in pipeline "...". | Passed an invalid stageSlug. | Verify stage slug using crm.stages.list(). |