Skip to main content
Skip table of contents

Use signature template

This scenario in Circularo offers users a streamlined and efficient way to create, customize, and share documents while incorporating standardized signature templates. Whether starting from scratch or utilizing existing templates, this scenario simplifies the process of document creation, signing, and collaboration.

If you are not familiar with Circularo signing templates make sure that you read this help section first - Templates

There are two approaches that can be considered:

  • Create and share the template entirely through API calls.

  • Create the template using the Circularo UI and share it through API.

We recommend the second approach because typically creating a template is a one-time task and doesn't require automation. Creating the template directly through the UI is a faster process, and since it doesn't need to be repeated frequently, it offers a more efficient solution.

By utilizing the Circularo UI for template creation, users can take advantage of the intuitive interface, allowing them to set up the template structure and define the necessary components effortlessly.

Overall, this approach strikes a balance between efficiency and flexibility, ensuring that the template creation process remains user-friendly while still offering the convenience of API sharing capabilities.

If you wish to create the template through the Circularo UI please use this guide and then follow from step 4 - Creating templates

With steps below we will create the signature template through API.

Step 1 - Sign in (optional)

Sign user in.

Please note that this step is optional, we recommend you create an API key to be used as a token with all requests - Create new API key

Read more about authentication - Authentication

Endpoint

CODE 
POST /login

Request

JSON 
POST /login

Content-Type: application/json

{
  "name": "mary.griffin@circularo.com",
  "password": "#32Password1!",
  "tenant": "default"
}

Response

Note following properties in response object:

  • token - In response object at position token.

    • It may have value of GK2neQNerr9xFhasK8UDk7j353H0cnBPJfG71FhnOn7cjDQbVMpx7avlDcoag17B.

Step 2 - Upload file

Upload new PDF file to the Circularo storage from which the document will be created.

Read more about file creation - Create file

Endpoint

CODE 
POST /files/saveFile

Request

JSON 
POST /files/saveFile?token=GK2neQNerr9xFhasK8UDk7j353H0cnBPJfG71FhnOn7cjDQbVMpx7avlDcoag17B

Content-Type: multipart/form-data

{
  "file": "blob",
  "fileName": "My PDF file"
}

Response

Note following properties in response object:

  • fileHash - In response object at position file.id.

    • It may have value of GyaZ315K9oMZDRVon68x2As9jrfLLyCSdLUhlz5eOFAQ5GecCk3Pa1RJR4bWhOcL.

The file is now created.

Step 3 - Create new signature template

In this step we use the pdf file that we uploaded and put signature fields that will be filled by signatories. Lets say we want to have a text field assigned to Derek Edward Trotter where he will put his name and one signature field on page 1 of our file. Similar to this:

Signature

Endpoint

CODE 
POST /templates

Request

JSON 
POST /templates?token=GK2neQNerr9xFhasK8UDk7j353H0cnBPJfG71FhnOn7cjDQbVMpx7avlDcoag17B

Content-Type: application/json

{
  "data": {
    "name": "Company Memo",
    "documentType": "d_default",
    "definitionType": "ext",
    "sequential": false,
    "category": "",
    "fields": [
      "D_DEFAULT_DESCRIPTION"
    ],
    "file": "GyaZ315K9oMZDRVon68x2As9jrfLLyCSdLUhlz5eOFAQ5GecCk3Pa1RJR4bWhOcL",
    "signEntities": [
      {
        "type": "user",
        "quorum": 1,
        "userRoleId": 0,
        "userRoleName": "Recipient 1",
        "shareType": "sign",
        "order": 1,
        "users": [
          {
            "name": "",
            "mail": "derek.trotter@circularo.com",
            "type": "external",
            "contactType": "mail"
          }
        ]
      }
    ],
    "signFields": [
      {
        "type": "annotation",
        "subtype": "annotation_generic",
        "pages": [
          1
        ],
        "multipage": false,
        "position": {
          "percentX": 0.1127450980392157,
          "percentY": 0.8053030303030304,
          "percentWidth": 0.2588235294117647,
          "percentHeight": 0.01742424242424243
        },
        "backgroundColor": "#FFFFFF00",
        "config": "{\"multipageType\":\"all\",\"multiPageCustom\":\"1\",\"placeholder\":\"Text\",\"group\":false}",
        "required": false,
        "order": 1,
        "tooltip": "",
        "cancelled": false,
        "filled": false,
        "user": [
          "derek.trotter@circularo.com"
        ],
        "userRoleId": 0,
        "userRoleName": "Recipient 1",
        "text": "",
        "align": "left",
        "bold": false,
        "font": "default",
        "fontSize": 10,
        "color": "#000000",
        "numberOfLines": -1
      },
      {
        "type": "signature",
        "pages": [
          1
        ],
        "multipage": false,
        "position": {
          "percentX": 0.3950980392156863,
          "percentY": 0.7492424242424244,
          "percentWidth": 0.2418301451439951,
          "percentHeight": 0.08080804998224432
        },
        "config": "{\"multipageType\":\"all\",\"multiPageCustom\":\"1\",\"group\":false}",
        "required": false,
        "order": 1,
        "tooltip": "",
        "cancelled": false,
        "filled": false,
        "user": [
          "derek.trotter@circularo.com"
        ],
        "userRoleId": 0,
        "userRoleName": "Recipient 1",
        "timestamp": false
      }
    ],
    "type": "sign",
    "__shared": false,
    "__editable": true,
    "rolesAsUsers": []
  }
}

Response

Note following properties in response object:

  • templateId - In response object at position id.

    • It may have value of d35b71c4-981d-45d6-a69b-1c501f05478a.

The template is now created in the application. See below how to read template data and use them to create a document and request signature.

Step 4 - Read signature data from template

The idea here is that you created the template some time ago and you did not save the positions of annotations and signature fields. In this step we gather all the template data.

We will need following:

  • ID of the template from previous step

Endpoint

CODE 
GET /templates/:templateId

Request

JSON 
GET /templates/d35b71c4-981d-45d6-a69b-1c501f05478a?token=GK2neQNerr9xFhasK8UDk7j353H0cnBPJfG71FhnOn7cjDQbVMpx7avlDcoag17B

Response

JSON 
{
  "definitionType": "ext",
  "documentType": "d_default",
  "fields": [
    "D_DEFAULT_DESCRIPTION"
  ],
  "file": "piZWEufOG4YKJI0Iv8c5yTeT6JamWnDBr4Ag735AMLWyLcHkudTUxKlG4CKR3oxW",
  "name": "Company Memo",
  "sequential": false,
  "signEntities": [
    {
      "type": "user",
      "users": [
        {
          "type": "external",
          "mail": "derek.trotter@circularo.com",
          "contactType": "mail"
        }
      ],
      "quorum": 1,
      "userRoleId": 0,
      "userRoleName": "Recipient 1",
      "shareType": "sign",
      "order": 1
    }
  ],
  "signFields": [
    {
      "type": "annotation",
      "position": {
        "percentX": 0.1127450980392157,
        "percentY": 0.8053030303030304,
        "percentWidth": 0.2588235294117647,
        "percentHeight": 0.01742424242424243
      },
      "pages": [
        1
      ],
      "user": [
        "derek.trotter@circularo.com"
      ],
      "required": false,
      "timestamp": false,
      "customId": "",
      "text": "",
      "subtype": "annotation_generic",
      "fontSize": 10,
      "font": "default",
      "color": "#000000",
      "bold": false,
      "align": "left",
      "config": "{\"multipageType\":\"all\",\"multiPageCustom\":\"1\",\"placeholder\":\"Text\",\"group\":false}",
      "userRoleId": 0,
      "userRoleName": "Recipient 1",
      ...
    },
    {
      "type": "signature",
      "position": {
        "percentX": 0.3950980392156863,
        "percentY": 0.7492424242424244,
        "percentWidth": 0.2418301451439951,
        "percentHeight": 0.08080804998224432
      },
      "pages": [
        1
      ],
      "user": [
        "derek.trotter@circularo.com"
      ],
      "required": false,
      "timestamp": false,
      "customId": "",
      "config": "{\"multipageType\":\"all\",\"multiPageCustom\":\"1\",\"group\":false}",
      "userRoleId": 0,
      "userRoleName": "Recipient 1",
      ...
    }
  ],
  "__id": "d35b71c4-981d-45d6-a69b-1c501f05478a",
  "__addedBy": "mary.griffin@circularo.com",
  "__addedOn": "2023-07-11T13:38:36.909Z",
  "__owner": "mary.griffin@circularo.com",
  "__users": [],
  "__groups": [],
  "__shareEdit": false,
  "__shared": false
}

Note following properties in response object:

  • newFileHash - In response object at position file.

    • This value will be needed when creating the document.

    • It may have value of piZWEufOG4YKJI0Iv8c5yTeT6JamWnDBr4Ag735AMLWyLcHkudTUxKlG4CKR3oxW.

Response contains all data saved before which can be further used for creating a document and requesting signature.

Step 5 - Create new document

In this step we will create document from the same file that we created the template.

Read more about document creation - Create document

Read more about Circularo documents - Document structure

We will need following:

  • new file hash (taken from previous step)

Endpoint

CODE 
POST /documents

Request

JSON 
POST /documents?token=GK2neQNerr9xFhasK8UDk7j353H0cnBPJfG71FhnOn7cjDQbVMpx7avlDcoag17B

Content-Type: application/json

{
  "body": {
    "documentType": "d_default",
    "documentTitle": "Company memo from template",
    "pdfFile": {
      "content": "piZWEufOG4YKJI0Iv8c5yTeT6JamWnDBr4Ag735AMLWyLcHkudTUxKlG4CKR3oxW"  //specify existing file hash
    }
  },
  "optionalData": {
    "cloneMainFile": true
  },
  "definitionType": "ext",
  "workflow": "wf_archive"
}

Response

Note following properties in response object:

  • documentId - In response object at position results[0].documentId.

    • It may have value of 2bff8d81-62f3-4084-adc1-245d4021919b.

Step 6 - Request signature

Now that we have created the document we will use the fields from the template in order to request signature from Derek Edward Trotter.

Read more about sign and signature request: Request signature

We will need following:

  • document ID from previous step

  • signature fields from the template

Explanations for the body of the request

  • data = a list of users that will be signing (or do any other action) on the document.

    Even if the user will have multiple fields assigned, he must be present in “data” only once

  • signFields = fields that the users will be signing/filling in. The users are taken from “data”

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=GK2neQNerr9xFhasK8UDk7j353H0cnBPJfG71FhnOn7cjDQbVMpx7avlDcoag17B

Content-Type: application/json

{
  "id": "2bff8d81-62f3-4084-adc1-245d4021919b",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "derek.trotter@circularo.com"
    }
  ],
  "signatureFields": [
    {
      "type": "annotation",
      "position": {
        "percentX": 0.1127450980392157,
        "percentY": 0.8053030303030304,
        "percentWidth": 0.2588235294117647,
        "percentHeight": 0.01742424242424243
      },
      "pages": [
        1
      ],
      "user": [
        "derek.trotter@circularo.com"
      ],
      "required": false,
      "timestamp": false,
      "customId": "",
      "text": "",
      "subtype": "annotation_generic",
      "fontSize": 10,
      "font": "default",
      "color": "#000000",
      "bold": false,
      "align": "left",
      "userRoleId": 0,
      "userRoleName": "Recipient 1"
    },
    {
      "type": "signature",
      "position": {
        "percentX": 0.3950980392156863,
        "percentY": 0.7492424242424244,
        "percentWidth": 0.2418301451439951,
        "percentHeight": 0.08080804998224432
      },
      "pages": [
        1
      ],
      "user": [
        "derek.trotter@circularo.com"
      ],
      "required": false,
      "timestamp": false,
      "customId": "",
      "userRoleId": 0,
      "userRoleName": "Recipient 1"
    }
  ]
}

Response

JSON 
[
  {
    "shareId": "jwxbwnNx2d9E8NpnMDDZ",
    "isActive": true,
    "isPermanentViewToken": false,
    "messageRead": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "2bff8d81-62f3-4084-adc1-245d4021919b",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    "passwordRequired": false,
    "language": "en",
    "sequential": false,
    "isDelegated": false,
    "shareGroup": "d8b1c194-2399-480e-898d-bcef2e8ff868",
    "rights": [
      "print",
      "delegate",
      "metadata",
      "canAnnotateOnReject"
    ],
    "sendAttachmentsOnComplete": false,
    "dateFormat": "d.M.yyyy",
    "timeFormat": "h:mm a",
    "isMandatory": true,
    "tokenGenerated": false
  }
]

The document was successfully sent for signature to Derek and he will receive an email notification to his email - derek.trotter@circularo.com

Final Note

In this scenario, we successfully shared a document using the template we prepared in Circularo. However, you may have noticed that achieving a similar result is possible by following these steps:

  • Upload the file.

  • Create a document.

  • Request a signature.

Furthermore, since it's possible to create multiple documents from a single file, you can repeat these steps instead of creating a template and reusing it within the Circularo UI.

It's important to note that templates are primarily a frontend/UI feature designed to enhance the user experience. They offer a convenient solution for users who frequently send the same document for signature. Templates eliminate the need to upload the file repeatedly and set up signatories each time it is sent for signature.

However, in cases where the integration focuses on sending the same PDF document for signature multiple times, the template creation step can be bypassed. Instead, the focus shifts to retrieving the signature field positions and populating them with data programmatically from the integrated application. This approach allows for a more efficient and streamlined process while still achieving the desired outcome of repeated document signatures.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close