Let recipients sign sequentially
Circularo REST API example
First user creates eDoc document and shares it to one internal and one external recipient for sign. Recipients sign the document sequentially (in selected order).
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 “ZnpR09Jv83ong4cHULDYLQCSvYrjlPi5zZ9rX6UgcUhc9UJyNttQDYnlEK8prr8S“.
Step 2 - Create new eDoc document
Create new eDoc document. eDoc is created from “documentType” HTML template and user inputs.
“D_BLANK_TEXTAREA” is document type specific variable.
Endpoint
POST - /documents
Example
/documents?token=ZnpR09Jv83ong4cHULDYLQCSvYrjlPi5zZ9rX6UgcUhc9UJyNttQDYnlEK8prr8S
Content-Type: application/json
{
"body": {
"documentType": "d_blank",
"documentTitle": "My document",
"D_BLANK_TEXTAREA": "Definition specific field value."
},
"definitionType": "edoc",
"workflow": "wf_archive"
}
Response
Note following properties in response object:
- documentId - In response object at position ‘results[0].documentId‘. It may have value of “cd47142b-2618-4993-acaa-15c662929c17“.
The document is now created.
Step 3 - Share document for sign
Share selected document to internal and external recipient to be signed.
As we specify ‘“sequential”: true’, users will sign the document one-by-one in the same order as the are defined.
Notice the annotation in “signatureFields”, this is there because used document type requires it.
Endpoint
POST - /share
Example
/share?token=ZnpR09Jv83ong4cHULDYLQCSvYrjlPi5zZ9rX6UgcUhc9UJyNttQDYnlEK8prr8S
Content-Type: application/json
{
"id": "cd47142b-2618-4993-acaa-15c662929c17",
"type": "d_blank",
"objectType": "document",
"sequential": true,
"data": [
{
"sharePurpose": "sign",
"shareTo": "derek.trotter@circularo.com",
"message": "Sign me"
},
{
"sharePurpose": "sign",
"shareTo": "external.bill@circularo.com",
"message": "Sign me, please",
"password": "SharePassword"
}
],
"signatureFields": [
{
"user": "derek.trotter@circularo.com",
"type": "signature",
"page": 1,
"position": {
"percentX": 0.1,
"percentY": 0.2,
"percentWidth": 0.2,
"percentHeight": 0.2
}
},
{
"user": "external.bill@circularo.com",
"type": "signature",
"page": 1,
"position": {
"percentX": 0.1,
"percentY": 0.6,
"percentWidth": 0.2,
"percentHeight": 0.2
}
},
{
"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:
- shareIdInternal - In response object at position ‘[0].shareId‘. It may have value of “FG0GTjrpXKSradhpMSnTqXBNWNJRVNItNLbaEKDsZHQLTKakV8TbWtOIs75CuDMK“.
- shareIdExternal - In response object at position ‘[1].shareId‘. It may have value of “wbpyKVuuXdKYiCp9TXQQxKuVntSF0lWzPbgFspfK9PlQJl8o58SykF8L9tkBtzfF“.
The document is now shared to two users to be signed.
In case you want to use the frontend to sign the document, you can use following links:
- For internal user: ‘/#!/sign//‘
- For external recipient: ‘/#!/share?shareId=‘
Step 4 - Sign out (Optional)
Sign user out.
Endpoint
GET - /logout
Example
/logout?token=ZnpR09Jv83ong4cHULDYLQCSvYrjlPi5zZ9rX6UgcUhc9UJyNttQDYnlEK8prr8S
Step 5 - Sign second user in
Sign second user in.
This user already has signature specified. For more information please see our scenario Set signature to user
.
Endpoint
POST - /login
Example
/login
Content-Type: application/json
{
"name": "derek.trotter@circularo.com",
"password": "#del.boy!",
"tenant": "default"
}
Response
Note following properties in response object:
- token - In response object at position ‘token‘. It may have value of “Vr4KkdTpf8fCLpt4s3DjoLqyI6lzHmOMe9Ol3IC0FPdqU4Z5VjAoQPmQMY4uYjUj“.
- signatureFileId - In response object at position ‘user.config.signature[0].imageId‘. It may have value of “buqPu8BWP3MDcMIViKJHRdGHm785Mkf7N16gkLKaM7qELBZt5amYLyjbx5hPc1au“.
Step 6 - Retrieve document
Retrieve document information.
Endpoint
GET - /documents/:documentId
Example
/documents/cd47142b-2618-4993-acaa-15c662929c17?token=Vr4KkdTpf8fCLpt4s3DjoLqyI6lzHmOMe9Ol3IC0FPdqU4Z5VjAoQPmQMY4uYjUj
Response
Note following properties in response object:
- documentVersion - In response object at position ‘results[0]._version‘. It may have value of 3.
- signatureFieldId - In response object at position ‘results[0].signFields[0].id‘. It may have value of “cgCGFTsVNGhjKbSM“.
- annotationFieldId - In response object at position ‘results[0].signFields[2].id‘. It may have value of “sRdDsBzjterhkCdi“.
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 7 - Internal user signs and annotates shared document
Internal user signs and annotates the document using the shareId.
Endpoint
PUT - /share/document/sign/:documentVersion
Example
/share/document/sign/3?shareId=FG0GTjrpXKSradhpMSnTqXBNWNJRVNItNLbaEKDsZHQLTKakV8TbWtOIs75CuDMK
Content-Type: application/json
{
"id": "cd47142b-2618-4993-acaa-15c662929c17",
"type": "d_blank",
"annotations": [
{
"percentHeight": 0.01,
"signFieldId": "sRdDsBzjterhkCdi",
"text": "DocID:cd47142b-2618-4993-acaa-15c662929c17"
}
],
"signatures": [
{
"blob": "buqPu8BWP3MDcMIViKJHRdGHm785Mkf7N16gkLKaM7qELBZt5amYLyjbx5hPc1au",
"decorationType": "empty",
"signFieldId": "cgCGFTsVNGhjKbSM"
}
]
}
The document is now signed.
Step 8 - Sign out (Optional)
Sign user out.
Endpoint
GET - /logout
Example
/logout?token=Vr4KkdTpf8fCLpt4s3DjoLqyI6lzHmOMe9Ol3IC0FPdqU4Z5VjAoQPmQMY4uYjUj
Step 9 - External recipient uploads signature
External recipient uploads its signature for document signing.
Endpoint
POST - /share/upload/signature
Example
/share/upload/signature?shareId=wbpyKVuuXdKYiCp9TXQQxKuVntSF0lWzPbgFspfK9PlQJl8o58SykF8L9tkBtzfF&otp=SharePassword
Content-Type: multipart/form-data
{
"file": "blob"
}
Response
Note following properties in response object:
- fileId - In response object at position ‘id‘. It may have value of “tICKXaOnZ7eMUIWc9TCHikdt0p5QLH4E739lq9Jy3XfdlgQEMHZV7H1aoj2sjomp“.
The signature is now uploaded.
Step 10 - Get shared document information
Retrieve shared document information.
Endpoint
GET - /share/document
Example
/share/document?shareId=wbpyKVuuXdKYiCp9TXQQxKuVntSF0lWzPbgFspfK9PlQJl8o58SykF8L9tkBtzfF&otp=SharePassword
Response
Note following properties in response object:
- documentVersion - In response object at position ‘results._version‘. It may have value of 5.
- signatureFieldId - In response object at position ‘results.signFields[1].id‘. It may have value of “cPDPZrNXdlywozDd“.
Retrieved object contains information about the document and interested users.
Step 11 - External recipient signs shared document
External recipient signs the document using the shareId and password.
Endpoint
PUT - /share/document/sign/:documentVersion
Example
/share/document/sign/5?shareId=wbpyKVuuXdKYiCp9TXQQxKuVntSF0lWzPbgFspfK9PlQJl8o58SykF8L9tkBtzfF&otp=SharePassword
Content-Type: application/json
{
"id": "cd47142b-2618-4993-acaa-15c662929c17",
"type": "d_blank",
"signatures": [
{
"blob": "tICKXaOnZ7eMUIWc9TCHikdt0p5QLH4E739lq9Jy3XfdlgQEMHZV7H1aoj2sjomp",
"decorationType": "empty",
"signFieldId": "cPDPZrNXdlywozDd"
}
]
}
The document is now signed.
eDoc document is now signed by both recipients.