Introduction: What Does “Listing Documents” Mean in Frappe?
Listing documents in Frappe refers to fetching multiple records of a DocType using the REST API instead of retrieving a single document.
This functionality is commonly used to:
- Display lists in external applications
- Sync ERPNext data with other systems
- Build dashboards and reports
- Implement search and filtering logic
Frappe v15 provides a flexible and secure REST endpoint to list documents with filters, field selection, sorting, and pagination.
What Is the Frappe List Documents API?
Answer
The Frappe List Documents API allows clients to retrieve multiple records of a DocType using the /api/resource/{DocType} endpoint.
It supports filtering, field selection, ordering, and pagination while respecting user permissions.
Base Endpoint for Listing Documents
GET /api/resource/{DocType}
Example:
GET /api/resource/Customer
How to List Documents Using Frappe REST API
Answer
Documents are listed by sending a GET request to the resource endpoint with optional query parameters.
Basic Example: List Documents
curl -X GET https://example.com/api/resource/Item \
-H "Authorization: token APIKEY:APISECRET"
Sample Response
{
"data": [
{
"name": "ITEM-0001"
},
{
"name": "ITEM-0002"
}
]
}
By default, only the name field is returned.
How to Select Specific Fields
Answer
You can control which fields are returned using the fields query parameter.
Example: Fetch Selected Fields
GET /api/resource/Customer?fields=["name","customer_name","customer_type"]
Example cURL Request
curl -G https://example.com/api/resource/Customer \
-H "Authorization: token APIKEY:APISECRET" \
--data-urlencode 'fields=["name","customer_name","customer_type"]'
Response
{
"data": [
{
"name": "CUST-0001",
"customer_name": "ABC Pharma",
"customer_type": "Company"
}
]
}
How to Filter Documents
Answer
Filters allow you to restrict results based on conditions.
Filter Syntax
filters=[[ "field", "operator", "value" ]]
Example: Filter Customers by Type
GET /api/resource/Customer?filters=[["customer_type","=","Company"]]
Example cURL
curl -G https://example.com/api/resource/Customer \
-H "Authorization: token APIKEY:APISECRET" \
--data-urlencode 'filters=[["customer_type","=","Company"]]'
Supported Operators
| Operator | Meaning |
| = | Equals |
| != | Not equals |
| > | Greater than |
| < | Less than |
| >= | Greater or equal |
| <= | Less or equal |
| like | Pattern match |
| in | Multiple values |
How to Use Multiple Filters
Answer
Multiple conditions can be combined using nested filter arrays.
Example: Multiple Filters
filters=[
["status","=","Open"],
["priority","=","High"]
]
How to Sort Documents
Answer
Sorting is controlled using the order_by parameter.
Example: Order by Creation Date
GET /api/resource/Lead?order_by=creation desc
Example cURL
curl -G https://example.com/api/resource/Lead \
-H "Authorization: token APIKEY:APISECRET" \
--data-urlencode 'order_by=creation desc'
How Pagination Works in Frappe List API
Answer
Pagination is handled using limit_start and limit_page_length.
Pagination Parameters
| Parameter | Description |
| limit_start | Starting index |
| limit_page_length | Number of records |
Example: Paginated Request
GET /api/resource/Item?limit_start=0&limit_page_length=10
Example cURL
curl -G https://example.com/api/resource/Item \
-H "Authorization: token APIKEY:APISECRET" \
--data-urlencode 'limit_start=0' \
--data-urlencode 'limit_page_length=10'
How Permissions Affect Listing Documents
Answer
The List Documents API strictly follows Frappe’s permission system.
If a user does not have read permission on a DocType, the API will deny access.
Common Permission Error
{
"exc_type": "PermissionError",
"message": "Not permitted"
}
Solution
Assign permissions via:
Role Permission Manager
Best Practices for Listing Documents via API
1. Always Limit Fields
Avoid fetching unnecessary fields to reduce payload size.
2. Use Pagination
Never fetch large datasets in a single request.
3. Apply Filters Early
Filtering improves performance and security.
4. Avoid Administrator Tokens
Use dedicated API users with limited roles.
5. Monitor API Usage
Track usage to avoid performance bottlenecks.
Advanced Topic: Combining Filters, Fields, and Pagination
Example
curl -G https://example.com/api/resource/Sales%20Order \
-H "Authorization: token APIKEY:APISECRET" \
--data-urlencode 'fields=["name","customer","status","grand_total"]' \
--data-urlencode 'filters=[["status","=","To Deliver"]]' \
--data-urlencode 'order_by=modified desc' \
--data-urlencode 'limit_page_length=5'
Integration Patterns Using List API
Pattern 1: External Dashboards
Fetch ERPNext data for BI tools or analytics platforms.
Pattern 2: Mobile Applications
List records with pagination for mobile-friendly views.
Pattern 3: Data Synchronization
Sync ERPNext records with external CRMs or accounting tools.
Pattern 4: Search Interfaces
Build advanced search UIs using filters and sorting.
Troubleshooting Common Issues
Issue 1: Empty Data Returned
Cause: No matching records or restrictive filters
Solution: Verify filter conditions
Issue 2: PermissionError
Cause: Missing read permission
Solution: Update role permissions
Issue 3: Invalid JSON in Filters
Cause: Incorrect filter format
Solution: Ensure valid JSON arrays
Issue 4: Slow Response
Cause: Large dataset without pagination
Solution: Always use limit_page_length
Frequently Asked Questions (FAQs)
1. Can I list child table records using this API?
No. Child tables must be accessed through their parent documents.
2. Is this API safe for production use?
Yes, when proper authentication and permissions are applied.
3. Can I apply OR conditions in filters?
Advanced OR logic requires server-side scripting.
4. What is the maximum page size?
There is no hard limit, but small page sizes are recommended.
5. Does listing respect user permissions?
Yes. Frappe enforces permission checks for every request.
Industry Relevance
Listing documents via REST API is widely used in:
- Manufacturing ERP integrations
- CRM and sales platforms
- Finance and accounting systems
- Logistics dashboards
- SaaS ERP ecosystems
Cross References
Related documentation:
- Fetching a Single Document
- Creating Documents via API
- Token-Based Authentication
- OAuth 2 Authentication
- REST API Overview
Conclusion: Efficient Data Retrieval with Frappe List API
The Listing Documents API in Frappe Framework v15 provides a powerful, flexible, and secure way to retrieve ERPNext data for external applications.
By leveraging filters, field selection, sorting, and pagination, developers can:
- Build scalable integrations
- Optimize performance
- Maintain data security
- Enable real-time data access
When used correctly, this API becomes a foundational tool for modern ERPNext integrations.
References
Official Documentation:
https://docs.frappe.io/framework/user/en/guides/integration/rest_api/listing_documents
