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.
Step 1 - Sign in (optional)
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
POST /loginRequest
POST /login
Content-Type: application/json
{
"name": "mary.griffin@circularo.com",
"password": "#32Password1!",
"returnToken": true
}Response
The response contains the following important properties:
token - Located at
tokenin the response.Example value:
0cJ7LCKPF75aH0CsDl1QV2bUxYoLQVSrUU0mnqVJo9wIxmsphonaqW2fUagNUUDT
signatureFileId - Located at
user.config.signature[0].imageIdin the response.Example value:
jLBLzityuBvKWcXp8TZTjMgT6op2AuXjUgkjeWesl5c74VVG0AQ8nd1bPjvUh68H
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
POST /files/saveFileRequest
POST /files/saveFile?token=0cJ7LCKPF75aH0CsDl1QV2bUxYoLQVSrUU0mnqVJo9wIxmsphonaqW2fUagNUUDT
Content-Type: multipart/form-data
{
"file": "blob",
"fileName": "My PDF file"
}Response
The response contains the following important properties:
fileHash - Located at
file.idin the response.Example value:
AzCeuNnvQiBzIDt1MYm8dimxCPUVfNorC3gseNiZnoAosHbJXtJQNEB5OEnbuTbF
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
POST /documentsRequest
POST /documents?token=0cJ7LCKPF75aH0CsDl1QV2bUxYoLQVSrUU0mnqVJo9wIxmsphonaqW2fUagNUUDT
Content-Type: application/json
{
"body": {
"documentType": "d_default",
"documentTitle": "My Document",
"pdfFile": {
"content": "AzCeuNnvQiBzIDt1MYm8dimxCPUVfNorC3gseNiZnoAosHbJXtJQNEB5OEnbuTbF" //specify existing file hash
}
},
"definitionType": "ext",
"workflow": "wf_archive",
"optionalData": {
"folder": "9b273bb8-bafa-4b6d-93df-84d93ee2d572" //optional - specify to which folder document will be placed
}
}Response
The response contains the following important properties:
documentId - Located at
results[0].documentIdin the response.Example value:
3043e471-1b8c-4ff4-9142-f95f2f90d6dc
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
We will be requesting signature from an internal user and add a field with his phone number next to the signature.
Endpoint
POST /shareRequest
POST /share?token=0cJ7LCKPF75aH0CsDl1QV2bUxYoLQVSrUU0mnqVJo9wIxmsphonaqW2fUagNUUDT
Content-Type: application/json
{
"id": "3043e471-1b8c-4ff4-9142-f95f2f90d6dc",
"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": "jLBLzityuBvKWcXp8TZTjMgT6op2AuXjUgkjeWesl5c74VVG0AQ8nd1bPjvUh68H",
"pages": [
1
],
"position": {
"percentX": 0.5,
"percentY": 0.3,
"percentWidth": 0.4,
"percentHeight": 0.1
}
}
]
}Response
[
{
"shareId": "gFLq5mz51dNFJhnDdHuf",
"isActive": true,
"isPermanentViewToken": false,
"messageRead": false,
"shareDate": "2023-07-20T14:04:36.186Z",
"shareType": "sign",
"sharedBy": "mary.griffin@circularo.com",
"sharedObjectEsId": "3043e471-1b8c-4ff4-9142-f95f2f90d6dc",
"sharedObjectEsType": "d_default",
"sharedObjectType": "document",
"sharedWith": [
"derek.trotter@circularo.com"
],
"passwordRequired": false,
"sharedUsername": "derek.trotter@circularo.com",
"sequential": false,
"isDelegated": false,
"shareGroup": "1f6fb7d5-979e-40e4-834e-c1392e1367ef",
"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.