Create new signature template, then use it to create and sign share a document
Circularo REST API example
Creates new signature template based on external file. This template is then used to create and sign share new document.
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 “oU6FZDg8FGpJylSeL1WBjvIxjuAi5j80rYl40T20exfUOJspsNBiPiTxVJs3wMFi“.
Step 2 - Create new PDF file
Create new PDF file in the Circularo.
Endpoint
POST - /files/saveFile
Example
/files/saveFile?token=oU6FZDg8FGpJylSeL1WBjvIxjuAi5j80rYl40T20exfUOJspsNBiPiTxVJs3wMFi
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 “MwJadlyzcj2UecsmaQJgPvS1Az5sWfDaOpZcbo1O6nCecAYsCI9Hqd37DyeMQOIE“.
The file is now created.
Step 3 - Create new signature template
Creates new signature template based on an external file. The template contains all the data necessary to create and share new documents.
Endpoint
POST - /enums/templates/record
Example
/enums/templates/record?token=pl2Z4W2TlZqHsCLyAwYqImHadLGR4eHFiTaYIQ9ywW3rFocIZE9v3OZfwfxdu6Zj
Content-Type: application/json
{
"data": {
"name": "My Template",
"type": "sign",
"documentType": "d_default",
"definitionType": "ext",
"fields": [
"D_DEFAULT_DESCRIPTION"
],
"file": "vTFOiushnmQMpAn1wSLVYKFzDzJjerzk0cWsMwlWqIDrn27jpGYEJ2ExGi1LGV5L",
"signFields": [
{
"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
}
},
{
"type": "annotation",
"subtype": "annotation_generic",
"customId": "mySpecificAnnotation",
"text": "API easily identifiable annotation",
"align": "left",
"fontSize": 8,
"backgroundColor": "#ffffff",
"bold": false,
"color": "#000000",
"page": 1,
"position": {
"percentX": 0.6,
"percentY": 0.75,
"percentWidth": 0.2,
"percentHeight": 0.01
}
}
]
}
}
Response
Note following properties in response object:
- templateId - In response object at position ‘id‘. It may have value of “dbb8ff65-1941-48a8-b2e5-c76164589731“.
The template is now created and its data can be used later.
One the annotation fields contains a "customId" property so it can be easily identified later and used as needed.
Note
The template is now ready to be used. See below how to read template data and use them to create and sign share document.
Step 4 - Get existing signature template
Gets existing signature template and its data.
Endpoint
GET - /enums/templates/record/:templateId
Example
/enums/templates/record/dbb8ff65-1941-48a8-b2e5-c76164589731?token=oU6FZDg8FGpJylSeL1WBjvIxjuAi5j80rYl40T20exfUOJspsNBiPiTxVJs3wMFi
Returned template contains all data saved before. You can use them to create and share new document.
Step 5 - Create new document
Creates new document from template data.
Endpoint
POST - /documents
Example
/documents?token=oU6FZDg8FGpJylSeL1WBjvIxjuAi5j80rYl40T20exfUOJspsNBiPiTxVJs3wMFi
Content-Type: application/json
{
"body": {
"customTemplate": "dbb8ff65-1941-48a8-b2e5-c76164589731",
"documentType": "d_default",
"documentTitle": "My template based document",
"pdfFile": {
"content": "MwJadlyzcj2UecsmaQJgPvS1Az5sWfDaOpZcbo1O6nCecAYsCI9Hqd37DyeMQOIE",
"_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 “92f4a880-6b6d-4c02-ba1c-30fb7cbeecdc“.
documentVersion - In response object at position 'results[0]._version'. It may have value of 5.
Document is now created.
Step 6 - Annotate document
We have stored a specific annotation in the template, which can now be identified by its "customId". We can use this annotation to annotate the document using the original stored text value, or we can use a different value as needed.
Endpoint
PUT - /documents/annotate/:documentVersion
Example
/documents/annotate/5?token=pl2Z4W2TlZqHsCLyAwYqImHadLGR4eHFiTaYIQ9ywW3rFocIZE9v3OZfwfxdu6Zj
Content-Type: application/json
{
"id": "7d9fbba1-fcfd-4db7-9e44-3a9818d42612",
"annotations": [
{
"align": "left",
"bold": false,
"color": "#000000",
"backgroundColor": "#ffffff",
"fontSize": 8,
"page": 1,
"position": {
"percentX": 0.6,
"percentY": 0.75,
"percentWidth": 0.2,
"percentHeight": 0.01
},
"text": "Custom value"
}
]
}
The document is now annotated. We used a specific annotation stored in the template with custom annotation text.
Step 7 - Share document
Share document to be signed. Signature fields come from the template.
Endpoint
POST - /share
Example
/share?token=oU6FZDg8FGpJylSeL1WBjvIxjuAi5j80rYl40T20exfUOJspsNBiPiTxVJs3wMFi
Content-Type: application/json
{
"id": "92f4a880-6b6d-4c02-ba1c-30fb7cbeecdc",
"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 “luW8WcOU2QOTE7hthvgTfrbqGlvcrrQeAsGmBY0si0UB3LRWA8k65lIiupl9mFSZ“.
The document is now shared to be signed.
Step 8 - Sign out (Optional)
Sign user out.
Endpoint
GET - /logout
Example
/logout?token=oU6FZDg8FGpJylSeL1WBjvIxjuAi5j80rYl40T20exfUOJspsNBiPiTxVJs3wMFi