Sign document and share it to internal user to sign it

Circularo REST API example

First user creates eDoc document, signs it and shares it to the other user. Then the other user also signs the shared 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 “G2CA52fmcE2ArdzRFCNM1islHBJhC0WMttRPuZWaMZOC3DzUSw9MCe1R5VD8GC2r“.
  • signatureFileId - In response object at position ‘user.config.signature[0].imageId‘. It may have value of “XlpO5QEBHWszp7BcjGzKI8KU9IxdE5gbC9fTx1GAow2ACy1GkVhwMzaKQoHElAWF“.

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=G2CA52fmcE2ArdzRFCNM1islHBJhC0WMttRPuZWaMZOC3DzUSw9MCe1R5VD8GC2r

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 “2390c2d2-f7b7-4cd7-8602-1570c4f6748b“.

The document is now created.

Step 3 - Sign and share document for sign

Sign and annotate document and share it to internal user to be signed.

Endpoint

POST - /share

Example

/share?token=G2CA52fmcE2ArdzRFCNM1islHBJhC0WMttRPuZWaMZOC3DzUSw9MCe1R5VD8GC2r

Content-Type: application/json

{
  "id": "2390c2d2-f7b7-4cd7-8602-1570c4f6748b",
  "type": "d_blank",
  "objectType": "document",
  "data": [
    {
      "sharePurpose": "sign",
      "shareTo": "derek.trotter@circularo.com",
      "message": "Sign me, please"
    }
  ],
  "signatureFields": [
    {
      "user": "derek.trotter@circularo.com",
      "type": "signature",
      "page": 1,
      "position": {
        "percentX": 0.1,
        "percentY": 0.6,
        "percentWidth": 0.2,
        "percentHeight": 0.2
      }
    }
  ],
  "signatures": [
    {
      "type": "signature",
      "blob": "XlpO5QEBHWszp7BcjGzKI8KU9IxdE5gbC9fTx1GAow2ACy1GkVhwMzaKQoHElAWF",
      "page": 1,
      "position": {
        "percentX": 0.5,
        "percentY": 0.3,
        "percentWidth": 0.4,
        "percentHeight": 0.1
      },
      "disableDecoration": true
    }
  ],
  "annotations": [
    {
      "align": "left",
      "backgroundColor": "#ffffff",
      "bold": false,
      "color": "#000000",
      "fontSize": 8,
      "page": 1,
      "percentX": 0.5,
      "percentY": 0.9,
      "percentWidth": 0.2,
      "percentHeight": 0.01,
      "subtype": "docId",
      "text": "{{{documentId}}}"
    }
  ]
}

Response

Note following properties in response object:

  • shareIdInternal - In response object at position ‘[0].shareId‘. It may have value of “LVoxRE8lwYrBkdtbPrBsMuPcNSaqCNXW138PRnlKuliwSwuuNesaX4Yrq2XMQb2E“.

The document is now signed and shared to the other user for another sign.

Step 4 - Sign out (Optional)

Sign user out.

Endpoint

GET - /logout

Example

/logout?token=G2CA52fmcE2ArdzRFCNM1islHBJhC0WMttRPuZWaMZOC3DzUSw9MCe1R5VD8GC2r

Step 5 - Sign second user in

Sign second user in.

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 “x7QwMNBHFfjWsL8O1cOaxHVLqBkhSkeIAgF7YhyaSTXoVVV0RBD7jTtxd6uLagNr“.
  • signatureFileId - In response object at position ‘user.config.signature[0].imageId‘. It may have value of “UZn57mnwe9fQvR0PrNnBUUtTCbuLAiCOvvJi5N5Im87BKVDr14Isb8tX7GgdjYjN“.

Step 6 - Retrieve document

Retrieve document information.

Endpoint

GET - /documents/:documentId

Example

/documents/2390c2d2-f7b7-4cd7-8602-1570c4f6748b?token=x7QwMNBHFfjWsL8O1cOaxHVLqBkhSkeIAgF7YhyaSTXoVVV0RBD7jTtxd6uLagNr

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 “LGipxWSVjLmQVytw“.

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 shared document

Internal user signs the document using the shareId.

Endpoint

PUT - /share/document/sign/:documentVersion

Example

/share/document/sign/3?shareId=LVoxRE8lwYrBkdtbPrBsMuPcNSaqCNXW138PRnlKuliwSwuuNesaX4Yrq2XMQb2E

Content-Type: application/json

{
  "id": "2390c2d2-f7b7-4cd7-8602-1570c4f6748b",
  "type": "d_blank",
  "signatures": [
    {
      "blob": "UZn57mnwe9fQvR0PrNnBUUtTCbuLAiCOvvJi5N5Im87BKVDr14Isb8tX7GgdjYjN",
      "decorationType": "empty",
      "signFieldId": "LGipxWSVjLmQVytw"
    }
  ]
}

The document is now signed.

Step 8 - Sign out (Optional)

Sign user out.

Endpoint

GET - /logout

Example

/logout?token=x7QwMNBHFfjWsL8O1cOaxHVLqBkhSkeIAgF7YhyaSTXoVVV0RBD7jTtxd6uLagNr

eDoc document is now signed by both users.

Circularo.com