Generate Document

Generate a PDF document using a template and dynamic data. This endpoint allows you to merge your template with data and receive the PDF in different formats.

Endpoint

POST https://api.docstron.com/v1/documents/generate

Authentication

This endpoint requires authentication using a Bearer token. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Parameters

---

Request Body

Parameter	Type	Required	Description
template_id	string	Yes	The unique identifier of the template to use
data	object	Yes	Key-value pairs to replace placeholders in the template (e.g., {"customer_name": "John Doe"})
response_type	string	Yes	Format of the response. Options: pdf, json_with_base64, or document_id

Response Type Options

Value	Description
pdf	Returns the PDF file directly in the HTTP response (binary)
json_with_base64	Returns JSON with base64-encoded PDF content and metadata
document_id	Returns JSON with document ID and download URL

Request Examples

---

Generate with Direct PDF Response

curl --location 'https://api.docstron.com/v1/documents/generate' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "template_id": "template-c2465c0b-fc54-4672-b9ac-7446886cd6de",
    "data": {
      "customer_name": "John Doe",
      "amount": "$299.00"
    },
    "response_type": "pdf"
  }'

Generate with Base64 Response

curl --location 'https://api.docstron.com/v1/documents/generate' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "template_id": "template-c2465c0b-fc54-4672-b9ac-7446886cd6de",
    "data": {
      "customer_name": "John Doe",
      "amount": "$299.00"
    },
    "response_type": "json_with_base64"
  }'

Generate with Document ID Response

curl --location 'https://api.docstron.com/v1/documents/generate' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
    "template_id": "template-c2465c0b-fc54-4672-b9ac-7446886cd6de",
    "data": {
      "customer_name": "John Doe",
      "amount": "$299.00"
    },
    "response_type": "document_id"
  }'

Response

---

200 - Success Response (pdf)

When response_type is pdf, the response is the PDF file directly as binary content.

Content-Type: application/pdf

The response will prompt a file download in browsers or can be saved directly in your application.

---

200 - Success Response (json_with_base64)

When response_type is json_with_base64, the response includes base64-encoded PDF content.

{
  "success": true,
  "message": "Request successful",
  "data": {
    "document_id": "document-fb5cf3c7-eddc-4edd-9683-81ff7fc61234",
    "template_id": "template-c2465c0b-fc54-4672-b9ac-7446886cd6de",
    "pdf_content": "JVBERi0xLjcKJfCflqQKNiAwIG9GaWx0ZXIgL0ZsYXRlRGVjb2RlL0xlbmd0aC...",
    "filename": "file_2025-10-12_17-07-54_90094aa5.pdf",
    "content_type": "application/pdf",
    "size_bytes": 5370
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
message	string	A message describing the response
data.document_id	string	Unique identifier of the generated document
data.template_id	string	The template used to generate the document
data.pdf_content	string	Base64-encoded PDF file content
data.filename	string	Generated filename for the PDF
data.content_type	string	MIME type of the document (application/pdf)
data.size_bytes	integer	Size of the PDF file in bytes

---

200 - Success Response (document_id)

When response_type is document_id, the response includes a document ID and download URL.

{
  "success": true,
  "message": "Request successful",
  "data": {
    "document_id": "document-fb5cf3c7-eddc-4edd-9683-81ff7fc61234",
    "template_id": "template-c2465c0b-fc54-4672-b9ac-7446886cd6de",
    "download_url": "https://api.docstron.com/v1/documents/download/document-fb5cf3c7-eddc-4edd-9683-81ff7fc61234",
    "size_bytes": 5370
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
message	string	A message describing the response
data.document_id	string	Unique identifier of the generated document
data.template_id	string	The template used to generate the document
data.download_url	string	URL to download the generated PDF
data.size_bytes	integer	Size of the PDF file in bytes

Error Responses

---

400 - Limit Reached

Returned when you’ve exceeded your subscription’s monthly document generation limit.

{
  "success": false,
  "message": "You've reached the maximum monthly limit of 20 documents for your subscription.",
  "data": []
}

Solution: Upgrade your subscription plan at Docstron Pricing or wait until your monthly limit resets.

---

404 - Template Not Found

Returned when the provided template_id does not exist or the template/application is inactive.

{
  "success": false,
  "message": "Template not found. Please ensure application and template are active.",
  "data": []
}

Common causes:

• Invalid or mistyped template_id
• Template has been deleted
• Template is marked as inactive (is_active: false)
• Application is marked as inactive

Solution: Verify the template_id is correct and ensure both the template and its application are active using the Get Template endpoint.

---

422 - Validation Error

Returned when the request data fails validation.

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "response_type",
      "message": "Input should be 'pdf', 'json_with_base64' or 'document_id'",
      "type": "literal_error"
    }
  ]
}

Common causes:

• Invalid response_type value
• Missing required fields (template_id or data)
• Invalid data types

Solution: Check the error details and ensure all fields are properly formatted. Valid response_type values are: pdf, json_with_base64, or document_id.

---

500 - Template Engine Error

Returned when there’s an error processing the template with the provided data.

{
  "success": false,
  "message": "Template engine error!",
  "data": []
}

Common causes:

• Missing data for required template placeholders
• Invalid placeholder syntax in template
• Template rendering issues

Solution: Verify that all placeholders in your template have corresponding data in the data object. Check your template content for syntax errors.

---

500 - Document Creation Failed

Returned when an unexpected server error occurs during document generation.

{
  "success": false,
  "message": "Failed to create the document",
  "data": []
}

Common causes:

• Temporary server issue
• PDF generation service unavailable
• Database connectivity problem

Solution: Wait a few moments and retry the request. If the problem persists, contact support@docstron.com.

Choosing Response Type

---

Use pdf when:

• You want to download the PDF immediately
• Building a direct download endpoint
• You don’t need to store the document ID

Use json_with_base64 when:

• You need the PDF content embedded in JSON
• Building APIs that return JSON responses
• You want to process the PDF content in memory

Use document_id when:

• You need to store the document reference for later
• Building asynchronous workflows
• You want to provide a download link to users
• You need to track or manage generated documents

Need Help?

If you have questions about applications or need assistance:

• 📧 Email: support@docstron.com
• 💬 Live Chat: Available in your dashboard
• 📚 Documentation: You’re reading it!