Insert a Document via API in Frappe Framework (v15)

Introduction: What Does “Insert a Document via API” Mean?

Inserting a document via API in Frappe Framework v15 allows external systems or custom applications to create records inside Frappe programmatically.
This is commonly used for integrations, mobile apps, third-party platforms, and automation workflows.

What Is the Frappe Insert Document API?

The Insert Document API is a REST endpoint that lets you create a new DocType record by sending structured JSON data.
It respects DocType validations, permissions, workflows, and server-side hooks, making it safe for production use.

When Should You Use the Insert Document API?

Use this API when you need to:

• Push data from external systems into Frappe
• Integrate ERPNext with third-party applications
• Create documents from mobile or frontend apps
• Automate data entry without UI interaction

Technical Prerequisites

Before using the Insert Document API, ensure:

• Frappe Framework v15 is installed
• Target DocType exists and is accessible
• API authentication is configured
• Required fields are known

How to Insert a Document via REST API (Step-by-Step)

Step 1: API Endpoint

The insert document endpoint in Frappe v15 is:

POST /api/resource/{DocType}

Replace {DocType} with the name of the DocType you want to create.

Step 2: Authentication

Frappe supports token-based authentication for API calls.

HTTP Header Example:

Authorization: token api_key:api_secret

Step 3: Request Payload Structure

Send a JSON payload containing the document fields.

Example: Insert a Customer

{
"customer_name": "ABC Industries",
"customer_type": "Company",
"customer_group": "Commercial",
"territory": "India"
}

All standard validations defined in the DocType are enforced.

Complete cURL Example (Frappe v15)

curl -X POST https://your-site.com/api/resource/Customer \
-H "Authorization: token api_key:api_secret" \
-H "Content-Type: application/json" \
-d '{
"customer_name": "ABC Industries",
"customer_type": "Company",
"customer_group": "Commercial",
"territory": "India"
}'

API Response Structure

On success, Frappe returns the newly created document:

{
"data": {
"name": "ABC-IND-0001",
"customer_name": "ABC Industries",
"doctype": "Customer"
}
}

What Happens Internally in Frappe (v15)?

When a document is inserted via API, Frappe:

1. Validates permissions
2. Applies DocType rules
3. Executes before_insert hooks
4. Saves the document
5. Executes after_insert hooks

This ensures API inserts behave exactly like UI-based inserts.

Inserting Child Table Data via API

You can insert child records by passing arrays.

Example: Sales Order with Items

{
"customer": "ABC Industries",
"items": [
{
"item_code": "ITEM-001",
"qty": 5,
"rate": 100
}
]
}

Frappe automatically links child rows to the parent document.

Common Errors and Troubleshooting

Validation Error

Occurs when required fields are missing or invalid.

Fix:

Verify mandatory fields in the DocType.

Permission Error

Occurs when the API user lacks create permission.

Fix:

Grant Create permission for the DocType.

Authentication Failed

Occurs due to invalid API key or secret.

Fix:

Regenerate API credentials and retry.

Best Practices for Insert Document API

• Use a dedicated API user
• Validate payload before sending
• Avoid bypassing business logic
• Log API responses for debugging
• Use background jobs for bulk inserts

Advanced Usage Patterns

ERP Integrations

• CRM → ERPNext
• E-commerce → ERPNext
• Accounting software → ERPNext

Automation Pipelines

• Webhooks
• IoT data ingestion
• Scheduled data sync

Target Audience

• ERPNext Developers
• Integration Engineers
• API Developers
• ERP Consultants

Industry Relevance

The Insert Document API is widely used in:

• Manufacturing ERPs
• Retail and distribution systems
• Finance and accounting platforms
• SaaS ERP solutions

Summary: Creating Records Programmatically in Frappe v15

The Insert Document API in Frappe Framework v15 provides a secure, consistent, and scalable way to create records programmatically.
It respects permissions, workflows, and validations—making it ideal for real-world ERPNext integrations.