Skip to navigation
eSignature API 101eSignature conceptsTabs

Prefilled tabs

View as Markdown
eSignature REST API 2.1 only

When you need to add tab data to one of your documents while sending your envelope, you can do that using prefilled tabs. A prefilled tab is a tab whose value is set by the sender and inserted to a document prior to sending its envelope to its recipients. These tabs are visible to all recipients during signing, but cannot be edited by them.

This enables you to:

  • Prefill data in a document during sending without using read-only tabs.
  • Edit the prefilled tab data via the correct option before recipients have acted on the document.
  • Add data to a document during sending that is not associated with a specific recipient.

You can use the following tab types for prefilled tabs:

  • Text
  • Checkbox
  • Radio
  • Company
  • Name

To define one or more prefilled tabs, enter your tab definition data in the new prefillTabs attribute alongside your other tab definition objects.

Note: Prefilled tabs are available to all developer accounts for development and testing, but not all account plans provide access to prefilled tabs in the production environment. Make sure your plan includes this feature before developing against it.

For a full list of available Docusign eSignature tab types, see the EnvelopeRecipientTabs Resource in the API Reference.

Using prefilled tabs

You can add a prefilled tab to a document in the same way you would add any other tab, using the EnvelopeDocumentTabs: create API method or its SDK equivalent. Rather than define the prefilled tab JSON directly within the tabs object, they are added to a new child object, prefillTabs, which will contain the tab declarations.

There is no separate API or endpoint specifically for prefilled tabs. Prefilled tabs are standard tabs with values set before the envelope is sent. To prefill a tab, include the tab definition and set its value when creating the envelope or recipient. The following JSON shows how to define a prefilled textTab within the tabs object of your document:

"tabs":
{
  "prefillTabs":{
    "textTabs": [
      {
        "tabLabel": "Text 2db4770d-xxxx-xxxx-xxxx-cef65ebd1a6a",
        "conditionalParentLabel": null,
        "conditionalParentValue": null,
        "fontSize": "size9",
        "underline": false,
        "italic": false,
        "fontColor": "black",
        "bold": false,
        "font": "lucidaconsole",
        "required": true,
        "locked": false,
        "concealValueOnDocument": false,
        "name": "",
        "shared": false,
        "requireAll": false,
        "requireInitialOnSharedChange": false,
        "value": "",
        "validationPattern": "",
        "validationMessage": "",
        "disableAutoSize": false,
        "maxLength": 4000,
        "width": 84,
        "height": 22,
        "mergeFieldXml": "",
        "pageNumber": 1,
        "documentId": "1",
        "xPosition": 104,
        "yPosition": 94
      }
    ]
  }
}

To get a list of all tabs (including prefilled tabs) in the documents of an envelope, use the EnvelopeDocuments:get API method or its SDK equivalent.

You can also add, update, or delete prefilled tabs data in your documents with the following API methods or their SDK equivalents:

Using prefilled tabs with composite templates

When you create a composite template with one or more templates that include documents that have prefilled tabs, the following rules determine whether the prefilled tabs are retained in the composite template.

  • If either the server template or inline template has prefilled tabs, but the other template does not, the tabs will be added to the envelope documents regardless of the sequence values of the templates.
  • If both server template and inline template have defined different prefilled tabs, then all of the tabs from all templates will be added, regardless of the sequence value of the templates.
  • If both the server template and inline template have the same prefilled tabs (prefilled tabs with the same tabLabel value) but have configured them with different properties, the prefilled tabs from the template with the lower sequence value will be used.