Adding Pre-filled Data to your Documents


The Dropbox API supports pre-filling data on a signature request document. This not only saves time for your senders and signers, but reduces the possibility of human error and adds precision to your documents.

You can use pre-filled data by adding merge fields to your document and passing values to the custom_fields parameter when sending a signature request. This guide will walk you through:


Before you start implementing pre-filled data, please make sure the following steps have been completed:

  1. Make sure that you have a Dropbox Sign Account with an API Key.
  2. Define if you are implementing an embedded or non-embedded workflow.
  3. Define the method you are going to implement to add fields on your document.

Note: You can fully test pre-filled data using a free Dropbox Sign API Plan with the test_mode parameter.

Merge Fields vs Custom Fields

In order to use pre-filled data with your signature requests you’ll need to implement both merge fields and custom_fields together. This is true for both non-embedded and embedded workflows.
Field TypeDescription
Merge FieldsThese fields will indicate where your pre-filled data will be placed on your documents. They can be set to be editable or non-editable and resolve to the values passed to them in custom_fields.
Custom FieldsThese fields specify the data you want to pre-fill the document with. The custom fields will pass values to the Merge fields in the document and allow you to specify options such as editable vs non-editable and if a field is required. The custom field name must match a merge field’s name in order for the value to populate.

We recommend limiting your merge fields to 200 or less per signature request. This allows for optimal performance and the best user experience when loading a specific document with merge fields. If you are creating an embedded template the number of merge fields to the document is 200. If you require an increase beyond this limit, please create a support ticket to reach out to the API Support Team for further assistance.

Note: Editable merge fields are only supported for single signer requests or the first signer of ordered signature requests. If more than one signer is assigned to the unordered signature request, any editor value is ignored and the field will not be editable.

Non-embedded and embedded requesting with pre-filled data

When implementing a non-embedded or embedded requesting workflow with pre-filled data, the requester will have the ability to adjust and modify merge fields on the document before sending a signature request.

In the case of editable merge fields for this type of workflow, this will create Text Fields assigned to the signer and the custom fields parameter will be ignored. If you apply non-editable merge fields for this type of workflow, this will create a Me (Now) Fields with the pre-filled data and will be applied to the document when the signature request is sent.