Skip to main content

Frappe REST API in Version 15

What is the REST API in Frappe?

The REST API in Frappe is a HTTP-based interface that allows external applications to communicate with Frappe sites, including ERPNext. It enables create, read, update, delete (CRUD) operations on DocTypes and allows calling whitelisted Python methods using standard HTTP requests.
Frappe REST API uses JSON for request and response formats and supports token, key, and session-based authentication.

Why use the REST API in Frappe v15?

The Frappe REST API enables:

  • Integration with third-party systems
  • Mobile app communication
  • IoT and edge device data exchange
  • External frontend frameworks (React, Vue, Flutter)
  • Automation from ERPNext into external platforms
  • API-based operations without UI usage

REST API is a standard, stable way to access, modify, and automate ERPNext data.

How to Authenticate API Requests?

Frappe supports multiple authentication methods:

1. Token-Based Authentication (Recommended)

Send in the request header:

Authorization: token <api_key>:<api_secret>

Where:

  • api_key and api_secret are generated in User → API Access
  • This is the most common method for production integrations

Example:

curl -X GET \
-H "Authorization: token a1b2c3:d4e5f6" \
https://example.com/api/resource/Item

2. Cookie / Session Authentication (Browser or Session)

If you are authenticated via browser / login session:

/api/resource/Sales Order

Frappe uses existing cookies to authorize the request.

How to Perform CRUD Calls in REST?

Frappe exposes generic REST endpoints for any DocType.

1. GET (Read Data)

Fetch a list of documents

GET /api/resource/<DocType>

Example:

GET /api/resource/Item

Supports filters, fields, and pagination.

Fetch a single document

GET /api/resource/<DocType>/<name>

Example:

GET /api/resource/Item/ITEM-001

2. POST (Create Document)

POST /api/resource/<DocType>

Body (JSON):

{
"item_code": "ITEM-NEW",
"item_name": "New Product",
"is_stock_item": 1
}

3. PUT (Update Document)

PUT /api/resource/<DocType>/<name>

Example body:

{
"item_name": "Product Updated"
}

4. DELETE (Delete Document)

DELETE /api/resource/<DocType>/<name>

Example:

DELETE /api/resource/Item/ITEM-NEW

Calling Whitelisted Python Methods

You can call server-side Python functions marked as whitelisted.

What is a whitelisted method?

A whitelisted method is a Python function explicitly exposed to the REST API layer.

Example definition:

@frappe.whitelist()
def get_price(item_code):
return {"price": 100}

Call whitelisted method through REST

POST /api/method/<dotted.path>

Example:

POST /api/method/my_app.api.get_price \
-d 'item_code=ITEM-001'

Whitelisted methods can return:

  • dict / JSON
  • raw data (CSV, text)
  • error responses

Passing Request Data

Frappe supports form data and JSON body.

Example JSON POST:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: token key:secret" \
-d '{"item_code": "ITEM-1"}' \
https://example.com/api/method/my_app.api.method

Response Format & Errors

API responses are always returned as JSON.

Success example:

{
"data": {
"name": "ITEM-001",
"item_name": "Item Name"
}
}

Error example:

{
"exc": "Traceback...",
"message": "Not permitted",
"status": "error"
}

Filtering & Query Parameters

Frappe supports filtering using:

/api/resource/DocType?filters=[["field","=","value"]]

Example:

GET /api/resource/Item?filters=[["item_group","=","Raw Material"]]

Returning Selected Fields

?fields=["item_code","item_name"]

Example:

GET /api/resource/Item?fields=["item_code","item_name"]

Pagination

?limit_page_length=20&limit_start=0

Best Practices for REST API Usage

Follow these recommendations for production usage:

1. Always use HTTPS
Secures data in transit.

2. Use API Keys
Avoid usernames/passwords.

3. Limit permission scope
Create dedicated integration user roles.

4. Avoid heavy document writes
Use background jobs for large imports.

5. Rate limiting
Design systems for efficient API usage.

6. Validate input
Never trust external data blindly.

7. Logging
Log API access for traceability.

Common Troubleshooting Issues

Not permitted

  • Missing role or permission
  • Validate permissions in Role Permissions Manager

Invalid method

  • Method not whitelisted
  • Missing @frappe.whitelist()

Invalid Authorization

  • Wrong token formatting
  • Token expired or revoked

CORS issues

  • Browser-side: configure allowed origins using site config or proxy

Real-World Integration Examples

REST API is widely used for:

  • eCommerce integration (Shopify, WooCommerce)
  • CRM systems
  • Mobile field service apps
  • BI dashboards
  • IoT inventory tracking
  • Accounting systems
  • Custom frontend UX

The REST API creates a bridge between ERPNext data and external applications.

Target Audience

  • ERPNext Integration Developers
  • Backend API engineers
  • Mobile App Developers
  • SaaS Integrators
  • Solution Architects

Technical Prerequisites

  • Knowledge of HTTP methods
  • Basic JSON formatting
  • Python function creation
  • Familiarity with DocTypes

Cross-References

To extend your API knowledge:

  • Frappe Authentication API
  • Whitelisted Method API
  • Document API (frappe.get_doc)
  • Background Jobs
  • Server Scripts
  • Frappe Hooks
  • Frappe Query Builder
Click to rate this post!
[Total: 0 Average: 0]

© 2025 | goERPNext | All rights reserved