Merge Fields

Signeasy's API allows prefilling text information on Templates before sending them to your signers. This can be a perfect use case where your signers would expect to see specific details pre-populated on your document before signing.

Setting up Merge Label

Step 1: Login to your Signeasy account https://developer.signeasy.com
Step 2: Navigate to the Web app to Create/Edit a Template

Step 3: Add a Text Field, and when selecting the field, enable Field Automation from the right panel.

Step 4: Choose an appropriate name for your Merge Label. Note that this place will be displayed with the value you set in the API request.

Assigning the value to the Merge Label

Step 1: Once you've set up the labels in your template you can map those labels to a value in the API request.

Step 2: You can assign value to this label in the API request on our Envelope API

The syntax for setting a value for a label looks like this.

{
  "merge_fields": [
    {
      "label": "mergeLabel",
      "value": "value of the label",
      "source_id": 1
    }
  ]
}

Sample Request of Merge Fields in an API request

curl --location --request POST 'https://api.signeasy.com/v3/rs/envelope/' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "embedded_signing": true,
    "sources": [{
        "source_id": 1,
        "type": "template",
        "id": 1234567
    }],
    "is_ordered": 0,
    "recipients": [{
        "first_name": "John",
        "last_name": "Doe",
        "email": "[email protected]",
        "recipient_id": 1
    }],
    "message": "API TESTING",
    "merge_fields": [
        {
            "label": "employeeId",
            "value": "JOHN1234",
            "source_id": 1
        }
    ],
    "recipient_role_mapping": [{
        "role_id": 1,
        "recipient_id": 1,
        "source_id": 1
    }]
}'

Pre-fill by Sender or Earlier Signers

Everything above fills template fields that aren't assigned to anyone. Only the sender fills them, and no signer can edit them.

You can also pre-fill a field that's assigned to a signer. The field still belongs to that signer, who sees the pre-filled value and can always change it. It gets filled before they sign, by the sender, by a signer earlier in the signing order, or by both. This works on text, checkbox, and combobox fields, and it's available only on the API Advanced Plan.

Pre-fill by sender

Give the field a label, set fillable_by.sender to true, and put the value in prefill_value. For a checkbox, Yes ticks it. For a combobox, the value must match one of additional_info.options exactly. With embedded sending, the sender can also fill these fields in the sending view.

Pre-fill by earlier signers

List the signers who can fill the field in fillable_by.recipients, using their recipient_ids. They must sign before the field's own recipient, so set is_ordered to true and put them earlier in recipients. A signer group can't pre-fill.

Sample request

Jane signs first and John signs second. The sender fills John's employee ID, and Jane fills in his manager's name before John signs. John can change either value.

curl --location --request POST 'https://api.signeasy.com/v3/rs/envelope/' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "embedded_signing": false,
    "is_ordered": true,
    "message": "Please review and sign",
    "sources": [{
        "source_id": 1,
        "type": "original",
        "id": 1234567
    }],
    "recipients": [
        {
            "recipient_id": 1,
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "[email protected]"
        },
        {
            "recipient_id": 2,
            "first_name": "John",
            "last_name": "Smith",
            "email": "[email protected]"
        }
    ],
    "fields_payload": [
        {
            "recipient_id": 2,
            "source_id": 1,
            "type": "text",
            "required": true,
            "page_number": 1,
            "label": "Employee ID",
            "fillable_by": { "sender": true },
            "prefill_value": "JOHN1234",
            "position": { "mode": "fixed", "x": 100, "y": 600, "width": 160, "height": 24 }
        },
        {
            "recipient_id": 2,
            "source_id": 1,
            "type": "text",
            "required": true,
            "page_number": 1,
            "label": "Manager Name",
            "fillable_by": { "recipients": [1] },
            "position": { "mode": "fixed", "x": 100, "y": 560, "width": 160, "height": 24 }
        }
    ]
}'

Templates

On a template, set label and fillable_by on the field with the Update template API. For earlier signers, use fillable_by.roles with role_ids. For pre-fill by sender, pass the value in merge_fields with the field's label when you send from the template, the same way as the unassigned fields above.