PDF Placeholders

Documenso can automatically detect placeholder text in your PDF documents and create fields at those locations. This allows you to prepare documents in your preferred editing tool (Word, Google Docs, etc.) with placeholders that become signature fields when uploaded.

How It Works

When you upload a PDF, Documenso scans for text matching the placeholder pattern {{...}}. Each placeholder can specify:

Field type - What kind of field to create (signature, name, email, etc.)
Recipient - Which signer the field belongs to (r1, r2, etc.)
Options - Additional settings like required, read-only, font size, etc.

The placeholder text is automatically hidden after fields are created, so your final document looks clean.

Placeholder Format

The basic format is:

{{FIELD_TYPE, RECIPIENT, option1=value1, option2=value2}}

Examples

Placeholder	Description
`{{signature, r1}}`	Signature field for recipient 1
`{{name, r1}}`	Name field for recipient 1
`{{email, r2}}`	Email field for recipient 2
`{{date, r1}}`	Date field for recipient 1
`{{text, r1, required=true}}`	Required text field for recipient 1
`{{initials, r1}}`	Initials field for recipient 1

Supported Field Types

The following field types are supported in placeholders:

Field Type	Placeholder Value
Signature	`signature`
Initials	`initials`
Name	`name`
Email	`email`
Date	`date`
Text	`text`
Number	`number`
Radio	`radio`
Checkbox	`checkbox`
Dropdown	`dropdown`

Field types are case-insensitive. {{ SIGNATURE, r1 }} and {{ signature, r1 }} are equivalent.

Recipient Identifiers

Recipients are identified using r1, r2, r3, etc. The number corresponds to the order in which recipients are created:

r1 - First recipient
r2 - Second recipient
r3 - Third recipient

When you upload a PDF with placeholders, Documenso will:

Create placeholder recipients for each unique identifier found (e.g., r1, r2)
You can then update these with real email addresses before sending

⚠️

Placeholders without a recipient identifier (e.g., {{ signature }} without r1) are reserved for API use and will not create fields during upload.

Field Options

You can customize fields by adding options after the recipient identifier:

Common Options

Option	Values	Description
`required`	`true`, `false`	Whether the field must be filled
`readOnly`	`true`, `false`	Whether the field is pre-filled and locked
`fontSize`	Number (e.g., `12`)	Font size in points
`textAlign`	`left`, `center`, `right`	Horizontal text alignment

Text Field Options

Option	Values	Description
`label`	Text	Label shown in the field
`placeholder`	Text	Placeholder text shown before signing
`text`	Text	Pre-filled text value
`characterLimit`	Number	Maximum characters allowed

Number Field Options

Option	Values	Description
`value`	Number	Pre-filled value
`minValue`	Number	Minimum allowed value
`maxValue`	Number	Maximum allowed value
`numberFormat`	Format string	Number display format

Examples with Options

{{text, r1, required=true, label=Company Name}}
{{number, r1, minValue=0, maxValue=100, value=50}}
{{name, r1, fontSize=14}}
{{text, r2, readOnly=true, text=Contract #12345}}

Signature and Free Signature fields do not support additional options beyond the field type and recipient.

Multiple Recipients Example

Here’s how a document might look with placeholders for two signers:

AGREEMENT

Party A Signature: {{signature, r1}}
Party A Name: {{name, r1}}
Party A Date: {{date, r1}}

Party B Signature: {{signature, r2}}
Party B Name: {{name, r2}}
Party B Date: {{date, r2}}

When uploaded, this creates:

3 fields assigned to recipient 1 (Party A)
3 fields assigned to recipient 2 (Party B)
2 placeholder recipients that you can update with real email addresses

Tips for Creating Documents

Use a readable font - Placeholders need to be readable by the PDF parser. Standard fonts like Arial, Helvetica, or Times New Roman work best.
Don’t split placeholders - Ensure the entire placeholder text {{...}} is on a single line and not broken across text boxes.
Size matters - The field will be sized to match the placeholder text width. Use spaces or longer placeholder text if you need wider fields.
Test with a draft - Upload your document as a draft first to verify fields are detected correctly before sending.

Placeholder detection happens automatically when you upload a PDF. You can review and adjust the created fields in the document editor before sending.

Troubleshooting

Placeholders Not Detected

Ensure placeholders use double curly braces: {{...}}
Check that the placeholder includes a recipient identifier (e.g., r1)
Verify the field type is spelled correctly
Try using a standard font in your source document

Wrong Field Position

The field is placed at the exact location of the placeholder text
If the position seems off, check that your PDF wasn’t scaled or reformatted when exported

Placeholder Text Still Visible

Placeholder text is covered with a white rectangle after field creation
If you see the text, try re-uploading the document

Document Fields Email Preferences