Using Text Tags with Pre-filled Data

Overview

Text tags are strings with a specific syntax, that are replaced by fields when parsed by Dropbox Sign during document workflows. You can read more about them in our Text Tags Walkthrough. Text tags allow you to incorporate pre-filled data into source documents that are passed to the Dropbox Sign API.

Using pre-filled data with text tags is an excellent way to use documents generated by third-party tools as source files for Dropbox Sign signature flows. We recommend using PDF files while using Text Tags. Other formats, such as plain text, may not render the tag correctly.

Example Text Tags with Pre-filled Data

Once the Text Tags is added to your document, you can execute a Dropbox Sign API endpoint to send the signature request. When making the request to the Dropbox Sign API, set the property use_text_tags to true and provide your data values in the custom_fields property.

Example Text tags with non-editable merge fields

Copy
Copied
[sig|req|signer1|customer_signature|customer_id]
[text-merge|req|sender|firstname|firstname_api_id]
[text-merge|req|sender|lastname|lastname_api_id]
[checkbox-merge|req|sender|is_registered|product_id]

Example Text tags with editable merge field

Copy
Copied
[sig|req|signer1|customer_signature|customer_id]
[text-merge|req|signer1|firstname|firstname_api_id]
[text-merge|req|signer1|lastname|lastname_api_id]
[checkbox-merge|req|signer1|is_registered|product_id]
Usage of custom_fields parameter for the above text tag:
Copy
Copied
[
  {"name":"firstname", "value":"John"},
  {"name":"lastname", "value":"Doe"},
  {"name":"is_registered", "value":"true"}
]

Using Text Tags with Pre-filled Data with non-embedded signing and embedded signing

Send Signature Request Endpoint with text tags

Copy
Copied
curl -X POST 'https://api.hellosign.com/v3/signature_request/send' \
    -u 'YOUR_API_KEY:' \
    -F 'files[0]=@test_text_editable.pdf' \
    -F 'title=NDA with Acme Co.' \
    -F 'subject=The NDA we talked about' \
    -F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
    -F 'signers[0][email_address]=jack@example.com' \
    -F 'signers[0][name]=Jack' \
    -F 'test_mode=1'\
    -F 'custom_fields=[{"name":"firstname", "value":"John"},{"name":"lastname", "value":"Doe"},{"name":"is_registered", "value":"true"}]' \
    -F 'use_text_tags=1'

Create Embedded Signature Request Endpoint with text tags

Copy
Copied
curl -X POST 'https://api.hellosign.com/v3/signature_request/create_embedded' \
    -u 'YOUR_API_KEY:' \
    -F 'client_id=YOUR_CLIENT_ID' \
    -F 'files[0]=@test_text_editable.pdf' \
    -F 'title=NDA with Acme Co.' \
    -F 'subject=The NDA we talked about' \
    -F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
    -F 'signers[0][email_address]=jack@example.com' \
    -F 'signers[0][name]=Jack' \
    -F 'test_mode=1'\
    -F 'custom_fields=[{"name":"firstname", "value":"John"},{"name":"lastname", "value":"Doe"},{"name":"is_registered", "value":"true"}]' \
    -F 'use_text_tags=1'

Using Text Tags with Pre-filled Data with non-embedded requesting and embedded requesting.

Create Unclaimed Draft Endpoint with text tags

Copy
Copied
curl -X POST 'https://api.hellosign.com/v3/unclaimed_draft/create' \
    -u 'YOUR_API_KEY:' \
    -F 'files[0]=@test_text_editable.pdf' \
    -F 'type=request_signature' \
    -F 'subject=The NDA we talked about' \
    -F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
    -F 'signers[0][email_address]=jack@example.com' \
    -F 'signers[0][name]=Jack' \
    -F 'test_mode=1'\
    -F 'custom_fields=[{"name":"firstname", "value":"John"},{"name":"lastname", "value":"Doe"},{"name":"is_registered", "value":"true"}]' \
    -F 'use_text_tags=1'

Create Embedded Unclaimed Draft Endpoint with text tags

Copy
Copied
curl -X POST 'https://api.hellosign.com/v3/unclaimed_draft/create_embedded' \
    -u 'YOUR_API_KEY:' \
    -F 'client_id=YOUR_CLIENT_ID' \
    -F 'signers[0][email_address]=jack@example.com' \
    -F 'signers[0][name]=Jack' \
    -F 'files[0]=@test_text_editable.pdf' \
    -F 'requester_email_address=jane@example.com' \
    -F 'test_mode=1'\
    -F 'custom_fields=[{"name":"firstname", "value":"John"},{"name":"lastname", "value":"Doe"},{"name":"is_registered", "value":"true"}]' \
    -F 'use_text_tags=1'

Things to consider

For further information on using Text Tags please review our Text Tag Walkthrough. Below are some highlights of things to consider when using Text Tags:

  • Pre-filled data is only supported for text-merge and checkbox-merge fields with text tags.
  • When implementing pre-filled fields with non-embedded or embedded requests, the requester/sender can adjust these fields prior to sending the signature request.
  • Hide your text tags by making the font the same color as the background (i.e. white on white).
  • Text tags with incorrect formatting will fail silently. We recommend using callbacks and events to listen for a signature_request_invalid event to catch incorrect text tags.