Create PDF document, sign it and download the signed file

Circularo REST API example

Create new PDF file in Circularo and use it to create the document. Then sign the document and download the signed file.

Step 1 - Sign in

Sign user in.

Endpoint

POST - /login

Example

/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 “b7qDPFh0Tp63nLLMLivrIsx99ejqtWNPwnDVt3vD3ASrpqZiWF615mYjvq2zJ41D“.
  • signatureFileId - In response object at position ‘user.config.signature[0].imageId‘. It may have value of “Q2t7L3LNyGxZpjHS3UyJDEJijTKCUbVcL2UceRJSJhWNK4iw5G2Y69ReLJeY1vwU“.

Step 2 - Create new PDF file

Create new PDF file in the Circularo.

Endpoint

POST - /files/saveFile

Example

/files/saveFile?token=b7qDPFh0Tp63nLLMLivrIsx99ejqtWNPwnDVt3vD3ASrpqZiWF615mYjvq2zJ41D

Content-Type: multipart/form-data

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

Response

Note following properties in response object:

  • fileId - In response object at position ‘file.id‘. It may have value of “oHw7Ghr1Eyv4IGA966HqOQcJUdFR9tllucaxQbSP5J4sM86qZOwsN8WGnTJ7uPuM“.

The file is now created.

Step 3 - Create PDF based document

Create new document from existing PDF file.

Endpoint

POST - /documents

Example

/documents?token=b7qDPFh0Tp63nLLMLivrIsx99ejqtWNPwnDVt3vD3ASrpqZiWF615mYjvq2zJ41D

Content-Type: application/json

{
  "body": {
    "documentType": "d_default",
    "documentTitle": "My file based document",
    "pdfFile": {
      "content": "oHw7Ghr1Eyv4IGA966HqOQcJUdFR9tllucaxQbSP5J4sM86qZOwsN8WGnTJ7uPuM",
      "_content_type": "application/pdf"
    }
  },
  "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 “70bf9842-e6b3-4a80-952f-f5f5a7cd443a“.

The PDF based document is now created.

Step 4 - Sign document

Sign selected document. “blob” is signature file id. If document has been just created, you can use ‘“documentVersion”: 1’.

Endpoint

PUT - /documents/sign/:documentVersion

Example

/documents/sign/1?token=b7qDPFh0Tp63nLLMLivrIsx99ejqtWNPwnDVt3vD3ASrpqZiWF615mYjvq2zJ41D

Content-Type: application/json

{
  "id": "70bf9842-e6b3-4a80-952f-f5f5a7cd443a",
  "type": "d_default",
  "signatures": [
    {
      "type": "signature",
      "blob": "Q2t7L3LNyGxZpjHS3UyJDEJijTKCUbVcL2UceRJSJhWNK4iw5G2Y69ReLJeY1vwU",
      "page": 1,
      "position": {
        "percentX": 0.5,
        "percentY": 0.3,
        "percentWidth": 0.4,
        "percentHeight": 0.1
      },
      "disableDecoration": true
    }
  ],
  "annotations": [
    {
      "align": "left",
      "backgroundColor": "#ffffff",
      "bold": false,
      "color": "#000000",
      "fontSize": 8,
      "page": 1,
      "percentX": 0.5,
      "percentY": 0.9,
      "percentWidth": 0.2,
      "percentHeight": 0.01,
      "subtype": "docId",
      "text": "{{{documentId}}}"
    }
  ]
}

The document is now signed.

Step 5 - Retrieve document

Retrieve document information.

Endpoint

GET - /documents/:documentId

Example

/documents/70bf9842-e6b3-4a80-952f-f5f5a7cd443a?token=b7qDPFh0Tp63nLLMLivrIsx99ejqtWNPwnDVt3vD3ASrpqZiWF615mYjvq2zJ41D

Response

Note following properties in response object:

  • documentVersion - In response object at position ‘results[0]._version‘. It may have value of 6.
  • fileId - In response object at position ‘results[0].pdfFile.content‘. It may have value of “kwHd8KMRdeCjTS9aykcRnY6LGrqKWi2NoaowhcdauFEGTTc0RQVdvjI1pwwjwOpP“.

Returned object contains information about the document.

If any of following endpoint calls will require document version and fails with status code ‘409 - Version mismatch’, please call this endpoint again to receive updated document version. There may be some background tasks that change document version after it is created.

Step 6 - Download file

Download file based on its hash (fileId).

Endpoint

GET - /files/loadFile/hash/:hash

Example

/files/loadFile/hash/kwHd8KMRdeCjTS9aykcRnY6LGrqKWi2NoaowhcdauFEGTTc0RQVdvjI1pwwjwOpP?token=b7qDPFh0Tp63nLLMLivrIsx99ejqtWNPwnDVt3vD3ASrpqZiWF615mYjvq2zJ41D

This endpoint now returns the file.

Step 7 - Sign out (Optional)

Sign user out.

Endpoint

GET - /logout

Example

/logout?token=b7qDPFh0Tp63nLLMLivrIsx99ejqtWNPwnDVt3vD3ASrpqZiWF615mYjvq2zJ41D
Circularo.com