Introduction: What Is Frappe REST API?

The Frappe REST API is a web-based interface that allows external applications to interact with Frappe and ERPNext systems using standard HTTP methods.

It enables developers to:

• Access DocTypes
• Create and update records
• Retrieve reports
• Authenticate users
• Integrate third-party systems

In Frappe Framework Version 15, the REST API is fully integrated into the core framework and follows secure authentication and permission models.

Technical Prerequisites

Before using the Frappe REST API, ensure you have:

• Frappe Framework Version 15 installed
• A running Frappe site
• Valid user credentials or API keys
• Basic knowledge of HTTP requests
• Access to REST client (Postman / Curl / Python requests)

How Does the Frappe REST API Work?

The Frappe REST API works by exposing server-side resources through URL endpoints.

Each request includes:

• HTTP method (GET, POST, PUT, DELETE)
• Authorization header
• JSON payload (when required)
• Endpoint URL

The server processes the request and returns a structured JSON response.

What Are the Base API Endpoints in Frappe v15?

All REST API endpoints start with:

/api

Common Base Paths

Example:

https://your-site.com/api/resource/Customer

How to Authenticate with Frappe REST API?

Method 1: Username and Password Authentication

You can authenticate using the login API.

Endpoint

POST /api/method/login

Example

curl -X POST https://site.com/api/method/login \
-d "usr=user@example.com" \
-d "pwd=yourpassword"

This creates a session cookie for subsequent requests.

Method 2: API Key and API Secret Authentication (Recommended)

API authentication is more secure for integrations.

Step 1: Generate API Keys

• Go to User DocType
• Open user record
• Click “Generate API Key”
• Copy API Key and API Secret

Step 2: Use Authorization Header

Format:

Authorization: token api_key:api_secret

Example:

Authorization: token 1234567890:abcdef123456

Method 3: OAuth Authentication

Frappe v15 supports OAuth2 for advanced integrations.

OAuth is recommended for public or third-party apps.

(Refer to OAuth documentation for setup.)

How to Fetch Data Using REST API?

Get All Records

Endpoint

GET /api/resource/{DocType}

Example

GET /api/resource/Customer

Response

{
"data": [
{
"name": "CUST-001",
"customer_name": "ABC Pvt Ltd"
}
]
}

Get Single Record

Endpoint

GET /api/resource/{DocType}/{name}

Example

GET /api/resource/Customer/CUST-001

Apply Filters

Example

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

Select Fields

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

How to Create Records Using REST API?

Create New Document

Endpoint

POST /api/resource/{DocType}

Example

POST /api/resource/Customer

Payload

{
"customer_name": "New Company",
"customer_group": "Commercial",
"territory": "India"
}

Response

{
"data": {
"name": "CUST-005"
}
}

How to Update Records?

Update Existing Document

Endpoint

PUT /api/resource/{DocType}/{name}

Example

PUT /api/resource/Customer/CUST-005

Payload

{
"customer_name": "Updated Company"
}

How to Delete Records?

Delete Document

Endpoint

DELETE /api/resource/{DocType}/{name}

Example

DELETE /api/resource/Customer/CUST-005

Requires delete permission.

How to Call Server Methods via API?

You can call whitelisted Python methods.

Endpoint

/api/method/{method_path}

Example

GET /api/method/frappe.auth.get_logged_user

Custom Method Example

In Python:

@frappe.whitelist()
def get_customer_count():
return frappe.db.count("Customer")

API Call:

GET /api/method/my_app.api.get_customer_count

How to Upload Files Using REST API?

Endpoint

POST /api/method/upload_file

Required Fields

• file
• doctype
• docname
• fieldname

Example:

POST /api/method/upload_file

Multipart form-data.

How Are Permissions Handled?

Frappe REST API follows role-based permissions.

API access is restricted based on:

• User role
• DocType permission
• Document ownership
• Workflow state

If permission is missing, API returns:

403 Forbidden

Common Integration Patterns

ERP + CRM Integration

• Sync leads and customers
• Auto-create sales orders

Mobile App Integration

• Fetch inventory
• Submit orders
• Update leads

Accounting System Integration

• Sync invoices
• Payment status
• Ledger entries

IoT Integration

• Machine data capture
• Production monitoring

Best Practices for Frappe REST API Integration

Use API Keys Instead of Passwords

Avoid storing user passwords in external systems.

Implement Rate Limiting

Prevent server overload.

Validate Data

Always validate payload before sending.

Use Background Jobs

For bulk operations, use async tasks.

Secure API Access

Restrict API users with minimal roles.

Log API Activities

Enable logs for debugging.

Advanced Topics

Pagination Support

Example:

GET /api/resource/Customer?limit=20&limit_start=0

Sorting Records

GET /api/resource/Customer?order_by=creation desc

Bulk Operations

Use background jobs with custom APIs for mass updates.

Custom REST Endpoints

You can create custom endpoints using whitelisted methods and route handling.

Troubleshooting Common Issues

401 Unauthorized

• Invalid API key
• Expired session
• Wrong header format

403 Forbidden

• Missing permission
• Role restriction

404 Not Found

• Wrong DocType
• Invalid record name

500 Server Error

• Python exception
• Missing dependency
• Custom code issue

Check frappe.log_error for debugging.

Industry Relevance

Target Audience Tags

• ERPNext Developers
• Integration Engineers
• Technical Consultants
• API Architects
• System Integrators

Conclusion

The Frappe REST API in Version 15 provides a secure, scalable, and fully integrated framework for building modern ERPNext integrations.
With built-in authentication, permission control, flexible endpoints, and extensibility, it enables organizations to connect ERPNext with mobile apps, CRM systems, analytics platforms, and third-party tools.
By following best practices and proper security models, businesses can build reliable, future-ready integrations using Frappe’s REST architecture.