crm.leads.list & crm.leads.search #

// Structured multi-field filtering with pagination
crm.leads.list(filters?: {
  page?: number;
  limit?: number;
  status?: Array<"new" | "contacted" | "qualified" | "unqualified" | "converted">;
  query?: string;
  assignedTo?: number;
  stageId?: number;
}): Promise<PaginatedResult<Lead>>;

// Full-text keyword search across lead fields
crm.leads.search(
  query: string,
  options?: { page?: number; limit?: number }
): Promise<PaginatedResult<Lead>>;

interface PaginatedResult<T> {
  data: T[];
  total: number;
}

async function run(context: Context, dolfin: DolfinApi): Promise<void> {
  const { lead } = context;
  const crm = await dolfin.crm.module(lead.moduleId);

  // Search for other leads from the same company domain
  const domain = lead.email?.split("@")[1];
  if (domain) {
    const results = await crm.leads.search(domain, { limit: 10 });
    console.log(`Found ${results.total} matching leads with domain @${domain}`);
  }
}

async function run(context: Context, dolfin: DolfinApi): Promise<void> {
  const { lead } = context;
  const crm = await dolfin.crm.module(lead.moduleId);

  if (!lead.email) {
    console.log("No email provided; skipping duplicate detection.");
    return;
  }

  console.log(`Checking duplicates for lead #${lead.id} (${lead.email})`);

  try {
    // 1. Search existing leads with the same email
    const searchResults = await crm.leads.search(lead.email, { limit: 10 });

    // 2. Filter out current lead record
    const existingDuplicates = searchResults.data.filter((match) => match.id !== lead.id);

    if (existingDuplicates.length > 0) {
      console.warn(`Detected ${existingDuplicates.length} potential duplicate records.`);

      const duplicateSummary = existingDuplicates
        .map((d) => `#${d.id} ("${d.name}" in Stage ID ${d.stageId})`)
        .join(", ");

      // 3. Mark duplicate flag in custom metadata
      await crm.leads.update(lead.id, {
        meta: {
          ...lead.meta,
          has_possible_duplicate: true,
          duplicate_lead_ids: existingDuplicates.map((d) => d.id),
          detected_at: new Date().toISOString()
        }
      });

      // 4. Record warning timeline note
      await crm.leads.notes.add(
        lead.id,
        `⚠️ Duplicate Alert: Found ${existingDuplicates.length} existing lead(s) with matching email: ${duplicateSummary}.`
      );

      console.log(`Successfully tagged duplicate warnings on lead #${lead.id}.`);
    } else {
      console.log("No duplicates found. Lead is unique.");
    }
  } catch (error: any) {
    console.error(`Duplicate detection query failed: ${error.message}`);
    throw error;
  }
}