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
Circularo.com