Create Template

Create a new HTML template for PDF generation using the Docstron API. Templates define the layout and structure of your PDF documents and can include dynamic placeholders for data injection.

Endpoint

POST https://api.docstron.com/v1/templates

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
application_id	string	Yes	The unique identifier of the application (e.g., app-7b4d78fb-820c-4ca9-84cc-46953f211234)
name	string	Yes	Name of the template (e.g., Invoice Template)
content	string	Yes	HTML content of the template. Supports dynamic placeholders like {{variable_name}}
is_active	boolean	No	Whether the template is active (default: true). Inactive templates cannot be used for document generation
extra_css	string	No	Additional CSS rules for styling the PDF (e.g., page margins, headers, footers)

Request Examples

curl --location 'https://api.docstron.com/v1/templates' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
    "application_id": "app-7b4d78fb-820c-4ca9-84cc-46953f211234",
    "name": "Template 1",
    "is_active": true,
    "content": "<h1>Hello World!</h1>",
    "extra_css": "@page { margin: 3cm; @bottom-left { color: #1ee494; content: '\''♥ Thank you!'\''; } }"
  }'

Response

---

201 - Success Response

{
  "success": true,
  "message": "Request successful",
  "data": {
    "template_id": "template-c2465c0b-fc54-4672-b9ac-7446886cd6de",
    "application_id": "app-7b4d78fb-820c-4ca9-84cc-46953f210301",
    "name": "Template 1",
    "is_active": true,
    "created_at": "2025-10-14T16:39:19",
    "updated_at": "2025-10-14T16:39:19",
    "content": "<h1>Hello World!</h1>",
    "extra_css": "@page { margin: 3cm; @bottom-left { color: #1ee494; content: '♥ Thank you!'; } }"
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
message	string	A message describing the response
data	object	The created template object
data.template_id	string	Unique identifier of the created template
data.application_id	string	The application ID associated with this template
data.name	string	Name of the template
data.is_active	boolean	Whether the template is active (true) or inactive (false)
data.created_at	string	Timestamp when the template was created (ISO 8601 format)
data.updated_at	string	Timestamp when the template was last updated (ISO 8601 format)
data.content	string	HTML content of the template
data.extra_css	string	Additional CSS rules for PDF styling

Error Responses

---

422 - Unprocessable Entity

Returned when required parameters are missing or invalid.

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "application_id",
      "message": "Field required",
      "type": "missing"
    },
    {
      "field": "name",
      "message": "Field required",
      "type": "missing"
    },
    {
      "field": "content",
      "message": "Field required",
      "type": "missing"
    }
  ]
}

Common causes:

• Missing application_id, name, or content
• Invalid JSON format
• Empty template content

Solution: Verify all required fields are provided and properly formatted.

---

404 - Application Not Found

Returned when the provided application_id does not exist or is invalid.

{
  "success": false,
  "message": "Application not found.",
  "data": []
}

Common causes:

• Invalid or mistyped application_id
• Application has been deleted
• The application belongs to a different account

Solution: Verify the application_id is correct. You can list all applications using the Get All Applications endpoint.

---

500 - Internal Server Error

Returned when an unexpected server error occurs while creating the template.

{
  "success": false,
  "message": "Failed to create template.",
  "data": []
}

Common causes:

• Temporary server issue
• Database connectivity problem
• Service maintenance

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

Best Practices

✅ Do’s

• Use semantic HTML - Use proper HTML5 structure for better rendering
• Test placeholders - Ensure all {{variable_name}} placeholders are correctly named
• Use inline CSS - Most CSS in <style> tags works better than external stylesheets
• Set page properties - Use extra_css for margins, headers, and footers

❌ Don’ts

• Don’t use JavaScript - JavaScript is not executed in PDFs
• Don’t hardcode data - Use placeholders for dynamic content
• Don’t forget to test - Always test templates with sample data before using in production

Template Placeholders

Use double curly braces to create dynamic placeholders in your template:

<h1>Hello {{customer_name}}</h1>
<p>Your order total is {{order_total}}</p>
<p>Delivery date: {{delivery_date}}</p>

When generating a PDF, pass the data to replace these placeholders:

{
  "customer_name": "John Doe",
  "order_total": "$299.00",
  "delivery_date": "2025-10-20"
}

Checkout Template Syntax for more details.

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!