List document template fields

Access & visibility

Allow documents.ListDocumentTemplateFields on your API key.

Acting member required. Send Brigg-Act-As with an approved member account ID. The key supplies permissions; the member selects whose data is used.

The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.

Set up authentication · Choose permissions

Request fields

Send a JSON object with the following fields. Required fields must be included; omit optional fields you do not need.

template_idstringRequired

Use a template_id from the template catalogue; this is not the ID of a generated document. workspace.ListTemplates.

At least 1 character.

Inspect a template before editing it

Find the template_id with List templates. This is an editor's inspection operation: it requires the same template-management authority as the editing operations, even though it changes nothing.

items contains generated fields and their instructions. inserts contains referenced text documents; available: false means the reference cannot currently be resolved for this caller, and title is null. landmarks is the ordered list of placement points for new fields or inserts. Use the returned IDs, never an offset into HTML.

A template edit creates a new version. version_id identifies the version you inspected, not an optimistic-lock token accepted by the edit operations. Re-list after an edit before choosing another landmark. For placement at the end, no landmark is needed.

Response

Returns 200 OK with a JSON body.

This operation has no continuation cursor. An empty items array means no matching visible results were returned.

version_idstringRequired

Version of the template inspected by this call. Editing creates a new version; this is not a field ID or an edit precondition.

insertsarray of Template insertRequired

Text documents inserted into this template at their selected versions.

Item fields

field_idstringRequired

Stable field or insert ID returned by documents.ListDocumentTemplateFields. It stays the same when its instruction or layout is edited.

file_idstringRequired

Stable file ID returned by documents.CompleteUpload, documents.ListDocuments or a document creation operation. Use the same ID for downloads, attachments and supported file-based workflows. Do not use a filename or storage path.

layoutstringOptional

Display layout for the inserted text document.

Allowed: "one-column", "two-column", "compact".

titlenull or stringRequired

Referenced text document's filename, or null when unavailable to this caller.

availablebooleanRequired

Whether this referenced content is currently available to the caller.

Allowed: false, true.

landmarksarray of Template landmarkRequired

Stable placement points that can be used when adding a field or insert.

Item fields

landmark_idstringRequired

Stable insertion landmark from documents.ListDocumentTemplateFields. Use it with position before or after; position end needs no landmark.

kindstringRequired

Placement-point kind: blocks for fixed content, field for a generated field, or insert for an inserted text document.

itemsarray of Template fieldRequired

Editable fields in the selected template version; inserts and placement landmarks are returned separately. This operation has no cursor pagination.

Item fields

field_idstringRequired

Stable field or insert ID returned by documents.ListDocumentTemplateFields. It stays the same when its instruction or layout is edited.

instructionstringRequired

Instructions used to fill this field when generating a document from the template.

Errors & retries

This operation reads data. It needs no idempotency key and can be retried after a transient failure.

For rate limits, follow the server’s retry guidance and back off. See HTTP errors and safe retries and limits.

HTTP status	Code	What to do
400	`invalid_json`	Send a JSON object with Content-Type: application/json.
400	`invalid_input`	Check the request fields and types.
401	`invalid_key`	The workspace API key is missing, invalid or revoked.
403	`forbidden`	Check the key’s operation and resource grants. Supply Brigg-Act-As with a member authorized by the key’s delegation grant. The selected member must be active and approved by the credential. This selects whose private data is used; the credential supplies permissions. Private ownership and project boundaries still apply.
404	`not_found`	The requested operation or resource is not available to this credential.
429	`rate_limited`	Wait for Retry-After before retrying.
409	`signing_locked`	Pending or completed signing protects this template. Do not retry the edit unchanged.
400	`not_a_template`	Choose a document template from ListTemplates, not a generated document.
404	`no_active_version`	This template has no editable version. Open it in Brigg to complete its setup.

Next steps

Download OpenAPI · Versioning & retirement

JSON schemas

Use the complete schemas for validation or client generation.

Full request JSON schema

{
  "type": "object",
  "properties": {
    "template_id": {
      "type": "string",
      "minLength": 1,
      "description": "Use a template_id from the template catalogue; this is not the ID of a generated document. [workspace.ListTemplates](/developers/reference/workspace/ListTemplates)."
    }
  },
  "required": [
    "template_id"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "template_id": "c_template_proposal"
    }
  ]
}

Full response JSON schema

{
  "type": "object",
  "properties": {
    "version_id": {
      "type": "string",
      "description": "Version of the template inspected by this call. Editing creates a new version; this is not a field ID or an edit precondition."
    },
    "inserts": {
      "type": "array",
      "items": {
        "title": "Template insert",
        "type": "object",
        "properties": {
          "field_id": {
            "type": "string",
            "description": "Stable field or insert ID returned by documents.ListDocumentTemplateFields. It stays the same when its instruction or layout is edited."
          },
          "file_id": {
            "type": "string",
            "description": "Stable file ID returned by documents.CompleteUpload, documents.ListDocuments or a document creation operation. Use the same ID for downloads, attachments and supported file-based workflows. Do not use a filename or storage path."
          },
          "layout": {
            "type": "string",
            "enum": [
              "one-column",
              "two-column",
              "compact"
            ],
            "description": "Display layout for the inserted text document."
          },
          "title": {
            "anyOf": [
              {
                "type": "null",
                "description": "Referenced text document's filename, or null when unavailable to this caller."
              },
              {
                "type": "string",
                "description": "Referenced text document's filename, or null when unavailable to this caller."
              }
            ],
            "description": "Referenced text document's filename, or null when unavailable to this caller."
          },
          "available": {
            "type": "boolean",
            "enum": [
              false,
              true
            ],
            "description": "Whether this referenced content is currently available to the caller."
          }
        },
        "required": [
          "field_id",
          "file_id",
          "title",
          "available"
        ],
        "additionalProperties": false
      },
      "description": "Text documents inserted into this template at their selected versions."
    },
    "landmarks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "landmark_id": {
            "type": "string",
            "description": "Stable insertion landmark from documents.ListDocumentTemplateFields. Use it with position before or after; position end needs no landmark."
          },
          "kind": {
            "type": "string",
            "description": "Placement-point kind: blocks for fixed content, field for a generated field, or insert for an inserted text document."
          }
        },
        "required": [
          "landmark_id",
          "kind"
        ],
        "additionalProperties": false,
        "title": "Template landmark"
      },
      "description": "Stable placement points that can be used when adding a field or insert."
    },
    "items": {
      "type": "array",
      "items": {
        "title": "Template field",
        "type": "object",
        "properties": {
          "field_id": {
            "type": "string",
            "description": "Stable field or insert ID returned by documents.ListDocumentTemplateFields. It stays the same when its instruction or layout is edited.",
            "examples": [
              "project_summary"
            ]
          },
          "instruction": {
            "type": "string",
            "description": "Instructions used to fill this field when generating a document from the template.",
            "examples": [
              "Summarize the project objectives and agreed deliverables."
            ]
          }
        },
        "required": [
          "field_id",
          "instruction"
        ],
        "additionalProperties": false
      },
      "description": "Editable fields in the selected template version; inserts and placement landmarks are returned separately. This operation has no cursor pagination."
    }
  },
  "required": [
    "version_id",
    "items",
    "inserts",
    "landmarks"
  ],
  "additionalProperties": false,
  "examples": [
    {
      "version_id": "v_proposal_3",
      "items": [
        {
          "field_id": "project-summary",
          "instruction": "Summarize the project objectives and agreed deliverables."
        }
      ],
      "inserts": [
        {
          "field_id": "terms",
          "file_id": "f_terms",
          "layout": "one-column",
          "title": "Standard terms",
          "available": true
        }
      ],
      "landmarks": [
        {
          "landmark_id": "introduction",
          "kind": "blocks"
        },
        {
          "landmark_id": "project-summary",
          "kind": "field"
        },
        {
          "landmark_id": "terms",
          "kind": "insert"
        }
      ]
    }
  ]
}

Try the request

Use your API key in a server environment.

Requires BRIGG_ACT_AS: an approved member account ID.

All three collections are independent. Save the exact field and landmark IDs returned by your template.

Request

cURL

curl 'https://api.brigg.app/v1/operations/documents.ListDocumentTemplateFields' \
  -H "Authorization: Bearer $BRIGG_API_KEY" \
  -H 'Content-Type: application/json' \
  -H "Brigg-Act-As: $BRIGG_ACT_AS" \
  --data-raw '{
  "template_id": "c_template_proposal"
}'

TypeScript

const actAs = process.env.BRIGG_ACT_AS;
if (!actAs) throw new Error("Set BRIGG_ACT_AS to an approved member account ID.");

const response = await fetch("https://api.brigg.app/v1/operations/documents.ListDocumentTemplateFields", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRIGG_API_KEY}`,
    "Content-Type": "application/json",
    "Brigg-Act-As": actAs,
  },
  body: JSON.stringify({
    "template_id": "c_template_proposal"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${result.error} — ${result.message}`);
console.log(result);

Python

import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

payload = {
  "template_id": "c_template_proposal"
}
request = Request(
    "https://api.brigg.app/v1/operations/documents.ListDocumentTemplateFields",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['BRIGG_API_KEY']}",
        "Content-Type": "application/json",
        "Brigg-Act-As": os.environ["BRIGG_ACT_AS"],
    },
    method="POST",
)
try:
    with urlopen(request) as response:
        print(json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))
    raise

200 OK Response example

{
  "version_id": "v_proposal_3",
  "items": [
    {
      "field_id": "project-summary",
      "instruction": "Summarize the project objectives and agreed deliverables."
    }
  ],
  "inserts": [
    {
      "field_id": "terms",
      "file_id": "f_terms",
      "layout": "one-column",
      "title": "Standard terms",
      "available": true
    }
  ],
  "landmarks": [
    {
      "landmark_id": "introduction",
      "kind": "blocks"
    },
    {
      "landmark_id": "project-summary",
      "kind": "field"
    },
    {
      "landmark_id": "terms",
      "kind": "insert"
    }
  ]
}

Illustrative values, not a live response.