Using Form Fields Per Document with Pre-filled Data

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.
Form Fields Per Document editable merge fieldsForm Fields Per Document non-editable merge fields:
Copy
Copied
[
    {
      "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
    }
]
Copy
Copied
[
    {
      "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": "sender",
      "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": "sender",
      "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": "sender",
      "page": 1
    }
]
The custom_fields value for the above form_fields_per_document:
Copy
Copied
[
  {"name":"firstname", "value":"John"},
  {"name":"lastname", "value":"Doe"},
  {"name":"is_registered", "value":"true"}
]

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

Send Signature Request Endpoint with Form Fields Per Document:

Non-editable Merge fields valueEditable Merge fields value
Copy
Copied
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}]]"'
Copy
Copied
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\": \"sender\",\"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\": \"sender\",\"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\": \"sender\",\"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\": \"sender\",\"page\": 1}]]"'

Create Embedded Signature Request Endpoint with Form Fields Per Document:

Non-editable Merge fields valueEditable Merge fields value
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-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}]]"'
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-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\": \"sender\",\"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\": \"sender\",\"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\": \"sender\",\"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\": \"sender\",\"page\": 1}]]"'

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

Create Unclaimed Draft Endpoint with Form Fields Per Document

Non-editable Merge fields valueEditable Merge fields value
Copy
Copied
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}]]"'
Copy
Copied
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\": \"sender\",\"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\": \"sender\",\"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\": \"sender\",\"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\": \"sender\",\"page\": 1}]]"'

Create Embedded Unclaimed Draft Endpoint with editable merge fields:

Non-editable Merge fields valueEditable Merge fields value
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.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}]]"'
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.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\": \"sender\",\"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\": \"sender\",\"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\": \"sender\",\"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\": \"sender\",\"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 documents x/y coordinates will cause an error and the signature request will not be sent.