---
title: "Effortlessly Position Form Fields in eSign Requests with API"
description: "This guide explores how to use the BoldSign API to dynamically add form fields to eSignature requests to enhance the overall signing experience for users."
url: "https://boldsign.com/blogs/how-to-dynamically-position-form-fields-in-esignature-requests-using-api/"
---

1. [Blog](https://boldsign.com/blogs.md)
2. [API](https://boldsign.com/category/api.md)

# How to Dynamically Position Form Fields in eSignature Requests Using API

[Gopinath Kannusamy](https://boldsign.com/author/gopinath-kannusamy/) May 13, 2024 Updated March 26, 2026 4 min read

When preparing documents for electronic signatures, knowing the exact coordinates (X and Y values) for placing form fields can be challenging. Traditional methods often require manual calculations, which are time-consuming and prone to errors. A more systematic and efficient approach involves using text tags within the document. In this blog post, we’ll explore using BoldSign text tags via the API to dynamically position form fields in eSignature requests.

## Using Text Tags with BoldSign

1. **Document Preparation:** While generating the document, you insert specific text tags where you want form fields to appear. The details of this syntax will be explained in the next paragraph.
2. **Tag Recognition and Replacement:** Once the document is uploaded into BoldSign, the system scans the document for these text tags. It then automatically replaces each tag with the corresponding form field.

This ensures that the form fields are precisely placed where the tags were located in the document, thus maintaining the intended layout and design.

## Syntax of BoldSign text tags

BoldSign [text tags](https://boldsign.com/blogs/automatically-add-document-fields-using-text-tags.md) follow a specific syntax, consisting of components separated by a pipe “|” symbol and encapsulated within double curly braces {{ }}. Let’s break down the components:

- **Field type:** Specifies the type of form field, such as text, signature, or initials.
- **Signer index:** Represents the index of signers to whom the form fields are assigned.
- **Required:** Indicates whether the form field is mandatory.
- **Field label:** Serves as a placeholder for text fields.
- **Field ID:** A unique identifier for the form field.

### Example text tag

Let’s consider an example to illustrate the usage of BoldSign text tags.

| |
| - |
| {{text\|1\|\*\|Enter name\|field_1}} |

In this example:

- The field type is text.
- The signer index is 1.
- Required is indicated by the asterisk.
- The field label is “Enter Name.”
- The field ID is “field_1.”

## Enabling text tags via the API

When sending a document to a signer via the BoldSign API, developers can enable text tags by setting the ***UseTextTags*** property to true. This allows the API to recognize and interpret text tags within the document, facilitating dynamic form field positioning.

```
curl -X 'POST' \
  'https://api.boldsign.com/v1/document/send' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {your API key}' \
  -H 'Content-Type: multipart/form-data' \
  -F 'Title="Sample Document"' \
  -F 'UseTextTags=true' \
  -F 'Signers={
  "name": "hanky",
  "emailAddress": "hankyWhites@boldsign.dev",
  "signerType": "Signer",
  "signerRole": "Signer",
  "locale": "EN"
}' \
  -F 'Files=@{your file}'
```

## Supported fields

The following form fields are supported in text tag creation.

| S. No | Form fields | Tags |
| - | - | - |
| 1 | Text box | text |
| 2 | Signature | sign |
| 3 | Initials | init |
| 4 | Date signed | date |
| 5 | Editable date | editdate |
| 6 | Title | title |
| 7 | Company | company |

If you want to add form fields other than these with tags, you can use definition tags.

## Definition tags

When text tags contain numerous directives, they may become lengthy, complicating the specification of fields with small bounds on the document. To address this challenge, you can use definition tags. Definition tags provide a structured approach to managing complex text tags, allowing developers to encapsulate field configurations for improved readability and efficiency. The fields that are not supported by texts tags are supported in the definition tags.

### Properties of definition tags

Definition tags consist of several properties, each serving a specific purpose in defining the attributes of a form field. Let’s examine the components and their descriptions:

- **DefinitionId**: An identifier used to match the text tag definition provided in the document.
- **Type**: Specifies the form field type, such as text, signature, or date.
- **SignerIndex**: Indicates the index of the signer to whom the field needs to be assigned.
- **IsRequired**: A Boolean value indicating whether the field is required or optional.
- **FieldId**: A unique identifier assigned to the form field.
- **Size**: Specifies the size of the text tag.
- **Font**: Defines the font to be used for the form field.
- **Validation**: Specifies validation rules for the content of the form field.
- **Placeholder**: Text displayed as placeholders in the text fields.
- **DateFormat**: Specifies the date format for date and time fields.
- **RadioGroupName**: Group name for radio button fields.
- **PageNumber**: Indicates the page number where the form field should be placed.

## Usage syntax for definitions

To incorporate definitions into text tags, usage begins with “@” followed by the definition ID from **_TextTagDefinitions_** provided in the send request. Here’s a sample syntax using the definition ID “tag1.”

| |
| - |
| `{{@tag1}}` |

Following is an annotated version of the sample send document API request with the **_UseTextTags_** property enabled and ***TextTagDefinitions***.

```
curl -X POST \
  'https://api.boldsign.com/v1/document/send' \
  -H 'X-API-KEY: {your-api-key}' \
  -F 'Title=Sent from API Curl' \
  -F 'Message=This is document message sent from API Curl' \
  -F 'Signers[0][Name]=Henry' \
  -F 'Signers[0][EmailAddress]=henry@boldsign.dev' \
  -F 'Signers[0][SignerType]=Signer' \
  -F 'UseTextTags=true' \
  -F 'TextTagDefinitions[0][DefinitionId]=tag1' \
  -F 'TextTagDefinitions[0][Type]=TextBox' \
  -F 'TextTagDefinitions[0][SignerIndex]=1' \
  -F 'TextTagDefinitions[0][IsRequired]=true' \
  -F 'TextTagDefinitions[0][FieldLabel]=Email field' \
  -F 'TextTagDefinitions[0][FieldId]=axq12367' \
  -F 'TextTagDefinitions[0][Size][Width]=500' \
  -F 'TextTagDefinitions[0][Size][Height]=50' \
  -F 'TextTagDefinitions[0][Placeholder]=Enter your email here' \
  -F 'TextTagDefinitions[0][PageNumber]=1' \
  -F 'TextTagDefinitions[0][Font][Name]=Helvetica' \
  -F 'TextTagDefinitions[0][Font][Size]=20' \
  -F 'TextTagDefinitions[0][Font][Style]=Italic' \
  -F 'TextTagDefinitions[0][Validation][Type]=Email' \
  -F 'Files=@{your file};type=application/pdf'
```

## Conclusion

BoldSign text tags offer a dynamic and efficient approach to embedding form fields into documents, enhancing the overall signing experience for users. By leveraging the BoldSign API and integrating text tags into your workflow, you can customize document layouts, streamline signing processes, and meet the specific needs of your organization or application. For further guidance and examples, refer to our [demo sample](https://demos.boldsign.com/text-tags/) and explore the [text tag documentation](https://developers.boldsign.com/text-tags/introduction/?region=us). Start mastering dynamic form field positioning with the BoldSign API today!

To experience BoldSign’s benefits, begin your [30-day BoldSign free trial](https://account.boldsign.com/signup?planId=1018\&utm_source=boldsignblogs\&utm_medium=redirect\&utm_campaign=boldsign) now. Please feel free to comment below; we truly value your opinions. If you have any questions or would like more information about our services, please [schedule a demo](https://boldsign.com/request-demo.md) or get in touch with our support team through our [support portal](https://support.boldsign.com/support/tickets/create).

Topics [API integration](https://boldsign.com/blogs/tag/api-integration.md)[Form fields](https://boldsign.com/blogs/tag/form-fields.md)

## Sign documents 3x faster

Send, sign and manage documents securely and efficiently.

[Try it today](https://account.boldsign.com/signup?planId=1018\&utm_source=boldsignblogs\&utm_medium=redirect\&utm_campaign=boldsign)

## Gopinath Kannusamy

Gopinath is a passionate software developer with 2 years of experience at BoldSign. He is an avid writer and enjoys sharing his insights on technology and development. In his free time, he enjoys exploring new technologies and learning new things. Connect with him on [LinkedIn](https://www.linkedin.com/in/gopinath-kannusamy-b7b84517a/).

[More posts by Gopinath Kannusamy](https://boldsign.com/author/gopinath-kannusamy/)

## Related posts

- [API](https://boldsign.com/category/api.md) September 18, 2026 8 min read

  ## [How the PDF Coordinate System Affects eSignature Fields](https://boldsign.com/blogs/pdf-coordinate-system-esignature-field-placement.md)

  Understand the PDF coordinate system and prevent misplaced eSignature fields. Fix point-to-pixel conversion, page rotation, font, and API placement issues.

- [API](https://boldsign.com/category/api.md) April 27, 2026 8 min read

  ## [Collect Signer Information Using Image Form Fields via API](https://boldsign.com/blogs/image-form-fields-esignature-api.md)

  Learn how to use the BoldSign API to add image form fields and collect signer information by uploading IDs, receipts, or photos during the signing process.

- [API](https://boldsign.com/category/api.md) April 14, 2026 9 min read

  ## [BoldSign Formula Fields: Automate Calculations in eSignature Documents](https://boldsign.com/blogs/automate-formula-fields-esignature-api.md)

  Use BoldSign API formula fields to automate document calculations like totals, taxes, and dates. Improve accuracy and streamline eSignature workflows.

Get started

## Sign up for your free trial today!

[Start free trial](https://account.boldsign.com/signup?planId=1018)

- 30-day free trial
- No credit card required

*Picture: A completed employment contract: signed by John Doe on 11/03/2026, all parties have signed*
