# Templates

> Adding your data to your document for a signature request using Templates.

# 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](/docs/walkthroughs/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

Non-embedded Templates are templates that are created on the Dropbox Sign Website. Using non-embedded Templates in the Dropbox Sign API production environment requires an `Essential API` or higher subscription plan.

You can add prefilled data to your template fields by adding Merge Fields in the document editor UI, then using the signature request's `custom_fields` property.

### 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.

<AccordionGroup>
  <Accordion title="Click here to view an example screenshot of the following workflow">
    <img src="https://files.buildwithfern.com/https://dropbox123432.docs.buildwithfern.com/81b19572e7b8c0628f7ff4609d69f00a8400d9d306c502da6b378c7a334f8c5b/docs/adding-pre-filled-data/img/non-embedded-template-prefill-data.png" alt="Screenshot of non-embedded templates with Merge Fields" />
  </Accordion>
</AccordionGroup>

<Steps>
  <Step>
    [Create a new template](https://faq.hellosign.com/hc/en-us/articles/211241477) or [edit an existing template](https://faq.hellosign.com/hc/en-us/articles/210562868) via the document editor.
  </Step>

  <Step>
    Click the dropdown menu below **Assigned to** in the left sidebar.
  </Step>

  <Step>
    Click **Sender**.
  </Step>

  <Step>
    Click and drag a Textbox from the left sidebar to your document.
  </Step>

  <Step>
    Give the field a name in the box below **Merge field**.
  </Step>

  <Step>
    Once you've added all your **Merge fields** and Signature Fields, click Next.
  </Step>

  <Step>
    Add a template title. You can also add CC recipients and a default message for signers as well.
  </Step>

  <Step>
    Click Save template. Note the template's `template_id` which will be used with the Dropbox Sign API.
  </Step>

  <Step>
    When sending a Signature Request with the template, you will use the `custom_fields` property to insert pre-filled data into the Merge fields.
  </Step>
</Steps>

<CodeBlock>
  ```json Non-editable custom fields value
  [
    {"name":"firstname", "value":"John"},
    {"name":"lastname", "value":"Doe"},
    {"name":"is_registered", "value":"true"}
  ]
  ```

  ```json Editable custom fields value

  [
    {"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}
  ]
  ```
</CodeBlock>

### Send with Template Endpoint with Pre-filled Data Example

<CodeBlock>
  ```bash Non-editable custom fields value
  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'
  ```

  ```bash Editable custom fields value
  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'
  ```
</CodeBlock>

### 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

Embedded templates allow users to create and edit templates within an iFrame in your application. The Merge Fields that your user can add to their Embedded Template are specified by using the `merge_field` request property.

<Note icon="fa-light fa-triangle-exclamation">
  **Note:** Embedded Templates require a Premium API Plan to be used in Production.
</Note>

### Workflow of adding Pre-filled Data with embedded Templates

These instructions detail how to create an embedded template draft using the `merge_field` request property. The API response will include an `edit_url`, which is used as the iFrame source. Your user can then place their signature and merge fields on the embedded template.

<AccordionGroup>
  <Accordion title="Click here to view an example screenshot of the following workflow">
    <img src="https://files.buildwithfern.com/https://dropbox123432.docs.buildwithfern.com/92cd8cdf0a6d61b375e19c6d45a517b53b68520c3a986838b9b352c39617de3d/docs/adding-pre-filled-data/img/embedded-template-prefill-data.png" alt="Screenshot of non-embedded templates with Merge Fields" />
  </Accordion>
</AccordionGroup>

<Steps>
  <Step>
    Send a request to [/template/create\_embedded\_draft](/api/template/create-embedded-draft) and add your merge fields using the `merge_field` property.
  </Step>

  <Step>
    Copy the `edit_url` of the embedded template draft from the response object.
  </Step>

  <Step>
    Open the `edit_url` in your application using the [hellosign-embedded](https://github.com/hellosign/hellosign-embedded) library. For this example workflow, you can use our [Embedded Testing Tool](/docs/additional-resources/embedded-testing-tool) to create the embedded template, which will open in a Dropbox Sign iFrame.
  </Step>

  <Step>
    Click the dropdown menu below **Assigned to** in the left sidebar.
  </Step>

  <Step>
    Click **Sender**.
  </Step>

  <Step>
    Drag and drop your merge fields(textbox or checkbox fields) from the left sidebar on your document.
  </Step>

  <Step>
    On the right sidebar, under "What text goes here?", select the Merge Field name you would like to use on your template.
  </Step>

  <Step>
    Once you've added all your Signature and Merge fields on your template, click Continue to complete the embedded template.
  </Step>

  <Step>
    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.
  </Step>

  <Step>
    When sending a Signature Request with template, you will need to use the `custom_fields` parameter for the **Merge fields** to be pre-filled.
  </Step>
</Steps>

<CodeBlock>
  ```json Non-editable custom fields value
  [
    {"name":"firstname", "value":"John"},
    {"name":"lastname", "value":"Doe"},
    {"name":"is_registered", "value":"true"}
  ]
  ```

  ```json Editable custom fields value
  [
    {"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}
  ]
  ```
</CodeBlock>

### Create Embedded Template Draft Endpoint with Merge Fields Example

```bash
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

<CodeBlock>
  ```bash Non-editable custom fields value
  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'
  ```

  ```bash Editable custom fields value

  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'

  ```
</CodeBlock>

### 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](/api/embedded/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.