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.

GroupNamestring Assign a group name for the form field to be used with form groups.

TabIndexNullable int Assign tab index to control the flow of field focus while using TAB key navigation. Default to null, which denotes it will follow regular flow. The accepted range starts from -1 to a valid integer.

Labelstring The label used to represent the value for a radio button. Also, can be used to prefill a radio button.

PageNumber integerRequired Page number in which the form field should be placed.

Offsetobject

Specifies the offset positioning for the text tag, allowing adjustments to its location relative to the computed position. The computed value after value must remain within the page dimensions.

OffsetXdouble	Adjusts the text tag's position horizontally (left or right).
OffsetYdouble	Adjusts the text tag's position vertically (top or bottom).

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
}

Offset

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

OffsetX - Adjust the textTag postion left or right.

OffsetY - Adjust the textTag postion top or bottom.

Note: If offset value out of bounds according to its page size then the document will not be sent, and the reason for this will be sent to the webhook endpoint configured.

{
    "offsetX": 0,
    "offsetY": 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 'TextTagDefinitions[0][Offset][OffsetX]=0' \
      -F 'TextTagDefinitions[0][Offset][OffsetY]=0' \
      -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 boldsign

configuration = boldsign.Configuration(
    api_key = "YOUR_API_KEY"
)

with boldsign.ApiClient(configuration) as api_client:

    document_api = boldsign.DocumentApi(api_client)

    form_fields = [
        boldsign.FormField(
            fieldType="Signature",
            pageNumber=1,
            bounds=boldsign.Rectangle(
                x=50,
                y=50,
                width=200,
                height=25
            )
        ),
        boldsign.FormField(
            fieldType="Label",
            value="Label Field",
            pageNumber=1,
            bounds=boldsign.Rectangle(
                x=150,
                y=250,
                width=200,
                height=25
            )
        ),
    ]

    document_signer = boldsign.DocumentSigner(
        name="David",
        emailAddress="david@cubeflakes.com",
        signerOrder=1,
        signerType="Signer",
        formFields=form_fields,
        locale="EN"
    )

    send_for_sign = boldsign.SendForSign(
        document_title = "SDK Document Test case",
        description="Testing document from SDK integration test case",
        files=["YOUR_FILE_PATH"],
        disableExpiryAlert=False,
        reminderSettings=boldsign.ReminderSettings(
            reminderDays=3,
            reminderCount=5,
            enableAutoReminder=False
        ),
        enableReassign=True,
        message='Please sign this.',
        signers=[document_signer],
        expiryDays=10,
        enablePrintAndSign=False,
        AutoDetectFields=False,
        onBehalfOf='',
        enableSigningOrder=False,
        title="Document SDK API",
        hideDocumentId=False,
        enableEmbeddedSigning=False,
        expiryDateType='Days',
        expiryDate=60,
        disableEmails=False,
        disableSMS=False,
        useTextTags=True,
        textTagDefinitions= [
            boldsign.TextTagDefinition(
                definitionId="tag1",
                type="TextBox",
                signerIndex=1,
                isRequired=True,
                label="Email field",
                font=boldsign.Font(
                    name="Helvetica",
                    size=20,
                    style="Italic"
                ),
                fieldId="axq12367",
                size=boldsign.Size(
                    width=500,
                    height=50
                ),
                placeholder="Enter your email here",
                validation=boldsign.Validation(
                    type="Email"
                ),
                offset= boldsign.TextTagOffset(
                    offsetX=0,
                    offsetY=0
                )
            )
        ]
    )

    send_document_response = document_api.send_document(send_for_sign)

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('TextTagDefinitions[0][Offset][OffsetX]','0');
form.append('TextTagDefinitions[0][Offset][OffsetY]','0');
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>' 
        } 
    } 
);