From 03e2e4f171b3d35f7464294d149724aa19456379 Mon Sep 17 00:00:00 2001
From: Ephraim Duncan <55143799+ephraimduncan@users.noreply.github.com>
Date: Thu, 5 Mar 2026 02:58:29 +0000
Subject: [PATCH] docs: clarify placeholder support is envelope.* only (#2560)
---
apps/docs/content/docs/developers/api/documents.mdx | 4 ++++
apps/docs/content/docs/developers/api/fields.mdx | 4 ++++
apps/docs/content/docs/developers/api/templates.mdx | 4 ++++
3 files changed, 12 insertions(+)
diff --git a/apps/docs/content/docs/developers/api/documents.mdx b/apps/docs/content/docs/developers/api/documents.mdx
index 05433cc3c..a21a2740b 100644
--- a/apps/docs/content/docs/developers/api/documents.mdx
+++ b/apps/docs/content/docs/developers/api/documents.mdx
@@ -269,6 +269,10 @@ Returns the full document object including recipients, fields, and envelope item
Create a new document with optional recipients and fields in a single request.
+
+ This endpoint automatically scans uploaded PDFs for [placeholder patterns](/docs/users/documents/advanced/pdf-placeholders) like `{"{{signature, r1}}"}` and creates fields at those locations.
+
+
```
POST /envelope/create
Content-Type: multipart/form-data
diff --git a/apps/docs/content/docs/developers/api/fields.mdx b/apps/docs/content/docs/developers/api/fields.mdx
index 6d55fb2d7..71f680a62 100644
--- a/apps/docs/content/docs/developers/api/fields.mdx
+++ b/apps/docs/content/docs/developers/api/fields.mdx
@@ -473,6 +473,10 @@ Instead of specifying exact coordinates, you can position fields using placehold
This approach is useful when generating PDFs programmatically or using templates with consistent layouts.
+
+ Placeholder support is only available in `envelope.*` endpoints. `POST /template/use` does not support placeholder parsing.
+
+
See the [PDF Placeholders](/docs/users/documents/advanced/pdf-placeholders) guide for the full placeholder format reference, including supported field types, recipient identifiers, and field options.
---
diff --git a/apps/docs/content/docs/developers/api/templates.mdx b/apps/docs/content/docs/developers/api/templates.mdx
index 91bdf5a07..8f5c5b667 100644
--- a/apps/docs/content/docs/developers/api/templates.mdx
+++ b/apps/docs/content/docs/developers/api/templates.mdx
@@ -240,6 +240,10 @@ Returns the full template object including recipients, fields, and metadata.
Create a new document using a template. This is the primary way to use templates programmatically.
+
+ This endpoint does not support [PDF placeholder parsing](/docs/users/documents/advanced/pdf-placeholders). Use `POST /envelope/create` for placeholder-based field positioning.
+
+
```
POST /template/use