crm.leads.assign
#
Reassigns the ownership of a lead to an individual sales representative, a collaborative team, or both simultaneously.
TypeScript Signature #
typescript
crm.leads.assign(
leadId: number,
target: {
userId?: number;
teamId?: number;
}
): Promise<Lead>;Parameters Reference #
| Parameter | Type | Required | Description |
|---|---|---|---|
leadId | number | Yes | The positive integer ID of the lead to assign. |
target.userId | number | Optional* | The numerical ID of the assigned user. |
target.teamId | number | Optional* | The numerical ID of the assigned team. |
*At least one of userId or teamId must be provided in the target object.
Returns: Promise<Lead> updated with assignedTo and/or teamId.
Minimal Quickstart Example #
typescript
async function run(context: Context, dolfin: DolfinApi): Promise<void> {
const { lead } = context;
const crm = await dolfin.crm.module(lead.moduleId);
// Assign to User ID 38
await crm.leads.assign(lead.id, {
userId: 38
});
}Production Recipe: Round-Robin Distribution Rota #
Distributes inbound leads evenly across an active sales rota, setting both individual and team assignments with full timeline audit notes:
typescript
async function run(context: Context, dolfin: DolfinApi): Promise<void> {
const { lead } = context;
const crm = await dolfin.crm.module(lead.moduleId);
console.log(`Evaluating assignment for lead ID: ${lead.id}`);
try {
// 1. Define active SDR sales reps rota
const sdrUserIds = [12, 15, 38, 44];
const inboundTeamId = 3;
// 2. Compute deterministic round-robin index using lead ID
const assignedUserId = sdrUserIds[lead.id % sdrUserIds.length];
// 3. Assign lead ownership
const updatedLead = await crm.leads.assign(lead.id, {
userId: assignedUserId,
teamId: inboundTeamId
});
// 4. Record audit note
await crm.leads.notes.add(
lead.id,
`🔄 Automated routing: Assigned to Sales Rep #${assignedUserId} (Team #${inboundTeamId}) via Round-Robin Policy.`
);
console.log(`Successfully assigned lead #${lead.id} to user #${assignedUserId}.`);
} catch (error: any) {
console.error(`Assignment failed: ${error.message}`);
throw error;
}
}Common Errors & Troubleshooting #
| Error Message | Cause | Resolution |
|---|---|---|
Provide userId and/or teamId | Both target.userId and target.teamId were omitted or undefined. | Provide at least one valid numerical target ID. |
Invalid userId / Invalid teamId | Passed a negative number, float, or string. | Ensure IDs are positive integers. |
Lead not found in this module | The leadId does not exist in the tenant or belongs to a different module. | Verify lead.id and lead.moduleId match. |