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.
Pre-fill and API PlansMerge fields, the template fields that aren't assigned to anyone, are available on the API Intermediate Plan and the API Advanced Plan. Pre-fill by the sender or by an earlier signer, on a field that belongs to a signer, is available only on the API Advanced Plan. You can try both in any sandbox app. Reach support or sales for more details.
Setting up Merge Label
Step 1: Sign in to the developer portal and choose Templates in the sidebar.
Step 2: Create a template, or edit one you already have.
Step 3: Drag a Text field onto the document. With the field selected, tick Pre-fill field in the Properties panel on the right. Pre-fill is only available on text fields.
Step 4: Set the Field label. This is the merge label you pass as label in the API request. Leave Roles empty so only the sender fills the field, then choose Save Template.
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
}
]
}When you send the envelope, the value fills the field before anyone opens the document.
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.
Updated 1 day ago