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

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=6EIKmvg1ECdSNpiXB6jFWuqYOw60e3s7NoWjzxicpTROgTl8eOLtj7DWZdzVVRrk

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

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=6EIKmvg1ECdSNpiXB6jFWuqYOw60e3s7NoWjzxicpTROgTl8eOLtj7DWZdzVVRrk

Content-Type: application/json

{
  "body": {
    "documentType": "d_default",
    "documentTitle": "My Document",
    "pdfFile": {
      "content": "MFOc7cPwK91eIeK1EfhY9D7Um0UCX9cTVYqK1rE2Eba9hdO6WtLcgqHDli1qzL9y"  //specify existing file hash
    }
  },
  "definitionType": "ext",
  "workflow": "wf_archive",
  "optionalData": {
    "folder": "542b9230-aa56-4fb9-aa66-c4f7a5c39a29"  //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 8d47eaa2-35da-4140-8acd-28035fa79c6b.

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=6EIKmvg1ECdSNpiXB6jFWuqYOw60e3s7NoWjzxicpTROgTl8eOLtj7DWZdzVVRrk

Content-Type: application/json

{
  "id": "8d47eaa2-35da-4140-8acd-28035fa79c6b",
  "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": "6iAsLYVFJc6XZoiYWB7FEsGi8fS8B2rF8zQ9dUp37sfnA98Go56zQP2j7NHhuzWu",
      "pages": [
        1
      ],
      "position": {
        "percentX": 0.5,
        "percentY": 0.3,
        "percentWidth": 0.4,
        "percentHeight": 0.1
      },
      "disableDecoration": true
    }
  ]
}

Response

JSON

[
  {
    "shareId": "q4k0NVcP4fEx8sOX2FYW",
    "isActive": true,
    "isPermanentViewToken": false,
    "messageRead": false,
    "shareDate": "2023-07-20T14:04:36.186Z",
    "shareType": "sign",
    "sharedBy": "mary.griffin@circularo.com",
    "sharedObjectEsId": "8d47eaa2-35da-4140-8acd-28035fa79c6b",
    "sharedObjectEsType": "d_default",
    "sharedObjectType": "document",
    "sharedWith": [
      "derek.trotter@circularo.com"
    ],
    "passwordRequired": false,
    "sharedUsername": "derek.trotter@circularo.com",
    "sequential": false,
    "isDelegated": false,
    "shareGroup": "84e96284-cea0-44a5-9e19-9049e493feae",
    "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