BoldSignDocumentation
BoldSign Mobile Icon

Definition

Tue, 1 February, 2022

The definition can be used for the long text tag handling, when text tags containing many directives may become very long, making it difficult to specify for the small fields on the document. To solve this, definition is introduced.

Property name Required Description
DefinitionId Required The ID will be used to match text tag definition provided in the document
Type Required The form field type
SignerIndex Required Index of the signer to which the field needs to be assigned.
IsRequired Optional Indicates whether the field is required
FieldLabel Optional Indicates the field label to be displayed in the field.
FieldId Optional Unique field Id to be set for all the individual fields.
Size Optional indicates the size of text tag.
Font Optional Font to be set for the form field.
Validation Optional Validation for the content present in the text box field type.
Placeholder Optional Place holder to be displayed in text box field
DateFormat Optional Date format to be set in the date time field.
RadioGroupName Optional Group name to be set in the radio button fields.
PageNumber Optional Page number in which the form field should be placed.

The definition can be declared in the API, in a list of text tag object.

C#CURL


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

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

// Creating signer field.
var signer = new DocumentSigner(
        name: "Signer Name 1",
        emailAddress: "signer1@email.com",
        signerOrder: 1,
        authenticationCode: "123",
        signerType: SignerType.Signer,
        privateMessage: "This is private message for signer");

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

// Creating a CC instance
var cc = new DocumentCC(emailAddress: "cc@mail.com");

// Adding the CC to the collection.
var documentCCs = new List<DocumentCC>
{
    cc
};

List<TextTag> definitionTags = new List<TextTag>()
{
    new TextTag(
        definitionId: "tag1",
        type: FieldType.TextBox,
        signerIndex: 1,
        isRequired: true,
        fieldLabel: "Email field",
        fieldId: "axQ12367",
        size: new Size(500, 50),
        placeholder: "Enter your email here",
        pageNumber: 1,
        font: new Font()
        { 
            Name = FontFamily.Helvetica,
            Size = 20,
            Style = FontStyle.Italic,
        }
            ,
        validation: new Validation()
        { 
            Type = Api.Model.ValidationType.Email
        }
        ),
};

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

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

    // Set the created TextTag definitions here.
    TextTagDefinitions = definitionTags,
};

// Send the document for signing.
var createdDocumentResult = this.DocumentClient.SendDocument(sendForign);
curl -X POST 'https://api.boldsign.com/v1/document/send' \
-H 'Authorization: Bearer <authtoken>' \
-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]=signer1@email.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]=cc@mail.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'

Usage syntax

Tag usage starts with @ and proceeds with the definition Id from TextTagDefinitions provided in send request. The sample for usage is given below:

e.g. {{@tag1       }} 

Note: If the definition Id provided in document is not present in TextTagDefinitions then the error will be thrown in document send request.

Override

The definition values can be override to the text tags with label and field ID. When there is a use for different field label and field id with same set of tags.

syntax:

{{@tag1:field_label|field_id}} 

e.g. 

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

Font

The name of font can be specified from the text tags, The font name, font size and font style can be given. The font usage is support only to text box and date signed field.

Property name Description
Name Font family name of the content in the field
Style Font style of the content in the field
Size Font size of the content in the field (font size supported range from 7 to 72).
Line height Height between each line set in text box field

Supported Fonts are given below:

  • Helvetica
  • Courier
  • Times New Roman

Below are the supported font styles.

  • Bold
  • Italic
  • Underline

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

Validation

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

  1. Numbers only
  2. Email address
  3. Currency
  4. Custom Regex

var emailValidation = new Validation()
{
    Type = Api.Model.ValidationType.Email
};

var regexlValidation = new Validation()
{
    Regex = @"\b[S]\w+",
    Type = Api.Model.ValidationType.Regex
};
Copied to clipboard