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 Smart Tag Documents

Download Smart 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": "2023-04-01" 
}

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": "2023-04-01",
  "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": "2023-04-01",
  "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

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": "2023-04-01",
  "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 signing, 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

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": "2023-04-01",
  "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": "2023-04-01",
  "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.

Advanced Usage 5: Send Smart Tag document with callback service

Smart Tag API supports set callback URL, it's only in API.

The callback URL will be called each time the document status changed.

Let's begin. Firstly, enable Callback in your API Key.

Secondly, set your callback URL to "NotifyUrl" property in Send Smart Tag API request:

{
  "DocumentReferences": [
    "DOCUMENT REFERENCE"
  ],
  "DueDate": "2023-04-01",
  "NotifyUrl":"[CallbackURL]"
  ]
}

The HTTP request we will call your callback URL is as followings

  • Request Url: Your callback URL
  • Request Method: Post
  • Content-Type: application/x-www-form-urlencoded
  • Body: Status=0 of 1 Signed&Doc=048237….2201121&Ref=0FFB1350….2A74F1&Event=Extend

The body contains 4 parts:

  • Status: current status of the document
  • Doc: the reference of the document, same as the reference you got after upload and send through API
  • Ref : the client reference you passed when uploading document, optional
  • Event: the notify event, possible values: Complete, Extend, Decline, Expired