GuidesPre-filled Document Data

Using Form Fields Per Document with Pre-filled Data

View as Markdown

Overview

Using pre-filled data with form_fields_per_document allows you to add data on your documents without the need for a template. Fields are programmatically placed on a document with form_fields_per_document using a x/y coordinate system. It’s well-suited for working with dynamically generated documents, transferring field mappings from old documents to new ones, and more.

Form Fields per Document Structure with Pre-filled Data

To add pre-filled data into Merge Fields, use the form_fields_per_document parameter and specify the field type as either text-merge or checkbox-merge. This creates the data fields, which can then be populated with data in the custom_fields property in the request.

1[
2    {
3      "document_index": 0,
4      "api_id": "signature_api_id",
5      "name": "main_signature",
6      "type": "signature",
7      "x": 100,
8      "y": 120,
9      "width": 120,
10      "height": 30,
11      "required": true,
12      "signer": 0,
13      "page": 1
14    },
15    {
16      "document_index": 0,
17      "api_id": "firstname_api_id",
18      "name": "firstname",
19      "type": "text-merge",
20      "x": 100,
21      "y": 170,
22      "width": 80,
23      "height": 25,
24      "required": true,
25      "signer": 0,
26      "page": 1
27    },
28    {
29      "document_index": 0,
30      "api_id": "lastname_api_id",
31      "name": "lastname",
32      "type": "text-merge",
33      "x": 100,
34      "y": 210,
35      "width": 80,
36      "height": 25,
37      "required": true,
38      "signer": 0,
39      "page": 1
40    },
41    {
42      "document_index": 0,
43      "api_id": "is_registered_id",
44      "name": "is_registered",
45      "type": "checkbox-merge",
46      "x": 100,
47      "y": 250,
48      "width": 15,
49      "height": 15,
50      "required": true,
51      "signer": 0,
52      "page": 1
53    }
54]

The custom_fields value for the above form_fields_per_document:

1[
2  {"name":"firstname", "value":"John"},
3  {"name":"lastname", "value":"Doe"},
4  {"name":"is_registered", "value":"true"}
5]

Using Form Fields per Document with non-embedded and embedded signing

Send Signature Request Endpoint with Form Fields Per Document:

$curl -X POST 'https://api.hellosign.com/v3/signature_request/send' \
>  -u 'YOUR_API_KEY:' \
>  -F 'files[0]=@test-file.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 'form_fields_per_document="[[{\"document_index\": 0,\"api_id\": \"signature_api_id\",\"name\": \"main_signature\",\"type\": \"signature\",\"x\": 100,\"y\": 120,\"width\": 120,\"height\": 30,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"firstname_api_id\",\"name\": \"firstname\",\"type\": \"text-merge\",\"x\": 100,\"y\": 170,\"width\": 80,\"height\": 25 ,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"lastname_api_id\",\"name\": \"lastname\",\"type\": \"text-merge\",\"x\": 100,\"y\": 210,\"width\": 80,\"height\": 25 ,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"is_registered_id\",\"name\": \"is_registered\",\"type\": \"checkbox-merge\",\"x\": 100,\"y\": 250,\"width\": 15,\"height\": 15,\"required\": true,\"signer\": 0,\"page\": 1}]]"'

Create Embedded Signature Request Endpoint with Form Fields Per Document:

$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-file.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 'form_fields_per_document="[[{\"document_index\": 0,\"api_id\": \"signature_api_id\",\"name\": \"main_signature\",\"type\": \"signature\",\"x\": 100,\"y\": 120,\"width\": 120,\"height\": 30,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"firstname_api_id\",\"name\": \"firstname\",\"type\": \"text-merge\",\"x\": 100,\"y\": 170,\"width\": 80,\"height\": 25 ,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"lastname_api_id\",\"name\": \"lastname\",\"type\": \"text-merge\",\"x\": 100,\"y\": 210,\"width\": 80,\"height\": 25 ,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"is_registered_id\",\"name\": \"is_registered\",\"type\": \"checkbox-merge\",\"x\": 100,\"y\": 250,\"width\": 15,\"height\": 15,\"required\": true,\"signer\": 0,\"page\": 1}]]"'

Using Form Fields per Document with non-embedded requesting and embedded requesting.

Create Unclaimed Draft Endpoint with Form Fields Per Document

$curl -X POST 'https://api.hellosign.com/v3/unclaimed_draft/create' \
>  -u 'YOUR_API_KEY:' \
>  -F 'type=request_signature' \
>  -F 'files[0]=@test-file.pdf' \
>  -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 'form_fields_per_document="[[{\"document_index\": 0,\"api_id\": \"signature_api_id\",\"name\": \"main_signature\",\"type\": \"signature\",\"x\": 100,\"y\": 120,\"width\": 120,\"height\": 30,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"firstname_api_id\",\"name\": \"firstname\",\"type\": \"text-merge\",\"x\": 100,\"y\": 170,\"width\": 80,\"height\": 25 ,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"lastname_api_id\",\"name\": \"lastname\",\"type\": \"text-merge\",\"x\": 100,\"y\": 210,\"width\": 80,\"height\": 25 ,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"is_registered_id\",\"name\": \"is_registered\",\"type\": \"checkbox-merge\",\"x\": 100,\"y\": 250,\"width\": 15,\"height\": 15,\"required\": true,\"signer\": 0,\"page\": 1}]]"'

Create Embedded Unclaimed Draft Endpoint with editable merge fields:

$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.pdf' \
>  -F 'requester_email_address=alice@example.com' \
>  -F 'test_mode=1'\
>  -F 'custom_fields=[{"name":"firstname", "value":"John"},{"name":"lastname", "value":"Doe"},{"name":"is_registered", "value":"true"}]' \
>  -F 'form_fields_per_document="[[{\"document_index\": 0,\"api_id\": \"signature_api_id\",\"name\": \"main_signature\",\"type\": \"signature\",\"x\": 100,\"y\": 120,\"width\": 120,\"height\": 30,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"firstname_api_id\",\"name\": \"firstname\",\"type\": \"text-merge\",\"x\": 100,\"y\": 170,\"width\": 80,\"height\": 25 ,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"lastname_api_id\",\"name\": \"lastname\",\"type\": \"text-merge\",\"x\": 100,\"y\": 210,\"width\": 80,\"height\": 25 ,\"required\": true,\"signer\": 0,\"page\": 1},
>    {\"document_index\": 0,\"api_id\": \"is_registered_id\",\"name\": \"is_registered\",\"type\": \"checkbox-merge\",\"x\": 100,\"y\": 250,\"width\": 15,\"height\": 15,\"required\": true,\"signer\": 0,\"page\": 1}]]"'

Things to consider

  • You’ll need to use both the form_fields_per_document and custom_fields parameters in the same API request to pre-fill data on the fields of the document.
  • The ability to make pre-filled fields editable or non-editable for your signers is set in the form_fields_per_document signer fields.
  • When implementing pre-filled fields with non-embedded or embedded requesting, the requester/sender can adjust these fields prior to sending a signature request.
  • Placing your pre-filled fields outside the document’s x/y coordinates will cause an error and the signature request will not be sent.