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