Introduction: What Does Manipulating Documents Mean in Frappe?
Manipulating documents in Frappe refers to programmatically creating, updating, submitting, canceling, or deleting DocType records using the REST API.
This capability is essential for:
- External system integrations
- Mobile and web applications
- Automated workflows
- Third-party service synchronization
- Headless ERPNext implementations
Frappe v15 exposes secure REST endpoints that fully respect role-based permissions and workflows.
What Is the Frappe Document Manipulation API?
Answer
The Frappe Document Manipulation API allows authenticated clients to perform CRUD and workflow operations on DocTypes using standard HTTP methods such as POST, PUT, and DELETE.
Base Resource Endpoint
/api/resource/{DocType}
Example:
/api/resource/Sales Order
How to Create a Document Using REST API
Answer
Documents are created by sending a POST request to the DocType resource endpoint with required field data in JSON format.
Example: Create a New Document
curl -X POST https://example.com/api/resource/Customer \
-H "Authorization: token APIKEY:APISECRET" \
-H "Content-Type: application/json" \
-d '{
"customer_name": "ABC Pharma",
"customer_type": "Company",
"customer_group": "Commercial"
}'
Response
{
"data": {
"name": "CUST-00025",
"customer_name": "ABC Pharma"
}
}
Key Notes
- Mandatory fields must be provided
- Default values are auto-applied
- Naming series is handled by Frappe
- Permissions are strictly enforce
How to Fetch a Single Document
Answer
A document can be retrieved using a GET request with its unique name.
Endpoint
GET /api/resource/{DocType}/{name}
Example
curl -X GET https://example.com/api/resource/Customer/CUST-00025 \
-H "Authorization: token APIKEY:APISECRET"
How to Update a Document Using REST API
Answer
Documents are updated using a PUT request with modified field values.
Example: Update an Existing Document
curl -X PUT https://example.com/api/resource/Customer/CUST-00025 \
-H "Authorization: token APIKEY:APISECRET" \
-H "Content-Type: application/json" \
-d '{
"customer_group": "Retail"
}'
Response
{
"data": {
"name": "CUST-00025",
"customer_group": "Retail"
}
}
Important Update Rules
- Only changed fields need to be sent
- Read-only fields cannot be modified
- Workflow states are validated
- Child tables can also be updated
How to Submit a Document via REST API
Answer
Submitting a document moves it from Draft (docstatus = 0) to Submitted (docstatus = 1).
Endpoint
PUT /api/resource/{DocType}/{name}
Example: Submit a Sales Order
curl -X PUT https://example.com/api/resource/Sales%20Order/SO-00045 \
-H "Authorization: token APIKEY:APISECRET" \
-H "Content-Type: application/json" \
-d '{
"docstatus": 1
}'
Validation Rules
- Document must be in Draft state
- Mandatory submit validations are enforced
- Workflow rules apply if configured
How to Cancel a Document Using REST API
Answer
Canceling sets docstatus to 2, reversing its accounting or stock impact.
Example: Cancel a Submitted Document
curl -X PUT https://example.com/api/resource/Sales%20Order/SO-00045 \
-H "Authorization: token APIKEY:APISECRET" \
-H "Content-Type: application/json" \
-d '{
"docstatus": 2
}'
Important Notes
- Only submitted documents can be canceled
- Linked documents may block cancellation
- Permission checks are enforced
How to Delete a Document
Answer
Documents are deleted using a DELETE request. This action is irreversible.
Example: Delete a Document
curl -X DELETE https://example.com/api/resource/Customer/CUST-00025 \
-H "Authorization: token APIKEY:APISECRET"
Deletion Rules
- Document must not be submitted
- Linked records may prevent deletion
- Only users with delete permission can perform this action
Working with Child Tables via REST API
Answer
Child table rows are manipulated as part of the parent document payload.
Example: Create Parent with Child Table
{
"customer_name": "XYZ Labs",
"contacts": [
{
"first_name": "John",
"email_id": "john@xyzlabs.com"
}
]
}
Best Practices for Document Manipulation
1. Validate Permissions Early
Always ensure the API user has correct role permissions.
2. Avoid Hard Deletes
Prefer canceling documents instead of deleting for audit safety.
3. Use Workflows Where Required
Let Frappe workflows manage approvals and state transitions.
4. Handle Errors Gracefully
Always check API responses for validation or permission errors.
5. Log External API Actions
Maintain logs for traceability and debugging.
Common Errors and Troubleshooting
PermissionError
Cause: Missing role permission
Fix: Update Role Permission Manager
Validation Error
Cause: Missing mandatory fields
Fix: Review DocType field requirements
Link Exists Error
Cause: Linked documents prevent deletion
Fix: Cancel or unlink dependent records
WorkflowError
Cause: Invalid workflow transition
Fix: Follow allowed workflow states
Integration Use Cases
Use Case 1: Mobile Sales Apps
Create and submit orders directly from field apps.
Use Case 2: E-Commerce Platforms
Sync customers, orders, and invoices automatically.
Use Case 3: Third-Party Accounting
Push transactions from external systems into ERPNext.
Use Case 4: Automation & RPA
Trigger ERP actions from bots or scheduled jobs.
Frequently Asked Questions (FAQs)
Can I manipulate submitted documents?
Only allowed actions such as cancel or amend are permitted.
Does REST API respect workflows?
Yes. All workflow rules are strictly enforced.
Can child tables be partially updated?
Yes, by sending only modified child rows.
Is bulk document manipulation supported?
Bulk operations require custom server-side APIs.
Is this API safe for production?
Yes, when secured with proper authentication and roles.
Industry Relevance
Document manipulation APIs are critical for:
- Manufacturing ERP automation
- Pharma batch processing systems
- Retail order management
- Finance and accounting integrations
- SaaS ERP ecosystems
Cross-References
- Listing Documents via REST API
- Fetching a Single Document
- Token-Based Authentication
- OAuth 2 Authentication
- Role & Permission Management
Conclusion
The Frappe REST API for Document Manipulation in Version 15 provides a powerful, secure, and permission-aware interface for managing ERPNext data programmatically.
By following best practices and respecting workflows, developers can build:
- Scalable integrations
- Secure automation
- Headless ERP systems
- Future-ready digital platforms
This API forms the backbone of modern ERPNext-powered applications.
Official References
Documentation:
https://docs.frappe.io/framework/user/en/guides/integration/rest_api/manipulating_documents
