Generating Document Templates via the API

TrialGrid supports user-defined document templates that produce Word, Excel, PDF or text reports for a Draft or a Project. The same generation flow is available over the REST API: callers can list the templates available for a Draft or Project, kick off a generation, poll the resulting background task, and download the finished file from a pre-signed AWS S3 URL.

This page walks through the end-to-end flow with two worked examples — one in Python, one in Node.js — using a fictional Excel template called Project Form Inventory.

Behaviour and constraints 

API requests run as you. Generating a document via the API is identical to clicking Generate in the UI: the document is created in your user scope, with your permissions, and the resulting file is added to your Documents collection on the homepage. Anything you can run from the UI you can run from the API; anything you cannot run from the UI you cannot run from the API.
Generation is asynchronous. The generate endpoint enqueues a background task and returns immediately with a task_id. You poll the task's status endpoint until it reports completion (or failure).
Downloads come straight from AWS S3. When the task is complete the status response includes a download URL. This URL is a pre-signed S3 URL — the file is served directly from S3 and never proxied through TrialGrid's own servers. The URL is time-limited: it expires after a short period (typically one hour).
The file persists; the URL does not. If your download URL has expired but you still want the same file, simply call the status endpoint again — it will return a freshly-signed URL pointing at the same stored result. The file itself is preserved in your Documents collection until you delete it.
Project Tickets templates are not available via the API. Document templates with a scope of Project Tickets cannot currently be generated through this API. Use the TrialGrid UI to run those.
The generate endpoint is rate-limited. Each generation kicks off a background task and writes a file to storage, so the POST /document_templates/<id>/generate/ endpoint is capped at 60 requests per hour per user by default (in addition to the global API rate limit that applies to every endpoint). When the cap is reached the API returns 429 Too Many Requests with a Retry-After header indicating how long to wait before retrying. The list, status and download endpoints are not subject to this tighter cap.

Authentication 

Document template endpoints accept the same credentials as the rest of the TrialGrid API — see Authentication for full details. The two schemes are:

HTTP Basic Authentication — send your TrialGrid username and password in the standard Authorization header. The server expects a base64-encoded username:password value:

Authorization: Basic YWxpY2VAZXhhbXBsZS5jb206c2VjcmV0LXBhc3N3b3Jk

Token Authentication — obtain a token from the token endpoint (see Token Authentication for how to generate and revoke tokens) and send it in the Authorization header prefixed with Token:

Authorization: Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b

Either scheme works against every endpoint described on this page. The worked examples below show how to set both header styles in code.

Important

Do not send TrialGrid credentials when issuing the final GET against the signed S3 download URL — the signature embedded in the URL is what authorises that request, and adding an unrelated Authorization header can cause the download to fail.

Setting the scene — our worked example 

Imagine your administrator has already created the following Excel-type template in TrialGrid:

Attribute	Value
Name	Project Form Inventory
Type	Excel 2003/2004 SpreadsheetML with conversion to XLSX
Scope	Project Home
Settings	`include_inactive_forms` (boolean, default `false`) — include forms marked inactive `sort_by` (choice: `FormName` or `OID`, default `FormName`) — how to sort the form list `report_title` (text, default `Form Inventory`) — heading shown at the top of the spreadsheet

Across the worked examples below we will:

Discover the template's id and the names of its settings.
Submit a generation request for a specific Project, overriding include_inactive_forms to true and sort_by to OID.
Poll the resulting background task until it completes.
Download the finished .xlsx file from S3.

Endpoint summary 

Every endpoint below is versioned with v1 or v2; the examples use v2 but there is no difference.

Method	Path	Purpose
`GET`	`/api/v2/drafts/{draft_id}/document_templates/`	List `Draft Home`-scoped templates available for that draft
`GET`	`/api/v2/projects/{project_id}/document_templates/`	List `Project Home`-scoped templates available for that project
`POST`	`/api/v2/document_templates/{annotate_def_id}/generate/`	Start a background generation, returns a `task_id`
`GET`	`/api/v2/document_template_tasks/{task_id}/`	Poll task status; when complete includes a signed S3 download URL

1. Discover the template 

Before you can generate anything you need the template's id and the exact names of its settings. List the templates available for the Project (or Draft) you intend to report on:

GET /api/v2/projects/123/document_templates/
Authorization: Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b

(or, equivalently, Authorization: Basic <base64-encoded username:password> — see the Authentication section above.)

Response:

{
    "results": [
        {
            "id": 42,
            "name": "Project Form Inventory",
            "description": "All forms across all drafts in this project.",
            "template_type": "Excel 2003/2004 SpreadsheetML with conversion to XLSX",
            "template_scope": "Project Home",
            "settings": [
                {
                    "name": "include_inactive_forms",
                    "display_name": "Include inactive forms?",
                    "description": "When checked, inactive forms are included in the output.",
                    "setting_type": "boolean",
                    "default_value": "false",
                    "setting_choices": null,
                    "display_order": 0
                },
                {
                    "name": "sort_by",
                    "display_name": "Sort forms by",
                    "description": "Order the form rows in the spreadsheet.",
                    "setting_type": "choice",
                    "default_value": "FormName",
                    "setting_choices": ["FormName", "OID"],
                    "display_order": 1
                },
                {
                    "name": "report_title",
                    "display_name": "Report title",
                    "description": "Heading shown at the top of the spreadsheet.",
                    "setting_type": "text",
                    "default_value": "Form Inventory",
                    "setting_choices": null,
                    "display_order": 2
                }
            ]
        }
    ]
}

The discovery endpoint only lists templates that are active and that match the requested scope. Templates outside your URL are excluded.

Note

template_type and template_scope are returned as the system's stored display strings (e.g. "Excel 2003/2004 SpreadsheetML with conversion to XLSX"). Treat them as opaque labels — match them by equality, don't parse them — they may be reworded between releases.

2. Start a generation 

POST to the generate endpoint, supplying the scope-specific id (project_id for a Project Home template, draft_id for a Draft Home template) and a settings object whose keys match the setting names from the discovery response. Any setting you omit falls back to its default.

POST /api/v2/document_templates/42/generate/
Authorization: Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b
Content-Type: application/json

{
    "project_id": 123,
    "settings": {
        "include_inactive_forms": true,
        "sort_by": "OID",
        "report_title": "Q2 form audit"
    }
}

Response (HTTP 202 Accepted):

{
    "task_id": 9876,
    "status_url": "/api/v2/document_template_tasks/9876/"
}

3. Poll the task 

The generation runs as a background task. Poll the status_url until state is C (complete) or F (failed):

GET /api/v2/document_template_tasks/9876/
Authorization: Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b

While the task is still running the response will look like (download is null until the task finishes successfully):

{
    "task_id": 9876,
    "name": "Generate Annotate",
    "task_type": "generate_annotate",
    "state": "R",
    "state_display": "Running",
    "progress_pct": 40,
    "state_message": "Generating Excel rows...",
    "created": "2026-05-06T10:00:00+00:00",
    "updated": "2026-05-06T10:00:08+00:00",
    "download": null
}

Once the task completes successfully the download block is populated:

{
    "task_id": 9876,
    "name": "Generate Annotate",
    "task_type": "generate_annotate",
    "state": "C",
    "state_display": "Complete",
    "progress_pct": 100,
    "state_message": "Generation complete",
    "created": "2026-05-06T10:00:00+00:00",
    "updated": "2026-05-06T10:00:23+00:00",
    "download": {
        "url": "https://s3.amazonaws.com/.../annotate.xlsx?X-Amz-Signature=...",
        "filename": "Project Form Inventory.xlsx",
        "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "size_in_bytes": 18234,
        "expires_in_seconds": 3600
    }
}

State codes are: P Pending, R Running, C Complete, F Failed, X Cancelled.

A reasonable poll cadence is every 2 – 5 seconds; large reports can take several minutes to generate. Note that progress_pct value may not change smoothly on each poll request, do not assume the task has stalled because this value has not changed between poll requests.

4. Download the result 

The download.url is a pre-signed AWS S3 URL. Issue an HTTP GET to it (no TrialGrid auth header required — the signature in the URL is what authorises the download) and stream the body to disk. The S3 response sets the correct Content-Type and Content-Disposition: attachment headers based on the template type.

The URL is valid for download.expires_in_seconds seconds (typically 3600). If it expires before you finish, simply call the status endpoint again — every call generates a fresh signed URL pointing at the same stored file. The file itself remains in your Documents collection until you delete it.

Worked example — Python 

This example uses requests. Install with pip install requests. Edit the constants at the top for your environment, or set the matching EXAMPLE_* environment variables.

# Copyright TrialGrid Limited

"""End-to-end example of generating a document template through the TrialGrid API.

This script:

1. Looks up a Project Home document template by name.
2. Submits a generation request, overriding three of its settings.
3. Polls the resulting background task until completion (or failure).
4. Downloads the finished file straight from the pre-signed S3 URL.

Edit the ``Configuration`` constants below for your environment, or set the matching
``EXAMPLE_*`` environment variables (the test suite uses the env-var path).
"""

import base64
import os
import time
from pathlib import Path

import requests

# ---- Configuration ----------------------------------------------------------------------
# Edit these constants for your environment, or set the matching environment variables.

BASE_URL = os.environ.get("EXAMPLE_BASE_URL", "https://www.trialgrid.io/api/v2")
PROJECT_ID = int(os.environ.get("EXAMPLE_PROJECT_ID", "123"))
TEMPLATE_NAME = os.environ.get("EXAMPLE_TEMPLATE_NAME", "Project Form Inventory")
OUTPUT_DIR = Path(os.environ.get("EXAMPLE_OUTPUT_DIR", ""))

# ---- Authentication: pick ONE of the two styles below -----------------------------------
# (a) HTTP Basic Authentication — username + password.
USERNAME = os.environ.get("EXAMPLE_USERNAME", "alice@example.com")
PASSWORD = os.environ.get("EXAMPLE_PASSWORD", "<your password>")
AUTH_HEADERS = {
    "Authorization": "Basic " + base64.b64encode(f"{USERNAME}:{PASSWORD}".encode()).decode(),
}
# (b) Token Authentication — see https://www.trialgrid.io/docs/api.html#token-authentication
#     for how to generate or revoke tokens.
# AUTH_HEADERS = {"Authorization": "Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b"}
# -----------------------------------------------------------------------------------------

POLL_SECONDS = float(os.environ.get("EXAMPLE_POLL_SECONDS", "3"))
TIMEOUT_SECONDS = int(os.environ.get("EXAMPLE_TIMEOUT_SECONDS", "600"))


def find_template(project_id: int, name: str) -> dict:
    """Look up a Project Home template by name and return its definition."""
    resp = requests.get(
        f"{BASE_URL}/projects/{project_id}/document_templates/",
        headers=AUTH_HEADERS,
        timeout=30,
    )
    resp.raise_for_status()
    for template in resp.json()["results"]:
        if template["name"] == name:
            return template
    raise LookupError(f"No template named {name!r} on project {project_id}")


def start_generation(template_id: int, project_id: int, settings: dict) -> int:
    """Kick off a generation. Returns the task_id."""
    resp = requests.post(
        f"{BASE_URL}/document_templates/{template_id}/generate/",
        json={"project_id": project_id, "settings": settings},
        headers=AUTH_HEADERS,
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["task_id"]


def wait_for_completion(
    task_id: int, poll_seconds: float = POLL_SECONDS, timeout_seconds: int = TIMEOUT_SECONDS
) -> dict:
    """Poll until the task is Complete or Failed. Returns the final status payload."""
    deadline = time.monotonic() + timeout_seconds
    while True:
        resp = requests.get(
            f"{BASE_URL}/document_template_tasks/{task_id}/",
            headers=AUTH_HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        status = resp.json()
        state = status["state"]
        if state == "C":
            return status
        if state == "F":
            raise RuntimeError(f"Generation failed: {status['state_message']}")
        if time.monotonic() > deadline:
            raise TimeoutError(f"Task {task_id} did not complete in {timeout_seconds}s")
        print(f"  state={state} progress={status['progress_pct']}% — {status['state_message']}")
        time.sleep(poll_seconds)


def download(status: dict, save_to: Path) -> None:
    """Stream the file to disk from the signed S3 URL.

    The S3 URL is time-limited (see ``download.expires_in_seconds``). If it has expired,
    re-poll ``document_template_tasks/{task_id}/`` to get a fresh URL for the same file.
    """
    download_info = status["download"]
    # Note: do NOT send AUTH_HEADERS here — the signed URL authorises the request, and
    # adding an unrelated Authorization header can cause S3 to reject the download.
    with requests.get(download_info["url"], stream=True, timeout=60) as resp:
        resp.raise_for_status()
        with save_to.open("wb") as fh:
            for chunk in resp.iter_content(chunk_size=64 * 1024):
                fh.write(chunk)
    print(f"Saved {download_info['size_in_bytes']} bytes to {save_to}")


if __name__ == "__main__":
    template = find_template(PROJECT_ID, TEMPLATE_NAME)
    print(f"Found template id={template['id']} ({template['template_type']})")

    task_id = start_generation(
        template_id=template["id"],
        project_id=PROJECT_ID,
        settings={
            "include_inactive_forms": True,
            "sort_by": "OID",
            "report_title": "Q2 form audit",
        },
    )
    print(f"Started task {task_id}")

    final = wait_for_completion(task_id)
    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
    download(final, OUTPUT_DIR / final["download"]["filename"])

Worked example — Node.js 

This example uses Node.js 18+ (which has fetch built in) and the standard library only.

// Copyright TrialGrid Limited
//
// End-to-end example of generating a document template through the TrialGrid API.
//
// This script:
//  1. Looks up a Project Home document template by name.
//  2. Submits a generation request, overriding three of its settings.
//  3. Polls the resulting background task until completion (or failure).
//  4. Downloads the finished file straight from the pre-signed S3 URL.
//
// Edit the Configuration constants below for your environment, or set the matching
// EXAMPLE_* environment variables (the test suite uses the env-var path).
//
// Requires Node.js 18+ for built-in fetch.

import { writeFile, mkdir } from "node:fs/promises";
import { Buffer } from "node:buffer";
import { join } from "node:path";

// ---- Configuration ----------------------------------------------------------------------
// Edit these constants for your environment, or set the matching environment variables.

const BASE_URL = process.env.EXAMPLE_BASE_URL ?? "https://www.trialgrid.io/api/v2";
const PROJECT_ID = parseInt(process.env.EXAMPLE_PROJECT_ID ?? "123", 10);
const TEMPLATE_NAME = process.env.EXAMPLE_TEMPLATE_NAME ?? "Project Form Inventory";
const OUTPUT_DIR = process.env.EXAMPLE_OUTPUT_DIR ?? ".";

// ---- Authentication: pick ONE of the two styles below -----------------------------------
// (a) HTTP Basic Authentication — username + password.
const USERNAME = process.env.EXAMPLE_USERNAME ?? "alice@example.com";
const PASSWORD = process.env.EXAMPLE_PASSWORD ?? "<your password>";
const AUTH_HEADERS = {
    Authorization: "Basic " + Buffer.from(`${USERNAME}:${PASSWORD}`).toString("base64"),
};
// (b) Token Authentication — see https://www.trialgrid.io/docs/api.html#token-authentication
//     for how to generate or revoke tokens.
// const AUTH_HEADERS = { Authorization: "Token fa2ae7f1c766ddea1c8b4ff14773de33569d399b" };
// -----------------------------------------------------------------------------------------

const POLL_MS = parseInt(process.env.EXAMPLE_POLL_MS ?? "3000", 10);
const TIMEOUT_MS = parseInt(process.env.EXAMPLE_TIMEOUT_MS ?? "600000", 10);

async function findTemplate(projectId, name) {
    const resp = await fetch(`${BASE_URL}/projects/${projectId}/document_templates/`, {
        headers: AUTH_HEADERS,
    });
    if (!resp.ok) throw new Error(`Discovery failed: ${resp.status} ${await resp.text()}`);
    const body = await resp.json();
    const template = body.results.find((t) => t.name === name);
    if (!template) throw new Error(`No template named "${name}" on project ${projectId}`);
    return template;
}

async function startGeneration(templateId, projectId, settings) {
    const resp = await fetch(`${BASE_URL}/document_templates/${templateId}/generate/`, {
        method: "POST",
        headers: { ...AUTH_HEADERS, "Content-Type": "application/json" },
        body: JSON.stringify({ project_id: projectId, settings }),
    });
    if (!resp.ok) throw new Error(`Generate failed: ${resp.status} ${await resp.text()}`);
    const body = await resp.json();
    return body.task_id;
}

function sleep(ms) {
    return new Promise((resolve) => setTimeout(resolve, ms));
}

async function waitForCompletion(taskId, { pollMs = POLL_MS, timeoutMs = TIMEOUT_MS } = {}) {
    const deadline = Date.now() + timeoutMs;
    while (true) {
        const resp = await fetch(`${BASE_URL}/document_template_tasks/${taskId}/`, {
            headers: AUTH_HEADERS,
        });
        if (!resp.ok) throw new Error(`Status failed: ${resp.status} ${await resp.text()}`);
        const status = await resp.json();
        if (status.state === "C") return status;
        if (status.state === "F") throw new Error(`Generation failed: ${status.state_message}`);
        if (Date.now() > deadline) throw new Error(`Task ${taskId} timed out`);
        console.log(
            `  state=${status.state} progress=${status.progress_pct}% — ${status.state_message}`,
        );
        await sleep(pollMs);
    }
}

async function download(status, savePath) {
    // The S3 URL is time-limited (see download.expires_in_seconds). If it has expired,
    // re-poll document_template_tasks/{taskId}/ to get a fresh URL for the same file.
    const { url, size_in_bytes } = status.download;
    // Note: do NOT send AUTH_HEADERS here — the signed URL authorises the request, and
    // adding an unrelated Authorization header can cause S3 to reject the download.
    const resp = await fetch(url);
    if (!resp.ok) throw new Error(`Download failed: ${resp.status} ${await resp.text()}`);
    const buffer = Buffer.from(await resp.arrayBuffer());
    await writeFile(savePath, buffer);
    console.log(`Saved ${size_in_bytes} bytes to ${savePath}`);
}

(async () => {
    const template = await findTemplate(PROJECT_ID, TEMPLATE_NAME);
    console.log(`Found template id=${template.id} (${template.template_type})`);

    const taskId = await startGeneration(template.id, PROJECT_ID, {
        include_inactive_forms: true,
        sort_by: "OID",
        report_title: "Q2 form audit",
    });
    console.log(`Started task ${taskId}`);

    const final = await waitForCompletion(taskId);
    await mkdir(OUTPUT_DIR, { recursive: true });
    await download(final, join(OUTPUT_DIR, final.download.filename));
})().catch((err) => {
    console.error(err);
    process.exit(1);
});

Error responses 

Status	Meaning
`400`	The request body was malformed — for example a missing `draft_id` / `project_id`, an invalid setting value, or a draft / project that doesn't belong to the template's URL.
`401`	Missing or invalid credentials.
`403`	You do not have permission to view the URL the template belongs to, or the project the draft belongs to.
`404`	The template, draft, project, or task does not exist (or, for the status endpoint, the task does not belong to you).
`405`	The template's scope is Project Tickets, which is not currently supported via the API.