Templates API

Manage document templates (PDF/Excel) programmatically.

Endpoints Overview

Method	Endpoint	Description
POST	/api/templates	Create new template
GET	/api/templates/:id	Get template by ID
PUT	/api/templates/:id	Update template
DELETE	/api/templates/:id	Delete template (soft delete)
POST	/api/templates/:id/publish	Publish template
POST	/api/templates/:id/duplicate	Duplicate template
GET	/api/templates/:id/export	Export template to JSON
POST	/api/templates/import	Import template from JSON
GET	/api/templates/:id/versions	List template versions
GET	/api/templates/:id/versions/:versionId	Get specific version
POST	/api/templates/:id/versions/:versionId/restore	Restore to version
POST	/api/templates/:id/preview	Preview template
GET	/api/templates/:id/analytics	Get template analytics
GET	/api/templates/:id/zapier-fields	Get Zapier field definitions
POST	/api/templates/bulk-delete	Bulk delete templates
POST	/api/templates/validate-schema	Validate schema
POST	/api/templates/validate-variables	Validate variables

note

All endpoints require JWT authentication. API key authentication is supported for read operations.

---

Create Template

POST /api/templates

Create a new document template.

Request Body

Field	Type	Required	Description
name	string	Yes	Template name
description	string	No	Template description
outputFormats	array	Yes	Output formats: ["pdf"], ["excel"], or ["pdf", "excel"]
schema	object	Yes	Template schema (see Template Schema)
variables	array	No	Template variables
constants	object	No	Constant values
calculatedVariables	array	No	Calculated variables with expressions
folderId	string	No	Folder ID to place template in

Request Example

{
  "name": "Invoice Template",
  "description": "Professional invoice with line items",
  "outputFormats": ["pdf"],
  "schema": {
    "format": "pdf",
    "pageSize": "A4",
    "sections": [
      {
        "id": "header",
        "components": [
          {
            "type": "text",
            "props": {
              "content": "Invoice #{{invoiceNumber}}"
            }
          }
        ]
      }
    ]
  },
  "variables": [
    {
      "name": "invoiceNumber",
      "type": "string",
      "required": true,
      "defaultValue": "INV-001"
    }
  ]
}

Response

{
  "id": "atpl_abc123",
  "shortId": "etpl_a1b2c3d4",
  "slug": "invoice-template",
  "name": "Invoice Template",
  "outputFormats": ["pdf"],
  "createdAt": "2025-01-15T00:00:00Z"
}

---

Get Template

GET /api/templates/:id

Get a template by ID, shortId, or slug.

Path Parameters

Parameter	Type	Description
id	string	Template ID, shortId (etpl_xxx), or slug

Response

{
  "id": "atpl_abc123",
  "shortId": "etpl_a1b2c3d4",
  "slug": "invoice-template",
  "name": "Invoice Template",
  "description": "Professional invoice with line items",
  "outputFormats": ["pdf"],
  "schema": {
    "sections": [...],
    "format": "pdf"
  },
  "variables": [
    {
      "name": "invoiceNumber",
      "type": "string",
      "required": true
    }
  ],
  "constants": {},
  "calculatedVariables": [],
  "isPublished": true,
  "publishedAt": "2025-01-15T10:00:00Z",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-15T00:00:00Z"
}

---

Update Template

PUT /api/templates/:id

Update a template.

Path Parameters

Parameter	Type	Description
id	string	Template ID, shortId, or slug

Request Body

Field	Type	Required	Description
name	string	No	Template name
description	string	No	Template description
schema	object	No	Updated template schema
variables	array	No	Updated variables
constants	object	No	Updated constants
calculatedVariables	array	No	Updated calculated variables
folderId	string	No	Move to folder

Response

Returns the updated template object.

---

Delete Template

DELETE /api/templates/:id

Soft delete a template.

Path Parameters

Parameter	Type	Description
id	string	Template ID, shortId, or slug

Response

{
  "success": true,
  "message": "Template deleted successfully"
}

---

Publish Template

POST /api/templates/:id/publish

Publish a template, creating a new version that can be used for document generation.

Path Parameters

Parameter	Type	Description
id	string	Template ID

Request Body

Field	Type	Required	Description
releaseNotes	string	No	Version release notes

Response

{
  "id": "atpl_abc123",
  "version": 2,
  "publishedAt": "2025-01-15T10:00:00Z"
}

---

Duplicate Template

POST /api/templates/:id/duplicate

Create a copy of an existing template.

Path Parameters

Parameter	Type	Description
id	string	Template ID to duplicate

Response

Returns the newly created template with "(Copy)" appended to the name.

---

Export Template

GET /api/templates/:id/export

Export a template to a JSON file for backup or sharing.

Path Parameters

Parameter	Type	Description
id	string	Template ID

Response

Returns a JSON file download containing the complete template definition.

---

Import Template

POST /api/templates/import

Import a template from a JSON file.

Request

Multipart form data with:

Field	Type	Required	Description
file	file	Yes	JSON file to import
duplicateHandling	string	No	Conflict strategy: rename, skip, or overwrite

Response

{
  "status": "success",
  "templateId": "atpl_abc123",
  "message": "Template imported successfully"
}

---

List Template Versions

GET /api/templates/:id/versions

Get all published versions of a template.

Path Parameters

Parameter	Type	Description
id	string	Template ID

Response

[
  {
    "id": "ver_abc123",
    "version": 2,
    "releaseNotes": "Updated layout",
    "publishedAt": "2025-01-15T10:00:00Z",
    "publishedBy": "John Doe"
  },
  {
    "id": "ver_xyz789",
    "version": 1,
    "releaseNotes": "Initial version",
    "publishedAt": "2025-01-01T00:00:00Z",
    "publishedBy": "John Doe"
  }
]

---

Get Template Version

GET /api/templates/:id/versions/:versionId

Get a specific version of a template.

Path Parameters

Parameter	Type	Description
id	string	Template ID
versionId	string	Version ID

Response

Returns the complete template state at that version.

---

Restore Template Version

POST /api/templates/:id/versions/:versionId/restore

Restore a template to a previous version.

Path Parameters

Parameter	Type	Description
id	string	Template ID
versionId	string	Version ID to restore

Request Body

Field	Type	Required	Description
releaseNotes	string	No	Notes for the restore

Response

{
  "success": true,
  "newVersion": 3,
  "message": "Template restored to version 1"
}

---

Preview Template

POST /api/templates/:id/preview

Generate a preview of the template with sample data.

Path Parameters

Parameter	Type	Description
id	string	Template ID

Request Body

Field	Type	Required	Description
variables	object	No	Variable values for preview
format	string	No	Output format: pdf or excel (default: pdf)

Response

Returns binary PDF or Excel file data.

---

Get Template Analytics

GET /api/templates/:id/analytics

Get usage analytics for a specific template.

Path Parameters

Parameter	Type	Description
id	string	Template ID

Query Parameters

Parameter	Type	Default	Description
startDate	string	-	Start date (ISO 8601)
endDate	string	-	End date (ISO 8601)
period	string	30d	Period: 7d, 30d, 90d, 1y

Response

{
  "templateId": "atpl_abc123",
  "templateName": "Invoice Template",
  "usage": {
    "total": 450,
    "last7Days": 45,
    "last30Days": 180
  },
  "performance": {
    "successRate": 99.1,
    "avgGenerationTimeMs": 2300,
    "failedCount": 4
  },
  "trend": [
    { "date": "2025-01-01", "count": 15 },
    { "date": "2025-01-02", "count": 18 }
  ]
}

---

Get Zapier Fields

GET /api/templates/:id/zapier-fields

Get template variables in Zapier-compatible field format for integration.

Path Parameters

Parameter	Type	Description
id	string	Template ID, shortId, or slug

Response

{
  "fields": [
    {
      "key": "invoiceNumber",
      "label": "Invoice Number",
      "type": "string",
      "required": true
    },
    {
      "key": "lineItems",
      "label": "Line Items",
      "type": "array",
      "children": [
        { "key": "description", "label": "Description", "type": "string" },
        { "key": "quantity", "label": "Quantity", "type": "number" },
        { "key": "price", "label": "Price", "type": "number" }
      ]
    }
  ]
}

---

Bulk Delete Templates

POST /api/templates/bulk-delete

Delete multiple templates at once.

Request Body

Field	Type	Required	Description
ids	array	Yes	Array of template IDs to delete

Response

{
  "deleted": 3,
  "skipped": 1,
  "errors": [
    { "id": "atpl_xyz", "reason": "Template not found" }
  ]
}

---

Validate Schema

POST /api/templates/validate-schema

Validate a template schema without saving.

Request Body

Field	Type	Required	Description
templateType	string	Yes	Type: pdf or excel
schema	object	Yes	Schema to validate

Response

{
  "valid": true,
  "errors": [],
  "warnings": [
    { "path": "sections[0].components[2]", "message": "Image source is empty" }
  ]
}

---

Validate Variables

POST /api/templates/validate-variables

Validate template variables without saving.

Request Body

Field	Type	Required	Description
variables	array	Yes	Variables array to validate
constants	object	No	Constants to validate
calculatedVariables	array	No	Calculated variables to validate

Response

{
  "valid": true,
  "errors": [],
  "warnings": []
}

---

Attachment Templates

For legacy compatibility, attachment template endpoints are also available at /api/templates/attachment/*:

Method	Endpoint	Maps to
POST	/api/templates/attachment	Create template
GET	/api/templates/attachment	List templates
GET	/api/templates/attachment/:id	Get template
PUT	/api/templates/attachment/:id	Update template
DELETE	/api/templates/attachment/:id	Delete template
POST	/api/templates/attachment/:id/publish	Publish template
GET	/api/templates/attachment/:id/export	Export template
POST	/api/templates/attachment/import	Import template
GET	/api/templates/attachment/:id/versions	List versions
GET	/api/templates/attachment/:id/versions/:versionId	Get version
POST	/api/templates/attachment/:id/versions/:versionId/restore	Restore version
POST	/api/templates/attachment/:id/preview	Preview template

---

Error Codes

Template Errors (ERR_TMPL_xxx)

Code	Description
ERR_TMPL_001	Template not found
ERR_TMPL_002	Document template not found
ERR_TMPL_003	Attachment template not found
ERR_TMPL_004	You do not have permission to access this template
ERR_TMPL_005	You do not have permission to edit this template
ERR_TMPL_006	You do not have permission to delete this template
ERR_TMPL_007	You do not have permission to view this template
ERR_TMPL_008	Template schema validation failed
ERR_TMPL_009	Invalid template type
ERR_TMPL_010	Template import data is invalid
ERR_TMPL_011	Template with the same name already exists
ERR_TMPL_012	Template export failed
ERR_TMPL_013	Template version not found
ERR_TMPL_014	Version does not belong to this template
ERR_TMPL_015	No file uploaded for template import
ERR_TMPL_016	Invalid JSON file format
ERR_TMPL_020	No draft version available to publish
ERR_TMPL_021	Template has no published version
ERR_TMPL_022	Template has no draft version
ERR_TMPL_023	Invalid version parameter

---

Related: Documents API | Template Schema | Analytics API