Frappe API Guide for Python and REST (v15)

What is the Frappe API?

The Frappe API is a unified interface that allows applications, scripts, and services to interact with data stored in Frappe and ERPNext. It provides Python APIs for server-side logic and REST APIs for external integrations, covering all core operations such as: fetching documents, creating records, updating data, running queries, invoking whitelisted methods, and handling authentication.

Types of APIs in Frappe v15

Frappe v15 offers two major API surfaces:

Python APIs are used in app modules, background jobs, hooks, DocType events, controllers, and custom scripts executed on the server.
REST APIs allow third-party systems, mobile apps, and frontend applications to communicate with Frappe using HTTP.

When to use which API?

• Use Python API when writing code inside Frappe:
  • DocType business logic
  • Scheduled tasks
  • App modules
  • Background jobs
  • ERPNext features
• Use REST API when:
  • Building integrations
  • Mobile apps
  • External systems
  • Cloud workflow automation
  • Third-party services

Python API Overview

How does the Python API work?

The Python API is exposed through the frappe module. It gives access to:

• Database operations (frappe.db)
• Document operations (frappe.get_doc)
• Search and queries
• File storage
• Caching
• Background jobs
• User management
• Session context

Everything in the Python API is designed to be safe, permission-aware, and DocType model-driven.

Python API — Common Operations

Fetch a document

import frappe
doc = frappe.get_doc("Customer", "CUST-0001")

Create a document

import frappe
doc = frappe.get_doc({
"doctype": "Customer",
"customer_name": "John Doe"
})
doc.insert()

Update a document

doc.customer_name = "John Smith"
doc.save()

Delete a document

frappe.delete_doc("Customer", "CUST-0001")

Database API (frappe.db)

The frappe.db object exposes database-level methods. It is DocType and permission aware, meaning the framework ensures access control checks automatically.

Example — Simple SELECT

customers = frappe.db.get_list("Customer", fields=["name", "customer_name"])

Example — Filtered Query

records = frappe.db.get_list(
"Sales Invoice",
filters={"status": "Paid"},
fields=["name", "grand_total"]
)

Example — Single Value

value = frappe.db.get_value("Item", "ITEM-0001", "item_name")

REST API Overview

What is the REST API in Frappe?

The REST API allows access over HTTP using standard verbs (GET, POST, PUT, DELETE). Every DocType becomes a REST resource automatically.

Frappe exposes:

• Document endpoints
• Search endpoints
• Whitelisted method endpoints
• Authentication endpoints

REST API — Authentication

Token Authentication

Send token in header:

Authorization: token <api_key>:<api_secret>

Basic Authentication

Authorization: Basic <base64 username:password>

REST API — Document Operations

Get a document

GET /api/resource/Customer/CUST-0001

Create a document

POST /api/resource/Customer
{
"customer_name": "John Doe"
}

Update a document

PUT /api/resource/Customer/CUST-0001
{
"customer_name": "John Smith"
}

Delete a document

DELETE /api/resource/Customer/CUST-0001

REST API — Search

Standard List API

GET /api/resource/Customer?fields=["name","customer_name"]

Filtered Search

GET /api/resource/Customer?filters=[["Customer","customer_group","=","Retail"]]

Calling Whitelisted Methods

Any Python function decorated as @frappe.whitelist() can be called through REST.

Python

@frappe.whitelist()
def get_balance(customer):
...

REST Call

GET /api/method/your_app.api.get_balance?customer=CUST-0001

Security and Permissions

Frappe enforces:

• Role Based Permissions
• User Permissions
• DocType Permissions
• Field Level Permissions
• Query Filters

All API operations respect Frappe’s permission engine.

Admin-level operations require administrator privilege or explicit whitelisting with protected flags.

Real-World Use Cases

Frappe API is widely used to integrate:

• ERPNext with CRM systems
• Warehouse scanners with ERPNext Stock module
• Third-party payment gateways
• Mobile sales applications
• AI assistants or chatbot tools
• IoT gateway devices
• Logistics or billing platforms

The API allows ERPNext to be used as an integration hub.

Technical References

Official Documentation

https://docs.frappe.io/framework/user/en/api

Frappe v15 Source Code

https://github.com/frappe/frappe/tree/version-15

Key API code areas:

• frappe/__init__.py
• frappe/database
• frappe/model/document.py
• frappe/utils
• frappe/api.py