Skip to main content

Upload Template with Optional Default Values

The Upload Template endpoint adds a new DOCX or PPTX template to your TurboDocx workspace in a single multipart request. Alongside the file, you can define the template's variables (the placeholders TurboDocx fills at generation time), give each one a default value, and attach tags. This lets you provision templates programmatically instead of uploading them by hand in the UI, which is how most developers onboard templates at scale.

When to use it​

Use this endpoint to let your users bring their own templates, to migrate a library of documents into TurboDocx during onboarding, or to keep templates in version control and push updates from CI. Once uploaded, generate documents from the returned template ID and manage it with Get Templates and Folders and Delete Template.

Request fields​

FieldTypeRequiredDescription
templateFilefile (binary)YesThe DOCX or PPTX file to upload.
namestringYesDisplay name for the template, for example SOW Template.
variablesJSON stringYesArray of placeholder definitions with optional default values. Send [] if the template has none.
descriptionstringNoHuman-readable description.
tagsJSON stringNoArray of tags for filtering and organization.

The "optional default values" in the name refers to the per-variable defaults, not to the variables field itself: the field is required, but each variable's default value is optional.

Example request​

curl -X POST "https://api.turbodocx.com/template" \
  -H "Authorization: Bearer $TURBODOCX_API_KEY" \
  -H "x-rapiddocx-org-id: $TURBODOCX_ORG_ID" \
  -F "templateFile=@./sow-template.docx" \
  -F "name=SOW Template" \
  -F "description=Standard statement of work" \
  -F 'variables=[{"placeholder":"CustomerName","name":"CustomerName","allowRichTextInjection":false,"order":0},{"placeholder":"ProjectName","name":"ProjectName","allowRichTextInjection":false,"order":1},{"placeholder":"BillRate","name":"BillRate","allowRichTextInjection":false,"order":2}]' \
  -F 'tags=["sales","legal"]'

Each entry in variables maps a placeholder in your document (for example {CustomerName}) to a named variable. Set allowRichTextInjection to true for fields that accept formatted content such as logos or rich blocks.

Example response​

On success the endpoint returns 201 Created. The new template row is returned under data.results.template:

{
  "data": {
    "results": {
      "template": {
        "id": "2b8f1c9e-4d3a-4a7c-9f21-6b0d5e9a1c34",
        "name": "SOW Template",
        "description": "Standard statement of work",
        "orgId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "createdBy": "f5e6d7c8-9a0b-4c1d-2e3f-4a5b6c7d8e9f",
        "isActive": true,
        "templateFolderId": null,
        "defaultFont": null,
        "fonts": null,
        "metadata": null,
        "projectspaceId": null,
        "createdOn": "2026-05-01T14:22:10.000Z",
        "updatedOn": "2026-05-01T14:22:10.000Z"
      }
    }
  }
}

Use the returned id as the TemplateId for generating documents or for Delete Template.

Common errors​

Error bodies vary by type: schema validation uses { "message", "type": "ValidationError", "data": { "errors": [...] } }, while file, storage, and plan-limit errors use { "message", ("error" | "type"), "data": { "explanation", "context" } }.

StatusWhenResponse body
401Missing or invalid API key/token, or the organization cannot be resolvedEmpty (status only)
403The key's role is not administrator, contributor, or userEmpty (status only)
400name or variables is missing, or variables/tags is not valid JSON (schema validation){ "message", "type": "ValidationError", "data": { "errors": [...] } }
400The uploaded file is invalid ("Improper File Upload"){ "message", "error", "data": { "explanation", "context" } }
400Your plan's template or storage limit is reached{ "message", "type", "data": { "explanation", "context" } }
503The storage service is temporarily unavailable{ "message", "error", "data": { "explanation", "context" } }
Last updated on