Skip to main content
ERPNext provides a comprehensive REST API built on the Frappe Framework that allows you to programmatically interact with your ERP system. You can perform CRUD operations on all DocTypes, execute whitelisted methods, and integrate ERPNext with external applications.

​
Base URL

All API requests are made to your ERPNext instance URL: 
https://your-instance.erpnext.com
For self-hosted installations: 
http://localhost:8000

​
API Endpoints Structure

The ERPNext API follows a consistent pattern for accessing resources:

​
Resource Endpoints

EndpointMethodDescription
/api/resource/{doctype}GETGet a list of documents
/api/resource/{doctype}POSTCreate a new document
/api/resource/{doctype}/{name}GETGet a specific document
/api/resource/{doctype}/{name}PUTUpdate a document
/api/resource/{doctype}/{name}DELETEDelete a document

​
Method Endpoints

/api/method/{method_path}
Execute custom whitelisted methods decorated with @frappe.whitelist().

​
Common DocTypes

ERPNext includes hundreds of DocTypes. Here are some commonly used ones:
  • Customer - Customer records
  • Item - Product/item master
  • Sales Order - Sales order transactions
  • Purchase Order - Purchase order transactions
  • Sales Invoice - Sales invoices
  • Purchase Invoice - Purchase invoices
  • Delivery Note - Delivery documents
  • Stock Entry - Stock movements
  • Payment Entry - Payment records
  • Journal Entry - Accounting entries

​
Request Format

All requests should include:
  • Content-Type: application/json
  • Accept: application/json
  • Authorization: API Key or Token (see Authentication)

​
Response Format

API responses are returned in JSON format: 
{
  "message": {
    "name": "CUST-00001",
    "customer_name": "John Doe",
    "customer_type": "Individual",
    "territory": "United States"
  }
}

​
Getting a List of Documents

Retrieve multiple documents with filtering, sorting, and pagination: 
curl -X GET \
  'https://your-instance.erpnext.com/api/resource/Customer?fields=["name","customer_name","territory"]&limit_page_length=20' \
  -H 'Authorization: token api_key:api_secret'

​
Query Parameters

​
fields
string
JSON array of field names to return. Example: ["name", "customer_name"]
​
filters
string
JSON array of filters. Example: [["Customer", "territory", "=", "United States"]]
​
limit_page_length
integer
default:"20"
Number of records to return per page
​
limit_start
integer
default:"0"
Starting index for pagination
​
order_by
string
Field to sort by. Example: modified desc or customer_name asc

​
Getting a Single Document

curl -X GET \
  'https://your-instance.erpnext.com/api/resource/Customer/CUST-00001' \
  -H 'Authorization: token api_key:api_secret'

​
Creating a Document

curl -X POST \
  'https://your-instance.erpnext.com/api/resource/Customer' \
  -H 'Authorization: token api_key:api_secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_name": "Jane Smith",
    "customer_type": "Individual",
    "territory": "United States"
  }'
When creating documents, you only need to provide required fields and any optional fields you want to set. ERPNext will automatically populate default values and generate naming series.

​
Updating a Document

curl -X PUT \
  'https://your-instance.erpnext.com/api/resource/Customer/CUST-00001' \
  -H 'Authorization: token api_key:api_secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_name": "Jane Smith Updated",
    "mobile_no": "+1-555-0123"
  }'

​
Deleting a Document

curl -X DELETE \
  'https://your-instance.erpnext.com/api/resource/Customer/CUST-00001' \
  -H 'Authorization: token api_key:api_secret'
Deleting documents is permanent. Some documents cannot be deleted if they have dependent transactions. Always check for references before deletion.

​
Calling Custom Methods

ERPNext has many whitelisted methods that provide additional functionality: 
curl -X POST \
  'https://your-instance.erpnext.com/api/method/erpnext.stock.get_item_details.get_item_details' \
  -H 'Authorization: token api_key:api_secret' \
  -H 'Content-Type: application/json' \
  -d '{
    "item_code": "ITEM-001",
    "warehouse": "Stores - WH",
    "doctype": "Sales Order"
  }'
Custom methods decorated with @frappe.whitelist() in the codebase are accessible via the API. Check the ERPNext source code to discover available methods.

​
File Uploads

Upload files and attach them to documents: 
import requests

url = "https://your-instance.erpnext.com/api/method/upload_file"
headers = {
    "Authorization": "token api_key:api_secret"
}

with open("document.pdf", "rb") as f:
    files = {"file": f}
    data = {
        "doctype": "Customer",
        "docname": "CUST-00001",
        "is_private": 1
    }
    response = requests.post(url, headers=headers, files=files, data=data)
    file_doc = response.json()["message"]
    print(f"File uploaded: {file_doc['file_url']}")

​
Rate Limiting

ERPNext doesn’t enforce strict rate limits by default, but it’s recommended to:
  • Batch requests when possible
  • Implement retry logic with exponential backoff
  • Monitor API usage to avoid overwhelming the server
  • Use webhooks for real-time updates instead of polling

​
Error Handling

Common HTTP status codes:
  • 200 OK - Successful GET request
  • 201 Created - Successful POST request
  • 202 Accepted - Successful PUT/DELETE request
  • 400 Bad Request - Invalid request format
  • 401 Unauthorized - Invalid or missing authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource doesn’t exist
  • 417 Expectation Failed - Validation error
  • 500 Internal Server Error - Server error
Always check both the HTTP status code and the response body for detailed error messages. ERPNext provides descriptive error messages in the exception and _server_messages fields.

​
Next Steps

  • Learn about Authentication methods
  • Explore the Frappe Framework documentation for advanced features
  • Check the ERPNext source code for available whitelisted methods
  • Join the ERPNext community forum for API support

Build docs developers (and LLMs) love

Get started for freeTalk to us