Documents

Document Basics¶

A document is basically a PDF File that is uploaded to Techsign DOC to be signed by one or more recipients. Techsign DOC holds this document as a combination of meta data (document object) and the corresponding PDF File. At the end of the workflow, a signed PDF File is created, which can be downloaded for future use or can be queried from Techsign DOC using the document meta data.

Getting and Listing Document Information¶

Every document in Techsign DOC has a corresponding UUID (universally unique identifier) and can be queried/handled using this UUID. Getting a document means getting the meta data of the document, ie getting the document data object, and can be completed using the following method:

GET /doc/{docId}

where docId means the UUID of the document. This method returns all relevant document data, which is explained below.

Curl request:

--- SHOW/HIDE ---

Returned data model:

--- SHOW/HIDE ---

{
  "id": "(UUID)",
  "name": "(document name)",
  "createdAt": "(document creation date)",
  "createdBy": "(document owner/created by)",
  "numberOfPages": "(if document has a valid PDF,
  number of pages is listed here)",
  "description": "(additional document description)",
  "status": "(document status, can be
  DRAFT/READY/SIGNED/DECLINED/EXPIRED)",
  "expireDate": "(document expiration date)",
  "recipients": [
    {
          "_comment":"Recipients of the document",
      "email": "(Email of the recipient)",
      "name": "(Name of the recipient)",
      "recipientType": "(Recipient type,
          can be signer/viewer)",
      "note": "(Notes for the recipient)",
      "authRequired": "(signer shall enter an authcode
          before signing, true/false)",
      "authCode": "(auth code, if required)",
      "authDeliveryType": "(how the auth code is delivered)",
      "orderNum": "(order of the recipient,
          if the recipients shall sign in order)"
    }
  ],
  "signatureLevel": "(how the document shall be signed,
  default LTA)",
  "pdfTemplate": {
        "_comment":"This template defines how data objects
        and signatures are placed on the PDF",
    "textFields": [
      {
            "_comment":"Static text fields",
        "id": "(UUID)",
        "value": "(text of the text field)",
        "rectangle": {
                  "_comment":"Where to place the field,
                  typical for each object",
          "leftTop": {
            "x": "(Left Top point X coordinate)",
            "y": "(Left Top point Y coordinate)"
          },
          "rightBottom": {
            "x": "(Right Bottom point X coordinate)",
            "y": "(Left Bottom point Y coordinate)"
          },
          "page": "(Page of the object)"
        },
        "font": "(Font of the text)",
        "fontSize": "(Font size of the text)",
        "fontColor": {
                 "_comment":"Font color, as rgb",
          "red": 0,
          "green": 0,
          "blue": 0
        },
        "owner": "(Owner (email) of the object,
                typical for each object)"
      }
    ],
    "editTextFields": [
      {
           "_comment":"Text fields which are editable by the owners,
           only differences from Static Text Fields listed below",
        "defaultText": "(Default value, if not edited)",
        "isRequired": "(Is editing this field mandatory
                before signing)",
        "isMultiline": "(True for multiple lines,
                false for single line)"
      }
    ],
    "dateFields": [
      {
          "_comment":"Date fields which can be set by the owners,
          only differences from Text Fields listed below",
        "format": "Date Format"
      }
    ],
    "dropDownFields": [
      {
          "_comment":"Drop down fields which can be set by the owners,
          only differences from Text Fields listed below",
        "optionList": [
          "(List of options, as string)"
        ],
        "selected": "(Selected option)"
      }
    ],
    "radioButtonFields": [
      {
          "_comment":"Radio button fields which can be set by the owners,
          only differences from Text Fields listed below",
       "radioList": [
          { "_comment":"A radio button field is a set of radio button
                  items, for which details are listed below",

          }
        ],
        "selected": "(Selected radio button list id)"
      }
    ],
    "checkBoxFields": [
      {
          "_comment":"Check box fields which can be set by the owners,
          only differences from Text Fields listed below",
        "isSelected": "true if selected by default, false otherwise"

      }
    ],
    "signatures": [
      {
           "_comment":"Signature areas where owner signs the document
           by adding signature, signature specific areas listed below",
        "clickToSign": "(True if signing can be completed by
                only clicking)",
        "drawToSign": "(True if biometric signature information
                shall not be captured)",
        "properties": [
          {
                "_comment":"(Additional properties, can be left empty)",
            "key": "string",
            "value": "string"
          }
        ]
      }
    ]
  },
  "orgId": "(Company/Organisation ID to which this document
  belongs to)",
  "pdfId": "(PDF ID if uploaded)",
  "message": "(Message sent to recipients)",
  "attachments": [
    {
        "_comment":"List of attachments, if necessary",
      "id": "(UUID)",
      "name": "(name of the uploaded attachment)",
      "identifier": "(how is this attachment called)",
      "owner": "(Which recipient shall add this attachment)"
    }
  ]
}

Get method can be used when the UUID is known in the workflow, ie when the document is newly created or sent to the user for signing. However, this is not always the case. A user may want to list its documents, in order to select a document to continue with the workflow. In this case, the listing method can be used, with the route:

POST /doc/massdocuments

This route accepts the following data object as POST Body:

--- SHOW/HIDE ---

Curl request:

--- SHOW/HIDE ---

Returns the following result:

--- SHOW/HIDE ---

By adding necessary business filters, such as requesting SIGNED or READY documents with status column, this API method can be used for many different purposes in a typical API integration.

Creating and Updating Documents¶

Document creation is the first step of a document’s life cycle. A document shall be created before a PDF can be linked to it, and can be updated with recipients and a PDF template to start the signing process.

A document is created with the following method:

POST /doc/create

where a document object is sent as POST Body:

--- SHOW/HIDE ---

Curl request:

--- SHOW/HIDE ---

This method, if successful, returns the UUID of the newly created document, which can be used to further enhance document information or upload a PDF for the document. For document update, the following method is used with the same POST Body:

POST /doc/{docId}/update

Curl request:

--- SHOW/HIDE ---

Create Document From Template¶

Documents can be easily created by using templates.

The following method is used to create documents from previously created templates:

POST /doc/{templateId}/copyFromTemplate

Curl request:

--- SHOW/HIDE ---

The output of this method is “document id”. In previous parts, document update operation was explained in details. If anyone needs to change recipients or any other things on document, he/she may use document update method.

Managing Document Files (PDFs)¶

Every document shall be associated with a PDF file in order to be signed. PDF File is the universal carrier of signing proof and is a standalone entity to prove/disprove any signing claim. Signing process is completed on this PDF File and after signing the file can not be changed without marking the signatures invalid.

A PDF is created/updated for a document using the following method:

POST /doc/{docId}/pdf

Curl request:

--- SHOW/HIDE ---

which takes the UUID of the document as route parameter and the PDF File as multipart/form-data.

The current PDF of a document can be queried using the method:

GET /doc/{docId}/pdf

Which returns application/pdf as result.

Curl request:

--- SHOW/HIDE ---

Removing Documents¶

Documents can be deleted in case of an error or in order to free storage space. Note that after a document is deleted, it only lefts a mark on workflow history and can not be queried/fetched by any means. Both document metadata and PDF file are erased from Techsign DOC servers.

The following method is used to delete documents, with UUID:

DELETE /doc/{docId}

Curl request:

--- SHOW/HIDE ---