# Form Fields

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

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

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:

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

### Create Embedded Signature Request Endpoint with Form Fields Per Document:

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

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

### Create Unclaimed Draft Endpoint with Form Fields Per Document

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

### Create Embedded Unclaimed Draft Endpoint with editable merge fields:

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

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