Smart Tag API Documentation

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
• Personalized text
• Ability to define signature type: full or initial
• Option to choose the sequential order of signers

Download Sample Smart Tag

Download Smart Tag Guide

Prerequisite

Before use Smart Tag API, you may already know:

• What is Smart Tag and how to create a document with Smart Tags (Secured Signing Smart Tag Guide);
• Understanding Secured Signing API (Developer Page);
• Getting access token from user authorization (API Authentication);
• Uploading document through API (Upload Document API);

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

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?

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-01-06",
  "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-01-06",
  "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.

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-01-06",
  "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

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-01-06",
  "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.

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-01-06",
  "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.

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-01-06",
  "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