Sign document and request signature

Introduction

In this scenario, the goal is to upload a file, create a document, sign it and share it with the intended recipients for signature. The scenario should demonstrate Circularo possibility to place and request signature at the same time (in one request). 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.
Sign and request signature (share for signature): In this step we place our signature and specify the recipients who need to sign the document.

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 ZlraCS4mijTnmqn6JfUVmrtS7GGC6RxdO11vCLl7HVWua0tFCzhvJYwno5fsikAo.
signatureFileId - In response object at position user.config.signature[0].imageId.
- It may have value of 878QpaKLioqlvNGt5zHVnxAa4pNdxFcFgHKlqQ2iYF25VmNZoXlX0QIxULgHlEL0.

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=ZlraCS4mijTnmqn6JfUVmrtS7GGC6RxdO11vCLl7HVWua0tFCzhvJYwno5fsikAo

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 06VlLbyLiIjaUw53OzaK6qExh76Q56BrHAkgEa5YXqZIji6LwCTCqTyrMThAoWAk.

The file is now created.

Step 3 - 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=ZlraCS4mijTnmqn6JfUVmrtS7GGC6RxdO11vCLl7HVWua0tFCzhvJYwno5fsikAo

Content-Type: application/json

{
  "body": {
    "documentType": "d_default",
    "documentTitle": "My Document",
    "pdfFile": {
      "content": "06VlLbyLiIjaUw53OzaK6qExh76Q56BrHAkgEa5YXqZIji6LwCTCqTyrMThAoWAk"  //specify existing file hash
    }
  },
  "definitionType": "ext",
  "workflow": "wf_archive",
  "optionalData": {
    "folder": "9be35fc5-2c5f-40ed-bd74-cb5c985a4fbc"  //optional - specify to which folder document will be placed
  }
}

Response

Note following properties in response object:

documentId - In response object at position results[0].documentId.
- It may have value of b99daca8-040c-4856-b4b6-edafed7affe1.

The PDF document is now created.

Step 4 - Sign and request signature

This step combines 2 requests that can be performed on the document - sign and request signature.

Read more about sign and signature request: Sign the document

Request signature

We will be requesting signature from an internal user and add a field with his phone number next to the signature.

Endpoint

CODE

POST /share

Request

JSON

POST /share?token=ZlraCS4mijTnmqn6JfUVmrtS7GGC6RxdO11vCLl7HVWua0tFCzhvJYwno5fsikAo

Content-Type: application/json

{
  "id": "b99daca8-040c-4856-b4b6-edafed7affe1",
  "type": "d_default",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "derek.trotter@circularo.com"
    }
  ],
  "signatureFields": [  //array with objects that are required from the user
    {
      "user": [
        "derek.trotter@circularo.com"
      ],
      "timestamp": false,
      "required": true,
      "type": "signature",  //type is signature
      "pages": [  //document page with signature
        1
      ],
      "position": {  //position and size of the signature in the document page
        "percentX": 0.2,
        "percentY": 0.6,
        "percentWidth": 0.4,
        "percentHeight": 0.1
      }
    },
    {
      "user": [
        "derek.trotter@circularo.com"
      ],
      "required": true,
      "type": "annotation",  //type is annotation
      "subtype": "annotation_phone",  //subtype is phone
      "pages": [
        1
      ],
      "position": {  //position and size of the annotation in the document page
        "percentX": 0.6,
        "percentY": 0.6,
        "percentWidth": 0.1,
        "percentHeight": 0.15
      }
    }
  ],
  "signatures": [  //array containing our signature
    {
      "type": "signature",
      "blob": "878QpaKLioqlvNGt5zHVnxAa4pNdxFcFgHKlqQ2iYF25VmNZoXlX0QIxULgHlEL0",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.5,
        "percentY": 0.3,
        "percentWidth": 0.4,
        "percentHeight": 0.1
      },
      "disableDecoration": true
    }
  ]
}

Response

JSON

[
  {
    "shareId": "iuEstVauWnFjjWNaRhRY",
    "isActive": true,
    "isPermanentViewToken": false,
    "messageRead": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "b99daca8-040c-4856-b4b6-edafed7affe1",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    "passwordRequired": false,
    "sharedUsername": "derek.trotter@circularo.com",
    "sequential": false,
    "isDelegated": false,
    "shareGroup": "a025b823-b5d0-4bf6-963b-37b40a95cde5",
    "rights": [
      "print",
      "delegate",
      "metadata",
      "canAnnotateOnReject"
    ],
    "sendAttachmentsOnComplete": false,
    "dateFormat": "dd/MM/yyyy",
    "timeFormat": "h:mm a",
    "isMandatory": true,
    "tokenGenerated": false
  }
]

Document is now signed with our signature and sent to Derek Edward Trotter who needs to fill in his phone and sign the document.

Introduction

Step 1 - Sign in (optional)

Step 2 - Upload file

Step 3 - Create document from file

Step 4 - Sign and request signature