Select the right tab placement strategy for your Docusign integration

Navigating the various methods for placing tabs in Docusign envelopes generated via API can be a complex task, especially when striving for efficiency and scalability. This blog post delves into six primary approaches, offering guidance to help you select the most suitable method for your specific integration needs. Understanding these options is crucial for optimizing your electronic signature workflows and ensuring a seamless user experience. 

Important questions

Before considering the options, take a step back and answer these important questions to help you select your optimal tab placement method. To get started, think about your envelope workflow and answer some key questions:

1. What is the source of the document? Is it supplied externally; say, from your customer? Or will your application generate the document?

2. Will the tab positions be static or dynamic? For example, will the DateSigned tab always be located 5 inches from the top margin and 6 inches from the left margin of page 4?

3. Will you have missing tabs? Put another way, will you plan on certain tabs that may not be needed for some documents?

4. Will you have some documents that must be configured once, but will be reused many times?

5. Will you have some documents that are effectively configured every time that they are sent for signature?

6. Is it acceptable for the workflow to include having the sending user manually place the tabs?

7. Is it acceptable for the recipient to place their own tabs?

Armed with answers to the above questions, consider which tab placement approach will best suit your needs.

Tab placement approaches

For placing tabs at scale for envelopes generated via API, Docusign offers six general approaches (in no particular order):

• Programmatic positioning

• Anchor tags

• PDF fillable fields

• Server templates

• Sender view

• Freeform signing

Programmatic (fixed) positioning

Programmatic positioning allows the calling program to place tabs in specific locations relative to the top left of the page, specifying those positions numerically in the envelope definition.

When to use

• The tab location will always be in a known location on a page.

When not to use

• The software making the API call to Docusign does not know the location of the tabs.

Caveats and best practices

Any changes to tab locations will require the API calls to change. That means that such a change will require that you either modify integration code or store tab placement information in a database for the code to reference when placing API calls.

Programmatic positioning can be used in many scenarios. Some developers have built their own front-end tab placement user interfaces to let the sending user place tabs as they wish; the application then records those locations and uses them to place tabs programmatically in the document. While this essentially replicates the functionality offered by embedding the Sender view (see below), it enables developers to customize the user experience further in ways appropriate to their own use case.

Anchor tags

Anchor tags enable Docusign to look for a specific string (the tag) in the document and then auto-place a particular tab at a specific offset from the tag. Docusign Document Generation is a natural fit for anchor tags.

Anchor tags can be applied in three ways:

1. During the API call that specifies the recipient tabs

2. As auto-place tabs in a server template

3. As a document custom field on the Docusign account

When to use

• You control the document generation and can ensure that the correct tag is in the correct place on each document.

When not to use

• There is not a predictable unique string available on the document that can serve as a location marker for placing tabs.

Caveats and best practices

• Place anchor tags so that they are invisible, such as in two-point white font on a white background.

• To avoid false tab placement, make sure to use an anchor tag that will never occur otherwise in the document. 

• If the anchor tag extends beyond the right edge of the page, Docusign will not recognize it.

• Avoid using pixel offset units because pixel size can vary based on the PDF image dots per inch (DPI) setting, causing the tabs to relocate based on DPI.

• Make the anchor tag signer-independent with the {r} syntax.

• Template anchor tags have the following restrictions:

  • All tags must be present in every document, or the createEnvelope call will throw an error.

  • The tab relative offset must be specified in pixels, causing the tabs to be in the wrong place if a document has an unexpected DPI.

PDF fillable fields

When importing PDF documents into an envelope or template, Docusign will offer to convert the fields into Docusign tabs. No coding is required. When you create a new envelope and upload a PDF document that contains form fields, Docusign eSignature automatically recognizes their presence and gives you three options for interpreting them: 

• Assign all of the fields to a recipient. This option preserves any data already in the fields, but makes them fillable and assigns them all to the same recipient; however, you can change that recipient after you import the PDF.

• Keep the form field data. This option preserves all the data in the fields, but makes it all read-only.

• Delete all of the fields and any data they contain. This gives you the option to create new fields in the document as you wish after import.

When to use

• You have a PDF available with fillable form fields.

• Your envelope workflow allows for a manual process.

When not to use

• You need a fully automated solution for configuring the tabs.

• You need to know the tab names created.

Caveats and best practices

• Because this operation depends on the Docusign user interface, it probably makes sense to perform this on a template instead of an envelope.

• The Docusign tabs will all be assigned to the first recipient/role.

• Docusign will apply tab names that appear to be arbitrary.

Server templates

Templates are the model for an envelope, containing at least one role and one document. When the same document will be reused multiple times, create a template for that document with the tabs preplaced.

When to use

• The same document will be reused multiple times.

• The tab locations will not change.

When not to use

• Your workflow does not allow for manual intervention between creation of the PDF and sending the envelope.

Caveats and best practices

Template editing is a manual process, but this allows for separation of concerns whereby the code invokes the template and the template is maintained by a separate team.

Sender view

Sender view is the Docusign eSignature UI screen that enables the envelope sender to edit the tabs, documents, recipients, and other settings of a draft envelope before it’s sent. Your integration can embed this view for your sending users with an API call to the createSenderView endpoint. Docusign will return a single-use URL that expires in five minutes. When the user is redirected to this URL, the user will have the same UI capabilities that the user would have if creating an envelope via Docusign eSignature.

When to use

• No other feasible method exists for automating placement of the tabs.

• The user interacting with your application is comfortable placing tabs on the outgoing envelope.

When not to use

• Your workflow requires an automated process without end-user interaction.

Caveats and best practices

• Make sure that the request body to the API call includes the viewAccess property.

Freeform signing

Freeform signing is the last-resort option when no other option is feasible for placing tabs. With this approach, the burden of placing tabs is pushed to the recipient.

When to use

• No other option exists.

• The envelope does not use the Document Visibility feature.

When not to use

• Every chance possible

Caveats and best practices

In general, relying on freeform signing represents a design failure. Avoid this if at all possible. The recipient will be prompted with the document(s) and no guidance on what to do with the various tabs made available on the left pane of the Docusign UI, leading to confusion and poorly executed agreements.

The entire signing process is at the mercy of the recipient doing the right thing in terms of placing tabs.

Tab placement examples

This section provides examples of how to implement each of the approaches listed in the previous section.

Programmatic positioning

Programmatically, this is relatively straightforward. The sample envelope definition below shows how to include the document and specify tab placements. Pass this to the createEnvelope endpoint, and then look in the Drafts folder in your Docusign account. To send an envelope this way, set the status property to "sent".

{
   "status": "created",
   "emailSubject": "Please Sign the Agreement {{$guid}}",
   "documents": [
       {
           "documentId": "1",
           "name": "simple_doc.pdf",
           "remoteUrl": "https://raw.githubusercontent.com/docusign/developer-blog-samples/refs/heads/main/tab-placement-strategy/simple_doc.pdf"
       }
   ],
   "recipients": {
       "signers": [
           {
               "email": "bob@bob.com",
               "name": "Bob Buyer",
               "recipientId": "1",
               "tabs": {
                   "signHereTabs": [
                       {
                           "documentId": "1",
                           "pageNumber": "1",
                           "xPosition": "256",
                           "yPosition": "42"
                       }
                   ],
                   "fullNameTabs": [
                       {
                           "documentId": "1",
                           "pageNumber": "1",
                           "xPosition": "72",
                           "yPosition": "60"
                       }
                   ],
                   "dateSignedTabs": [
                       {
                           "documentId": "1",
                           "pageNumber": "1",
                           "xPosition": "398",
                           "yPosition": "60"
                       }
                   ]
               }
           }
       ]
   }
}

The important properties are xPosition and yPosition. In each of the three tabs, those properties specify the distance down and to the right from the top-left corner of the page. The position units are points: 1/72 of an inch.

Anchor tags

Anchor tags place the tabs relative to text on the page. This section will show how to use anchor tags in the three different ways supported by Docusign:

1. During the API call that specifies the recipient tabs

2. As auto-place tabs in a server template

3. As a shared document custom field in the Docusign account

During the API call that specifies the recipient tabs

This approach is similar to the programmatic positioning approach, except here you specify an anchor string and the relative offset from that string.

Pass the envelope definition below to the createEnvelope endpoint, and then look in the Drafts folder in your Docusign account. This will place the tabs with zero x offset and 14 mm above where the strings were found. That way, if the strings move on the document, the tabs will be in the correct place.

{
   "status": "created",
   "emailSubject": "Please Sign the Agreement {{$guid}}",
   "documents": [
       {
           "documentId": "1",
           "name": "simple_doc.pdf",
           "remoteUrl": "https://raw.githubusercontent.com/docusign/developer-blog-samples/refs/heads/main/tab-placement-strategy/simple_doc.pdf"
       }
   ],
   "recipients": {
       "signers": [
           {
               "email": "bob@bob.com",
               "name": "Bob Buyer",
               "roleName": "Buyer",
               "recipientId": "1",
               "tabs": {
                   "signHereTabs": [
                       {
                           "documentId": "1",
                           "pageNumber": "1",
                           "anchorString": "Signature",
                           "anchorXOffset": "0",
                           "anchorYOffset": "-14",
                           "anchorUnits": "mms"
                       }
                   ],
                   "fullNameTabs": [
                       {
                           "documentId": "1",
                           "pageNumber": "1",
                           "anchorString": "Name",
                           "anchorXOffset": "0",
                           "anchorYOffset": "-14",
                           "anchorUnits": "mms"
                       }
                   ],
                   "dateSignedTabs": [
                       {
                           "documentId": "1",
                           "pageNumber": "1",
                           "anchorString": "Date Signed",
                           "anchorXOffset": "0",
                           "anchorYOffset": "-14",
                           "anchorUnits": "mms"
                       }
                   ]
               }
           }
       ]
   }
}

In a real deployment, the anchorString property would contain a hidden string on the page that would never occur in a real document, such as a GUID.

When appropriate for your workflow, Docusign Document Generation works seamlessly with anchor tags to produce publication-quality documents that reflow paragraphs as needed based on input data length. 

As auto-place tabs in a server template

This approach involves creating a server template, but using the anchor tags approach, as described at Docusign Support.

As a shared document custom field on the Docusign account

Tab naming conventions can be a bit confusing. A tab is what you place on a document for recipient interaction, such as the SignHere tab. The API is consistent in referring to this as a tab. API endpoints exist for manipulating recipient tabs and document tabs.

Docusign also describes a field, which is a name and value pair that you can associate with a document or envelope. These fields are not visible to the signer and generally not visible to the sender, but are stored as metadata with the document. API endpoints exist for manipulating document fields and envelope fields.

Within the Docusign eSignature web app, naming can be a little blurry. Often the web app refers to tabs as fields. These are what the API would refer to as tabs, not fields. Docusign has the ability to store custom tabs that include anchor strings. In Docusign eSignature, these are known as document custom fields. These are what the API would refer to as tabs, not fields.

Using custom tabs with anchor tags involves two steps:

1. Defining the custom tab in the Docusign account

2. Applying the custom tab to envelope documents

Defining the custom tab in the Docusign account

You can define a custom tab through the Docusign eSignature web app or through the API. 

To create a SignHere custom tab via the API with the anchor string of /Signature{r}/, pass the body below to the createCustomTabs endpoint.

{
   "anchor": "/Signature{r}/",
   "shared": "false",
   "tabLabel": "Anchor SignHere Tab",
   "scaleValue": "1",
   "type": "signHere",
   "editable": "true"
}

Applying the custom tab to envelope documents

With the above custom tab defined, pass the envelope definition below to the createEnvelope endpoint to see the document pick up the anchor string. Note that this approach does not allow you to set x and y offsets. The document custom_tab.pdf has the anchor string in light gray text so that it is visible for this exercise.

{
   "status": "created",
   "emailSubject": "Please Sign the Agreement {{$guid}}",
      "recipients": {
       "signers": [
           {
               "email": "bob@bob.com",
               "name": "Bob Buyer",
               "roleName": "Buyer",
               "recipientId": "1"
           }
       ]
   },
   "documents": [
       {
           "documentId": "1",
           "name": "custom_tab.pdf",
           "remoteUrl": "https://raw.githubusercontent.com/docusign/developer-blog-samples/refs/heads/main/tab-placement-strategy/custom_tab.pdf"
       }
   ]
}

PDF fillable fields

This approach allows converting PDF fillable fields into Docusign tabs. Docusign Support provides detailed instructions for creating tabs from PDF form fields in the Docusign eSignature UI.

Server templates

To use a server template when creating an envelope, first create the template in Docusign eSignature as described on Docusign Support. Make sure that the template has one or more of each of:

• documents

• roles

• tabs

Armed with the template ID, make an API call to the CreateEnvelope endpoint with a body similar to that below. Substitute your correct template ID in the body.

{
    "emailSubject": "Please Sign the Agreement {{$guid}}",
    "compositeTemplates": [
        {
            "serverTemplates": [
                {
                    "sequence": "1",
                    "templateId": "7f2f5d2c-xxxx-xxxx-xxxx-52b241cc8d1d"
                }
            ]
        }
    ]
}

Sender view

Embed the Sender view by calling the createSenderView API endpoint. You can pass into that endpoint some properties to restrict the user experience. The API will return a single-use URL that is valid for five minutes. Redirect the user to the URL. Below is an example body for this endpoint.

{
   "returnUrl": "https://imageio.forbes.com/blogs-images/chrismyers/files/2018/02/ikigai-1.jpg?height=640&width=640&fit=bounds",
   "viewAccess": "envelope",
   "settings": {
       "taggerSettings": {
           "paletteSections": "custom",
           "paletteDefault": "custom"
       },
       "startingScreen": "Tagger",
       "showBackButton": "false"
   }
}

Freeform signing

This is the simplest way to place tabs: have the recipient place them. While simple, this approach is the least elegant since it relies on the recipient placing tabs correctly. To use freeform signing, simply send an envelope with no tabs defined.

Conclusion

The post outlines six general approaches for placing tabs at scale in Docusign envelopes generated via API:

• Programmatic positioning

• Anchor tags

• PDF fillable fields

• Server templates

• Sender view

• Freeform signing

Your specific envelope workflow drives approach selection. To determine the best approach, consider factors such as:

• The source of the document (external or application-generated)

• Whether tab positions will be static or dynamic

• The possibility of missing tabs

• If documents will be configured once and reused many times, or configured each time they are sent

• The acceptability of manual tab placement by the sending user or the recipient

Each approach has distinct use cases and limitations.

• Programmatic positioning is ideal when tab locations are always known and static, allowing the calling program to place tabs at specific coordinates. However, any location changes necessitate modifications to API calls or database storage.

• Anchor tags offer flexibility by placing tabs relative to specific text on the document. This method is particularly suitable when you control document generation and can embed unique, often invisible, anchor strings. Docusign Document Generation is a natural fit for anchor tags, enabling tabs to adjust even if the document content shifts. Careful placement is crucial to avoid issues like false tab placement or tags extending beyond page edges.

• PDF fillable fields can convert existing PDF form fields into Docusign tabs, which works well if you have such PDFs and your workflow allows for a manual process, though it's not suited for fully automated solutions or when specific tab names are required.

• Server templates are highly effective for documents that will be reused multiple times with unchanging tab locations. While template editing is a manual process, it allows for a clear separation of concerns, where code invokes the template and a separate team maintains it.

• Sender view provides a Docusign UI element for manual tab placement by the sending user. This is a viable option when full automation is not feasible, or the user is comfortable with manual tab placement.

• Freeform signing is considered a last-resort option, pushing the burden of tab placement entirely onto the recipient. This approach should be avoided whenever possible as it represents a design failure due to its reliance on the recipient for correct tab placement.

Understanding the nature of your documents, the level of automation desired, and the flexibility required in tab placement will guide you in leveraging Docusign API methods to configure envelopes efficiently. The synergy between Document Generation tools and methods such as anchor tags can significantly streamline tab placement for dynamically created documents.

Apply these decision points to your electronic signature project. Consider applying Document Generation to simplify creating publication-quality documents.

Additional resources

• Docusign Developer Center: Tabs

• eSignature REST API Reference: EnvelopeRecipientTabs Resource

• Tabs deep dive: tab types

• Tabs deep dive: Custom tabs

• Tabs deep dive: placing tabs in documents

• Common API Tasks🐈: Let your signers decide where to place the tabs for you