Share document to sign and then download the signed file
Circularo REST API example
First user creates new file in Circularo and use it to create the document. Document is then shared to the other user to sign it. Once the user signs the document using frontend, first user downloads 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 “HwBQSK0EmDUsRtqekIiUDsVis2XndQ5lUylw1jF0N7B6qJBViRJ4kz97xXuSG9Wi“.
Step 2 - Create new PDF file
Create new PDF file in the Circularo.
Endpoint
POST - /files/saveFile
Example
/files/saveFile?token=HwBQSK0EmDUsRtqekIiUDsVis2XndQ5lUylw1jF0N7B6qJBViRJ4kz97xXuSG9Wi
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 “zwgBysTGG621fRGar2VvaBGCY53x6umaKPAgqzsFjBBcoUuWeFkh9FV4CTCSf4bM“.
The file is now created.
Step 3 - Create PDF based document
Create new document from existing PDF file.
Endpoint
POST - /documents
Example
/documents?token=HwBQSK0EmDUsRtqekIiUDsVis2XndQ5lUylw1jF0N7B6qJBViRJ4kz97xXuSG9Wi
Content-Type: application/json
{
"body": {
"documentType": "d_default",
"documentTitle": "My file based document",
"pdfFile": {
"content": "zwgBysTGG621fRGar2VvaBGCY53x6umaKPAgqzsFjBBcoUuWeFkh9FV4CTCSf4bM",
"_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 “38716b51-d968-416a-ac57-5ad8f4220c54“.
The PDF based document is now created.
Step 4 - Share document to be signed
Share selected document to internal user for sign.
You can specify multiple users in “data” array and multiple signatures in “signatureFields” array. You can use parameter ‘sequential: true’ to enforce the users will sign the document in given order one-by-one.
Notice the annotation in “signatureFields”, this is there because used document type requires it.
Endpoint
POST - /share
Example
/share?token=HwBQSK0EmDUsRtqekIiUDsVis2XndQ5lUylw1jF0N7B6qJBViRJ4kz97xXuSG9Wi
Content-Type: application/json
{
"id": "38716b51-d968-416a-ac57-5ad8f4220c54",
"type": "d_default",
"objectType": "document",
"data": [
{
"sharePurpose": "sign",
"shareTo": "derek.trotter@circularo.com"
}
],
"signatureFields": [
{
"user": "derek.trotter@circularo.com",
"type": "signature",
"page": 1,
"position": {
"percentX": 0.5,
"percentY": 0.3,
"percentWidth": 0.4,
"percentHeight": 0.1
}
},
{
"user": "derek.trotter@circularo.com",
"type": "annotation",
"subtype": "docId",
"text": "{{{documentId}}}",
"align": "left",
"fontSize": 8,
"backgroundColor": "#ffffff",
"bold": false,
"color": "#000000",
"page": 1,
"position": {
"percentX": 0.5,
"percentY": 0.9,
"percentWidth": 0.2,
"percentHeight": 0.01
}
}
]
}
Response
Note following properties in response object:
- shareId - In response object at position ‘[0].shareId‘. It may have value of “iYK0H5PTggzCetVgRyf71pnFt1UyVnRcQLB87jqWeLBki9KkZNBguRrDDduKdokN“.
The document is now shared to be signed.
Internal user can sign the document using signature field Id property which is now presented in the document.
In case you want to use the frontend to sign the documents, you can use following links:
- For internal user: ‘/#!/sign//
Note: Now the other user signs the document using frontend.
Step 5 - Retrieve document
Retrieve document information.
Endpoint
GET - /documents/:documentId
Example
/documents/38716b51-d968-416a-ac57-5ad8f4220c54?token=HwBQSK0EmDUsRtqekIiUDsVis2XndQ5lUylw1jF0N7B6qJBViRJ4kz97xXuSG9Wi
Response
Note following properties in response object:
- documentVersion - In response object at position ‘results[0]._version‘. It may have value of 12.
- fileId - In response object at position ‘results[0].pdfFile.content‘. It may have value of “F03K4EKi1hMk7UuTbVZHe0oAoAVp8WlLAKAUsYlOzKo8jI40unkzx091Yp7MbRTC“.
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/F03K4EKi1hMk7UuTbVZHe0oAoAVp8WlLAKAUsYlOzKo8jI40unkzx091Yp7MbRTC?token=HwBQSK0EmDUsRtqekIiUDsVis2XndQ5lUylw1jF0N7B6qJBViRJ4kz97xXuSG9Wi
This endpoint now returns the file.
Step 7 - Sign out (Optional)
Sign user out.
Endpoint
GET - /logout
Example
/logout?token=HwBQSK0EmDUsRtqekIiUDsVis2XndQ5lUylw1jF0N7B6qJBViRJ4kz97xXuSG9Wi