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

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

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"
 }

Remind all signers of the Signature Request

POST /v1/files/pending/<pending_id>/remind/
POST /v2/template/rs/<pending_id>/remind/

Cancel the Signature Request

POST /v1/files/pending/<pending_id>/cancel/
POST /v2/template/rs/<pending_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"
        }
   ]
}

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=="
        }
 ]

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=="
        },

Download the completed Signature Request

GET /v1/files/signed/<signed_id>/download

PDF Contents
GET /v2/template/rs/signed/<signed_id>/download/

PDF Content

Delete the completed Signature Request

DELETE /v1/files/signed/<signed_id>
DELETE /v2/template/rs/signed/<signed_id>/