Frappe Server Calls API in Frappe Framework v15
What Are Server Calls in Frappe?
Server Calls in Frappe Framework v15 allow client-side JavaScript to securely execute Python functions on the server. This communication is handled through the frappe.call method and forms the backbone of ERPNext client–server interaction.
Server calls enable real-time data processing, validations, and integrations without page reloads.
Who Should Use Frappe Server Calls?
Target Audience
- ERPNext Developers
- Frappe Framework Developers
- Backend & Integration Engineers
- ERP Consultants
Technical Prerequisites
- Frappe Framework v15
- JavaScript (ES6)
- Python (Frappe backend)
- Understanding of DocTypes and permissions
How Does frappe.call Work?
The frappe.call method sends an HTTP request from the browser to the Frappe backend. The server executes a whitelisted Python method and returns the response to the client.
Core API: frappe.call
Module: Desk
Source (v15): frappe/public/js/frappe/request.js
How to Make a Basic Server Call in Frappe v15?
Client-Side JavaScript Example
frappe.call({
method: "frappe.client.get",
args: {
doctype: "User",
name: "Administrator"
},
callback: function (r) {
console.log(r.message);
}
});
What this does:
Fetches a User document from the server and returns it to the client in the callback.
How to Call Custom Python Methods?
Step 1: Create a Whitelisted Python Method
import frappe
@frappe.whitelist()
def get_company_name():
return frappe.defaults.get_global_default("company")
Step 2: Call the Method from JavaScript
frappe.call({
method: "my_app.api.get_company_name",
callback: function (r) {
frappe.msgprint(r.message);
}
});
Only methods marked with @frappe.whitelist() can be accessed from the client.
How Are Arguments Passed to Server Calls?
Arguments are passed using the args key and must match the Python method signature.
frappe.call({
method: "my_app.api.get_customer",
args: {
customer: "ABC Corp"
}
});
Frappe automatically maps arguments by name.
What Does a Server Call Return?
Server responses are returned in the r object.
| Property | Description |
| r.message | Primary return value |
| r.exc | Exception details (if any) |
| r._server_messages | Server-side messages |
How to Handle Errors in Server Calls?
frappe.call({
method: "my_app.api.action",
error: function (err) {
console.error(err);
}
});
Errors include permission issues, validation failures, or unhandled exceptions.
Common ERPNext Use Cases for Server Calls
Industry Relevance
- Manufacturing: Production validations
- Finance: Ledger checks and approvals
- Sales: Pricing and discount logic
- HR: Attendance and payroll processing
Server calls enable complex business logic to run securely on the server.
Best Practices for Using Server Calls
- Always whitelist methods explicitly
- Validate permissions on the server
- Avoid heavy logic in client scripts
- Return only required data
- Use meaningful method paths
Security Considerations in Frappe v15
- Only whitelisted methods are callable
- User permissions are enforced automatically
- CSRF protection is handled internally
- Avoid exposing sensitive data in responses
Server calls are designed to be secure by default.
Advanced Usage Patterns
Asynchronous Server Calls with Promises
frappe.call({
method: "my_app.api.get_data"
}).then(r => {
console.log(r.message);
});
Frappe v15 supports promise-based handling for cleaner async code.
Integration Patterns
Server calls integrate seamlessly with:
- Client Scripts
- Custom Buttons
- Workflows
- REST APIs
- Background Jobs (via enqueue)
They form the foundation of ERPNext extensibility.
Troubleshooting Common Issues
Method Not Found
- Verify method path
- Ensure method is whitelisted
Permission Error
- Check user roles
- Validate DocType permissions
Official References (Verified)
Server Calls Docs (v15):
https://docs.frappe.io/framework/user/en/api/server-calls
GitHub Source (v15):
