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