Using Templates with Pre-filled Data

Overview

Templates are an effective method for preserving document formatting and enabling their reuse in the future. If you add Embedded Templates to your web application, your users can even create their own templates. Adding pre-filled data to templates makes sending signature requests even easier.

Using Non-embedded Templates with Pre-filled Data

How to Add Pre-filled Data with Non-embedded Templates

These instructions detail how to create a non-embedded Template on the Dropbox Sign Website, add your Signature and Merge Fields to your document, and send a signature request with pre-filled data.

Click here to view an example screenshot of the following workflow

1. Create a new template or edit an existing template via the document editor.
2. Click the dropdown menu below Assigned to in the left sidebar.
3. Click Sender.
4. Click and drag a Textbox from the left sidebar to your document.
5. Give the field a name in the box below Merge field.
6. Once you’ve added all your Merge fields and Signature Fields, click Next.
7. Add a template title. You can also add CC recipients and a default message for signers as well.
8. Click Save template. Note the template's template_id which will be used with the Dropbox Sign API.
9. When sending a Signature Request with the template, you will use the custom_fields property to insert pre-filled data into the Merge fields.

[
  {"name":"firstname", "value":"John"},
  {"name":"lastname", "value":"Doe"},
  {"name":"is_registered", "value":"true"}
]

[
  {"name":"firstname", "value":"John", "editor":"ExampleRole", "required":true},
  {"name":"lastname", "value":"Doe","editor":"ExampleRole", "required":true},
  {"name":"is_registered", "value":"true","editor":"ExampleRole", "required":true}
]

Send with Template Endpoint with Pre-filled Data Example

curl 'https://api.hellosign.com/v3/signature_request/send_with_template' \
    -u 'YOUR_API_KEY:' \
    -F 'template_id=YOUR_TEMPLATE_ID' \
    -F 'subject=Purchase Order' \
    -F 'message=Glad we could come to an agreement.' \
    -F 'signers[ExampleRole][name]=John' \
    -F 'signers[ExampleRole][email_address]=john@example.com' \
    -F 'custom_fields=[{"name":"firstname", "value":"John"},{"name":"lastname", "value":"Doe"},{"name":"is_registered", "value":"true"}]' \
    -F 'test_mode=1'

curl 'https://api.hellosign.com/v3/signature_request/send_with_template' \
    -u 'YOUR_API_KEY:' \
    -F 'template_id=YOUR_TEMPLATE_ID' \
    -F 'subject=Purchase Order' \
    -F 'message=Glad we could come to an agreement.' \
    -F 'signers[ExampleRole][name]=John' \
    -F 'signers[ExampleRole][email_address]=john@example.com' \
    -F 'custom_fields=[{"name":"firstname", "value":"John", "editor":"ExampleRole", "required":true},{"name":"lastname", "value":"Doe","editor":"ExampleRole", "required":true},{"name":"is_registered", "value":"true","editor":"ExampleRole", "required":true}]' \
    -F 'test_mode=1'

Things to consider:

• The Merge Fields will need to be assigned to the Signer Role Sender. The Sender role is pre-built within the template and used for Merge fields.
• The Merge Field name on your template will need to match the custom_fields value to pre-fill the data.
• A custom_fields error will occur if your custom_fields value doesn't match your Merge Field name on your template.

Using Embedded Templates with Pre-filled Data

Workflow of adding Pre-filled Data with embedded Templates

Click here to view an example screenshot of the following workflow

1. Send a request to /template/create_embedded_draft and add your merge fields using the merge_field property.
2. Copy the edit_url of the embedded template draft from the response object.
3. Open the edit_url in your application using the hellosign-embedded library. For this example workflow, you can use our Embedded Testing Tool to create the embedded template, which will open in a Dropbox Sign iFrame.
4. Click the dropdown menu below Assigned to in the left sidebar.
5. Click Sender.
6. Drag and drop your merge fields(textbox or checkbox fields) from the left sidebar on your document.
7. On the right sidebar, under “What text goes here?”, select the Merge Field name you would like to use on your template.
8. Once you’ve added all your Signature and Merge fields on your template, click Continue to complete the embedded template.
9. Once you complete the embedded template creation on the iFrame, you can use the template_id to send a signature request with the Dropbox Sign API.
10. When sending a Signature Request with template, you will need to use the custom_fields parameter for the Merge fields to be pre-filled.

[
  {"name":"firstname", "value":"John"},
  {"name":"lastname", "value":"Doe"},
  {"name":"is_registered", "value":"true"}
]

[
  {"name":"firstname", "value":"John", "editor":"ExampleRole", "required":true},
  {"name":"lastname", "value":"Doe","editor":"ExampleRole", "required":true},
  {"name":"is_registered", "value":"true","editor":"ExampleRole", "required":true}
]

Create Embedded Template Draft Endpoint with Merge Fields Example

curl 'https://api.hellosign.com/v3/template/create_embedded_draft' \
    -u 'YOUR_API_KEY:' \
    -F 'test_mode=1' \
    -F 'client_id=YOUR_CLIENT_ID' \
    -F 'file[0]=@NDA.pdf' \
    -F 'title=Test Template' \
    -F 'subject=Please sign this document' \
    -F 'message=For your approval.' \
    -F 'signer_roles[0][name]=ExampleRole' \
    -F 'merge_fields=[{"name":"firstname","type":"text"},{"name":"lastname","type":"text"},{"name":"is_registered","type":"checkbox"}]'

Send with Template Endpoint with Pre-filled Data Example

curl 'https://api.hellosign.com/v3/signature_request/send_with_template' \
    -u 'YOUR_API_KEY:' \
    -F 'template_id=YOUR_TEMPLATE_ID' \
    -F 'subject=Purchase Order' \
    -F 'message=Glad we could come to an agreement.' \
    -F 'signers[ExampleRole][name]=John' \
    -F 'signers[ExampleRole][email_address]=john@example.com' \
    -F 'custom_fields=[{"name":"firstname", "value":"John"},{"name":"lastname", "value":"Doe"},{"name":"is_registered", "value":"true"}]' \
    -F 'test_mode=1'

curl 'https://api.hellosign.com/v3/signature_request/send_with_template' \
    -u 'YOUR_API_KEY:' \
    -F 'template_id=YOUR_TEMPLATE_ID' \
    -F 'subject=Purchase Order' \
    -F 'message=Glad we could come to an agreement.' \
    -F 'signers[ExampleRole][name]=John' \
    -F 'signers[ExampleRole][email_address]=john@example.com' \
    -F 'custom_fields=[{"name":"firstname", "value":"John", "editor":"ExampleRole", "required":true},{"name":"lastname", "value":"Doe","editor":"ExampleRole", "required":true},{"name":"is_registered", "value":"true","editor":"ExampleRole", "required":true}]' \
    -F 'test_mode=1'

Things to consider:

• Embedded Templates will be in a draft state until they are completed in the embedded iFrame.
• Your user won’t be able to add new Merge Fields within the embedded Iframe. They must be set up previously, in the embedded template request.
• If you need to edit or add a Merge Field to an existing Embedded Template you will need to execute the Get Embedded Template Edit URL Endpoint with the merge_field parameter specifying the new Merge Fields for the template.
  • Merge fields already placed by the user remain on the template while the user must place the newly added ones.