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.

Circularo.com