> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hellosign.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hellosign.com/_mcp/server.

> Adding your data to your document for a signature request using Form Fields Per Document.

# 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](/api/manual-reference-pages/constants#field-types) 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.

```json maxLines=0 Form Fields Per Document editable merge fields

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

```json maxLines=0 Form Fields Per Document non-editable merge fields:

[
    {
      "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`:

```json
[
  {"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:

```bash Non-editable Merge fields value

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}]]"'
```

```bash Editable Merge fields value

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:

```bash Non-editable Merge fields value


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}]]"'
```

```bash Editable Merge fields value


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

```bash Non-editable Merge fields value

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}]]"'
```

```bash Editable Merge fields value

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:

```bash Non-editable Merge fields value

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}]]"'
```

```bash Editable Merge fields value

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 document's x/y coordinates will cause an error and the signature request will not be sent.