Automate Lead Creation with Server Scripts

Server Scripts allow you to automate actions in Frappe CRM without creating a custom app. Using server-side Python, you can create Leads automatically when specific events occur, expose custom API endpoints, or run scheduled automation tasks.

This guide focuses on three commonly used Server Script types for automating Lead creation:

• DocType Event — Trigger automation when records are created or updated.
• API — Create Leads from external applications through a custom endpoint.
• Scheduler Event — Run Lead creation automatically on a schedule.

DocType Event: Create a Lead from Incoming Emails

You can automatically create a new Lead whenever an email is received by using a DocType Event script.

Step 1: Open Server Script

Navigate to:

Desk > Search “Server Script” > Add Server Script

Configure the script with the following values:

Sample Script

if doc.communication_type == 'Communication' and doc.sent_or_received == 'Received':
    existing_lead = frappe.db.exists("CRM Lead", {"email": doc.sender})
    if not existing_lead:
        frappe.get_doc({
            "doctype": "CRM Lead",
            "first_name": doc.sender_full_name,
            "email": doc.sender,
            "source": "Email",
            "status": "New",
        }).insert(ignore_permissions=True)

This script checks every incoming email and creates a new Lead only if a Lead with the same email address does not already exist.

API Script: Create Leads from External Applications

API Server Scripts expose a custom REST endpoint that external applications can call to create Leads automatically.

Step 1: Create an API Script

Navigate to:

Desk > Search “Server Script” > Add Server Script

Configure the script as follows:

Sample Script

data = frappe.local.form_dict

if not data.get("email") or not data.get("name"):
    frappe.throw("Missing required fields: 'email' and 'name'")

existing_lead = frappe.db.exists("CRM Lead", {"email": data["email"]})
if existing_lead:
    frappe.response["message"] = f"Lead already exists: {existing_lead}"
else:
    lead = frappe.get_doc({
        "doctype": "CRM Lead",
        "first_name": data["name"],
        "email": data["email"],
        "status": "New",
        "source": "API"
    })
    lead.insert(ignore_permissions=True)
    frappe.response["message"] = f"Lead created: {lead.name}"

Calling the API

Send a POST request to:

https://<your-site>/api/method/create_lead_api

Example request body:

{
  "email": "someone@example.com",
  "name": "Someone"
}

The endpoint validates the required fields, checks for duplicate Leads, and creates a new Lead when appropriate.

Scheduler Event: Create Leads Automatically

Scheduler Event scripts execute automatically based on a CRON schedule, making them useful for periodic Lead generation or data synchronization.

Step 1: Create a Scheduler Script

Navigate to:

Desk > Search “Server Script” > Add Server Script

Configure the following values:

Sample Script

frappe.get_doc({
    "doctype": "CRM Lead",
    "first_name": "Auto Generated Lead",
    "email": f"demo_{frappe.utils.now_datetime().strftime('%H%M%S')}@example.com",
    "source": "Scheduled Script",
    "status": "New"
}).insert(ignore_permissions=True)

This example creates a demonstration Lead every hour. In production, you would replace this logic with your own business rules, such as importing Leads from another database, processing queued records, or synchronizing external systems.

Permission Query Scripts

Although Permission Query is another available Server Script type, it is designed for controlling record visibility rather than creating Leads, so it is not covered in this guide.

Best Practices

• Test all scripts on a development or staging site before deploying to production.
• Use ignore_permissions=True only when absolutely necessary.
• Validate all incoming data before creating records.
• Check for duplicate Leads to prevent unnecessary records.
• Log errors appropriately to simplify troubleshooting.
• Keep server scripts focused on a single responsibility.