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 #

ParameterTypeRequiredDescription
data.namestringYesFull name or company title for the lead.
data.emailstring | nullOptionalPrimary email address.
data.phonestring | nullOptionalPrimary phone number string.
data.countryCodestring | nullOptionalE.164 country dial code (e.g. "+1", "+91").
data.assignedTonumberOptionalNumerical ID of the assigned user.
data.teamIdnumberOptionalNumerical ID of the assigned team.
data.pipelineSlugstringOptional*Pipeline slug for initial placement (requires stageSlug).
data.stageSlugstringOptional*Stage slug for initial placement (requires pipelineSlug).
data.metaRecord<string, unknown>OptionalCustom 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 MessageCauseResolution
Lead name is requireddata.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().