NAV

Introduction

Welcome to Dedoco Platform API Specifications for Developers!

This document contains the API specifications for integration with the Dedoco Platform. The Dedoco platform manages business and document processes and stores the relevant evidence on blockchain. Dedoco APIs interface between the frontend, application logic and the blockchain smart contracts, allowing the document process to be managed in a trusted and immutable manner.

Version History

Date Content
29 Oct 2021 Version 0.6g
Added verification endpoint
1 Oct 2021 Version 0.6f
Updated sequence diagram
13 Sep 2021 Version 0.6e
Added OTP feature for signers
8 Sep 2021 Version 0.6d
Added "type" field to custom texts
9 Jun 2021 Version 0.6c
Updated instructions on completion of generated links
26 Mar 2021 Version 0.6b
Added sample requests and responses
15 Mar 2021 Version 0.6a
Added API Developer Account process
12 Mar 2021 Version 0.6
Added attributes details
10 Mar 2021 Version 0.5
Initial Release

A. API Developer Account

To have access to our Early Access (EA) API Platform, please provide the following information and submit your application request to developers@dedoco.com.

Name of Organization:
Business Address:
Business Country:
Business Website URL:

Contact Person (Full Name):
Contact Person (Email):
Contact Person (Mobile):

Application Name:
Application Description/Use Case:
Application Type: [ Internal Use | Public SaaS | Enterprise App | Development | Testing | Others ]
Application URL:

After your application has been reviewed and approved, you will receive an email containing the API credentials to access the Dedoco EA API platform.

B. Sequence Diagram

C. Authentication

Dedoco uses JWT tokens to allow access to Dedoco’s public API. Clients can request for a JWT token through the Get JWT token endpoint. Dedoco expects for the JWT token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <jwt_token>

where jwt_token should be replaced with the obtained JWT token. The following section describes the attributes of the JWT token.

JWT Payload

Attribute Type Description
subId string Id of the subject (i.e. client id).
subTyp string Type of the subject. “public” in this case.
usrName string Name of the client’s user the client is requesting the JWT token on behalf of. This attribute will not exist if not provided in the Get JWT token endpoint.
usrEmail string Email address of the client’s user the client is requesting the JWT token on behalf of. This attribute will not exist if not provided in the Get JWT token endpoint.
iat number Unix time the JWT token was issued at.
exp number Unix time the JWT token will expire by.
v number Version number of Dedoco’s API that generated the JWT token.

Endpoint: Get JWT Token

POST /public/auth/token HTTP/1.1
Generates a JWT token.

Authorization:
Basic

Content-Type:
application/json

Header Parameters:

Parameters Type Description Required/Optional
client_id string Id sent to the client during the onboarding process Required
client_secret string Secret sent to the client during the onboarding process. Required

Request Body:

The callback url for fileCallback should accept POST requests with the following request body:

{
  "businessProcessId": string,
  "file": string
}

where businessProcessId is the id of the business process the updated file is sent for and
> file is the base64 string of the updated pdf.

The callback url for callbackStatus should accept POST requests with the request body:

{
  "businessProcessId": string,
  "status": string,
  "signers": {
    "id": string,
    "name": string,
    "email": string,
    "sequence_number": number,
    "has_signed": boolean
  }[]
}

where businessProcessId is the id of the business process the status is sent for,
> status is a string describing the state of the business process,
> signers is an array of objects containing information on each signer,
> signers.has_signed indicates if the signer has signed, and
> signers.sequence_number exists only if the signers are required to sign in a sequence for the business process.

Attribute Type Description Required/Optional
fileCallback string Client’s callback url for Dedoco to send updated files to. Required
statusCallback string Client’s callback url for Dedoco to notify the client on changes in the statuses of the client’s business processes. Required
userName string Name of the client’s user the client is requesting the JWT token on behalf of. Optional
userEmail string Email address of the client’s user the client is requesting. Optional

Responses:

Response body for code 201:

{
  "token": string
}

Response body for code 4xx:

{
  "statusCode": number,
  "message": string,
  "error": string
}

where statusCode is the status code of the error,
> message is a string describing the cause of error and
> error is a string describing the type of error.

Response body for code 5xx:

{
  "statusCode": number,
  "message": string,
  "error": string
}

where statusCode is the status code of the error,
> message is a string describing the cause of error and
> error is a string describing the type of error.

Code Description
201 JWT token has been successfully granted.
4xx Errors caused by API consumers. Error codes such as 400, 401, 403 and 404 can be expected if incorrect requests are made to the API.
5xx Errors caused by the API provider or its dependencies. Error codes such as 500, 502 and 503 can be expected if there is an issue on the API side.
Child attribute Type Description
token string Base64 string of the encoded JWT token. Refer to JWT payload for more details.

Sample Request Header:

POST https://beta-api.dedoco.com/api/v1/public/auth/token HTTP/1.1
content-type: application/json
Authorization: Basic <id> <secret>

Sample Request Body:

{
  "fileCallback": "https://sample-url.com/file-callback",
  "statusCallback": "https://sample-url.com/status-callback",
  "userName": "Jim Lee",
  "userEmail": "jimmylee@gmail.com"
}

Sample Response Header:

HTTP/1.1 201 Created

Sample Request Body

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWJJZCI6IjhiMjIyY2JiLTA2ZTMtNGY5Yi1iNzljLTA4Y2FjMjdlOGZhYSIsInN1YlR5cCI6InB1YmxpYyIsInVzck5hbWUiOiJKaW0gTGVlIiwidXNyRW1haWwiOiJqaW1teWxlZUBnbWFpbC5jb20iLCJ2IjoiMSIsImlhdCI6MTYxNjc0MjMzNSwiZXhwIjoxNjE2Nzg1NTM1fQ...."
}

D. Folders

Folders are used to group relevant document(s). A folder can have multiple documents but must contain at least one document.

Folder Attributes

Attribute Type Description
id string Unique identifier of the folder.
name string Name of the folder set by the creator of the folder. Could be used as a descriptor.
date_created date Time the folder is created. Cannot be changed after the folder is created.
child_documents string[] Array of ids of the documents contained in the folder.
linked_folders string[] Array of ids of linked folders (if any). Linking of folders is an optional functionality to indicate the relevance of the folders to each other but at the same time retaining their segregation as separate folders.
status string Value could be “active”, “closed” or “voided”. “active” indicates that the folder is valid and still in use. “closed” indicates that the folder is valid but not in use at the moment. “voided” indicates that the folder is invalid and no longer in use.
history object[] Array of objects involving changes made to the folder

A history object:

{
  "action": string,
  "actor": {
    "id": string,
    "email": string,
    "name": string
  },
  "timestamp": date,
  "transaction_hash": string
}
Child Attribute Type Description
history.action string Description of the action recorded in the history attribute.
history.actor.id string User id of the entity that took the action.
history.actor.email string Email address (if any) of the entity that took the action.
history.actor.name string Name (if any) of the entity that took the action.
history.timestamp date Time the action took place.
history.timestamp_hash string Hash of the blockchain transaction updating the data (only if there are any changes in data) on the blockchain due to the action that took place. Can be used to view the transaction details on the blockchain’s explorer.

Endpoint: Create Folder

POST /public/folders HTTP/1.1
Creates a folder along with documents and business processes. Existing folders can be linked to the folder to be created.

Authorization:
Bearer <jwt_token>

Content-Type:
application/json

Header Parameter:

Parameter Type Description Required/Optional
jwt_token string Token obtained by the client through the Get JWT Token endpoint. Required

Request Body:

A documents object:

{
    "name": string,
    "file_type": string,
    "document_hash": string
}

A business_processes object:

{
    "type": string,
    "expiration_time": number,
    "document_id": number,
    "is_sequential": boolean,
    "allow_download": boolean,
    "signers": {
      "signer_email": string,
      "signer_name": string,
      "signer_phone": string,
      "sequence_number": number,
      "require_authentication": boolean,
      "verify_method": string,
      "esignatures": {
        "placement": {
          "page": number,
          "x": string,
          "y": string
        },
        "dimensions": {
          "width": string,
          "height": string
        }
      }[],
      "digi_signatures": {
        "type": string,
        "placement": {
          "page": number,
          "x": string,
          "y": string
        },
        "dimensions": {
          "width": string,
          "height": string
        }
      }[],
      "custom_texts": {
        "descriptor": string,
        "is_mandatory": boolean,
        "type": string,
        "placement": {
          "page": number,
          "x": string,
          "y": string
        },
        "dimensions": {
          "width": string,
          "height": string
        }
      }[]
    }[],
    "completion_requirement": {
      "min_number": number
    }
}
Attribute Type Description Required/Optional
folder_name string Name of the folder. Set by the folder's creator. Required
date_created date Date of folder creation in Unix time. Required
documents object[] Array of objects, represented on the right. More details are given below. Required
linked_folders string[] Array of ids of linked folders (if any). Optional (Use an empty array if not used)
business_processes object[] Array of objects, represented on the right. More details are given below. Optional (Use an empty array if not used)

A business_processes.signers object

{
    "signer_email": string,
    "signer_name": string,
    "signer_phone": string,
    "sequence_number": number,
    "require_authentication": boolean,
    "verify_method": string,
    "esignatures": {
        "placement": {
            "page": number,
            "x": string,
            "y": string
        },
        "dimensions": {
            "width": string,
            "height": string
        }
    }[],
    "digi_signatures": {
        "type": string,
        "placement": {
            "page": number,
            "x": string,
            "y": string
        },
        "dimensions": {
            "width": string,
            "height": string
        }
    }[],
    "custom_texts": {
        "descriptor": string,
        "is_mandatory": boolean,
        "type": string,
        "placement": {
            "page": number,
            "x": string,
            "y": string
        },
        "dimensions": {
            "width": string,
            "height": string
        }
    }[]
}

A business_processes.signers.esignatures object

{
    "placement": {
        "page": number,
        "x": string,
        "y": string
    },
    "dimensions": {
        "width": string,
        "height": string
    }
}

A business_processes.signers.esignatures.placement object:

{
    "page": number,
    "x": string,
    "y": string
}

A business_processes.signers.esignatures.dimensions object:

{
    "width": string,
    "height": string
}

A business_processes.signers.digi_signatures object:

{
    "type": string,
    "placement": {
        "page": number,
        "x": string,
        "y": string
    },
    "dimensions": {
        "width": string,
        "height": string
    }
}

A business_processes.signers.digi_signatures.placement object:

{
    "page": number,
    "x": string,
    "y": string
}

A business_processes.signers.digi_signatures.dimensions object:

{
    "width": string,
    "height": string
}

A business_processes.signers.custom_texts object:

{
    "descriptor": string,
    "is_mandatory": boolean,
    "type": string,
    "placement": {
        "page": number,
        "x": string,
        "y": string
    },
    "dimensions": {
        "width": string,
        "height": string
    }
}

A business_processes.signers.custom_texts.placement object:

{
    "page": number,
    "x": string,
    "y": string
}

A business_processes.signers.custom_texts.dimensions object:

{
    "width": string,
    "height": string
}
Child attribute Type Description
documents.name string Name of the document. Does not need to follow the original name of the file and could be used as a descriptor.
documents.file_type string File type of the file used as the document. Accepted values are “pdf” and “json”, but only “pdf” is supported at the moment.
documents.document_hash string SHA3-256 hash of the file in hexadecimal format without the ‘0x’ prefix.
business_processes.type string Currently, the only supported business process type is “signature”.
business_processes.expiration_time number Expiration time of the business process in Unix. Value must be higher than the current Unix time unless there is no expiration time. Use 0 if there is no expiration time.
business_processes.document_id number Index of the document in this request body’s documents attribute to attach the business process to.
business_processes.is_sequential boolean Boolean indicating if the business process requires signers to sign in a sequence. Note that signers have to sign in a sequence if digital signatures are used.
business_processes.allow_download boolean Boolean indicating if the signers are allowed to manually download the signed pdf on Dedoco’s signing app after signing.
business_processes.signers object[] Array of objects. The structure of an object is given on the right.
business_processes.signers
.signer_email
string Email address of the signer.
business_processes.signers
.signer_name
string Name of the signer.
business_processes.signers
.signer_phone
string Phone number of the signer. E.164 format is expected. E.164 numbers are formatted +[country code][subscriber number including area code]. E.g. for a Singapore number 8123 4567, the E.164 string is “+6581234567”.
business_processes.signers
.sequence_number
number Sequence number of the signer if the business process requires signers to sign in a sequence. Starts from 1. 0 is used if there is no sequence.
business_processes.signers
.require_authentication
boolean Boolean indicating whether or not the signer is required to be authenticated (via either email or SMS OTPs) before accessing the signing link.
business_processes.signers
.verify_method
string String indicating means to send OTP (if authentication is required). Possible values are “SMS”, “EMAIL” and “NO_AUTHENTICATION”. Use “SMS” if using SMS to send OTP. Use “EMAIL” if using email to send OTP. Use “NO_AUTHENTICATION” if the signer is not required to be authenticated.
business_processes.signers
.esignatures
object[] Array of objects. The structure of an object is given on the right.
Each object represents an electronic signature placeholder. An electronic signature, as opposed to a digital signature, is an image that is drawn, typed or uploaded by the signer. Use an empty array to indicate that electronic signature is not used.
Note that due to the nature of how a digital signature is computed, all signers of the same business process can only and have to sign either using electronic signatures or digital signatures.
business_processes.signers
.esignatures.placement
object Object containing information on where the electronic signature is placed on the file.
business_processes.signers
.esignatures.placement.page
number Page number of the page on which the electronic signature is placed. Starts from 1.
business_processes.signers
.esignatures.placement.x
string Float string which indicates the horizontal distance the top left corner of the electronic signature box is from the left edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the placement of the electronic signature box’s top left corner to the center of the page horizontally, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the width of the electronic signature box for the entire signature box to be contained within the page) is strictly less than 1.
business_processes.signers
.esignatures.placement.y
string Float string which indicates the vertical distance the top left corner of the electronic signature box is from the top edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the placement of the electronic signature box’s top left corner to the center of the page vertically, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the height of the electronic signature box for the entire signature box to be contained within the page) is strictly less than 1.
business_processes.signers
.esignatures.dimensions
object Object containing information on the size of the electronic signature on the file.
business_processes.signers
.esignatures.dimensions.width
string Float string which indicates the width of the electronic signature box. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the width of the electronic signature box to be half of the page’s width, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the x-coordinate of the electronic signature box for the entire signature box to be contained within the page) is less than 1.
Note that currently, even though this value will be validated and stored, the stored value will not be used by Dedoco’s signing app because electronic signatures are displayed in a fixed height:width ratio (1:2 specifically) using business_processes.signers.esignatures.dimensions.height as reference.
business_processes.signers
.esignatures.dimensions.height
string Float string which indicates the height of the electronic signature box. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the height of the electronic signature box to be half of the page’s height, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the y-coordinate of the electronic signature box for the entire signature box to be contained within the page) is less than 1.
business_processes.signers
.digi_signatures
object[] Array of objects. The structure of an object is given on the right.
Each object represents a digital signature placeholder. A digital signature, as opposed to an electronic signature, is a signature derived cryptographically using the signer’s credentials. Use an empty array to indicate that digital signature is not used. Note that due to the nature of how a digital signature is computed, all signers of the same business process can only and have to sign either using electronic signatures or digital signatures.
business_processes.signers
.digi_signatures.type
string Values could be “ndi” or “blockchain”. Currently, only “ndi” is supported. Note that only one “ndi” signature can be added for a signer.
business_processes.signers
.digi_signatures.placement
object Object containing information on where the digital signature is placed on the file.
business_processes.signers
.digi_signatures.placement.page
number Page number of the page on which the digital signature is placed. Starts from 1.
business_processes.signers
.digi_signatures.placement.x
string Float string which indicates the horizontal distance the top left corner of the digital signature box is from the left edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the width of the page. For example, to set the placement of the electronic signature box’s top left corner to the center of the page horizontally, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the width of the electronic signature box for the entire signature box to be contained within the page) is strictly less than 1.
business_processes.signers
.digi_signatures.placement.y
string Float string which indicates the vertical distance the top left corner of the electronic signature box is from the top edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the height of the page. For example, to set the placement of the electronic signature box’s top left corner to the center of the page vertically, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the height of the electronic signature box for the entire signature box to be contained within the page) is strictly less than 1.
business_processes.signers
.digi_signatures.dimensions
object Object containing information on the size of the digital signature on the file.
business_processes.signers
.digi_signatures.dimensions.width
string Float string which indicates the width of the digital signature box. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the width of the digital signature box to be half of the page’s width, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the x-coordinate of the digital signature box for the entire signature box to be contained within the page) is less than 1.
Note that currently, even though this value will be stored, the stored value will not be used by Dedoco’s signing app because only “ndi” digital signatures are supported and their sizes are fixed.
business_processes.signers
.digi_signatures.dimensions.height
string Float string which indicates the height of the digital signature box. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the height of the digital signature box to be half of the page’s height, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the y-coordinate of the digital signature box for the entire signature box to be contained within the page) is less than 1.
Note that currently, even though this value will be stored, the stored value will not be used by Dedoco’s signing app because only “ndi” digital signatures are supported and their sizes are fixed.
business_processes.signers
.custom_texts
object[] Array of objects. The structure of an object is given on the right. Note that due to the nature of how a digital signature is computed, there cannot be custom texts if the business process has more than one signer and “ndi” digital signatures are used (i.e. an empty array is expected).
business_processes.signers
.custom_texts.descriptor
string Brief description of custom text. Helps the signer know what to fill into the custom text field. If any of the special values are used, the custom text field will be displayed in the signing app differently from a typical custom text field. Currently, the special values are the strings “Actual Date” and “Custom Date”. If “Actual Date” is used, the signing app will generate the signer’s current date within the custom text box when the signer accesses the signing link (i.e. the signer does not get to edit the value of the custom text). If “Custom Date” is used, the signing app will display a calendar for the signer to choose a date.
business_processes.signers
.custom_texts.is_mandatory
boolean Boolean indicating whether or not filling in the custom text is mandatory.
business_processes.signers
.custom_texts.type
string String indicating the type of custom text. Possible values are “text”, “custom-date”, “actual-date”, “stamp”, “initials”. If “text” is used, the displayed custom text field will accept any text. If “custom-date” is used, the displayed custom text field will accept any date. If “actual-date” is used, the displayed custom text field will automatically take on the date the signer viewed the file. If “stamp” is used, the displayed custom text field will accept any image. If “initials” is used, the displayed custom text field will accept any text but displayed differently than when “text” is used.
business_processes.signers
.custom_texts.placement
object Object containing information on where the custom text is placed on the file.
business_processes.signers
.custom_texts.placement.page
number Page number of the page on which the custom text is placed. Starts from 1.
business_processes.signers
.custom_texts.placement.x
string Float string which indicates the horizontal distance the top left corner of the custom text box is from the left edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the placement of the custom text box’s top left corner to the center of the page horizontally, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the width of the custom text box for the entire box to be contained within the page) is strictly less than 1.
business_processes.signers
.custom_texts.placement.y
string Float string which indicates the vertical distance the top left corner of the custom text box is from the top edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the placement of the custom text box’s top left corner to the center of the page vertically, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the height of the custom text box for the entire box to be contained within the page) is strictly less than 1.
business_processes.signers
.custom_texts.dimensions
object Object containing information on the size of the custom text on the file.
business_processes.signers
.custom_texts.dimensions.width
string Float string which indicates the width of the custom text box. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the width of the custom text box to be half of the page’s width, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the x-coordinate of the custom text box for the entire box to be contained within the page) is less than 1. Note that if the business_processes.signers.custom_texts.descriptor is “Actual Date” or “Custom Date”, even though this value will be validated and stored, the stored value will not be used by Dedoco’s signing app because “Actual Date”s and “Custom Date”s are displayed in a fixed height:width ratio (1:4 specifically) using business_processes.signers.custom_texts.dimensions.height as reference.
business_processes.signers
.custom_texts.dimensions.height
string Float string which indicates the height of the custom text box. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the height of the custom text box to be half of the page’s height, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the y-coordinate of the custom text box for the entire box to be contained within the page) is less than 1.
business_processes.
completion_requirement.min_number
number Minimum number of signers who have signed for the business process to be ‘completed’. If the business process has a signing sequence defined, this number is expected to be equal to the total number of signers of the business process.

Responses:

Response body for code 201:

{
  "folder": Folder,
  "documents": Document[],
  "businessProcesses": BusinessProcess[],
  "links": {
    "documentId": string,
    "documentName": string,
    "businessProcessId": string,
    "signerId": string,
    "signerName": string,
    "signerEmail": string,
    "link": string
  }[]
}

Response body for code 4xx:

{
  "statusCode": number,
  "message": string,
  "error": string
}

where statusCode is the status code of the error,
> message is a string describing the cause of error and
> error is a string describing the type of error.

Response body for code 5xx:

{
  "statusCode": number,
  "message": string,
  "error": string
}

where statusCode is the status code of the error,
> message is a string describing the cause of error and
> error is a string describing the type of error.

Code Description
201 Folder, along with its documents and business processes, has been successfully created.
4xx Errors caused by API consumers. Error codes such as 400, 401, 403 and 404 can be expected if incorrect requests are made to the API.
5xx Errors caused by the API provider or its dependencies. Error codes such as 500, 502 and 503 can be expected if there is an issue on the API side.

A links object:

{
  "documentId": string,
  "documentName": string,
  "businessProcessId": string,
  "signerId": string,
  "signerName": string,
  "signerEmail": string,
  "link": string
}
Child attribute Type Description
folder Folder Folder object. Refer to Folders for more details.
documents Document[] Array of Document objects. Refer to Documents for more details.
businessProcesses BusinessProcess[] Array of BusinessProcess objects. Refer to Business Processes for more details.
links object[] Array of objects. The structure of an object is given on the right. Contains information on the signing links for each signer involved.
links.documentId string Id of the document the link attribute in the same object is for.
links.documentName string Name of the document the link attribute in the same object is for.
links.businessProcessId string Id of the business process the link attribute in the same object is for.
links.signerId string Id of the signer the link attribute in the same object is for.
links.signerName string Name of the signer the link attribute in the same object is for.
links.signerEmail string Email of the signer the link attribute in the same object is for.
links.link string The base URL of the signing link for the specified signer. To complete the signing link, append the base64 encoding of the file retrieval URL for Dedoco to retrieve the relevant file to sign on. Note that the base64 encoding should be in the URL safe format (i.e. use ‘-’ instead of ‘+’, and ‘_’ instead of ‘/’). The file retrieval URL should accept a GET request for Dedoco to retrieve the relevant file and should return a JSON object {file: string} where file is the base64 string of the retrieved pdf.
For example, if the file retrieval URL is “https://www.sample-url.com/path/file-id”, the base64 encoding would be “aHR0cHM6Ly93d3cuc2FtcGxlLXVybC5jb20vcGF0aC9maWxlLWlkIA==”. Appending “aHR0cHM6Ly93d3cuc2FtcGxlLXVybC5jb20vcGF0aC9maWxlLWlkIA==” to the base URL obtained from this request would complete the signing link. Note that the file retrieval URL appended should always be retrieving the most up-to-date (i.e. with signatures if there were previous signers) pdf. In the case of a business process with a signing sequence defined, the client should send out the links in the same sequence (even though Dedoco prevents a signer from signing before the previous signer has signed) and make sure that the appended URL retrieves the latest pdf with signatures (if any). And in the case of a business process where signers are allowed to sign simultaneously or in any order, the client can send out the links to all the signers at the same time but should make sure that the appended URL always retrieves the latest pdf with signatures (if any) so that the signers will receive the right pdf to sign on.

Sample Request Header:

POST https://beta-api.dedoco.com/api/v1/public/folders HTTP/1.1
Authorization: Bearer <token>
content-type: application/json

Sample Request Body:

{
  "folder_name": "Test Folder",
  "date_created": 1616383852,
  "documents": [
    {
      "name": "sample_pdf",
      "file_type": "pdf",
      "document_hash": "a3c124f1ae5d1e57a4a646512ca0471710e092ef0a39aa3a740da5447bcde237"
    },
    {
      "name": "sample_pdf_2",
      "file_type": "pdf",
      "document_hash": "ce997dea6abb909f745de1aa18d26c7f99003233894876d6635a5d166c02862e"
    }
  ],
  "linked_folders": [],
  "business_processes": [
    {
      "type": "signature",
      "expiration_time": 0,
      "document_id": 0,
      "is_sequential": true,
      "allow_download": true,
      "signers": [
        {
          "signer_email": "alicetan@gmail.com",
          "signer_name": "Alice Tan",
          "signer_phone": "+6581234567",
          "sequence_number": 1,
          "require_authentication": true,
          "verify_method": "SMS",
          "esignatures": [
            {
              "placement": {
                "page": 1,
                "x": "0.5",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "digi_signatures": [],
          "custom_texts": [
            {
              "descriptor": "NRIC",
              "is_mandatory": true,
              "type": "text",
              "placement": {
                "page": 1,
                "x": "0.123",
                "y": "0.123"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ]
        },
        {
          "signer_email": "bobbychia@gmail.com",
          "signer_name": "Bobby Chia",
          "signer_phone": "+6581234567",
          "sequence_number": 2,
          "require_authentication": true,
          "verify_method": "SMS",
          "esignatures": [
            {
              "placement": {
                "page": 1,
                "x": "0.6",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "digi_signatures": [],
          "custom_texts": [
            {
              "descriptor": "NRIC",
              "is_mandatory": true,
              "type": "text",
              "placement": {
                "page": 1,
                "x": "0.223",
                "y": "0.223"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.05"
              }
            }
          ]
        }
      ],
      "completion_requirement": {
        "min_number": 2
      }
    },
    {
      "type": "signature",
      "expiration_time": 0,
      "document_id": 1,
      "is_sequential": true,
      "allow_download": false,
      "signers": [
        {
          "signer_email": "alanteo@gmail.com",
          "signer_name": "Alan Teo",
          "sequence_number": 1,
          "require_authentication": false,
          "verify_method": "NO_AUTHENTICATION",
          "esignatures": [],
          "digi_signatures": [
            {
              "type": "ndi",
              "placement": {
                "page": 1,
                "x": "0.6",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "custom_texts": []
        },
        {
          "signer_email": "beverlychan@gmail.com",
          "signer_name": "Beverly Chan",
          "sequence_number": 2,
          "require_authentication": false,
          "verify_method": "NO_AUTHENTICATION",
          "esignatures": [],
          "digi_signatures": [
            {
              "type": "ndi",
              "placement": {
                "page": 1,
                "x": "0.5",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "custom_texts": []
        }
      ],
      "completion_requirement": {
        "min_number": 2
      }
    }
  ]
}

Sample Response Header:

HTTP/1.1 201 Created

Sample Response Body:

{
  "folder": {
    "id": "605d89b600f7ab4d00541d2d",
    "name": "Test Folder",
    "date_created": "2021-03-22T03:30:52.000Z",
    "child_documents": ["605d89b600f7ab4d00541d2e", "605d89b600f7ab4d00541d2f"],
    "linked_folders": [],
    "status": "active",
    "history": [
      {
        "action": "create Folder",
        "actor": {
          "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
          "email": "jimmylee@gmail.com",
          "name": "Jim Lee"
        },
        "timestamp": "2021-03-22T03:30:52.000Z",
        "transaction_hash": ""
      },
      {
        "action": "add Document with id: 605d89b600f7ab4d00541d2e",
        "actor": {
          "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
          "email": "jimmylee@gmail.com",
          "name": "Jim Lee"
        },
        "timestamp": "2021-03-22T03:30:52.000Z",
        "transaction_hash": ""
      },
      {
        "action": "add Document with id: 605d89b600f7ab4d00541d2f",
        "actor": {
          "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
          "email": "jimmylee@gmail.com",
          "name": "Jim Lee"
        },
        "timestamp": "2021-03-22T03:30:52.000Z",
        "transaction_hash": ""
      }
    ]
  },
  "documents": [
    {
      "id": "605d89b600f7ab4d00541d2e",
      "name": "sample_pdf",
      "file_type": "pdf",
      "date_created": "2021-03-22T03:30:52.000Z",
      "document_hashes": [
        "a3c124f1ae5d1e57a4a646512ca0471710e092ef0a39aa3a740da5447bcde237"
      ],
      "business_processes": ["605d89b600f7ab4d00541d30"],
      "status": "active",
      "parent_folder": "605d89b600f7ab4d00541d2d",
      "history": [
        {
          "action": "create Document",
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": ""
        },
        {
          "action": "add Business Process (Signature) with id: 605d89b600f7ab4d00541d30",
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": ""
        }
      ]
    },
    {
      "id": "605d89b600f7ab4d00541d2f",
      "name": "sample_pdf_2",
      "file_type": "pdf",
      "date_created": "2021-03-22T03:30:52.000Z",
      "document_hashes": [
        "ce997dea6abb909f745de1aa18d26c7f99003233894876d6635a5d166c02862e"
      ],
      "business_processes": ["605d89b600f7ab4d00541d33"],
      "status": "active",
      "parent_folder": "605d89b600f7ab4d00541d2d",
      "history": [
        {
          "action": "create Document",
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": ""
        },
        {
          "action": "add Business Process (Signature) with id: 605d89b600f7ab4d00541d33",
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": ""
        }
      ]
    }
  ],
  "businessProcesses": [
    {
      "id": "605d89b600f7ab4d00541d30",
      "type": "signature",
      "date_created": "2021-03-22T03:30:52.000Z",
      "expiration_time": "1970-01-01T00:00:00.000Z",
      "document_id": "605d89b600f7ab4d00541d2e",
      "allow_download": true,
      "signers": [
        {
          "has_signed": false,
          "signer_id": "SIG_605d89b600f7ab4d00541d31",
          "signer_name": "Alice Tan",
          "signer_email": "alicetan@gmail.com",
          "signer_phone": "+6581234567",
          "sequence_number": 1,
          "require_authentication": true,
          "verify_method": "SMS",
          "esignatures": [
            {
              "placement": {
                "page": 1,
                "x": "0.5",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "digi_signatures": [],
          "custom_texts": [
            {
              "descriptor": "NRIC",
              "is_mandatory": true,
              "type": "text",
              "placement": {
                "page": 1,
                "x": "0.123",
                "y": "0.123"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ]
        },
        {
          "has_signed": false,
          "signer_id": "SIG_605d89b600f7ab4d00541d32",
          "signer_name": "Bobby Chia",
          "signer_email": "bobbychia@gmail.com",
          "signer_phone": "+6581234567",
          "sequence_number": 2,
          "require_authentication": true,
          "verify_method": "SMS",
          "esignatures": [
            {
              "placement": {
                "page": 1,
                "x": "0.6",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "digi_signatures": [],
          "custom_texts": [
            {
              "descriptor": "NRIC",
              "is_mandatory": true,
              "type": "text",
              "placement": {
                "page": 1,
                "x": "0.223",
                "y": "0.223"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.05"
              }
            }
          ]
        }
      ],
      "sequential_requirement": [
        {
          "sequence_number": 1,
          "signers": [
            {
              "signer_id": "SIG_605d89b600f7ab4d00541d31",
              "signer_name": "Alice Tan",
              "signer_email": "alicetan@gmail.com"
            }
          ]
        },
        {
          "sequence_number": 2,
          "signers": [
            {
              "signer_id": "SIG_605d89b600f7ab4d00541d32",
              "signer_name": "Bobby Chia",
              "signer_email": "bobbychia@gmail.com"
            }
          ]
        }
      ],
      "completion_requirement": {
        "min_number": 2,
        "overriding_signers": []
      },
      "status": "pending",
      "history": [
        {
          "action": "create Business Process (Signature)",
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": ""
        }
      ]
    },
    {
      "id": "605d89b600f7ab4d00541d33",
      "type": "signature",
      "date_created": "2021-03-22T03:30:52.000Z",
      "expiration_time": "1970-01-01T00:00:00.000Z",
      "document_id": "605d89b600f7ab4d00541d2f",
      "allow_download": false,
      "signers": [
        {
          "has_signed": false,
          "signer_id": "SIG_605d89b600f7ab4d00541d34",
          "signer_name": "Alan Teo",
          "signer_email": "alanteo@gmail.com",
          "sequence_number": 1,
          "require_authentication": false,
          "verify_method": "NO_AUTHENTICATION",
          "esignatures": [],
          "digi_signatures": [
            {
              "type": "ndi",
              "placement": {
                "page": 1,
                "x": "0.6",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "custom_texts": []
        },
        {
          "has_signed": false,
          "signer_id": "SIG_605d89b600f7ab4d00541d35",
          "signer_name": "Beverly Chan",
          "signer_email": "beverlychan@gmail.com",
          "sequence_number": 2,
          "require_authentication": false,
          "verify_method": "NO_AUTHENTICATION",
          "esignatures": [],
          "digi_signatures": [
            {
              "type": "ndi",
              "placement": {
                "page": 1,
                "x": "0.5",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "custom_texts": []
        }
      ],
      "sequential_requirement": [
        {
          "sequence_number": 1,
          "signers": [
            {
              "signer_id": "SIG_605d89b600f7ab4d00541d34",
              "signer_name": "Alan Teo",
              "signer_email": "alanteo@gmail.com"
            }
          ]
        },
        {
          "sequence_number": 2,
          "signers": [
            {
              "signer_id": "SIG_605d89b600f7ab4d00541d35",
              "signer_name": "Beverly Chan",
              "signer_email": "beverlychan@gmail.com"
            }
          ]
        }
      ],
      "completion_requirement": {
        "min_number": 2,
        "overriding_signers": []
      },
      "status": "pending",
      "history": [
        {
          "action": "create Business Process (Signature)",
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": ""
        }
      ]
    }
  ],
  "links": [
    {
      "documentId": "605d89b600f7ab4d00541d2e",
      "documentName": "sample_pdf",
      "businessProcessId": "605d89b600f7ab4d00541d30",
      "signerId": "SIG_605d89b600f7ab4d00541d31",
      "signerName": "Alice Tan",
      "signerEmail": "alicetan@gmail.com",
      "link": "https://sample-url/public/sign/605d89b600f7ab4d00541d30/SIG_605d89b600f7ab4d00541d31"
    },
    {
      "documentId": "605d89b600f7ab4d00541d2e",
      "documentName": "sample_pdf",
      "businessProcessId": "605d89b600f7ab4d00541d30",
      "signerId": "SIG_605d89b600f7ab4d00541d32",
      "signerName": "Bobby Chia",
      "signerEmail": "bobbychia@gmail.com",
      "link": "https://sample-url/public/sign/605d89b600f7ab4d00541d30/SIG_605d89b600f7ab4d00541d32"
    },
    {
      "documentId": "605d89b600f7ab4d00541d2f",
      "documentName": "sample_pdf_2",
      "businessProcessId": "605d89b600f7ab4d00541d33",
      "signerId": "SIG_605d89b600f7ab4d00541d34",
      "signerName": "Alan Teo",
      "signerEmail": "alanteo@gmail.com",
      "link": "https://sample-url/public/sign/605d89b600f7ab4d00541d33/SIG_605d89b600f7ab4d00541d34"
    },
    {
      "documentId": "605d89b600f7ab4d00541d2f",
      "documentName": "sample_pdf_2",
      "businessProcessId": "605d89b600f7ab4d00541d33",
      "signerId": "SIG_605d89b600f7ab4d00541d35",
      "signerName": "Beverly Chan",
      "signerEmail": "beverlychan@gmail.com",
      "link": "https://sample-url/public/sign/605d89b600f7ab4d00541d33/SIG_605d89b600f7ab4d00541d35"
    }
  ]
}

E. Documents

Documents are used to represent the uploaded files. A document can have zero to multiple business processes attached to it. However, at any point in time, there can only be at most one “pending” business process attached to it.

Document Attributes

A history object:

{
    "action": string,
    "actor": {
        "id": string,
        "email": string,
        "name": string
    },
    "timestamp": date,
    "transaction_hash": string
}
Attribute Type Description
id string Unique identifier of the document.
name string Name of the document set by the creator of the document. Does not need to follow the original name of the uploaded document and could be used as a descriptor.
file_type string File type of the uploaded file. Accepted values are “pdf” and “json”.
date_created date Time the document is created. Cannot be changed after the document is created.
document_hashes string[] Array of SHA3-256 hashes. First hash will be the hash of the original document. Subsequently, upon completion of a business process attached to the document, the hash of the resultant document will be generated and added to this array.
parent_folder string Id of the parent folder.
business_processes string[] Array of ids of attached business processes. Each document can only have at most one “pending” business process at any time.
status string Value could be “active”, “closed” or “voided”. “active” indicates that the document is valid and can still be edited. “closed” indicates that the document is valid but cannot be edited. “voided” indicates that the document is invalid and cannot be edited.
history object[] Array of objects involving changes made to the document. The structure of an object is given on the right.
Child attribute Type Description
history.action string Description of the action recorded in the history attribute.
history.actor.id string User id of the entity that took the action.
history.actor.email string Email address (if any) of the entity that took the action.
history.actor.name string Name (if any) of the entity that took the action.
history.timestamp date Time the action took place.
history.transaction_hash string Hash of the blockchain transaction updating the data (only if there are any changes in data) on the blockchain due to the action that took place. Can be used to view the transaction details on the blockchain’s explorer.

Endpoint: Add Document

POST /public/documents HTTP/1.1
Adds a document with at most one business process to a folder.

Authorization:
Bearer

Content-Type:
application/json

Header Parameter:

Parameter Type Description Required/Optional
jwt_token string Token obtained by the client through the Get JWT Token endpoint. Required

Request Body:

A business_process object:

{
    "type": string,
    "expiration_time": number,
    "is_sequential": boolean,
    "allow_download": boolean,
    "signers": {
        "signer_email": string,
        "signer_name": string,
        "signer_phone": string,
        "sequence_number": number,
        "require_authentication": boolean,
        "verify_method": string,
        "esignatures": {
            "placement": {
                "page": number,
                "x": string,
                "y": string
            },
            "dimensions": {
                "width": string,
                "height": string
            }
        }[],
        "digi_signatures": {
            "type": string,
            "placement": {
                "page": number,
                "x": string,
                "y": string
            },
            "dimensions": {
                "width": string,
                "height": string
            }
        }[],
        "custom_texts": {
            "descriptor": string,
            "is_mandatory": boolean,
            "type": string,
            "placement": {
                "page": number,
                "x": string,
                "y": string
            },
            "dimensions": {
                "width": string,
                "height": string
            }
        }[]
    }[],
    "completion_requirement": {
        "min_number": number
    }
}

Attribute Type Description Required/Optional
document_name string Name of the document (not required to be the same as the original file name). Set by the document’s creator. Required
date_created number Date of the document's creation in Unix time Required
file_type string File type of the document. Currently, only “pdf” is accepted. Required
document_hash string SHA3-256 hash of the document in hexadecimal. Required
parent_folder string Id of folder to add document to. Required
business_process object Object containing details of the business process to be added to the document. The structure of the object is shown on the right. Optional

A business_process.signers object:

{
    "signer_email": string,
    "signer_name": string,
    "signer_phone": string,
    "sequence_number": number,
    "require_authentication": boolean,
    "verify_method": string,
    "esignatures": {
        "placement": {
            "page": number,
            "x": string,
            "y": string
        },
        "dimensions": {
            "width": string,
            "height": string
        }
    }[],
    "digi_signatures": {
        "type": string,
        "placement": {
            "page": number,
            "x": string,
            "y": string
        },
        "dimensions": {
            "width": string,
            "height": string
        }
    }[],
    "custom_texts": {
        "descriptor": string,
        "is_mandatory": boolean,
        "type": string,
        "placement": {
            "page": number,
            "x": string,
            "y": string
        },
        "dimensions": {
            "width": string,
            "height": string
        }
    }[]
}

A business_process.signers.esignatures object:

{
    "placement": {
        "page": number,
        "x": string,
        "y": string
    },
    "dimensions": {
        "width": string,
        "height": string
    }
}

A business_process.signers.esignatures.placement object:

{
    "page": number,
    "x": string,
    "y": string
}

A business_process.signers.esignatures.dimensions object:

{
    "width": string,
    "height": string
}

A business_process.signers.digi_signatures object:

{
    "type": string,
    "placement": {
        "page": number,
        "x": string,
        "y": string
    },
    "dimensions": {
        "width": string,
        "height": string
    }
}

A business_process.signers.digi_signatures.placement object:

{
    "page": number,
    "x": string,
    "y": string
}

A business_process.signers.digi_signatures.dimensions object:

{
    "width": string,
    "height": string
}

A business_process.signers.custom_texts object:

{
    "descriptor": string,
    "is_mandatory": boolean,
    "type": string,
    "placement": {
        "page": number,
        "x": string,
        "y": string
    },
    "dimensions": {
        "width": string,
        "height": string
    }
}

A business_process.signers.custom_texts.placement object:

{
    "page": number,
    "x": string,
    "y": string
}

A business_process.signers.custom_texts.dimensions object:

{
    "width": string,
    "height": string
}
Child Attribute Type Description
business_process.type string Currently, the only supported business process type is “signature”.
business_process.expiration_time string Expiration time of the business process in Unix. Value must be higher than the current Unix time unless there is no expiration time. Use 0 if there is no expiration time.
business_process.is_sequential boolean Boolean indicating if the business process requires signers to sign in a sequence.
business_process.allow_download boolean Boolean indicating if the signers are allowed to manually download the signed pdf on Dedoco’s signing app after signing.
business_process.signers object[] Array of objects containing details about the signers of the document. The structure of an object is given on the right.
business_process.signers
.signer_email
string Email address of the signer.
business_process.signers
.signer_name
string Name of the signer.
business_process.signers
.signer_phone
string Phone number of the signer. E.164 format is expected. E.164 numbers are formatted +[country code][subscriber number including area code]. E.g. for a Singapore number 8123 4567, the E.164 string is “+6581234567”.
business_process.signers
.sequence_number
number Sequence number of the signer if the business process requires signers to sign in a sequence. Starts from 1. 0 is used if there is no sequence.
business_process.signers
.require_authentication
boolean Boolean indicating whether or not the signer is required to be authenticated (via either email or SMS OTPs) before accessing the signing link.
business_process.signers
.verify_method
string String indicating means to send OTP (if authentication is required). Possible values are “SMS”, “EMAIL” and “NO_AUTHENTICATION”. Use “SMS” if using SMS to send OTP. Use “EMAIL” if using email to send OTP. Use “NO_AUTHENTICATION” if the signer is not required to be authenticated.
business_process.signers
.esignatures
object[] Array of objects. The structure of an object is given on the right.
Each object represents an electronic signature placeholder. An electronic signature, as opposed to a digital signature, is an image that is drawn, typed or uploaded by the signer. Use an empty array to indicate that electronic signature is not used. Note that due to the nature of how a digital signature is computed, all signers of the same business process can only and have to sign either using electronic signatures or digital signatures.
business_process.signers
.esignatures.placement
object Object containing information on where the electronic signature is placed on the file. Its structure is shown on the right.
business_process.signers
.esignatures.placement.page
number Page number of the page on which the electronic signature is placed. Starts from 1.
business_process.signers
.esignatures.placement.x
string Float string which indicates the horizontal distance the top left corner of the electronic signature box is from the left edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the placement of the electronic signature box’s top left corner to the center of the page horizontally, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the width of the electronic signature box for the entire signature box to be contained within the page) is strictly less than 1.
business_process.signers
.esignatures.placement.y
string Float string which indicates the vertical distance the top left corner of the electronic signature box is from the top edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the placement of the electronic signature box’s top left corner to the center of the page vertically, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the height of the electronic signature box for the entire signature box to be contained within the page) is strictly less than 1.
business_process.signers
.esignatures.dimensions
object Object containing information on the size of the electronic signature on the file. Its structure is shown on the right.
business_process.signers
.esignatures.dimensions.width
string Float string which indicates the width of the electronic signature box. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the width of the electronic signature box to be half of the page’s width, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the x-coordinate of the electronic signature box for the entire signature box to be contained within the page) is less than 1. Note that currently, even though this value will be validated and stored, the stored value will not be used by Dedoco’s signing app because electronic signatures are displayed in a fixed height:width ratio (1:2 specifically) using business_process.signers.esignatures.dimensions.height as reference.
business_process.signers
.esignatures.dimensions.height
string Float string which indicates the height of the electronic signature box. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the height of the electronic signature box to be half of the page’s height, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the y-coordinate of the electronic signature box for the entire signature box to be contained within the page) is less than 1.
business_process.signers
.digi_signatures
object[] Array of objects. The structure of an object is given on the right.
Each object represents a digital signature placeholder. A digital signature, as opposed to an electronic signature, is a signature derived cryptographically using the signer’s credentials. Use an empty array to indicate that digital signature is not used. Note that due to the nature of how a digital signature is computed, all signers of the same business process can only and have to sign either using electronic signatures or digital signatures.
business_process.signers
.digi_signatures.type
string Values could be “ndi” or “blockchain”. Currently, only “ndi” is supported. Note that only one “ndi” signature can be added for a signer.
business_process.signers
.digi_signatures.placement
object Object containing information on where the digital signature is placed on the file. Its structure is given on the right.
business_process.signers
.digi_signatures.placement.page
number Page number of the page on which the digital signature is placed. Starts from 1.
business_process.signers
.digi_signatures.placement.x
string Float string which indicates the horizontal distance the top left corner of the digital signature box is from the left edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the placement of the electronic signature box’s top left corner to the center of the page horizontally, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the width of the electronic signature box for the entire signature box to be contained within the page) is strictly less than 1.
business_process.signers
.digi_signatures.placement.y
string Float string which indicates the vertical distance the top left corner of the electronic signature box is from the top edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the placement of the electronic signature box’s top left corner to the center of the page vertically, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the height of the electronic signature box for the entire signature box to be contained within the page) is strictly less than 1.
business_process.signers
.digi_signatures.dimensions
object Object containing information on the size of the digital signature on the file. Its structure is given on the right.
business_process.signers
.digi_signatures.dimensions.width
string Float string which indicates the width of the digital signature box. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the width of the digital signature box to be half of the page’s width, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the x-coordinate of the digital signature box for the entire signature box to be contained within the page) is less than 1. Note that currently, even though this value will be stored, the stored value will not be used by Dedoco’s signing app because only “ndi” digital signatures are supported and their sizes are fixed.
business_process.signers
.digi_signatures.dimensions.height
string Float string which indicates the height of the digital signature box. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the height of the digital signature box to be half of the page’s height, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the y-coordinate of the digital signature box for the entire signature box to be contained within the page) is less than 1. Note that currently, even though this value will be stored, the stored value will not be used by Dedoco’s signing app because only “ndi” digital signatures are supported and their sizes are fixed.
business_process.signers
.custom_texts
object[] Array of objects. The structure of an object is given on the right.
Note that due to the nature of how a digital signature is computed, there cannot be custom texts if the business process has more than one signer and “ndi” digital signatures are used (i.e. an empty array is expected).
business_process.signers
.custom_texts.descriptor
string Brief description of custom text. Helps the signer know what to fill into the custom text field. If any of the special values is used, the custom text field will be displayed in the signing app differently from a typical custom text field. Currently, the special values are the strings “Actual Date” and “Custom Date”. If “Actual Date” is used, the signing app will generate the signer’s current date within the custom text box when the signer accesses the signing link (i.e. the signer does not get to edit the value of the custom text). If “Custom Date” is used, the signing app will display a calendar for the signer to choose a date.
business_process.signers
.custom_texts.is_mandatory
boolean Boolean indicating whether or not filling in the custom text is mandatory.
business_process.signers
.custom_texts.type
string String indicating the type of custom text. Possible values are “text”, “custom-date”, “actual-date”, “stamp”, “initials”. If “text” is used, the displayed custom text field will accept any text. If “custom-date” is used, the displayed custom text field will accept any date. If “actual-date” is used, the displayed custom text field will automatically take on the date the signer viewed the file. If “stamp” is used, the displayed custom text field will accept any image. If “initials” is used, the displayed custom text field will accept any text but displayed differently than when “text” is used.
business_process.signers
.custom_texts.placement
object Object containing information on where the custom text is placed on the file. Its structure is given on the right.
business_process.signers
.custom_texts.placement.page
number Page number of the page on which the custom text is placed. Starts from 1.
business_process.signers
.custom_texts.placement.x
string Float string which indicates the horizontal distance the top left corner of the custom text box is from the left edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the placement of the custom text box’s top left corner to the center of the page horizontally, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the width of the custom text box for the entire box to be contained within the page) is strictly less than 1.
business_process.signers
.custom_texts.placement.y
string Float string which indicates the vertical distance the top left corner of the custom text box is from the top edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the placement of the custom text box’s top left corner to the center of the page vertically, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the height of the custom text box for the entire box to be contained within the page) is strictly less than 1.
business_process.signers
.custom_texts.dimensions
object Object containing information on the size of the custom text on the file. Its structure is given on the right.
business_process.signers
.custom_texts.dimensions.width
string Float string which indicates the width of the custom text box. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the width of the custom text box to be half of the page’s width, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the x-coordinate of the custom text box for the entire box to be contained within the page) is less than 1. Note that if the business_process.signers.custom_texts.descriptor is “Actual Date” or “Custom Date”, even though this value will be validated and stored, the stored value will not be used by Dedoco’s signing app because “Actual Date”s and “Custom Date”s are displayed in a fixed height:width ratio (1:4 specifically) using business_process.signers.custom_texts.dimensions.height as reference.
business_process.signers
.custom_texts.dimensions.height
string Float string which indicates the height of the custom text box. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the height of the custom text box to be half of the page’s height, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the y-coordinate of the custom text box for the entire box to be contained within the page) is less than 1.
business_process.
completion_requirement.min_number
number Minimum number of signers who have signed for the business process to be ‘completed’. If the business process has a signing sequence defined, this number is expected to be equal to the total number of signers of the business process.

Responses:

Response body for code 201

{
    "document": Document,
    "businessProcess": BusinessProcess,
    "links": {
      "documentId": string,
      "documentName": string,
      "businessProcessId": string,
      "signerId": string,
      "signerName": string,
      "signerEmail": string,
      "link": string
    }[]
}

Response body for code 4xx:

{
    "statusCode": number,
    "message": string,
    "error": string
}

Response body for code 5xx:

{
    "statusCode": number,
    "message": string,
    "error": string
}
Code Description
201 Document, along with its business process (if any), has been successfully added to the specified folder.
4xx Errors caused by API consumers. Error codes such as 400, 401, 403 and 404 can be expected if incorrect requests are made to the API.
5xx Errors caused by the API provider or its dependencies. Error codes such as 500, 502 and 503 can be expected if there is an issue on the API side.

A links object:

{
    "documentId": string,
    "documentName": string,
    "businessProcessId": string,
    "signerId": string,
    "signerName": string,
    "signerEmail": string,
    "link": string
}

Child Attribute Type Description
document Document A Document object. Refer to Documents for more details.
businessProcess BusinessProcess A BusinessProcess object. Refer to Business Processes for more details.
links object[] Array of objects containing information on the signing links for each signer involved. The structure of an object is given on the right.
links.documentId string Id of the document the link attribute in the same object is for.
links.documentName string Name of the document the link attribute in the same object is for.
links.businessProcessId string Id of the business process the link attribute in the same object is for.
links.signerId string Id of the signer the link attribute in the same object is for.
links.signerName string Name of the signer the link attribute in the same object is for.
links.signerEmail string Email of the signer the link attribute in the same object is for.
links.link string The base URL of the signing link for the specified signer. To complete the signing link, append the base64 encoding of the file retrieval URL for Dedoco to retrieve the relevant file to sign on. Note that the base64 encoding should be in the URL safe format (i.e. use ‘-’ instead of ‘+’, and ‘_’ instead of ‘/’). The file retrieval URL should accept a GET request for Dedoco to retrieve the relevant file and should return a JSON object { file: string } where file is the base64 string of the retrieved pdf.
For example, if the file retrieval URL is “https://www.sample-url.com/path/file-id”, the base64 encoding would be “aHR0cHM6Ly93d3cuc2FtcGxlLXVybC5jb20vcGF0aC9maWxlLWlkIA==”. Appending “aHR0cHM6Ly93d3cuc2FtcGxlLXVybC5jb20vcGF0aC9maWxlLWlkIA==” to the base URL obtained from this request would complete the signing link.
Note that the file retrieval URL appended should always be retrieving the most up-to-date (i.e. with signatures if there were previous signers) pdf. In the case of a business process with a signing sequence defined, the client should send out the links in the same sequence (even though Dedoco prevents a signer from signing before the previous signer has signed) and make sure that the appended URL retrieves the latest pdf with signatures (if any). And in the case of a business process where signers are allowed to sign simultaneously or in any order, the client can send out the links to all the signers at the same time but should make sure that the appended URL always retrieves the latest pdf with signatures (if any) so that the signers will receive the right pdf to sign on.

Sample request header:

POST https://beta-api.dedoco.com/api/v1/public/documents HTTP/1.1
content-type: application/json
Authorization: Bearer <token>

Sample request body:

{
  "document_name": "sample_pdf",
  "date_created": 1616387681,
  "file_type": "pdf",
  "document_hash": "45c6fca6181822fe43912280bedd1f5766174ed69abd3b74cd3c3c0fbb8fe2e8",
  "parent_folder": "60581dbbc79151135ddd6b57",
  "business_process": {
    "type": "signature",
    "expiration_time": 0,
    "is_sequential": false,
    "allow_download": true,
    "signers": [
      {
        "signer_email": "alicia@gmail.com",
        "signer_name": "Alicia Macaron",
        "signer_phone": "+6581234567",
        "sequence_number": 0,
        "require_authentication": true,
        "verify_method": "SMS",
        "esignatures": [
          {
            "placement": {
              "page": 1,
              "x": "0.5",
              "y": "0.5"
            },
            "dimensions": {
              "width": "0.01",
              "height": "0.005"
            }
          }
        ],
        "digi_signatures": [],
        "custom_texts": []
      }
    ],
    "completion_requirement": {
      "min_number": 1
    }
  }
}

Sample response header:

Sample Response:
HTTP/1.1 201 Created

Sample response body:

{
  "document": {
    "id": "605d8bdf00f7ab4d00541d3b",
    "name": "sample_pdf",
    "file_type": "pdf",
    "date_created": "2021-03-22T04:34:41.000Z",
    "document_hashes": [
      "45c6fca6181822fe43912280bedd1f5766174ed69abd3b74cd3c3c0fbb8fe2e8"
    ],
    "business_processes": ["605d8bdf00f7ab4d00541d3c"],
    "status": "active",
    "parent_folder": "60581dbbc79151135ddd6b57",
    "history": [
      {
        "action": "create Document",
        "actor": {
          "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
          "email": "jimmylee@gmail.com",
          "name": "Jim Lee"
        },
        "timestamp": "2021-03-22T04:34:41.000Z",
        "transaction_hash": ""
      },
      {
        "action": "add Business Process (Signature) with id: 605d8bdf00f7ab4d00541d3c",
        "actor": {
          "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
          "email": "jimmylee@gmail.com",
          "name": "Jim Lee"
        },
        "timestamp": "2021-03-22T04:34:41.000Z",
        "transaction_hash": ""
      }
    ]
  },
  "businessProcess": {
    "id": "605d8bdf00f7ab4d00541d3c",
    "type": "signature",
    "date_created": "2021-03-22T04:34:41.000Z",
    "expiration_time": "1970-01-01T00:00:00.000Z",
    "document_id": "605d8bdf00f7ab4d00541d3b",
    "allow_download": true,
    "signers": [
      {
        "has_signed": false,
        "signer_id": "SIG_605d8bdf00f7ab4d00541d3d",
        "signer_name": "Alicia Macaron",
        "signer_email": "alicia@gmail.com",
        "signer_phone": "+6581234567",
        "sequence_number": 0,
        "require_authentication": true,
        "verify_method": "SMS",
        "esignatures": [
          {
            "placement": {
              "page": 1,
              "x": "0.5",
              "y": "0.5"
            },
            "dimensions": {
              "width": "0.01",
              "height": "0.005"
            }
          }
        ],
        "digi_signatures": [],
        "custom_texts": []
      }
    ],
    "sequential_requirement": [],
    "completion_requirement": {
      "min_number": 1,
      "overriding_signers": []
    },
    "status": "pending",
    "history": [
      {
        "action": "create Business Process (Signature)",
        "actor": {
          "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
          "email": "jimmylee@gmail.com",
          "name": "Jim Lee"
        },
        "timestamp": "2021-03-22T04:34:41.000Z",
        "transaction_hash": ""
      }
    ]
  },
  "links": [
    {
      "documentId": "605d8bdf00f7ab4d00541d3b",
      "documentName": "sample_pdf",
      "businessProcessId": "605d8bdf00f7ab4d00541d3c",
      "signerId": "SIG_605d8bdf00f7ab4d00541d3d",
      "signerName": "Alicia Macaron",
      "signerEmail": "alicia@gmail.com",
      "link": "https://sample-url.com/public/sign/605d8bdf00f7ab4d00541d3c/SIG_605d8bdf00f7ab4d00541d3d"
    }
  ]
}

Endpoint: Void Document

PUT /public/documents/{document_id}/status HTTP/1.1
Changes a document’s status to “voided”. Statuses of attached business processes will also be changed to “voided”. “voided” status indicates that the document is invalid and cannot be edited anymore.

Authorization:
Bearer <jwt_token>

Header Parameter:

Parameter Type Description Required/Optional
jwt_token string Token obtained by the client through the Get JWT Token endpoint. Required

Path Parameter:

Parameter Type Description Required/Optional
document_id string Id of the document to void. Required

Request Body:

Attribute Type Description Required/Optional
value string New status of the document to change to. Only the value “voided” is accepted. Required
request_date number Date of request in Unix time. Required

Responses:

Response body for code 4xx:

{
  "statusCode": number,
  "message": string,
  "error": string
}

where statusCode is the status code of the error,
> message is a string describing the cause of error and
> error is a string describing the type of error.

Response body for code 5xx:

{
    "statusCode": number,
    "message": string,
    "error": string
}

where statusCode is the status code of the error,
> message is a string describing the cause of error and
> error is a string describing the type of error.

Code Description
201 Document has been successfully voided. Returns an empty JSON object { } as its body.
4xx Errors caused by API consumers. Error codes such as 400, 401, 403 and 404 can be expected if incorrect requests are made to the API.
5xx Errors caused by the API provider or its dependencies. Error codes such as 500, 502 and 503 can be expected if there is an issue on the API side.

Sample request header:

PUT https://beta-api.dedoco.com/api/v1/public/documents/60581f41c79151135ddd6b65/status HTTP/1.1
content-type: application/json
Authorization: Bearer <token>

Sample request body:

{
  "status": "voided",
  "request_date": 1616388028
}

Sample response header:

HTTP/1.1 200 OK

Sample response body:

{}

F. Business Processes

Business processes are used to represent processes involving files, that are usually conducted in a corporate setting, such as signing of files. A business process stores information on the entire flow of the process and other information essential to generate the final output of the process.

Business Process Attributes

A signers object:

{
    "signer_id": string,
    "signer_name": string,
    "signer_email": string,
    "signer_phone": string,
    "sequence_number": number,
    "require_authentication": boolean,
    "verify_method": string,
    "is_mandatory": boolean,
    "has_signed": boolean,
    "esignatures": {
        "type": string,
        "is_mandatory": boolean,
        "placement": {
            "page": number,
            "x": string,
            "y": string
        },
        "dimensions": {
            "width": string,
            "height": string
        },
        "signature": string,
        "signature_hash": string,
        "ip_address": string,
        "timestamp": date
    }[],
    "digi_signatures": {
        "type": string,
        "is_mandatory": boolean,
        "placement": {
            "page": number,
            "x": string,
            "y": string
        },
        "dimensions": {
            "width": string,
            "height": string
        },
        "signature": string,
        "ip_address": string,
        "timestamp": date
    }[],
    "custom_texts": {
        "descriptor": string,
        "is_mandatory": boolean,
        "type": string,
        "placement": {
            "page": number,
            "x": string,
            "y": string
        },
        "dimensions": {
            "width": string,
            "height": string
        },
        "text": string,
        "text_hash": string,
        "ip_address": string,
        "timestamp": date
    }[]
}

A sequential_requirement object:

{
    "sequence_number": number,
    "signers": {
        "signer_id": string,
        "signer_name": string,
        "signer_email": string
    }[]
}

A completion_requirement object

{
    "minimum": number
}

A history object:

{
    "action": string,
    "actor": {
        "id": string,
        "email": string,
        "name": string
    },
    "timestamp": date,
    "transaction_hash": string
}

Attribute Type Description
id string Unique identifier of the business process
type string String specifying the type of business process. Currently, only “signature" is supported.
date_created date Time the business process is created. Cannot be changed after the business process is created.
expiration_time date An optional attribute that indicates the time the business process expires. Beyond which, signers cannot add signatures. However, the expiration time can be extended by the owner.
document_id string Id of the document the business process is attached to.
allow_download boolean Boolean indicating if the signers are allowed to manually download the signed pdf on Dedoco’s signing app after signing.
signers object[] Array of objects. The structure of an object is given on the right.
Contains completed signatures. Only applicable to 'signature" business processes.
sequential_requirement object[] Array of objects. The structure of an object is given on the right.
Each signer is only given one sequence number. Signers are only allowed to sign when signers with a lower sequence number have signed. Only applicable for sequential “signature” business processes.
completion_requirement object Contains attribute(s) each determining the completion of the business process. The business process is completed when at least one of these requirement(s) is met. Its structure is given on the right.
status string Value could be “pending”, “completed”, “expired” or “voided”. “pending” indicates that the business process is valid, incomplete and can still have signatures added. “completed” indicates that the business process is valid and completed. “expired” indicates that the business process is valid, incomplete and can only be extended by the owner. “voided” indicates that the document is invalid and cannot be edited.
history object[] Array of objects involving changes made to the business process. The structure of an object is given on the right.

A signers.esignatures object:

{
    "type": string,
    "is_mandatory": boolean,
    "placement": {
        "page": number,
        "x": string,
        "y": string
    },
    "dimensions": {
        "width": string,
        "height": string
    },
    "signature": string,
    "signature_hash": string,
    "ip_address": string,
    "timestamp": date
}

A signers.esignatures.placement object:

{
    "page": number,
    "x": string,
    "y": string
}

A signers.esignatures.dimensions object:

{
    "width": string,
    "height": string
}

A signers.digi_signatures object:

{
    "type": string,
    "is_mandatory": boolean,
    "placement": {
        "page": number,
        "x": string,
        "y": string
    },
    "dimensions": {
        "width": string,
        "height": string
    },
    "signature": string,
    "ip_address": string,
    "timestamp": date
}

A signers.digi_signatures.placement object:

{
    "page": number,
    "x": string,
    "y": string
}

A signers.digi_signatures.dimensions object:

{
    "width": string,
    "height": string
}

A signers.custom_texts object:

{
    "descriptor": string,
    "is_mandatory": boolean,
    "type": string,
    "placement": {
        "page": number,
        "x": string,
        "y": string
    },
    "dimensions": {
        "width": string,
        "height": string
    },
    "text": string,
    "text_hash": string,
    "ip_address": string,
    "timestamp": date
}

A signers.custom_texts.placement object:

{
    "page": number,
    "x": string,
    "y": string
}

A signers.custom_texts.dimensions object:

{
    "width": string,
    "height": string
}
Child attribute Type Description
signers.signer_id string Identifier of the signer. Will be the user id of the signer if the signer is a Dedoco user.
signers.signer_name string Name of the signer. Will be displayed in email if Dedoco’s email service is used.
signers.signer_email string Email address of the signer. Used by Dedoco’s email service and used to identify if the signer is a Dedoco user.
signers.signer_phone string Phone number of the signer. May be used for SMS OTP.
signers.sequence_number number Sequence number of the signer if the signers are required to sign in a sequence. Starts from 1. 0 is used if there is no sequence.
signers.is_mandatory boolean Boolean indicating whether or not the signer is required to sign for the business process to be completed.
signers.has_signed boolean Boolean indicating whether or not the signer has completed his/her signature for the business process.
signers.require_authentication boolean Boolean indicating whether or not the signer is required to be authenticated (via either email or SMS OTPs) before accessing the signing link.
signers.verify_method string String indicating means to send OTP (if authentication is required). Possible values are “SMS”, “EMAIL” and “NO_AUTHENTICATION”.
signers.esignatures object[] Array of objects. The structure of an object is given on the right.
signers.esignatures.type string Value can be “drawing”, “text” or “upload”. “drawing” indicates that the electronic signature was electronically drawn. “text” indicates that the electronic signature was typed. “upload” indicates that the electronic signature was an uploaded image.
signers.esignatures.is_mandatory boolean Boolean indicating whether or not the electronic signature is mandatory.
signers.esignatures.placement object Object containing information on where the electronic signature is placed on the file. Its structure is given on the right.
signers.esignatures.placement.page number Page number of the page on which the electronic signature is placed. Starts from 1.
signers.esignatures.placement.x string Float string which indicates the horizontal distance the top left corner of the electronic signature box is from the left edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the placement of the electronic signature box’s top left corner to the center of the page horizontally, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the width of the electronic signature box for the entire signature box to be contained within the page) is strictly less than 1.
signers.esignatures.placement.y string Float string which indicates the vertical distance the top left corner of the electronic signature box is from the top edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the placement of the electronic signature box’s top left corner to the center of the page vertically, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the height of the electronic signature box for the entire signature box to be contained within the page) is strictly less than 1.
signers.esignatures.dimensions object Object containing information on the size of the electronic signature on the file. Its structure is given on the right.
signers.esignatures.dimensions.width string Float string which indicates the width of the electronic signature box. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the width of the electronic signature box to be half of the page’s width, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the x-coordinate of the electronic signature box for the entire signature box to be contained within the page) is less than 1.
signers.esignatures.dimensions.height string Float string which indicates the height of the electronic signature box. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the height of the electronic signature box to be half of the page’s height, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the y-coordinate of the electronic signature box for the entire signature box to be contained within the page) is less than 1.
signers.esignatures.signature string Base64 string of the electronic signature.
signers.esignatures.signature_hash string SHA3-256 hash of the electronic signature in hexadecimal format.
signers.esignatures.ip_address string Ip address of the signer.
signers.esignatures.timestamp date Time the electronic signature was received by Dedoco API.
signers.digi_signatures object[] Array of objects. The structure of an object is given on the right.
signers.digi_signatures.type string Value can be “ndi” or “blockchain”. “ndi” indicates that the digital signature was performed via the NDI Document Signing Service. “blockchain” indicates that the digital signature was performed using Dedoco’s blockchain service. Currently, only “ndi” is supported.
signers.digi_signatures.is_mandatory boolean Boolean indicating whether or not the digital signature is mandatory.
signers.digi_signatures.placement object Object containing information on where the digital signature is placed on the file. Its structure is given on the right.
signers.digi_signatures.placement.page number Page number of the page on which the digital signature is placed. Starts from 1.
signers.digi_signatures.placement.x string Float string which indicates the horizontal distance the top left corner of the digital signature box is from the left edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the placement of the digital signature box’s top left corner to the center of the page horizontally, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the width of the digital signature box for the entire signature box to be contained within the page) is strictly less than 1.
signers.digi_signatures.placement.y string Float string which indicates the vertical distance the top left corner of the digital signature box is from the top edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the placement of the digital signature box’s top left corner to the center of the page vertically, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the height of the digital signature box for the entire signature box to be contained within the page) is strictly less than 1.
signers.digi_signatures.dimensions object Object containing information on the size of the digital signature on the file. Its structure is given on the right.
signers.digi_signatures.dimensions.width string Float string which indicates the width of the digital signature box. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the width of the digital signature box to be half of the page’s width, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the x-coordinate of the digital signature box for the entire signature box to be contained within the page) is less than 1.
signers.digi_signatures.dimensions.height string Float string which indicates the height of the digital signature box. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the height of the digital signature box to be half of the page’s height, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the y-coordinate of the digital signature box for the entire signature box to be contained within the page) is less than 1.
signers.digi_signatures.signature string Digital signature in hexadecimal format.
signers.digi_signatures.ip_address string Ip address of the signer.
signers.digi_signatures.timestamp date Time the digital signature was received by Dedoco API.
signers.custom_texts object[] Array of objects. The structure of an object is given on the right.
signers.custom_texts.descriptor string Brief description of custom text. Helps the signer know what to fill into the custom text field.
signers.custom_texts.is_mandatory boolean Boolean indicating whether or not filling in the custom text is mandatory.
signers.custom_texts.type string String indicating the type of custom text. Possible values are “text”, “custom-date”, “actual-date”, “stamp”, “initials”. If “text” is used, the displayed custom text field will accept any text. If “custom-date” is used, the displayed custom text field will accept any date. If “actual-date” is used, the displayed custom text field will automatically take on the date the signer viewed the file. If “stamp” is used, the displayed custom text field will accept any image. If “initials” is used, the displayed custom text field will accept any text but displayed differently than when “text” is used.
signers.custom_texts.placement object Object containing information on where the custom text is placed on the file. Its structure is given on the right.
signers.custom_texts.placement.page number Page number of the page on which the custom text is placed. Starts from 1.
signers.custom_texts.placement.x string Float string which indicates the horizontal distance the top left corner of the custom text box is from the left edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the placement of the custom text box’s top left corner to the center of the page horizontally, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the width of the custom text box for the entire box to be contained within the page) is strictly less than 1.
signers.custom_texts.placement.y string Float string which indicates the vertical distance the top left corner of the custom text box is from the top edge of the page. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the placement of the custom text box’s top left corner to the center of the page vertically, a float string of “0.5” should be used. Minimum represented float value is 0 and maximum represented float value (depends on the height of the custom text box for the entire box to be contained within the page) is strictly less than 1.
signers.custom_texts.dimensions object Object containing information on the size of the custom text on the file. Its structure is given on the right.
signers.custom_texts.dimensions.width string Float string which indicates the width of the custom text box. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
For example, to set the width of the custom text box to be half of the page’s width, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the x-coordinate of the custom text box for the entire box to be contained within the page) is less than 1.
signers.custom_texts.dimensions.height string Float string which indicates the height of the custom text box. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
For example, to set the height of the custom text box to be half of the page’s height, a float string of “0.5” should be used. Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the y-coordinate of the custom text box for the entire box to be contained within the page) is less than 1.
signers.custom_texts.text string Value of the custom text filled in by the signer.
signers.custom_texts.text_hash string SHA3-256 hash of the custom text’s value in hexadecimal format.
signers.custom_texts.ip_address string Ip address of the signer.
signers.custom_texts.timestamp date Time the custom text was received by Dedoco API.
sequential_requirement.sequence_number number Sequence number of the signer(s) listed within the object. Starts from 1.
sequential_requirement.signer.signer_id string Id of the signer.
sequential_requirement.signer.signer_name string Name of the signer.
sequential_requirement.signer.signer_email string Email address of the signer.
completion_requirement.minimum number Minimum number of signers who have signed for the business process to be ‘completed’.
history.action string Description of the action recorded in the history attribute.
history.actor.id string User id of the entity that took the action.
history.actor.email string Email address (if any) of the entity that took the action.
history.actor.name string Name (if any) of the entity that took the action.
history.timestamp date Time the action took place.
history.transaction_hash string Hash of the blockchain transaction updating the data (only if there are any changes in data) on the blockchain due to the action that took place. Can be used to view the transaction details on the blockchain’s explorer.

GET /public/business-processes/{business_process_id}/links HTTP/1.1
Gets generated links for each requestee specified in the business process.

Authorization:
Bearer <jwt_token>

Header Parameter:

Parameter Type Description Required/Optional
jwt_token string Token obtained by the client through the Get JWT Token endpoint. Required

Path Parameter:

Parameter Type Description Required/Optional
business_process_id string Id of the business process to get generated links for. Required

Responses:

Response body for code 200:

{
    "links": {
        "documentId": string,
        "documentName": string,
        "businessProcessId": string,
        "signerId": string,
        "signerName": string,
        "signerEmail": string,
        "link": string
    }[]
}

Response body for code 4xx:

{
    "statusCode": number,
    "message": string,
    "error": string
}

where statusCode is the status code of the error,
> message is a string describing the cause of error and
> error is a string describing the type of error.

Response body for code 5xx:

{
    "statusCode": number,
    "message": string,
    "error": string
}

where statusCode is the status code of the error,
> message is a string describing the cause of error and
> error is a string describing the type of error.

Code Description
200 Request links have been successfully retrieved.
4xx Errors caused by API consumers. Error codes such as 400, 401, 403 and 404 can be expected if incorrect requests are made to the API.
5xx Errors caused by the API provider or its dependencies. Error codes such as 500, 502 and 503 can be expected if there is an issue on the API side.

A links object:

{
    "documentId": string,
    "documentName": string,
    "businessProcessId": string,
    "signerId": string,
    "signerName": string,
    "signerEmail": string,
    "link": string
}

Child Attribute Type Description
links object[] Array of objects. The structure of an object is given on the right.
Contains information on the signing links for each signer involved.
links.documentId string Id of the document the link attribute in the same object is for.
links.documentName string Name of the document the link attribute in the same object is for.
links.businessProcessId string Id of the business process the link attribute in the same object is for.
links.signerId string Id of the signer the link attribute in the same object is for.
links.signerName string Name of the signer the link attribute in the same object is for.
links.signerEmail string Email of the signer the link attribute in the same object is for.
links.link string The base URL of the signing link for the specified signer. To complete the signing link, append the base64 encoding of the file retrieval URL for Dedoco to retrieve the relevant file to sign on. Note that the base64 encoding should be in the URL safe format (i.e. use ‘-’ instead of ‘+’, and ‘_’ instead of ‘/’). The file retrieval URL should accept a GET request for Dedoco to retrieve the relevant file and should return a JSON object { file: string } where file is the base64 string of the retrieved pdf.
For example, if the file retrieval URL is “https://www.sample-url.com/path/file-id”, the base64 encoding would be “aHR0cHM6Ly93d3cuc2FtcGxlLXVybC5jb20vcGF0aC9maWxlLWlkIA==”. Appending “aHR0cHM6Ly93d3cuc2FtcGxlLXVybC5jb20vcGF0aC9maWxlLWlkIA==” to the base URL obtained from this request would complete the signing link. Note that the file retrieval URL appended should always be retrieving the most up-to-date (i.e. with signatures if there were previous signers) pdf. In the case of a business process with a signing sequence defined, the client should send out the links in the same sequence (even though Dedoco prevents a signer from signing before the previous signer has signed) and make sure that the appended URL retrieves the latest pdf with signatures (if any). And in the case of a business process where signers are allowed to sign simultaneously or in any order, the client can send out the links to all the signers at the same time but should make sure that the appended URL always retrieves the latest pdf with signatures (if any) so that the signers will receive the right pdf to sign on.

Sample Request Header:

GET https://beta-api.dedoco.com/api/v1/public/business-processes/60581dbbc79151135ddd6b5a/links HTTP/1.1
Authorization: Bearer <token>

Sample Request Body:

{}

Sample Response Header:

HTTP/1.1 200 OK

Sample Response Body:

{
  "links": [
    {
      "documentId": "60581dbbc79151135ddd6b58",
      "documentName": "sample_pdf",
      "businessProcessId": "60581dbbc79151135ddd6b5a",
      "signerId": "SIG_60581dbbc79151135ddd6b5b",
      "signerName": "Alice Tan",
      "signerEmail": "alicetan@gmail.com",
      "link": "https://sample-url.com/public/sign/60581dbbc79151135ddd6b5a/SIG_60581dbbc79151135ddd6b5b"
    },
    {
      "documentId": "60581dbbc79151135ddd6b58",
      "documentName": "sample_pdf",
      "businessProcessId": "60581dbbc79151135ddd6b5a",
      "signerId": "SIG_60581dbbc79151135ddd6b5c",
      "signerName": "Bobby Chia",
      "signerEmail": "bobbychia@gmail.com",
      "link": "https://sample-url.com/public/sign/60581dbbc79151135ddd6b5a/SIG_60581dbbc79151135ddd6b5c"
    }
  ]
}

G. Verification

Dedoco stores the evidence of business processes on its blockchain and offers the service of verifying the authenticity of a document that has undergone Dedoco’s processing by querying Dedoco’s blockchain and database.

Endpoint: Verify Own Document

GET /public/verifier/doc-hashes/{doc_hash}/result HTTP/1.1
Gets a list of document(s) and business process(es) created by the client associated with the document hash (SHA3-256) provided.

Authorization:
Bearer <jwt_token>

Header Parameter:

Parameter Type Description Required/Optional
jwt_token string Token obtained by the client through the Get JWT Token endpoint. Required

Path Parameter:

Parameter Type Description Required/Optional
doc_hash string SHA3-256 hash of the document to be verified in hexadecimal. Having the prefix “0x” is optional. Required

Responses:

Response body for code 200:

{
    "process": {
      "id": string,
      "type": string,
      "owner": {
        "id": string,
        "type": string,
        "name": string
      },
      "date_created": string,
      "expiration_time": string,
      "document_id": string,
      "allow_download": boolean,
      "signers": {
        "signer_email": string,
        "signer_name": string,
        "signer_phone": string,
        "sequence_number": number,
        "has_signed": boolean,
        "require_authentication": boolean,
        "verify_method": string,
      "esignatures": {
        "placement": {
          "page": number,
          "x": string,
          "y": string
          },
          "dimensions": {
            "width": string,
            "height": string
          }
        }[],
        "digi_signatures": {
          "type": string,
          "placement": {
            "page": number,
            "x": string,
            "y": string
          },
          "dimensions": {
            "width": string,
            "height": string
            }
        }[],
        "custom_texts": {
          "descriptor": string,
          "is_mandatory": boolean,
          "type": string,
          "placement": {
            "page": number,
            "x": string,
            "y": string
          },
          "dimensions": {
            "width": string,
          "height": string
          }
        }[]
      }[],
      "sequential_requirement": {
        "signer": {
          "signer_id": string,
          "signer_name": string,
          "signer_email": string
        },
        "sequence_number": number
      }[],
      "status": string,
      "history": {
        "actor": {
          "id": string,
          "email": string,
          "name": string
        },
        "action": string,
        "timestamp": string,
        "transaction_hash": string
      }[],
      "completion_requirement": {
        "min_number": number
      },
      "last_modified": string
    },
    "document": {
      "id": string,
      "name": string,
      "file_type": string,
      "document_hashes": string[],
      "business_processes": string[],
      "owner": string,
      "date_created": string,
      "status": string,
      "parent_folder": {
        "id": string,
        "name": string
      },
      "history": {
        "actor": {
          "id": string,
          "email": string,
          "name": string
        },
        "action": string,
        "timestamp": string,
        "transaction_hash": string
      }[]
  }
}[]

where process is similar to the Business Process object (refer to Business Processes for more details) with the exception of process.owner and process.last_modified.
> Tips: To get the latest business process created, look for the business process with the latest process.date_created date string. To get the latest business process acted on, look for the business process with the latest process.last_modified date string.

where document is similar to the Document object (refer to Documents for more details) with the exception of document.parent_folder.

Response body for code 4xx:

{
    "statusCode": number,
    "message": string,
    "error": string
}

where statusCode is the status code of the error,
> message is a string describing the cause of error and
> error is a string describing the type of error.

Response body for code 5xx:

{
    "statusCode": number,
    "message": string,
    "error": string
}

where statusCode is the status code of the error,
> message is a string describing the cause of error and
> error is a string describing the type of error.

Code Description
200 Document hash has been verified successfully.
4xx Document hash is not found or other errors caused by API consumers. Error codes such as 400, 401, 403 and 404 can be expected if incorrect requests are made to the API.
5xx Errors caused by the API provider or its dependencies. Error codes such as 500, 502 and 503 can be expected if there is an issue on the API side.
Child Attribute Type Description
process.owner.id string Id of the business process owner.
process.owner.type string Type of business process owner. Value is "public-api" in this case.
process.owner.name string Name of the business process owner.
process.last_modified string Date string of the time the business process was last acted on.
document.parent_folder.id string Id of the folder in which the document is contained.
document.parent_folder.name string Name of the folder in which the document is contained.

Sample Request Header:

GET https://beta-api.dedoco.com/api/v1/public/verifier/doc-hashes/624d0793ef16111d737165a75c5673f527dc70ced1c75536f2f06f3db6288de3/result HTTP/1.1
Authorization: Bearer <token>

Sample Request Body:

{}

Sample Response Header:

HTTP/1.1 200 OK

Sample Response Body:

[
  {
    "process": {
      "current_signer": null,
      "completion_requirement": {
        "min_number": 1
      },
      "id": "6180da467defd93ae24e31d5",
      "type": "signature",
      "owner": {
        "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
        "type": "public-api",
        "name": "dedoco"
      },
      "date_created": "2021-03-22T03:30:52.000Z",
      "expiration_time": "1970-01-01T00:00:00.000Z",
      "document_id": "6180da467defd93ae24e31d4",
      "allow_download": true,
      "signers": [
        {
          "has_signed": true,
          "require_authentication": false,
          "signer_id": "0ec1e860-90a0-4e81-8b03-b5390ac5a93e",
          "signer_name": "Alice Tan",
          "signer_email": "alice@gmail.com",
          "sequence_number": 1,
          "esignatures": [
            {
              "placement": {
                "page": 1,
                "x": "0.5",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.1",
                "height": "0.05"
              },
              "type": "drawing",
              "signature": "data:image/png;base64,iVBORw...",
              "signature_hash": "7aecfaacac334204bfee79481283ac21e68b174d5752ea99c0722c97ef40dc75",
              "ip_address": "1",
              "timestamp": "2021-11-02T06:28:18.821Z"
            }
          ],
          "digi_signatures": [],
          "custom_texts": [
            {
              "placement": {
                "page": 1,
                "x": "0.123",
                "y": "0.123"
              },
              "dimensions": {
                "width": "0.1",
                "height": "0.05"
              },
              "type": "text",
              "descriptor": "NRIC",
              "is_mandatory": true,
              "text": "test",
              "text_hash": "e5a8ec19b53214297ad3405f20386033d5b2fe1dc10915441886f3de3c2122f2",
              "ip_address": "1",
              "timestamp": "2021-11-02T06:28:18.821Z"
            }
          ],
          "confirmations": []
        }
      ],
      "observers": [],
      "approvers": [],
      "sequential_requirement": [
        {
          "signer": {
            "signer_id": "0ec1e860-90a0-4e81-8b03-b5390ac5a93e",
            "signer_name": "Alice Tan",
            "signer_email": "alice@gmail.com"
          },
          "sequence_number": 1
        }
      ],
      "status": "completed",
      "history": [
        {
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "action": "Document Sent Out for Signing",
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": "0x3f72fe302b9b2e1374f042ec1615711c074403ba6f8b951d311ff1cd552bf7fc"
        },
        {
          "actor": {
            "id": "0ec1e860-90a0-4e81-8b03-b5390ac5a93e",
            "email": "alice@gmail.com",
            "name": "Alice Tan"
          },
          "action": "Custom Text Filled",
          "timestamp": "2021-11-02T06:28:18.821Z",
          "transaction_hash": "0xb9b6ec38c56377c3e9d8545ae22ebf4a669698f77ea0d82b1817823091326859"
        },
        {
          "actor": {
            "id": "0ec1e860-90a0-4e81-8b03-b5390ac5a93e",
            "email": "alice@gmail.com",
            "name": "Alice Tan"
          },
          "action": "Electronic Signature Captured",
          "timestamp": "2021-11-02T06:28:18.821Z",
          "transaction_hash": "0xb9b6ec38c56377c3e9d8545ae22ebf4a669698f77ea0d82b1817823091326859"
        },
        {
          "actor": {
            "id": "0ec1e860-90a0-4e81-8b03-b5390ac5a93e",
            "email": "alice@gmail.com",
            "name": "Alice Tan"
          },
          "action": "Signing Completed",
          "timestamp": "2021-11-02T06:28:18.821Z",
          "transaction_hash": "0xb9b6ec38c56377c3e9d8545ae22ebf4a669698f77ea0d82b1817823091326859"
        }
      ],
      "last_modified": "2021-11-02T06:28:18.821Z"
    },
    "document": {
      "document_hashes": [
        "6d0b4a52c986d6511bd74b2e32d2f9c024e6ad2839a91734e2bf2ae89f93307e",
        "624d0793ef16111d737165a75c5673f527dc70ced1c75536f2f06f3db6288de3"
      ],
      "prerequisite_documents": [],
      "business_processes": ["6180da467defd93ae24e31d5"],
      "id": "6180da467defd93ae24e31d4",
      "name": "dummy_pdf",
      "file_type": "pdf",
      "owner": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
      "date_created": "2021-03-22T03:30:52.000Z",
      "status": "active",
      "parent_folder": {
        "id": "6180da467defd93ae24e31d3",
        "name": "Test Folder"
      },
      "history": [
        {
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "action": "create Document",
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": "0x96e49090a821a728dab4afa3f67e46dcea8597f886bd159166fbd69a817522e8"
        },
        {
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "action": "add Business Process (Signature) with id: 6180da467defd93ae24e31d5",
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": "0x3f72fe302b9b2e1374f042ec1615711c074403ba6f8b951d311ff1cd552bf7fc"
        }
      ]
    }
  }
]