Start a document from a template

POST /api/v1/documents

Fills it with values or form answers. Needs the documents permission.

Permission	documents
MCP tool	start_document
Retries	Safe with an Idempotency-Key

Request

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	Makes a retried call safe: the same key returns the first result instead of creating or sending again. Matches ^[A-Za-z0-9_-]{8,100}$.

Body

Give merge_values or answers, not both.

Field	Type	Required	Description
template_id	string (uuid)	Yes	—
title	string	No	1–255 characters.
merge_values	object of string	No	Fill-in values by key.
answers	object	No	Answers to the template's intake form, by question key.

Responses

Status	Meaning
201	The new document.
400	The input is invalid.
401	No key, or a key that is unknown, expired or revoked, or whose creator is no longer an owner or admin.
403	The key lacks the permission, or it is an API key and the workspace isn't on Teams & Platform.
404	Not found in the key's workspace (a key works only in the workspace it was made in; get_workspace says which).
409	The request is in a state that doesn't allow this, or the Idempotency-Key was used for something else.
429	More than 120 calls a minute through this key, more than 2000 from one network address (for IPv6, its /56 block) across all keys, or a limit on sending reached: the key's daily sends, the plan's or a recipient's daily requests, or the workspace's waiting approvals.

Errors share one shape, { "message": "…" }: see Errors and rate limits.

201 body

Field	Type	Description
id	string (uuid)	—
title	string	—
source_type	string	—
status	string	—
draft_revision	integer	—
fill_ins	array of objects	—
fill_ins[].key	string	—
fill_ins[].label	string	—
fill_ins[].value	string or null	—
team_access	string	—
created_at	string (date-time) or null	—
updated_at	string (date-time) or null	—

Example

{
  "id": "8a1f5c2e-3b4d-4e6f-9a7b-1c2d3e4f5a6b",
  "title": "Mutual NDA — Acme",
  "source_type": "editor",
  "status": "draft",
  "draft_revision": 1,
  "fill_ins": [
    {
      "key": "client_name",
      "label": "Client name",
      "value": "Acme Inc."
    },
    {
      "key": "effective_date",
      "label": "Effective date",
      "value": "November 3, 2026"
    }
  ],
  "team_access": "view",
  "created_at": "2026-11-03T16:20:00.000Z",
  "updated_at": "2026-11-03T16:20:00.000Z"
}

Examples

curl

curl -X POST https://tryjustdocs.com/api/v1/documents \
  -H "Authorization: Bearer $JUSTDOCS_API_KEY" \
  -H "Idempotency-Key: deal-4821-start-document" \
  -H "Content-Type: application/json" \
  -d '{
  "template_id": "5d0f8c3a-6b1e-4f2a-9c7d-3e8b1a2f4c6d",
  "title": "Mutual NDA — Acme",
  "merge_values": {
    "client_name": "Acme Inc.",
    "effective_date": "November 3, 2026"
  }
}'

Node.js

const response = await fetch("https://tryjustdocs.com/api/v1/documents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JUSTDOCS_API_KEY}`,
    "Idempotency-Key": "deal-4821-start-document",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    template_id: "5d0f8c3a-6b1e-4f2a-9c7d-3e8b1a2f4c6d",
    title: "Mutual NDA — Acme",
    merge_values: {
      client_name: "Acme Inc.",
      effective_date: "November 3, 2026"
    }
  }),
});
if (!response.ok) throw new Error((await response.json()).message);
const result = await response.json();

Python

import os
import requests

response = requests.post(
    "https://tryjustdocs.com/api/v1/documents",
    headers={"Authorization": f"Bearer {os.environ['JUSTDOCS_API_KEY']}", "Idempotency-Key": "deal-4821-start-document"},
    json={
        "template_id": "5d0f8c3a-6b1e-4f2a-9c7d-3e8b1a2f4c6d",
        "title": "Mutual NDA — Acme",
        "merge_values": {
            "client_name": "Acme Inc.",
            "effective_date": "November 3, 2026",
        },
    },
    timeout=30,
)
response.raise_for_status()
result = response.json()