ERPNext Syntax: Whitelisted Methods

Whitelisted Methods expose Python functions as REST API endpoints.

Quick Reference

Basic Whitelisted Method

import frappe

@frappe.whitelist()
def get_customer_summary(customer):
    """Basic API endpoint - authenticated users only."""
    if not frappe.has_permission("Customer", "read"):
        frappe.throw(_("Not permitted"), frappe.PermissionError)
    
    return frappe.get_doc("Customer", customer).as_dict()

Endpoint URL

/api/method/myapp.api.get_customer_summary

Decorator Options

allow_guest

False

True

methods

["GET"]

["POST"]

xss_safe

False

True

# Public endpoint, POST only
@frappe.whitelist(allow_guest=True, methods=["POST"])
def submit_contact_form(name, email, message):
    # Validate input carefully with guest access!
    if not name or not email:
        frappe.throw(_("Name and email required"))
    return {"success": True}

# Read-only endpoint
@frappe.whitelist(methods=["GET"])
def get_status(order_id):
    return frappe.db.get_value("Sales Order", order_id, "status")

Full options: See decorator-options.md

Permission Patterns

ALWAYS Check Permissions

@frappe.whitelist()
def get_data(doctype, name):
    # Check BEFORE fetching data
    if not frappe.has_permission(doctype, "read", name):
        frappe.throw(_("Not permitted"), frappe.PermissionError)
    return frappe.get_doc(doctype, name).as_dict()

Role-Based Access

@frappe.whitelist()
def admin_function():
    frappe.only_for("System Manager")  # Throws if user lacks role
    return {"admin_data": "sensitive"}

@frappe.whitelist()
def multi_role_function():
    frappe.only_for(["System Manager", "HR Manager"])
    return {"data": "value"}

Security patterns: See permission-patterns.md

Error Handling

frappe.throw() for User-Facing Errors

@frappe.whitelist()
def process_order(order_id, amount):
    # Validation error
    if not order_id:
        frappe.throw(_("Order ID required"), title=_("Missing Data"))
    
    # Permission error
    if not frappe.has_permission("Sales Order", "write"):
        frappe.throw(_("Not permitted"), frappe.PermissionError)
    
    # Business logic error
    if amount < 0:
        frappe.throw(
            _("Amount cannot be negative: {0}").format(amount),
            frappe.ValidationError
        )

Exception Types and HTTP Codes

frappe.ValidationError

frappe.PermissionError

frappe.DoesNotExistError

frappe.DuplicateEntryError

frappe.AuthenticationError

Robust Error Pattern

@frappe.whitelist()
def robust_api(param):
    try:
        result = process_data(param)
        return {"success": True, "data": result}
    except frappe.DoesNotExistError:
        frappe.local.response["http_status_code"] = 404
        return {"success": False, "error": "Not found"}
    except frappe.PermissionError:
        frappe.local.response["http_status_code"] = 403
        return {"success": False, "error": "Access denied"}
    except Exception:
        frappe.log_error(frappe.get_traceback(), "API Error")
        frappe.local.response["http_status_code"] = 500
        return {"success": False, "error": "Internal error"}

Full error patterns: See error-handling.md

Response Patterns

Return Value (Recommended)

@frappe.whitelist()
def get_summary(customer):
    return {
        "customer": customer,
        "total": 15000
    }
# Response: {"message": {"customer": "...", "total": 15000}}

Custom HTTP Status

@frappe.whitelist()
def create_item(data):
    if not data:
        frappe.local.response["http_status_code"] = 400
        return {"error": "Data required"}
    # ... create item
    frappe.local.response["http_status_code"] = 201
    return {"created": True}

Full response patterns: See response-patterns.md

Client Calls

frappe.call() - Standalone APIs

// Promise-based (recommended)
frappe.call({
    method: 'myapp.api.get_customer_summary',
    args: { customer: 'CUST-00001' }
}).then(r => {
    console.log(r.message);
});

// With loading indicator
frappe.call({
    method: 'myapp.api.process_data',
    args: { data: myData },
    freeze: true,
    freeze_message: __('Processing...')
});

frm.call() - Controller Methods

frm.call('calculate_taxes', {
    include_shipping: true
}).then(r => {
    frm.set_value('tax_amount', r.message.tax_amount);
});

Full client patterns: See client-calls.md

Decision Tree: Which Options?

Who may call the API?
│
├─► Anyone (including guests)?
│   └─► allow_guest=True + extra input validation
│
└─► Logged-in users only?
    │
    └─► Specific role required?
        ├─► Yes → frappe.only_for("RoleName") in method
        └─► No → frappe.has_permission() check

Which HTTP methods?
│
├─► Read only?
│   └─► methods=["GET"]
│
├─► Write only?
│   └─► methods=["POST"]
│
└─► Both?
    └─► methods=["GET", "POST"] or default (all)

Security Checklist

For EVERY whitelisted method:

• Permission check present (

  frappe.has_permission()

  or

  frappe.only_for()

  )
• Input validation (types, ranges, formats)
• No SQL injection (parameterized queries)
• No sensitive data in error messages

• allow_guest=True

  only with explicit reason

• ignore_permissions=True

  only with role check
• HTTP method restricted where possible

Critical Rules

1. NEVER Skip Permission Check

# ❌ WRONG - anyone can see all data
@frappe.whitelist()
def get_all_salaries():
    return frappe.get_all("Salary Slip", fields=["*"])

# ✅ CORRECT
@frappe.whitelist()
def get_salaries():
    frappe.only_for("HR Manager")
    return frappe.get_all("Salary Slip", fields=["*"])

2. NEVER Use User Input in SQL

# ❌ WRONG - SQL injection!
@frappe.whitelist()
def search(term):
    return frappe.db.sql(f"SELECT * FROM tabCustomer WHERE name LIKE '%{term}%'")

# ✅ CORRECT - parameterized
@frappe.whitelist()
def search(term):
    return frappe.db.sql("""
        SELECT * FROM tabCustomer WHERE name LIKE %(term)s
    """, {"term": f"%{term}%"}, as_dict=True)

3. NEVER Leak Sensitive Data in Errors

# ❌ WRONG - leaks internal information
except Exception as e:
    frappe.throw(str(e))  # May leak stack traces!

# ✅ CORRECT
except Exception:
    frappe.log_error(frappe.get_traceback(), "API Error")
    frappe.throw(_("An error occurred"))

All anti-patterns: See anti-patterns.md

Version Differences (v14 vs v15)

/api/v2/

@rate_limit()

/api/v2/document/{dt}/{name}/method/{m}

v15 Type Validation

@frappe.whitelist()
def get_orders(customer: str, limit: int = 10) -> dict:
    """v15 validates types automatically on request."""
    return {"orders": frappe.get_all("Sales Order", limit=limit)}

Reference Files