Skip to main content
Skip table of contents

Request signature and download document once completed

Introduction

In this scenario, the goal is to upload a file, create a document, and share it with the intended recipients for signature. Additionally, a webhook is set up to receive a "documentCompleted" notification. Once the document has been successfully signed, the scenario downloads the signed file for further processing. To achieve this, the following steps will be taken:

  • Upload a file: The first step is to create a file that will be used to store the PDF document.

  • Create document: New PDF document will be created.

  • Request signature (share for signature): In this step we specify the recipients who need to sign the document.

  • Set Up a Webhook: To track the progress of the signing process, a webhook is set up within Circularo. This webhook listens for specific events related to document completion.

  • Download Signed File: Upon receiving the "documentCompleted" POST request, the scenario downloads the signed document from Circularo storage.

This scenario requires user token or API key, read more - Authentication

Step 1 - 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=I9u889Udt7SIUyEl8RCPfHAnbWUdKQCaGEPr1it3aNEPuO9776GnCWyWiCE65H6M

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 yjzgpFC82cn4fz6QwYxIFweXokGVoMUdAZhrkwdqlQGoj4o6prgxqaRCBLeFUbMM.

The file is now created.

Step 2 - Create document from file

Create new document from existing PDF file in storage.

Read more about document creation - Create document

Read more about Circularo documents - Document structure

Endpoint

CODE 
POST /documents

Request

JSON 
POST /documents?token=I9u889Udt7SIUyEl8RCPfHAnbWUdKQCaGEPr1it3aNEPuO9776GnCWyWiCE65H6M

Content-Type: application/json

{
  "body": {
    "documentType": "d_default",
    "documentTitle": "My Document",
    "pdfFile": {
      "content": "yjzgpFC82cn4fz6QwYxIFweXokGVoMUdAZhrkwdqlQGoj4o6prgxqaRCBLeFUbMM"  //specify existing file hash
    }
  },
  "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 0985035e-2850-41e5-a2d8-071409cb6757.

The PDF document is now created.

Step 3 - Request signature (Share document for sign)

In this scenario we created an Agreement between two parties. First one will be external user from another company and the second will be internal user who needs to sign on behalf our company.

Our internal user will be filling only his signature, whereas external user needs to fill in his name and signature so we will prepare a text field (annotation) for him.

The recipients will sign sequentially (first external then internal).

Read more about signature request - Request signature

Endpoint

CODE 
POST /share

Request

JSON 
POST /share?token=I9u889Udt7SIUyEl8RCPfHAnbWUdKQCaGEPr1it3aNEPuO9776GnCWyWiCE65H6M

Content-Type: application/json

{
  "objectType": "document",
  "type": "d_default",
  "id": "0985035e-2850-41e5-a2d8-071409cb6757",  //document id
  "data": [  //specify at least one participant
    {
      "sharePurpose": "sign",
      "shareTo": "external.bill@circularo.com",  //external user
      "order": 0
    },
    {
      "sharePurpose": "sign",
      "shareTo": "derek.trotter@circularo.com",  //internal username
      "order": 1
    }
  ],
  "signatureFields": [
    {
      "type": "annotation",
      "position": {
        "percentX": 0.13474484256243213,
        "percentY": 0.2118678728457018,
        "percentWidth": 0.1,
        "percentHeight": 0.017619188628960617
      },
      "pages": [
        1
      ],
      "user": [
        "external.bill@circularo.com"
      ],
      "required": true,
      "timestamp": false,
      "text": "",
      "subtype": "annotation_generic",
      "fontSize": 10,
      "font": "default",
      "color": "#000000",
      "bold": false,
      "align": "left",
      "order": 0
    },
    {
      "user": [
        "external.bill@circularo.com"
      ],
      "timestamp": false,
      "required": true,
      "tooltip": "Signature tooltip text",
      "type": "signature",  //sign type
      "pages": [  //document page with signature
        1
      ],
      "position": {  //position and size of the signature in the document page
        "percentX": 0.5,
        "percentY": 0.1,
        "percentWidth": 0.2,
        "percentHeight": 0.05
      },
      "order": 0
    },
    {
      "user": [
        "derek.trotter@circularo.com"
      ],
      "timestamp": true,
      "required": true,
      "tooltip": "Stamp tooltip text",
      "type": "signature",
      "pages": [
        2
      ],
      "position": {  //position and size of the signature in the document page
        "percentX": 0.3,
        "percentY": 0.65,
        "percentWidth": 0.15,
        "percentHeight": 0.15
      },
      "order": 1
    }
  ],
  "sequential": true  //recipients are required to sign one-by-one
}

Response

JSON 
[
  {
    "shareId": "PYlUUln90ROUf2kxqnGG",
    "isActive": true,
    "isPermanentViewToken": false,
    "messageRead": false,
    "shareDate": "2023-07-19T10:16:58.241Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "0985035e-2850-41e5-a2d8-071409cb6757",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "external.bill@circularo.com"
    ],
    "passwordRequired": false,
    "language": "en",
    "sequential": true,
    "isDelegated": false,
    "shareGroup": "6c584124-925f-4a8d-ba92-b1364841588b",
    "rights": [
      "print",
      "delegate",
      "metadata",
      "canAnnotateOnReject"
    ],
    "sendAttachmentsOnComplete": false,
    "dateFormat": "dd/MM/yyyy",
    "timeFormat": "h:mm a",
    "isMandatory": true,
    "order": 0,
    "tokenGenerated": false
  },
  {
    "shareId": "Wuj2cLGWZL5oAEWdDzsT",
    "isActive": true,
    "isPermanentViewToken": false,
    "messageRead": false,
    "shareDate": "2023-07-19T10:16:58.241Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "0985035e-2850-41e5-a2d8-071409cb6757",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    "passwordRequired": false,
    "language": "en",
    "sequential": true,
    "isDelegated": false,
    "shareGroup": "6c584124-925f-4a8d-ba92-b1364841588b",
    "rights": [
      "print",
      "delegate",
      "metadata",
      "canAnnotateOnReject"
    ],
    "sendAttachmentsOnComplete": false,
    "dateFormat": "dd/MM/yyyy",
    "timeFormat": "h:mm a",
    "isMandatory": true,
    "order": 1,
    "tokenGenerated": false
  }
]

Response contains 2 share objects, one for Bill External and second for Derek Edward Trotter with additional info.

Step 4 - Set up a webhook (one time only)

To avoid confusion - this step is required only when you previously did not set up a webhook in the system. If you already did, skip this step.

At this point we would like to be notified when Bill External and Derek Edward Trotter finished signing the document (document will be completed). For this we can set up a webhook that will send a post request anytime there are actions being done on a document and filter the ones for “documentCompleted” trigger.

Read more about webhooks - Webhooks

Our account is an organization (team) admin so we will use "type": "team". And for demonstration purposes we will setup our callback URL from the 3rd party webhook browser - webhook.site.

Endpoint

CODE 
POST /webhooks

Request

JSON 
POST /webhooks?token=I9u889Udt7SIUyEl8RCPfHAnbWUdKQCaGEPr1it3aNEPuO9776GnCWyWiCE65H6M

Content-Type: application/json

{
  "type": "team",
  "callbackUrl": "https://webhook.site/7d041a97-550a-4e9f-97c9-66547b4807a3"
}

When document is completed we receive POST request with body similar to this:

JSON 
{
  "documentId": "0985035e-2850-41e5-a2d8-071409cb6757",
  "event": "documentCompleted",
  "actor": "derek.trotter@circularo.com", //last signatory
  "timestamp": "2023-07-19T10:32:02.872Z"
}

Step 5 - Retrieve signed document

The document cycle in Circularo was successfully completed and we were informed about that through webhook. Now we can download the document back to our system.

First we need to retrieve the document file hash.

Read more about hash retrieval and document download - Retrieve the document

Endpoint

CODE 
GET /documents/:documentId

Request

JSON 
GET /documents/0985035e-2850-41e5-a2d8-071409cb6757?token=I9u889Udt7SIUyEl8RCPfHAnbWUdKQCaGEPr1it3aNEPuO9776GnCWyWiCE65H6M

Response

JSON 
{
  "results": [
    {
      ...
      "pdfFile": {
        "content": "UgunQ18GlNFtoS30VCzjIcKTwSiPOv6T1Llui6QWEMXc5ASNBwUGRA4qSo02Rn2T",
        ...
      },
      ...
    }
  ]
}

Note following properties in response object:

  • pdfFileHash - In response object at position results[0].pdfFile.content.

    • It may have value of UgunQ18GlNFtoS30VCzjIcKTwSiPOv6T1Llui6QWEMXc5ASNBwUGRA4qSo02Rn2T.

Step 6 - Download signed document

Now that we retrieved the file hash we can download the document file to our storage.

Endpoint

CODE 
GET /files/loadFile/hash/:hash

Request

JSON 
GET /files/loadFile/hash/UgunQ18GlNFtoS30VCzjIcKTwSiPOv6T1Llui6QWEMXc5ASNBwUGRA4qSo02Rn2T?token=I9u889Udt7SIUyEl8RCPfHAnbWUdKQCaGEPr1it3aNEPuO9776GnCWyWiCE65H6M

The response of the API call will be the main file of the specified document.

JavaScript errors detected

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

If this problem persists, please contact our support.

Contact Support Close