Tabs (Fields)

Tabs - aka fields or tags- can be added to documents and templates and are used several ways. First they are used to indicate to a recipient where a signature or initials are required. Second, they can be used to show data or information to recipients, such as dates, names, addresses, and other data. Third, tabs can be used as editable information fields so you can retrieve data or information from your recipients.

Some tabs automatically populate with the recipient's data (such as emailTabs or fullNameTabs) while others require the signer to enter some information (textTabs) or make a choice (listTabs, checkboxTabs, radioGroupTabs).

For a full list of tab types, their corresponding object names, and see the EnvelopeTabs resource.

Adding Tabs to Envelopes

Tabs are always associated with specific recipients or template roles which means they are a property of recipient types, such as signer or inPersonSigner. For example, the following envelope definition defines one signature tab and one initial tab for the signer. The signature tab is located 100 pixels right and 100 pixels down from the top left corner of the document, with the initials tab a further 100 pixels to the right of that:

{
    "status": "sent",
    "emailSubject": "Basic Tabs Example",
    "documents": [{
        "documentId": "1",
        "name": "contract.pdf",
        "documentBase64": "base64 document bytes...",
    }],
    "recipients": {
        "signers": [{
            "email": "john@email.com",
            "name": "John Doe",
            "recipientId": "1",
            "tabs": {
                "signHereTabs": [{
                    "xPosition": "100",
                    "yPosition": "100",
                    "documentId": "1",
                    "pageNumber": "1"
                }],
                "initialHereTabs": [{
                    "xPosition": "200",
                    "yPosition": "100",
                    "documentId": "1",
                    "pageNumber": "1"
                }]
            }
        }]
    }
}

Tab Locations and Positioning

There are three ways of specifying tab and field locations in your envelopes:

  • Fixed (or Absolute) Positioning
  • Auto-Place (or Anchor-tag) Positioning
  • PDF Form Field Transformation

You can also use the DocuSign website to manually position recipient tabs and save those locations and settings in a template for repeated use. Additionally you can use the embedded sending workflow to load the tagging view of an envelope at run-time.

Tab Placement Method 1: Fixed Positioning

Fixed (or absolute) positioning works well if you know where on your documents you want to people to sign, view, or take other actions and your documents don't change much over time. With fixed positioning you specify tab locations using the xPosition and yPosition tab properties:

"tabs": {
    "signHereTabs": [{
        "xPosition": "100",
        "yPosition": "200",
        "documentId": "1",
        "pageNumber": "1"
    }]
}

The above tab definition would place a signature tab 100 pixels to the right and 200 pixels down from the top left corner of the first page of the document. When using this placement method you should ensure your tabs are not obscuring any document content.

Tab Placement Method 2: Auto-Place (Anchor Tagging)

Using the auto-place feature (also called anchor-tagging) you can specify the location of your tabs based on content or "markers" contained within your documents.

For instance, let's say we have a document that contains the text "Please Sign Here:". If we want to place a signature tab where this string is found in the document, or better yet place a signature tab 1 inch to the right of the string to make sure the signature does not overwrite it, we can use the following tab properties:

"tabs": {
    "signHereTabs": [{
        "anchorString": "Please Sign Here:",
        "anchorXOffset": "1",
        "anchorYOffset": "0",
        "anchorIgnoreIfNotPresent": "false",
        "anchorUnits": "inches"
    }]
}

Since we set anchorString to the value "Please Sign Here:" a signHere tab will be placed wherever that string is found in the document, and since anchorXOffset is set to "1" and anchorUnits is set to inches the signature tabs will be placed 1 inch to the right in each location. Note that with anchorIgnoreIfNotPresent set to false an error will be returned if the text "Please Sign Here:" is not found anywhere in the document.

One common approach towards anchor tagging is to put unique tags or character sequences in the document that aren't normally found in the document's content, and make them invisible by setting them to the same color as the background (white in most cases). For instance, the string "\s1\" could be used to indicate where signature tabs for the first recipient should be placed, and "\i2\" could be used to indicate where initial tabs for the second recipient go, etc. And by setting their font color to the same color as the background the recipients will only see the tabs at those locations, hence you won't need to offset at all.

Tab Placement Method 3: PDF Form Field Transformation

A third approach to placing tabs on documents through the API is to use PDF Form Field Transformations. There are two different types of transformations you can perform - 1) you can transform pdf form fields into DocuSign tabs and 2) you can transfer the values contained in PDF fields into DocuSign tabs. In this case the location of DocuSign tab(s) are based on the location of the corresponding PDF form fields.

To transform PDF form fields into DocuSign tabs you need to make use of the compositeTemplates node and enable the transformPdfFields property on the documents whose fields you want to transform. For example, the following request will transform the fields in the irs 4506T pdf that is supplied through the composite template:

{
    "status": "sent",
    "emailSubject": "Transform PDF Fields Example 1",
    "recipients": {
        "signers": [{
            "email": "john@email.com",
            "name": "Jon Dough",
            "recipientId": "1"
        }]
    },
    "compositeTemplates": [{
        "inlineTemplates": [{
            "sequence": "1",
            "recipients": {
                "signers": [{
                    "email": "john@email.com",
                    "name": "Jon Dough",
                    "recipientId": "1",
                    "defaultRecipient": "true"
                }]
            }
        }],
        "document": {
            "documentId": "1",
            "name": "irs_f4506t.pdf",
            "documentBase64": "<base64 encoded bytes>",
            "transformPdfFields": "true"
        }
    }]
}

To transfer the values of PDF form fields into their corresponding DocuSign tabs (perhaps in a template) set the transformPdfFields property to true on documents array at the root level of the envelope definition. It is important to note that the names of the PDF fields must match the tabLabel of the DocuSign tabs (case-sensitive) you wish to transfer values to. If the PDF field names match the DocuSign tabLabel then simply setting the transformPdfFields property to true for a given document in the documents array like this:

{
    "status": "sent",
    "emailSubject": "PDF Transform Example 2",
    "recipients": {
        "signers": [{
            "email": "sally@email.com",
            "name": "Sally Dough",
            "recipientId": "1"
        }]
    },
    "documents": [{
        "documentId": "1",
        "name": "contract.pdf"
        "transformPdfFields": true
    }],
}

Data Fields

Data Fields - aka text tabs or form fields - have a variety of uses. Editable data fields can be used to gather information from your recipients. Or you can make them read-only by setting their locked property to "true" and simply display information to your recipients.

For example, the following definition defines two textTabs (data fields) with the first being an editable field while the second is read-only:

"tabs": {
    "textTabs": [{
        "tabLabel": "EditableDataField",
        "locked": "false",
        "xPosition": "200",
        "yPosition": "200",
        "documentId": "1",
        "pageNumber": "1"
    },
    {
        "tabLabel": "ReadOnlyDataField",
        "value": "$100",
        "locked": "true",
        "xPosition": "300",
        "yPosition": "200",
        "documentId": "1",
        "pageNumber": "1"
    }]
}

Shared Tab Labels

If you give tabs of the same type the same tabLabel when a recipient updates one tab it will update all the others with the same data in real-time. For instance, let's say you create an envelope with a 2 page document and add the following tabs for a given recipient:

"tabs": {
    "textTabs": [{
        "tabLabel": "SharedDataField",
        "xPosition": "25",
        "yPosition": "100",
        "documentId": "1",
        "pageNumber": "1"
    },
    {
        "tabLabel": "SharedDataField",
        "xPosition": "25",
        "yPosition": "100",
        "documentId": "1",
        "pageNumber": "2"
    }]
}

Even though there are two individual tabs, each added to a different page of the document, both these fields will update in real-time when the recipient edits one of them.

Calculated Fields

Using Calculated Fields you can add tabs to your transactions that reference other tabs and calculate and display values as recipients make changes. Use the formulaTabs tab type to add calculated fields to your envelopes.

Formula tabs let senders build calculations using other tabs - known as "reference tabs" - in an envelope or template. Recipients can not edit the value of the formula tab itself, however the may be able to edit tabs its formula references. To reference other tabs in your formulas you must match their case-sensitive [tabLabel] in square brackets. Also note that formula tabs can reference other formula fields, giving you flexibility for more complex equations.

Numeric and Date Formulas Supported

Formulas may contain numbers or dates but not both - they can only reference numberTabs or dateTabs and dateSignedTabs. A numeric formula, for instance, may be comprised of numbers only, a combination of numbers and reference tabs, or reference tabs only. The following examples are all valid numeric formulas (assuming the tabs referenced exist and have matching tab labels): (2 * 3) + 4, 2 * [amount], [line1] + [line2] + [tax].

The following standard mathematical operators are supported:

  1. Addition (+)
  2. Subtraction (-)
  3. Multiplication (*)
  4. Division (/)

Numeric Formulas

The following example shows a formula that references two other numberTabs: the first is a sub-total tab the recipient can modify and the second is a read-only tax value set at 5%. The formula tab performs the following calculation: (subTotal * .05) + subTotal

{
    "tabs": {
        "numberTabs": [{
            "tabLabel": "subTotal",
            "xPosition": "20",
            "yPosition": "100",
            "documentId": "1",
            "pageNumber": "1"
        }, {
            "tabLabel": "tax",
            "value": "0.05",
            "locked": "true",
            "xPosition": "50",
            "yPosition": "100",
            "documentId": "1",
            "pageNumber": "1"
        }],
        "formulaTabs": [{
            "tabLabel": "calculatedPrice",
            "formula": "([subTotal] * [tax]) + [subTotal]",
            "xPosition": "80",
            "yPosition": "100",
            "documentId": "1",
            "pageNumber": "1"
        }]
    }
}

Date Formulas

Formula tabs also support a set of Date functions to calculate a number of days or determine a date. The following date related functions are supported:

  • AddDays(d1,n1) : Calculates a number of days (n1) to add or subtract from a date (d1). To subtract, a minus sign ("-") is used before (n1).
  • AddMonths(d1,n1) : Returns a number of months (n1) to add or subtract from a date (d1). To subtract, a minus sign ('-") is used before (n1).
  • AddYears(d1,n1) : Returns a number of years (n1) to add or subtract from a date (d1). To subtract, a minus sign ('-") is used before (n1).
  • DateDiff(d1,d2) : Calculates the number of days between two dates (d1-d2).
  • Day(d) : Returns the current day of the month as a value, 1 through 31.
  • Days(d) : Returns the number of days in the month for the reference date field (d).

For example, let's say we have a contract which we want valid for 30 days, starting from the date the document is signed. We could use the following tabs definition which makes use of the AddDays(d1,n1) function:

{
    "tabs": {
        "dateSignedTabs": [{
            "tabLabel": "todaysDate",
            "xPosition": "20",
            "yPosition": "75",
            "documentId": "1",
            "pageNumber": "1"
        }],
        "formulaTabs": [{
            "tabLabel": "contractLength",
            "formula": "AddDays([todaysDate], 30)",
            "xPosition": "150",
            "yPosition": "75",
            "documentId": "1",
            "pageNumber": "1"
        }]
    }
}

Conditional Fields

With conditional fields, you can hide fields until the recipient makes an entry in your document that triggers the fields to show, such as selecting an option or marking a checkbox. Conditional fields allow you to create dynamic documents that support a conditional work flow and only appear to the recipient when a specified condition is met.

Here are some typical conditions to trigger a conditional field:

  1. A checkbox is checked and the recipient is asked for additional information
  2. In a drop-down, the option "Other" is selected and the recipient must provide further details
  3. Specific text is entered in a text field and the recipient must answer an additional question

You can apply conditional logic to the following field types:

  1. Checkbox
  2. Radio Button
  3. Drop-down
  4. Text

Use the conditionalParentLabel tab property to reference a conditional field and the conditionalParentValue to check its value. If the conditional field is a checkbox or radio button use "on" as the value to show that the parent tab is active. For example, if we wanted to only show a signHere tab when a checkbox is checked we could define the following tabs:

{
    "status": "sent",
    "emailSubject": "Conditional Tabs Example",
    "documents": [{
        "documentId": "1",
        "name": "contract.pdf",
        "documentBase64": "base64 document bytes..."
    }],
    "recipients": {
        "signers": [{
            "email": "smason@email.com",
            "name": "Sara Mason",
            "recipientId": "1",
            "tabs": {
                "checkboxTabs": [{
                    "tabLabel": "sampleCheckbox",
                    "xPosition": "20",
                    "yPosition": "20",
                    "documentId": "1",
                    "pageNumber": "1"
                }],
                "signHereTabs": [{
                    "conditionalParentLabel": "sampleCheckbox",
                    "conditionalParentValue": "On",
                    "xPosition": "80",
                    "yPosition": "40",
                    "documentId": "1",
                    "pageNumber": "1"
                }]
            }
        }]
    }
}

Free Form Signing

If you do not add any tabs to an envelope then it becomes what's known as a Free-Form signing experience. During free-form signing the recipients decide where to place tabs on the documents as well as the location of those tabs, instead of the sender controlling those aspects. The only requirement for free-form signers is that they place at least one tab in the envelope. Creating free-form signing workflows is easy: just don't specify any tabs for your recipients.

Sample Request

The following envelope definition sends a request to two unique recipients. Both recipients are of type signers with the first recipient having a signature tab and a couple of radio buttons configured for them (note that the first radio button is checked by default). The second recipient has an initial tab and a signature tab assigned to them. Note that there is no routingOrder element defined for either of the recipients- which means they both inherit a routingOrder of 1 and will therefore receive the request at the same time.

{
    "emailSubject": "Please sign this document...",
    "emailBlurb": "Sent from the DocuSign API",
    "status": "sent",
    "documents": [{
        "documentId": "1",
        "name": "test.pdf"
    }],
    "recipients": {
        "signers": [{
            "email": "sallydoe@email.com",
            "name": "Sally Doe",
            "recipientId": "1",
            "tabs": {
                "signHereTabs": [{
                    "xPosition": "100",
                    "yPosition": "200",
                    "documentId": "1",
                    "pageNumber": "1"
                }],
                "radioGroupTabs": [{
                    "documentId": "1",
                    "groupName": "RadioGroup1",
                    "radios": [{
                        "pageNumber": "1",
                        "selected": "true",
                        "value": "X",
                        "xPosition": "300",
                        "yPosition": "75"
                    },
                    {
                        "pageNumber": "1",
                        "selected": "false",
                        "xPosition": "350",
                        "yPosition": "75"
                    }]
                }]
            }
        },
        {
            "email": "johndoe@email.com",
            "name": "John Doe",
            "recipientId": "2",
            "tabs": {
                "signHereTabs": [{
                    "xPosition": "100",
                    "yPosition": "300",
                    "documentId": "1",
                    "pageNumber": "1"
                }],
                "initialHereTabs": [{
                    "xPosition": "200",
                    "yPosition": "300",
                    "documentId": "1",
                    "pageNumber": "1"
                }]
            }
        }]
    }
}

For more information on tabs refer to the REST API Guide.