Migrating Signature Requests using Templates and Merge Fields
Sending Signature requests using templates with merge fields is one of the common flows used by customers on Signeasy.
Below are the steps to migrate your existing integration to v2.
Create a request signature using templates.
POST /v1/files/pending/template/
{
"template_file_id": 113443,
{
"recipients": [
{
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"role_id": 1
}
],
"is_ordered": 0,
"name": "Employee Contract - John Doe.pdf",
"message": "Kindly sign it within a week",
"embedded_signing": 0
}
}
POST /v2/template/<template_id>/rs/
{
{
"recipients": [
{
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"role_id": 1
}
],
"is_ordered": 0,
"name": "Employee Contract.pdf",
"message": "Kindly sign it within a week",
"embedded_signing": 0
}
}
POST /v2.1/rs/envelope/
{
"embedded_signing": true,
"sources": [{
"source_id": 1,
"type": "template",
"id": 4000000
}, {
"source_id": 2,
"type": "template",
"id": 4000001
}],
"is_ordered": 0,
"recipients": [{
"first_name": "john",
"last_name": "doe",
"email": "[email protected]",
"recipient_id": 1
},{
"first_name": "jacob",
"last_name": "Doe",
"email": "[email protected]",
"recipient_id": 2
}],
"message": "Signature Request with Templates v2.1",
"recipient_role_mapping": [{
"role_id": 1,
"recipient_id": 1,
"source_id": 1
},{
"role_id": 2,
"recipient_id": 2,
"source_id": 1
},{
"role_id": 3,
"recipient_id": 1,
"source_id": 2
},{
"role_id": 4,
"recipient_id": 2,
"source_id": 2
}],
"signature_panel_types": ["draw"]
}
Create a request signature using templates with merge fields
POST /v1/files/pending/template/
{
"template_file_id": 113443,
{
"recipients": [
{
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"role_id": 1
}
],
"is_ordered": 0,
"name": "Employee Contract - New Joinee.pdf",
"message": "Kindly sign it within a week",
"embedded_signing": 0,
"merge_fields": [
{
"label": "name",
"value": "John"
}
]
}
}
POST /v2/template/<template_id>/rs/
{
{
"recipients": [
{
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"role_id": 1
}
],
"is_ordered": 0,
"name": "Employee Contract - New Joinee.pdf",
"message": "Kindly sign it within a week",
"embedded_signing": 0,
"merge_fields": [
{
"label": "name",
"value": "John"
}
]
}
}
POST /v2.1/rs/envelope/
{
"embedded_signing": true,
"sources": [{
"source_id": 1,
"type": "template",
"id": 4000000
}],
"is_ordered": 0,
"recipients": [{
"first_name": "john",
"last_name": "doe",
"email": "[email protected]",
"recipient_id": 1
},{
"first_name": "jacob",
"last_name": "Doe",
"email": "[email protected]",
"recipient_id": 2
}],
"message": "Signature Request with Templates + Merge Fields v2.1",
"merge_fields": [
{
"label": "uniqueID",
"value": "1234-abcd",
"source_id": 1
}
],
"recipient_role_mapping": [{
"role_id": 1,
"recipient_id": 1,
"source_id": 1
},{
"role_id": 2,
"recipient_id": 2,
"source_id": 1
}],
"signature_panel_types": ["draw"]
}
Fetch the details of the Signature Request
GET /v1/files/pending/<pending_id>/
{
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235649,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - Jane Doe.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "John",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557465369,
"email": "[email protected]",
"first_name": "Jane",
"last_modified_time": 1591780421,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377928,
"recipient_user_id": 3625901,
"status": "viewed"
}
],
"status": "incomplete"
}
GET /v2/rs/template/<pending_id>/
{
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235645,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - New Joinee.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "John",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557465369,
"email": "[email protected]",
"first_name": "John",
"last_modified_time": 1591780421,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377928,
"recipient_user_id": 3625901,
"status": "viewed"
}
],
"status": "incomplete"
}
GET /v2.1/rs/envelope/3000000
{
"cc": [],
"owner_email": "[email protected]",
"created_time": 1650266260,
"last_modified_time": 1650266504,
"message": "Hiring Letter - John",
"public_link": "0",
"subject": "",
"owner_first_name": "Jane",
"is_embedded_signing": 1,
"id": 3000000,
"is_envelope": 1,
"owner_last_name": "",
"next": 6248933,
"envelope_size": 1,
"is_in_person": 0,
"aadhaar_enabled": 0,
"status": "complete",
"recipients": [
{
"status": "finalized",
"phone_number": "",
"first_name": "John",
"last_name": "Doe",
"otp_type": "",
"verification_status": 0,
"order_id": 1,
"verification_time": null,
"created_time": 1650266263,
"recipient_user_id": 5112872,
"recipient_id": 6248933,
"country_code": "",
"last_modified_time": 1650266502,
"2fa_enable": false,
"email": "[email protected]"
}
],
"is_ordered": 0,
"has_markers": 1,
"owner_user_id": 8161249,
"is_readonly": 0,
"has_radio_buttons": 0,
"owner_company": "Jane Doe Industries",
"sources": [
{
"type": "template",
"id": 4247045,
"name": "Offer Letter"
}
]
}
Remind all signers of the Signature Request
POST /v1/files/pending/<pending_id>/remind/
POST /v2/template/rs/<pending_id>/remind/
POST /v2.1/rs/envelope/{pending_file_id}/remind/
Cancel the Signature Request
POST /v1/files/pending/<pending_id>/cancel/
POST /v2/template/rs/<pending_id>/cancel/
POST v2.1/rs/envelope/{pending_file_id}/cancel/
List all Signature Requests
The v1 API suite did not support the fetching of only the Signature Requests created using templates. With v2 the endpoint GET /v2/template/rs/ supports fetching only the requests created using templates.
GET /v1/files/pending/
{
"count":2,
"files":[
{
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235641,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - Jane.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "John",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557465369,
"email": "[email protected]",
"first_name": "Jane",
"last_modified_time": 1591780421,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377928,
"recipient_user_id": 3625901,
"status": "viewed"
}
],
"status": "incomplete"
},
{
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235641,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - New Joinee.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "John",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557422123,
"email": "[email protected]",
"first_name": "Jane",
"last_modified_time": 1591780425,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377929,
"recipient_user_id": 3625921,
"status": "viewed"
}
],
"status": "incomplete"
}
]
}
GET /v2/template/rs/
{
"count":2,
"files":[
{
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235641,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - New Joinee.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "John",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557465369,
"email": "[email protected]",
"first_name": "John",
"last_modified_time": 1591780421,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377928,
"recipient_user_id": 3625901,
"status": "viewed"
}
],
"status": "incomplete"
},
{
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235641,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - John.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "John",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557422123,
"email": "[email protected]",
"first_name": "John",
"last_modified_time": 1591780425,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377929,
"recipient_user_id": 3625921,
"status": "viewed"
}
],
"status": "incomplete"
}
]
}
GET /v2.1/rs/envelope/
List all Completed Signature requests
The v1 API suite did not support the fetching of only the completed Signature Requests created using templates. With v2 the endpoint GET /v2/template/rs/signed/ supports fetching only the requests created using templates.
GET /v1/files/signed/
{
"count": 2,
"files": [
{
"aadhaar_enabled": null,
"checksum": "37d1a91062553e4602880e675c4d1f9d1c1f407e084c9d7866d2b3b8b248f174",
"created_time": 1557731017,
"fa_aadhaar_enabled": null,
"id": 14845678,
"last_modified_time": 1557731017,
"name": "Offer letter - New Joinee.pdf",
"pending_file": {
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235649,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - New Joinee.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "John",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557465369,
"email": "[email protected]",
"first_name": "Jane",
"last_modified_time": 1591780421,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377928,
"recipient_user_id": 3625901,
"status": "viewed"
}
],
"status": "incomplete"
},
"public_identifier": "pNovCTn7_nQ5imZW6_Nhgw=="
},
{
"aadhaar_enabled": null,
"checksum": "e3c10aa1faf10d6feab10f348790bcda1fbb4f0ba2a1151f8a9d92e3fc263d14",
"created_time": 1557731210,
"fa_aadhaar_enabled": null,
"id": 14845680,
"last_modified_time": 1557731210,
"name": "Offer letter - New Joinee.pdf",
"pending_file": {
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235650,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - New Joinee.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "John",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557422123,
"email": "[email protected]",
"first_name": "Jane",
"last_modified_time": 1591780425,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377929,
"recipient_user_id": 3625921,
"status": "viewed"
}
],
"status": "incomplete"
},
"public_identifier": "ip_dRR0POvdI9cQgwbPqcg=="
}
]
GET /v2/template/rs/signed/
{
"count": 2,
"files": [
{
"aadhaar_enabled": null,
"checksum": "37d1a91062553e4602880e675c4d1f9d1c1f407e084c9d7866d2b3b8b248f174",
"created_time": 1557731017,
"fa_aadhaar_enabled": null,
"id": 14845678,
"last_modified_time": 1557731017,
"name": "Offer letter - Prashanth.pdf",
"pending_file": {
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235649,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - John Doe.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "John",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557465369,
"email": "[email protected]",
"first_name": "John",
"last_modified_time": 1591780421,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377928,
"recipient_user_id": 3625901,
"status": "viewed"
}
],
"status": "incomplete"
},
"public_identifier": "pNovCTn7_nQ5imZW6_Nhgw=="
},
{
"aadhaar_enabled": null,
"checksum": "e3c10aa1faf10d6feab10f348790bcda1fbb4f0ba2a1151f8a9d92e3fc263d14",
"created_time": 1557731210,
"fa_aadhaar_enabled": null,
"id": 14845680,
"last_modified_time": 1557731210,
"name": "Offer letter - Jane Doe.pdf",
"pending_file": {
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235650,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - John Doe.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "Jane",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557422123,
"email": "[email protected]",
"first_name": "John",
"last_modified_time": 1591780425,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377929,
"recipient_user_id": 3625921,
"status": "viewed"
}
],
"status": "incomplete"
},
"public_identifier": "ip_dRR0POvdI9cQgwbPqcg=="
}
]
GET /v2.1/rs/envelope/signed/
Fetch details of the Completed Signature request
GET /v1/files/signed/<signed_file_id>/
{
"aadhaar_enabled": null,
"checksum": "37d1a91062553e4602880e675c4d1f9d1c1f407e084c9d7866d2b3b8b248f174",
"created_time": 1557731017,
"fa_aadhaar_enabled": null,
"id": 14845678,
"last_modified_time": 1557731017,
"name": "Offer letter - New Joinee.pdf",
"pending_file": {
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235649,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - New Joinee.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "John",
"owner_last_name": "Doe",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557465369,
"email": "[email protected]",
"first_name": "Jane",
"last_modified_time": 1591780421,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377928,
"recipient_user_id": 3625901,
"status": "viewed"
}
],
"status": "incomplete"
},
"public_identifier": "pNovCTn7_nQ5imZW6_Nhgw=="
},
GET /v2/template/rs/<signed_file_id>
{
"aadhaar_enabled": null,
"checksum": "37d1a91062553e4602880e675c4d1f9d1c1f407e084c9d7866d2b3b8b248f174",
"created_time": 1557731017,
"fa_aadhaar_enabled": null,
"id": 14845678,
"last_modified_time": 1557731017,
"name": "Offer letter - New Joinee.pdf",
"pending_file": {
"aadhaar_enabled": null,
"created_time": 1557465368,
"has_markers": 0,
"id": 235649,
"is_in_person": 0,
"is_ordered": 1,
"last_modified_time": 1557465371,
"logo": null,
"name": "Offer letter - New Joinee.pdf",
"next": 377928,
"owner_company": "",
"owner_email": "[email protected]",
"owner_first_name": "Sunil",
"owner_last_name": "Patro EK",
"owner_user_id": 3625900,
"recipients": [
{
"created_time": 1557465369,
"email": "[email protected]",
"first_name": "John",
"last_modified_time": 1591780421,
"last_name": "Doe",
"order_id": 1,
"recipient_id": 377928,
"recipient_user_id": 3625901,
"status": "viewed"
}
],
"status": "incomplete"
},
"public_identifier": "pNovCTn7_nQ5imZW6_Nhgw=="
},
GET /v2.1/rs/envelope/signed/{signed_id}
Download the completed Signature Request
GET /v1/files/signed/<signed_id>/download
PDF Contents
GET /v2/template/rs/signed/<signed_id>/download/
PDF Content
GET /v2.1/rs/envelope/signed/{signed_id}/download
Delete the completed Signature Request
DELETE /v1/files/signed/<signed_id>
DELETE /v2/template/rs/signed/<signed_id>/
DELETE /v2.1/rs/envelope/signed/{signed_id}
Updated about 2 years ago