Smart Tag API


Secured Signing Smart Tag Guide

Secured Signing’s Smart Tag technology automates document creation and streamlines the invitation and signing process to enhance faster document turnaround and better user experience.

Smart Tag technology enables the addition of a signature placeholder during the document formation process that includes:

  • Signatory’s details: full name, email address
  • Personalised text
  • Ability to define signature type: full or initial
  • Option to choose the sequential order of signers
Smart Tag further unique characteristics:
  • Smart Tag can be used with MS Word, and PDF document file formats.
  • Smart Tag supports fill-in fields’ option that enables the simple addition of a Field Tag on a document that has to be completed by both invitee and signatory.
  • For increased security, an SMS can be sent to the invitee as a two-factor authentication function for document access or to complete the signing process.
  • Smart Tag Workflow supports the ability to identify a specific workflow name, and to initiate its application from the Secured Signing system. (Workflow initiation involves additional setup fee costs).

Download Sample Tag Documents

Download Sample Tag Guide


How to send Smart Tag document through API

Prerequisite

Before use Smart Tag API, you may already know:

So, you shall have:

  • ACCESS TOKEN
  • DOCUMENT REFERENCE: reference to the Smart Tag document with signer details inside after uploaded.

in your hand.

Basic Usage

Here's a sample how to send Smart Tag through API.

The Send Smart Tag API request:

API Endpoint:

POST https://api.securedsigning.com/web/v1.4/SmartTag/Send

Headers:

please refer to API Authentication.

Request in JSON format, which is:

{
  "DocumentReferences": [
    "DOCUMENT REFERENCE"
  ],
  "DueDate": "2016-12-13" 
}
                    

Response in JSON format, which is infomation for the sent invitation of Smart Tag document:

[
  {
    "Name": "",                 //document name
    "Reference": "",            //document reference
    "FileType": "",             //Word or PDF file
    "Signers": [
      {
        "SignerReference": "",  //Signer reference
        "FirstName": "",        //Signer's firstname
        "LastName": "",         //Signer's lastname
        "Email": ""             //Signer's email address
      }
    ],
    "Status": "",               //document status
    "DueDate": "Date",          //signing due date
  }
]

Easy, isn't it?


Advanced Usage 1: Send Smart Tag document with email template

Email Template

Please login to Secured Signing, navigate to My Account / My Email Templates to setup your email template first.

Get invitation template through API EmailTemplate/EmailTemplateRequest

The Get Invitation Email Template API:

API Endpoint:

Get https://api.securedsigning.com/web/v1.4/EmailTemplate/GetInvitationTemplates 

Headers:

please refer to API Authentication.

Response in JSON format, which is list of email template details:

[
  {
    "Reference": "167...172",
    "Name": "template 1",
    "Subject": "Please Sign ...",
    "Template": "Hi,<br/><p>[!Invitation.SecuredSigningText]</p>"
  },
  {
    "Reference": "167...031",
    "Name": "template 2",
    "Subject": "Please Sign ...",
    "Template": "Hi,<br/><p>[!Invitation.SecuredSigningText]</p>"
  }
]

Choose the template you want to send with and get TEMPLATE REFERENCE.

Send Smart Tag document with email template

Set [Template Reference] to "EmailTemplateReference" property in Send Smart Tag API request:

{
  "DocumentReferences": [
    "DOCUMENT REFERENCE"
  ],
  "DueDate": "2016-12-13",
  "EmailTemplateReference":"TEMPLATE REFERENCE"
}
                    

The response is same as above.

Send Smart Tag document with one-off template

Please refer to Advanced Usage 3 to see how to setup invitee details.

Set properties related email template for User object in Send Smart Tag API request for each invitee:

{
  "DocumentReferences": [
    "DOCUMENT REFERENCE"
  ],
  "DueDate": "2016-12-13",
  "Signers": [
      {
      "FirstName": "",
      "LastName": "",
      "Email": "",
      "IsPersonalMessage":true,
      "InvitationText":"please sign",
      "EmailSubject":"Please sign"
    }
  ]
}
                    

Some rules here:

  • IsPersonalMessage: If it's true, InvitationText will be used as personal message and it only works with the default Secured Signing template; i.e. leave EmailTemplateReference empty.
  • InvitationText: If IsPersonalMessage is false or empty, it will be used as whole email template text. It's HTML text, so you can use HTML tags. Please try to setup email template on web portal and use the Get Invitation Email Template API to download templates to see how it would looks like.
    Please make sure that email template must include:
    [!Invitation.SecuredSigningText]
    It will be replaced by Secured Signing Service with signing link, signing code, download button, etc.
  • Settings for an invitee will override EmailTemplateReference setting, leave InvitationText or EmailSubject empty to use default one.

The response is same as above.


Advanced Usage 2: Send Embedded Smart Tag document with return URL

Send embedded smart tag document

In some situation, you may want to embed signing page on your website/client. Embedded signing will be what you want.

Set [Embedded] to "true" in Send Smart Tag API request:

{
  "DocumentReferences": [
    "DOCUMENT REFERENCE"
  ],
  "DueDate": "2016-12-13",
  "Embedded":true 
}
                    

Response in JSON format, there's a new property called SigningKey returned in Signer object:

[
  {
    "Name": "",                     //document name
    "Reference": "",                //document reference
    "FileType": "",                 //Word or PDF file
    "Signers": [
      {
        "SignerReference": "",      //Signer reference
        "FirstName": "",            //Signer's firstname
        "LastName": "",             //Signer's lastname
        "Email": ""                 //Signer's email address
        "SigningKey":"112...5093"   //SigningKey to use in embedded signing
      }
    ],
    "Status": "",                   //document status
    "DueDate": "Date",              //signing due date
  }
]

Secured Signing will not send an invitation email for embedded singing, instead of giving you the SigningKey to use in an embedded page by yourself.

Embedded Signing

You may need Secured Signing UI SDK to complete embedding signing, refer to UI SDK in developer page for more details.

Here's a sample html page with how to do embedded signing inside. You can use your API Key and Secret, and put SigningKey inside, host it in your website and have a look how it works.

Embedded Signing Sample

Return URL

After you put the embedded page avobe on your server, you may want to receive some updates about the process. Since the embedded signing page is hosted in your website, you may know the page status so that you can know the documents have been signed or not. Another way is that you can set a return URL when sending smart tag document.

After the document signed, the invitee will be redirect to the URL you set, with the document reference in it. So that you can customised your own completion page and check the document status at that point.

Set Return Url to "ReturnUrl" property in Send Smart Tag API request (must use with embedded as true together):

{
  "DocumentReferences": [
    "DOCUMENT REFERENCE"
  ],
  "DueDate": "2016-12-13",
  "Embedded": true,
  "ReturnUrl": "Return Url"
}
                    

Try it and put the returned signing key in embedded signing page to see how it works.

You can include pattern "{DocumentReference}" in return URL, no matter part of url or as query string, Secured Signing will replace it with document reference when redirect to the URL. e.g.

https://[your domain]/Signed/{DocumentReference} or https://[your domain]/Signed?doc={DocumentReference}
                    

will be replaced to

https://[your domain]/Signed/83659...8384849 or https://[your domain]/Signed?doc=83659...8384849
                    

Advanced Usage 3: Send Smart Tag document with invitee details

You can also just have Smart Tag like

[!Sign.1.F]
in the document for just locating the signature position but without any invitee details, then populate the details when sending smart tag document through API.

This is useful if you use the document as template or you're not able to modify the document everytime.

Set details to "Signers" array property in Send Smart Tag API request:

{
  "DocumentReferences": [
    "DOCUMENT REFERENCE"
  ],
  "DueDate": "2016-12-13",
  "Signers": [
      {
      "FirstName": "",
      "LastName": "",
      "Email": "",
      "MobileCountry": "",  //optional, if smart tag with SMS
      "MobileNumber": ""    //optional, if smart tag with SMS
    }
  ]
}
                    

The response is same as above.

If you have two or more signers in your document, the order of signers is related as index of Signers array. e.g. Signers[0] in API request will be applied to smart tag [Sign.1] in document.


Advanced Usage 4: Send Smart Tag document with attachments

Smart Tag API supports attachments now, it's only in API.

The attachments will be sent with the invitation email without extra cost. They can be some documents invitees need to read but not need to sign.

Let's begin. Firstly, get {AttachmentReference} by Uploading attachment through API (Upload Attachment API);

Upload more attachment if you need, record all attachment references.

Set details to "Signers" array property in Send Smart Tag API request:

{
  "DocumentReferences": [
    "DOCUMENT REFERENCE"
  ],
  "DueDate": "2016-12-13",
  "Signers": [
      {
        "Attachments":[
            "{AttachmentReference1}",
            "{AttachmentReference2}"
            ]
    }
  ]
}
                    

The response is same as above.

If you have two or more signers in your document, the order of signers is related as index of Signers array. e.g. Signers[0] in API request will be applied to smart tag [Sign.1] in document. You can set differenct attachment for each signer.