Advanced usage

The definition tags can be used to handle long text tags. When text tags contain many directives, they may become very long, making it difficult to specify fields with small bounds on the document. To solve this, the definition is introduced.

Following is the list of definitions that can be added to the tags with descriptions.

DefinitionIdstringRequired	The ID will be used to match the text tag definition provided in the document.
TypestringRequired	The form field type.
SignerIndexintegerRequired	Index of the signer to which the field needs to be assigned.
IsRequiredboolean	Indicates whether the field is required or not.
FieldIdstring	Unique field Ids are to be set for all the individual fields.
Sizejson	Indicates the size of the text tag.
Fontjson	Font to be set for the form field.
Validationjson	Validation for the content present in the textbox field type.
Placeholderstring	Placeholder to be displayed in the textbox field.
DateFormatstring	Date format to be set in the date time field.
RadioGroupNamestring	Group name to be set in the radio button fields.
PageNumber integerRequired	Page number in which the form field should be placed.

Usage syntax

Tag usage starts with @ and proceeds with the definition Id from TextTagDefinitions provided in the send request.

The sample for the definition Id set as tag1 is given below:

{{@tag1}}

Note: If the definition Id provided in the document is not present in TextTagDefinitions, then the document will not be sent, and the reason for this will be sent to the webhook endpoint configured.

Substitution and override

When there is a use for different field labels and field ids with the same set of tags, the definition values can be overridden in the text tags with label and field ID.

{{@tag1:Please enter your first name|firstName}}

Size

The size of the field can be configured using the Size property in definition tags. This will override the size of the definition tag, which is set in the document.

{
    "width": 0,
    "height": 0
}

Font

Different aspects of fonts, like the font name, font size, and font style, can be configured in the definition tags. This provides further customization to the fields, and this helps in differentiating different fields when filling.

Supported fonts are given as follows:

Helvetica
Courier
TimesRoman

Following are the supported font styles.

Regular
Bold
Italic
Underline

{
    "name": "Helvetica",
    "color": "string",
    "size": 0,
    "style": "Regular",
    "lineHeight": 0
  }

Note: Helvetica is the default font type for all the fields.

Validation

Even though the textbox field accepts any value, you can control and define what values are accepted by using validations. The textbox fields support a number of built-in form validations as well as your own custom Regex validation to allow only certain characters or only uppercase, etc. Validation can take one of three types:

NumberOnly
Email
Currency
CustomRegex

{
    "type": "NumberOnly",
    "regex": "string"
}

Sample document

The sample document with text tags can be downloaded here. Kindly note that the tags will not be visible since they are added in the same color as the background (white-on-white).

Sample document with hidden text tags:

BoldSign invisible tags

Sample document with visible text tags:

BoldSign visible tags

A sample send document API request with the UseTextTags property enabled and TextTagDefinitions is shown below.

Request Body - containing definition tags

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 'EnableSigningOrder=false' \
      -F 'Signers[0][Name]=Signer Name 1' \
      -F 'Signers[0][EmailAddress]=luthercooper@cubeflakes.com' \
      -F 'Signers[0][SignerOrder]=1' \
      -F 'Signers[0][SignerType]=Signer' \
      -F 'Signers[0][authenticationCode]=123' \
       F 'Signers[0][PrivateMessage]=This is private message for signer' \
      -F 'CC[0][emailAddress]=stacywilson@cubeflakes.com' \
      -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=@NDA.pdf;type=application/pdf'

ApiClient apiClient = new ApiClient("https://api.boldsign.com", " API-KEY ");

DocumentClient documentClient = new DocumentClient(apiClient);

// Directly provide file path of the document.
var documentFilePath = new DocumentFilePath
{
ContentType = "application/pdf",
FilePath = @"D:\Bill-of-Sale.pdf",
};

// Creating collection with all loaded documents.
var filesToUpload = new List<IDocumentFile>
{
documentFilePath,
};

// Creating signer field.
var signer = new DocumentSigner(
name: "Alex Gayle",
emailAddress: "alexgayle@cubeflakes.com",
signerType: SignerType.Signer);

// Adding the signer to the collection.
var documentSigners = new List<DocumentSigner>
{
signer
};


// Create send for sign request object.
var sendForign = new SendForSign
{
Title = "Sent from BoldSign API SDK",
Message = "This is document message sent from API SDK",
EnableSigningOrder = false,
Files = filesToUpload,
Signers = new List<DocumentSigner>
{
signer
},

// Enabling this property will convert text tags in the document to UI form fields.
UseTextTags = true,
};

// Send the document for signing.
var createdDocumentResult = await documentClient.SendDocumentAsync(sendForign).ConfigureAwait(false);

import requests

url = "https://api.boldsign.com/v1/document/send"

payload={'Title': 'Sent from API Curl',
'Message': 'This is document message sent from API Curl',
'EnableSigningOrder': 'false',
'Signers[0][Name]': 'Signer Name 1',
'Signers[0][EmailAddress]': 'luthercooper@cubeflakes.com',
'Signers[0][SignerOrder]': '1',
'Signers[0][SignerType]': 'Signer',
'Signers[0][authenticationCode]': '123',
'Signers[0][PrivateMessage]': 'This is private message for signer',
'CC[0][emailAddress]': 'stacywilson@cubeflakes.com',
'UseTextTags': 'true',
'TextTagDefinitions[0][DefinitionId]': 'tag1',
'TextTagDefinitions[0][Type]': 'TextBox',
'TextTagDefinitions[0][SignerIndex]': '1',
'TextTagDefinitions[0][IsRequired]': 'true',
'TextTagDefinitions[0][FieldLabel]': 'Email field',
'TextTagDefinitions[0][FieldId]': 'axq12367',
'TextTagDefinitions[0][Size][Width]': '500',
'TextTagDefinitions[0][Size][Height]': '50',
'TextTagDefinitions[0][Placeholder]': 'Enter your email here',
'TextTagDefinitions[0][PageNumber]': '1',
'TextTagDefinitions[0][Font][Name]': 'Helvetica',
'TextTagDefinitions[0][Font][Size]': '20',
'TextTagDefinitions[0][Font][Style]': 'Italic',
'TextTagDefinitions[0][Validation][Type]': 'Email'}
files=[
  ('Files',('file',open('{file path}','rb'),'application/octet-stream'))
]
headers = {
  'X-API-KEY': '{your API key}'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

const axios = require('axios'); 
const FormData = require('form-data'); 
const fs = require('fs'); 
const form = new FormData(); 
form.append('Title', 'Sent from API Curl'); 
form.append('Message', 'This is document message sent from API Curl'); 
form.append('EnableSigningOrder', 'false'); 
form.append('Signers[0][Name]', 'Signer Name 1'); 
form.append('Signers[0][EmailAddress]', 'luthercooper@cubeflakes.com'); 
form.append('Signers[0][SignerOrder]', '1'); 
form.append('Signers[0][SignerType]', 'Signer'); 
form.append('Signers[0][authenticationCode]', '123'); 
form.append('Signers[0][PrivateMessage]', 'This is private message for signer'); 
form.append('CC[0][emailAddress]', 'stacywilson@cubeflakes.com'); 
form.append('UseTextTags', 'true'); 
form.append('TextTagDefinitions[0][DefinitionId]', 'tag1'); 
form.append('TextTagDefinitions[0][Type]', 'TextBox'); 
form.append('TextTagDefinitions[0][SignerIndex]', '1'); 
form.append('TextTagDefinitions[0][IsRequired]', 'true'); 
form.append('TextTagDefinitions[0][FieldLabel]', 'Email field'); 
form.append('TextTagDefinitions[0][FieldId]', 'axq12367'); 
form.append('TextTagDefinitions[0][Size][Width]', '500'); 
form.append('TextTagDefinitions[0][Size][Height]', '50'); 
form.append('TextTagDefinitions[0][Placeholder]', 'Enter your email here'); 
form.append('TextTagDefinitions[0][PageNumber]', '1'); 
form.append('TextTagDefinitions[0][Font][Name]', 'Helvetica'); 
form.append('TextTagDefinitions[0][Font][Size]', '20'); 
form.append('TextTagDefinitions[0][Font][Style]', 'Italic'); 
form.append('TextTagDefinitions[0][Validation][Type]', 'Email'); 
form.append('Files', fs.readFileSync('NDA.pdf;type=application/pdf'), 'NDA.pdf;type=application/pdf'); 
const response = await axios.post( 

    ' https://api.boldsign.com/v1/document/send', 

    form, 
    { 
        headers: { 
            ...form.getHeaders(), 
            'Authorization': 'Bearer <authtoken>' 
        } 
    } 
);