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
8 Mar 2024 Version 0.7
Deprecated unused fields from previous versions
25 Oct 2023 Version 0.6q
Added documentation for text tags
15 Sep 2023 Version 0.6p
Added "initials" as new custom text type
28 Apr 2023 Version 0.6o
Updated get token endpoint
3 Oct 2022 Version 0.6n
Added approver feature and updated status callback request body
6 Sep 2022 Version 0.6m
Added get business process endpoint and updated status callback request body
12 Aug 2022 Version 0.6l
Added meeting feature
5 Jul 2022 Version 0.6k
Added Environments section; added "signer_nric" feature
20 Jun 2022 Version 0.6j
Updated "business_process" and "business_processes" to be required
5 Apr 2022 Version 0.6i
Updated request body of status callback
14 Feb 2022 Version 0.6h
Added observer feature
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 API Platform, please provide the following information and submit your application request to openapi@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 API platform.

B. Sequence Diagram

C. Environments

Stage

Base URL

https://api.stage.dedoco.com/api/v1

Prod

Base URL

https://api.dedoco.com/api/v1

D. 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 <client_id> <client_secret>

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 expect POST requests with the following data according to the MIME type provided:

"application/json":

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

"multipart/form-data":

businessProcessId = Text
file = File
  • businessProcessId is the id of the business process the updated file is sent for.
  • file is the base64 string of the updated pdf (when sent as application/json) or the pdf itself (when sent as multipart/form-data).

The callback url for statusCallback should expect POST requests with the following data according to the MIME type provided:

"application/json":

{
  "businessProcessId": string,
  "status": string,
  "latestActor": {
    "id": string,
    "type": "signer" | "approver",
    "remark": string
  },
  "signers": {
    "id": string,
    "name": string,
    "email": string,
    "sequence_number": number,
    "has_signed": boolean,
    "signedTime": number,
    "customTexts": {
      "placement": {
        "page": number,
        "x": string,
        "y": string
      },
      "dimensions": {
        "width": string,
        "height": string
      },
      "type": string,
      "descriptor": string,
      "isMandatory": boolean,
      "value": string
    }[],
    "signatures": {
      "placement": {
        "page": number,
        "x": string,
        "y": string
      },
      "dimensions": {
        "width": string,
        "height": string
      },
      "type": "electronic" | "digital",
      "value": string
    }[]
  }[],
  "approvers": {
    "id": string,
    "name": string,
    "email": string,
    "sequence_number": number,
    "has_approved": boolean,
    "has_declined": boolean
  }[]
}

"multipart/form-data":

businessProcessId = Text
status = Text
latestActor = Text
signers = Text
approvers = Text
  • businessProcessId is the id of the business process the status is sent for.
  • status is a string describing the state of the business process.
  • latestActor is an object containing information about the entity who has made changes to the business process (when sent as application/json) or a JSON string representation of the object (when sent as multipart/form-data).
  • latestActor.remark exists only if the actor is an approver and is a string containing the approver's remark.
  • signers is an array of objects containing information on each signer (when sent as application/json) or a JSON string representation of the array (when sent as multipart/form-data).
  • signers.has_signed indicates if the signer has signed.
  • signers.sequence_number exists only if the signers are required to act in a sequence for the business process.
  • signers.signedTime is the Unix time the signer signed at and is only present if signer has signed.
  • signers.customTexts is an array of objects containing information of each custom text filled in by the signer and is only present if signer has signed.
  • signers.customTexts.value is the value filled in by the signer for the corresponding custom text.
  • signers.signatures is an array of objects containing information of each signature of the signer and is only present if signer has signed.
  • signers.signatures.value is the signature of the signer.
  • approvers is an array of objects containing information on each approver (when sent as application/json) or a JSON string representation of the array (when sent as multipart/form-data).
  • approvers.sequence_number exists only if the approvers are required to act 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
fileCallbackMimeType string Format of data sent to fileCallback. Value can "application/json" or "multipart/form-data". "application/json" is used if no value is provided. Optional
statusCallbackMimeType string Format of data sent to statusCallback. Value can "application/json" or "multipart/form-data". "application/json" is used if no value is provided. Optional
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
}
  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • error is a string describing the type of error.

Response body for code 5xx:

{
  "statusCode": number,
  "message": string,
  "error": string
}
  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • 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://api.stage.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",
  "fileCallbackMimeType": "multipart/form-data",
  "statusCallbackMimeType": "application/json",
  "userName": "Jim Lee",
  "userEmail": "jimmylee@gmail.com"
}

Sample Response Header:

HTTP/1.1 201 Created

Sample Response Body:

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

E. 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.
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,
    "text_tagged_doc_base64": string,
    "text_tagged_doc_url": 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,
      "signer_nric": optional string,
      "sequence_number": number,
      "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
        }
      }[]
    }[],
    "observers": optional {
      "name": string,
      "email": string,
      "phone": string
    }[],
    "approvers": optional {
      "approver_email": string,
      "approver_name": string,
      "approver_phone": string,
      "sequence_number": number
    }[],
    "completion_requirement": {
      "min_number": number
    },
    "meeting": optional {
      "title": string,
      "description": optional string,
      "host_email": string
    }
}
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
business_processes object[] Array of objects, represented on the right. More details are given below. Required

A business_processes.signers object

{
    "signer_email": string,
    "signer_name": string,
    "signer_phone": string,
    "signer_nric": optional string,
    "sequence_number": number,
    "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
}

A business_processes.observers object:

{
    "email": string,
    "name": string,
    "phone": string
}

A business_processes.approvers object:

{
    "approver_email": string,
    "approver_name": string,
    "approver_phone": string,
    "sequence_number": number
}
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.
documents.text_tagged_doc_base64 string Optional field. Base64 representation of the document with text tags.
documents.text_tagged_doc_url string Optional field. Download URL of the document with text tags. text_tagged_doc_base64 will take precedence.
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 and approvers to act 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. Note that this field is optional. If provided, 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
.signer_nric
string Optional field. Last 4 characters of Signer's Singapore NRIC/FIN. Provide this field if signer is expected to Sign with Singpass that matches the given partial NRIC/FIN
business_processes.signers
.sequence_number
number Sequence number of the signer if the business process requires signers and approvers to act in a sequence. Starts from 1. 0 is used if there is no sequence.
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. If this object is not provided, the business processes' corresponding document must have either text_tagged_doc_base64 or text_tagged_doc_url provided so that the API can extract the placements based on the text tags. See the Text Tags section for more details.
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 Only “ndi” is accepted here. NDI refers to Sign with Singpass.
business_processes.signers
.digi_signatures.placement
object Object containing information on where the digital signature is placed on the file. If this object is not provided, the business processes' corresponding document must have either text_tagged_doc_base64 or text_tagged_doc_url provided so that the API can extract the placements based on the text tags. See the Text Tags section for more details.
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” and "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 "initials" is used, users are allowed to draw or type out their initials.
business_processes.signers
.custom_texts.placement
object Object containing information on where the custom text is placed on the file. If this object is not provided, the business processes' corresponding document must have either text_tagged_doc_base64 or text_tagged_doc_url provided so that the API can extract the placements based on the text tags. See the Text Tags section for more details.
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.observers object[] Array of objects. The structure of an object is given on the right.
business_processes
.observers.email
string Email address of the observer.
business_processes
.observers.name
string Name of the observer.
business_processes
.observers.phone
string Phone number of the observer. Note that this field is optional. If provided, 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.approvers object[] Array of objects. The structure of an object is given on the right.
business_processes.approvers
.approver_email
string Email address of the approver.
business_processes.approvers
.approver_name
string Name of the approver.
business_processes.approvers
.approver_phone
string Phone number of the approver. Note that this field is optional. If provided, 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.approvers
.sequence_number
number Sequence number of the approver if the business process requires signers and approvers to act in a sequence. Starts from 1. 0 is used if there is no sequence.
business_processes
.completion_requirement.min_number
number Minimum number of signers or approvers who have acted for the business process to be ‘completed’. If the business process has a sequence defined, this number is expected to be equal to the total number of signers and approvers of the business process.
business_processes.meeting
.title
string Title of the meeting displayed to the participants.
business_processes.meeting
.description
string Optional field. Description of the meeting displayed to the participants.
business_processes.meeting
.host_email
string Email of the meeting host. Has to be one of the email addresses provided in business_processes.signers, business_processes.observers, or business_processes.approvers. Note that duplicate emails in business_processes.signers, business_processes.observers, and business_processes.approvers are not allowed if meeting is used.

Responses:

Response body for code 201:

{
  "folder": Folder,
  "documents": Document[],
  "businessProcesses": BusinessProcess[],
  "links": {
    "documentId": string,
    "documentName": string,
    "businessProcessId": string,
    ["signer" | "observer" | "approver"]"Id": string,
    ["signer" | "observer" | "approver"]"Name": string,
    ["signer" | "observer" | "approver"]"Email": string,
    "link": string
  }[]
}

Response body for code 4xx:

{
  "statusCode": number,
  "message": string,
  "error": string
}
  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • error is a string describing the type of error.

Response body for code 5xx:

{
  "statusCode": number,
  "message": string,
  "error": string
}
  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • 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,
  ["signer" | "observer" | "approver"]"Id": string,
  ["signer" | "observer" | "approver" ]"Name": string,
  ["signer" | "observer" | "approver"]"Email": 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 links for each signer/observer/approver 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.[signer | observer | approver]Id string Id of the signer/observer/approver the link attribute in the same object is for.
links.[signer | observer | approver]Name string Name of the signer/observer/approver the link attribute in the same object is for.
links.[signer | observer | approver]Email string Email of the signer/observer/approver the link attribute in the same object is for.
links.link string The base URL of the link for the specified signer/observer/approver. To complete the 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. For business processes with a sequence defined, the client should send out the links in the same sequence (even though Dedoco enforces that signers and approvers must act according to their sequence numbers) and make sure that the appended URL retrieves the latest pdf with signatures (if any). For business processes without a sequence defined, the client can send out the links to all the signers and approvers 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 and approvers will receive the right pdf for signing or approving. Links for observers, on the other hand, can be sent out at any time without waiting for the signers and approvers to act.

Sample Request Header:

POST https://api.stage.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"
    }
  ],
  "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,
          "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,
              "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,
          "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,
              "placement": {
                "page": 1,
                "x": "0.223",
                "y": "0.223"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.05"
              }
            }
          ]
        }
      ],
      "observers": [
        {
          "email": "troy@gmail.com",
          "name": "Troy Gan",
          "phone": "+6512345678"
        }
      ],
      "approvers": [
        {
          "approver_email": "llynn@gmail.com",
          "approver_name": "Lynn Lim",
          "approver_phone": "+6510101010",
          "sequence_number": 3
        }
      ],
      "completion_requirement": {
        "min_number": 3
      }
    },
    {
      "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,
          "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,
          "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": "620a08c38b2cd7001e0bfdad",
    "name": "Test Folder",
    "date_created": "2021-03-22T03:30:52.000Z",
    "child_documents": ["620a08c38b2cd7001e0bfdae", "620a08c38b2cd7001e0bfdaf"],
    "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": "0x478c18e70726ef0c8707e9955f0f97152c27226325210ada89d4489f3d83d5f7"
      },
      {
        "action": "add Document with id: 620a08c38b2cd7001e0bfdae",
        "actor": {
          "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
          "email": "jimmylee@gmail.com",
          "name": "Jim Lee"
        },
        "timestamp": "2021-03-22T03:30:52.000Z",
        "transaction_hash": "0x478c18e70726ef0c8707e9955f0f97152c27226325210ada89d4489f3d83d5f7"
      },
      {
        "action": "add Document with id: 620a08c38b2cd7001e0bfdaf",
        "actor": {
          "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
          "email": "jimmylee@gmail.com",
          "name": "Jim Lee"
        },
        "timestamp": "2021-03-22T03:30:52.000Z",
        "transaction_hash": "0x478c18e70726ef0c8707e9955f0f97152c27226325210ada89d4489f3d83d5f7"
      }
    ]
  },
  "documents": [
    {
      "id": "620a08c38b2cd7001e0bfdae",
      "name": "sample_pdf",
      "file_type": "pdf",
      "date_created": "2021-03-22T03:30:52.000Z",
      "document_hashes": [
        "a3c124f1ae5d1e57a4a646512ca0471710e092ef0a39aa3a740da5447bcde237"
      ],
      "business_processes": ["620a08c38b2cd7001e0bfdb0"],
      "status": "active",
      "parent_folder": "620a08c38b2cd7001e0bfdad",
      "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": "0x478c18e70726ef0c8707e9955f0f97152c27226325210ada89d4489f3d83d5f7"
        },
        {
          "action": "add Business Process (Signature) with id: 620a08c38b2cd7001e0bfdb0",
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": "0x4054812d47d2d9fc447834732aa6e8ece521f471bf4eb6fd83a786575c710aca"
        }
      ]
    },
    {
      "id": "620a08c38b2cd7001e0bfdaf",
      "name": "sample_pdf_2",
      "file_type": "pdf",
      "date_created": "2021-03-22T03:30:52.000Z",
      "document_hashes": [
        "ce997dea6abb909f745de1aa18d26c7f99003233894876d6635a5d166c02862e"
      ],
      "business_processes": ["620a08c38b2cd7001e0bfdb1"],
      "status": "active",
      "parent_folder": "620a08c38b2cd7001e0bfdad",
      "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": "0x478c18e70726ef0c8707e9955f0f97152c27226325210ada89d4489f3d83d5f7"
        },
        {
          "action": "add Business Process (Signature) with id: 620a08c38b2cd7001e0bfdb1",
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": "0x0c6afe6e2b72aac97c649c6b9e4b0b83ba0ed8339694f17c5469f0c5923550aa"
        }
      ]
    }
  ],
  "businessProcesses": [
    {
      "id": "620a08c38b2cd7001e0bfdb0",
      "type": "signature",
      "date_created": "2021-03-22T03:30:52.000Z",
      "expiration_time": "1970-01-01T00:00:00.000Z",
      "document_id": "620a08c38b2cd7001e0bfdae",
      "allow_download": true,
      "signers": [
        {
          "has_signed": false,
          "signer_id": "95fce26f-54f9-4b58-bd3a-77ffebea66ab",
          "signer_name": "Alice Tan",
          "signer_email": "alicetan@gmail.com",
          "signer_phone": "+6581234567",
          "sequence_number": 1,
          "esignatures": [
            {
              "placement": {
                "page": 1,
                "x": "0.5",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "digi_signatures": [],
          "custom_texts": [
            {
              "type": "text",
              "descriptor": "NRIC",
              "is_mandatory": true,
              "placement": {
                "page": 1,
                "x": "0.123",
                "y": "0.123"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "confirmations": []
        },
        {
          "has_signed": false,
          "signer_id": "c451a0f3-dd5e-44bf-a7b1-c2ff2ee286ee",
          "signer_name": "Bobby Chia",
          "signer_email": "bobbychia@gmail.com",
          "signer_phone": "+6581234567",
          "sequence_number": 2,
          "esignatures": [
            {
              "placement": {
                "page": 1,
                "x": "0.6",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "digi_signatures": [],
          "custom_texts": [
            {
              "type": "text",
              "descriptor": "NRIC",
              "is_mandatory": true,
              "placement": {
                "page": 1,
                "x": "0.223",
                "y": "0.223"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.05"
              }
            }
          ],
          "confirmations": []
        }
      ],
      "observers": [
        {
          "id": "89eaa88e-3ddd-4fd7-a0de-269b0f9942ff",
          "email": "troy@gmail.com",
          "name": "Troy Gan",
          "phone": "+6512345678"
        }
      ],
      "approvers": [
        {
          "has_approved": false,
          "has_declined": false,
          "approver_id": "c756f4c4-90e3-4ddc-b0e0-24c100d80bdb",
          "approver_email": "llynn@gmail.com",
          "approver_name": "Lynn Lim",
          "approver_phone": "+6510101010",
          "sequence_number": 3
        }
      ],
      "sequential_requirement": [
        {
          "signer": {
            "signer_id": "95fce26f-54f9-4b58-bd3a-77ffebea66ab",
            "signer_name": "Alice Tan",
            "signer_email": "alicetan@gmail.com"
          },
          "sequence_number": 1
        },
        {
          "signer": {
            "signer_id": "c451a0f3-dd5e-44bf-a7b1-c2ff2ee286ee",
            "signer_name": "Bobby Chia",
            "signer_email": "bobbychia@gmail.com"
          },
          "sequence_number": 2
        },
        {
          "approver": {
            "approver_id": "c756f4c4-90e3-4ddc-b0e0-24c100d80bdb",
            "approver_name": "Lynn Lim",
            "approver_email": "llynn@gmail.com"
          },
          "sequence_number": 3
        }
      ],
      "completion_requirement": {
        "min_number": 3,
        "overriding_signers": []
      },
      "status": "pending",
      "history": [
        {
          "action": "Document Sent Out for Signing",
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": "0x4054812d47d2d9fc447834732aa6e8ece521f471bf4eb6fd83a786575c710aca"
        }
      ]
    },
    {
      "id": "620a08c38b2cd7001e0bfdb1",
      "type": "signature",
      "date_created": "2021-03-22T03:30:52.000Z",
      "expiration_time": "1970-01-01T00:00:00.000Z",
      "document_id": "620a08c38b2cd7001e0bfdaf",
      "allow_download": false,
      "signers": [
        {
          "has_signed": false,
          "signer_id": "46b2a0e8-f92c-4d0e-b739-b8b8eab887ba",
          "signer_name": "Alan Teo",
          "signer_email": "alanteo@gmail.com",
          "sequence_number": 1,
          "esignatures": [],
          "digi_signatures": [
            {
              "type": "ndi",
              "placement": {
                "page": 1,
                "x": "0.6",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "custom_texts": [],
          "confirmations": []
        },
        {
          "has_signed": false,
          "signer_id": "74d0f86e-26f5-412e-b286-d8e13c722323",
          "signer_name": "Beverly Chan",
          "signer_email": "beverlychan@gmail.com",
          "sequence_number": 2,
          "esignatures": [],
          "digi_signatures": [
            {
              "type": "ndi",
              "placement": {
                "page": 1,
                "x": "0.5",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "custom_texts": [],
          "confirmations": []
        }
      ],
      "observers": [],
      "approvers": [],
      "sequential_requirement": [
        {
          "signer": {
            "signer_id": "46b2a0e8-f92c-4d0e-b739-b8b8eab887ba",
            "signer_name": "Alan Teo",
            "signer_email": "alanteo@gmail.com"
          },
          "sequence_number": 1
        },
        {
          "signer": {
            "signer_id": "74d0f86e-26f5-412e-b286-d8e13c722323",
            "signer_name": "Beverly Chan",
            "signer_email": "beverlychan@gmail.com"
          },
          "sequence_number": 2
        }
      ],
      "completion_requirement": {
        "min_number": 2,
        "overriding_signers": []
      },
      "status": "pending",
      "history": [
        {
          "action": "Document Sent Out for Signing",
          "actor": {
            "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
            "email": "jimmylee@gmail.com",
            "name": "Jim Lee"
          },
          "timestamp": "2021-03-22T03:30:52.000Z",
          "transaction_hash": "0x0c6afe6e2b72aac97c649c6b9e4b0b83ba0ed8339694f17c5469f0c5923550aa"
        }
      ]
    }
  ],
  "links": [
    {
      "documentId": "620a08c38b2cd7001e0bfdae",
      "documentName": "sample_pdf",
      "businessProcessId": "620a08c38b2cd7001e0bfdb0",
      "signerId": "95fce26f-54f9-4b58-bd3a-77ffebea66ab",
      "signerName": "Alice Tan",
      "signerEmail": "alicetan@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/sign/620a08c38b2cd7001e0bfdb0/95fce26f-54f9-4b58-bd3a-77ffebea66ab"
    },
    {
      "documentId": "620a08c38b2cd7001e0bfdae",
      "documentName": "sample_pdf",
      "businessProcessId": "620a08c38b2cd7001e0bfdb0",
      "signerId": "c451a0f3-dd5e-44bf-a7b1-c2ff2ee286ee",
      "signerName": "Bobby Chia",
      "signerEmail": "bobbychia@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/sign/620a08c38b2cd7001e0bfdb0/c451a0f3-dd5e-44bf-a7b1-c2ff2ee286ee"
    },
    {
      "documentId": "620a08c38b2cd7001e0bfdae",
      "documentName": "sample_pdf",
      "businessProcessId": "620a08c38b2cd7001e0bfdb0",
      "observerId": "89eaa88e-3ddd-4fd7-a0de-269b0f9942ff",
      "observerName": "Troy Gan",
      "observerEmail": "troy@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/observe/620a08c38b2cd7001e0bfdb0/89eaa88e-3ddd-4fd7-a0de-269b0f9942ff"
    },
    {
      "documentId": "620a08c38b2cd7001e0bfdae",
      "documentName": "sample_pdf",
      "businessProcessId": "620a08c38b2cd7001e0bfdb0",
      "approverId": "c756f4c4-90e3-4ddc-b0e0-24c100d80bdb",
      "approverName": "Lynn Lim",
      "approverEmail": "llynn@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/approve/620a08c38b2cd7001e0bfdb0/c756f4c4-90e3-4ddc-b0e0-24c100d80bdb"
    },
    {
      "documentId": "620a08c38b2cd7001e0bfdaf",
      "documentName": "sample_pdf_2",
      "businessProcessId": "620a08c38b2cd7001e0bfdb1",
      "signerId": "46b2a0e8-f92c-4d0e-b739-b8b8eab887ba",
      "signerName": "Alan Teo",
      "signerEmail": "alanteo@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/sign/620a08c38b2cd7001e0bfdb1/46b2a0e8-f92c-4d0e-b739-b8b8eab887ba"
    },
    {
      "documentId": "620a08c38b2cd7001e0bfdaf",
      "documentName": "sample_pdf_2",
      "businessProcessId": "620a08c38b2cd7001e0bfdb1",
      "signerId": "74d0f86e-26f5-412e-b286-d8e13c722323",
      "signerName": "Beverly Chan",
      "signerEmail": "beverlychan@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/sign/620a08c38b2cd7001e0bfdb1/74d0f86e-26f5-412e-b286-d8e13c722323"
    }
  ]
}

F. 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,
        "signer_nric": optional string,
        "sequence_number": number,
        "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
            }
        }[]
    }[],
    "observers": optional {
      "name": string,
      "email": string,
      "phone": string
    }[],
    "approvers": optional {
      "approver_email": string,
      "approver_name": string,
      "approver_phone": string,
      "sequence_number": number
    }[],
    "completion_requirement": {
        "min_number": number
    },
    "meeting": optional {
      "title": string,
      "description": optional string,
      "host_email": string
    }
}

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
text_tagged_doc_base64 string Base64 representation of the document with text tags. Optional
text_tagged_doc_url string Download URL of the document with text tags. text_tagged_doc_base64 will take precedence. Optional
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. Required

A business_process.signers object:

{
    "signer_email": string,
    "signer_name": string,
    "signer_phone": string,
    "signer_nric": optional string,
    "sequence_number": number,
    "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
}

A business_process.observers object:

{
    "email": string,
    "name": string,
    "phone": string
}

A business_processes.approvers object:

{
    "approver_email": string,
    "approver_name": string,
    "approver_phone": string,
    "sequence_number": number
}
Child attribute Type Description
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 and approvers to act 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. Note that this field is optional. If provided, 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
.signer_nric
string Optional field. Last 4 characters of Signer's Singapore NRIC/FIN. Provide this field if signer is expected to Sign with Singpass that matches the given partial NRIC/FIN
business_processes.signers
.sequence_number
number Sequence number of the signer if the business process requires signers and approvers to act in a sequence. Starts from 1. 0 is used if there is no sequence.
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. If this object is not provided, the business processes' corresponding document must have either text_tagged_doc_base64 or text_tagged_doc_url provided so that the API can extract the placements based on the text tags. See the [Text Tags][text-tags-section-link] section for more details.
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 Only “ndi” is accepted here. NDI refers to Sign with Singpass.
business_processes.signers
.digi_signatures.placement
object Object containing information on where the digital signature is placed on the file. If this object is not provided, the business processes' corresponding document must have either text_tagged_doc_base64 or text_tagged_doc_url provided so that the API can extract the placements based on the text tags. See the [Text Tags][text-tags-section-link] section for more details.
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” and "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 "initials" is used, users are allowed to draw or type out their initials.
business_processes.signers
.custom_texts.placement
object Object containing information on where the custom text is placed on the file. If this object is not provided, the business processes' corresponding document must have either text_tagged_doc_base64 or text_tagged_doc_url provided so that the API can extract the placements based on the text tags. See the [Text Tags][text-tags-section-link] section for more details.
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.observers object[] Array of objects. The structure of an object is given on the right.
business_processes
.observers.email
string Email address of the observer.
business_processes
.observers.name
string Name of the observer.
business_processes
.observers.phone
string Phone number of the observer. Note that this field is optional. If provided, 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.approvers object[] Array of objects. The structure of an object is given on the right.
business_processes.approvers
.approver_email
string Email address of the approver.
business_processes.approvers
.approver_name
string Name of the approver.
business_processes.approvers
.approver_phone
string Phone number of the approver. Note that this field is optional. If provided, 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.approvers
.sequence_number
number Sequence number of the approver if the business process requires signers and approvers to act in a sequence. Starts from 1. 0 is used if there is no sequence.
business_processes
.completion_requirement.min_number
number Minimum number of signers or approvers who have acted for the business process to be ‘completed’. If the business process has a sequence defined, this number is expected to be equal to the total number of signers and approvers of the business process.
business_processes.meeting
.title
string Title of the meeting displayed to the participants.
business_processes.meeting
.description
string Optional field. Description of the meeting displayed to the participants.
business_processes.meeting
.host_email
string Email of the meeting host. Has to be one of the email addresses provided in business_processes.signers, business_processes.observers, or business_processes.approvers. Note that duplicate emails in business_processes.signers, business_processes.observers, and business_processes.approvers are not allowed if meeting is used.

Responses:

Response body for code 201

{
    "document": Document,
    "businessProcess": BusinessProcess,
    "links": {
      "documentId": string,
      "documentName": string,
      "businessProcessId": string,
    ["signer" | "observer" | "approver"]"Id": string,
    ["signer" | "observer" | "approver"]"Name": string,
    ["signer" | "observer" | "approver"]"Email": 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,
  ["signer" | "observer" | "approver"]"Id": string,
  ["signer" | "observer" | "approver" ]"Name": string,
  ["signer" | "observer" | "approver"]"Email": string,
  "link": string
}
Child Attribute Type Description
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 links for each signer/observer/approver 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.[signer | observer | approver]Id string Id of the signer/observer/approver the link attribute in the same object is for.
links.[signer | observer | approver]Name string Name of the signer/observer/approver the link attribute in the same object is for.
links.[signer | observer | approver]Email string Email of the signer/observer/approver the link attribute in the same object is for.
links.link string The base URL of the link for the specified signer/observer/approver. To complete the 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. For business processes with a sequence defined, the client should send out the links in the same sequence (even though Dedoco enforces that signers and approvers must act according to their sequence numbers) and make sure that the appended URL retrieves the latest pdf with signatures (if any). For business processes without a sequence defined, the client can send out the links to all the signers and approvers 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 and approvers will receive the right pdf for signing or approving. Links for observers, on the other hand, can be sent out at any time without waiting for the signers and approvers to act.

Sample request header:

POST https://api.stage.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": "6d0b4a52c986d6511bd74b2e32d2f9c024e6ad2839a91734e2bf2ae89f93307a",
  "parent_folder": "620a08c38b2cd7001e0bfdad",
  "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": "+6521345678",
        "sequence_number": 0,
        "esignatures": [
          {
            "placement": {
              "page": 1,
              "x": "0.5",
              "y": "0.5"
            },
            "dimensions": {
              "width": "0.01",
              "height": "0.005"
            }
          }
        ],
        "digi_signatures": [],
        "custom_texts": []
      }
    ],
    "observers": [
      {
        "email": "gordonlieu@gmail.com",
        "name": "Gordon Lieu",
        "phone": "+6543216587"
      }
    ],
    "approvers": [
      {
        "approver_email": "samanthatay@gmail.com",
        "approver_name": "Samantha Tay",
        "approver_phone": "+6520304050",
        "sequence_number": 0
      }
    ],
    "completion_requirement": {
      "min_number": 2
    }
  }
}

Sample response header:

Sample Response:
HTTP/1.1 201 Created

Sample response body:

{
  "document": {
    "id": "620a0e238b2cd7001e0bfdc4",
    "name": "sample_pdf",
    "file_type": "pdf",
    "date_created": "2021-03-22T04:34:41.000Z",
    "document_hashes": [
      "6d0b4a52c986d6511bd74b2e32d2f9c024e6ad2839a91734e2bf2ae89f93307a"
    ],
    "business_processes": ["620a0e238b2cd7001e0bfdc5"],
    "status": "active",
    "parent_folder": "620a08c38b2cd7001e0bfdad",
    "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": "0xf5ec5bcb272c93eeebed77d33a6d1cb2278203352d91f42148f93b54b3c9e5ae"
      },
      {
        "action": "add Business Process (Signature) with id: 620a0e238b2cd7001e0bfdc5",
        "actor": {
          "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
          "email": "jimmylee@gmail.com",
          "name": "Jim Lee"
        },
        "timestamp": "2021-03-22T04:34:41.000Z",
        "transaction_hash": "0xe835148701b13da0c8ed3d20d9737912a099b5d54e168d38447a800321b39941"
      }
    ]
  },
  "businessProcess": {
    "id": "620a0e238b2cd7001e0bfdc5",
    "type": "signature",
    "date_created": "2021-03-22T04:34:41.000Z",
    "expiration_time": "1970-01-01T00:00:00.000Z",
    "document_id": "620a0e238b2cd7001e0bfdc4",
    "allow_download": true,
    "signers": [
      {
        "has_signed": false,
        "signer_id": "d2772c44-2f59-449f-b01c-77f0faa20d6b",
        "signer_name": "Alicia Macaron",
        "signer_email": "alicia@gmail.com",
        "signer_phone": "+6521345678",
        "sequence_number": 0,
        "esignatures": [
          {
            "placement": {
              "page": 1,
              "x": "0.5",
              "y": "0.5"
            },
            "dimensions": {
              "width": "0.01",
              "height": "0.005"
            }
          }
        ],
        "digi_signatures": [],
        "custom_texts": [],
        "confirmations": []
      }
    ],
    "observers": [
      {
        "id": "a2380231-8e70-4ed7-991e-59f23f80fda6",
        "email": "gordonlieu@gmail.com",
        "name": "Gordon Lieu",
        "phone": "+6543216587"
      }
    ],
    "approvers": [
      {
        "has_approved": false,
        "has_declined": false,
        "approver_id": "b77780ca-515d-46cc-9d6a-99821fa19059",
        "approver_email": "samanthatay@gmail.com",
        "approver_name": "Samantha Tay",
        "approver_phone": "+6520304050",
        "sequence_number": 0
      }
    ],
    "sequential_requirement": [],
    "completion_requirement": {
      "min_number": 2,
      "overriding_signers": []
    },
    "status": "pending",
    "history": [
      {
        "action": "Document Sent Out for Signing",
        "actor": {
          "id": "8b222cbb-06e3-4f9b-b79c-08cac27e8faa",
          "email": "jimmylee@gmail.com",
          "name": "Jim Lee"
        },
        "timestamp": "2021-03-22T04:34:41.000Z",
        "transaction_hash": "0xe835148701b13da0c8ed3d20d9737912a099b5d54e168d38447a800321b39941"
      }
    ]
  },
  "links": [
    {
      "documentId": "620a0e238b2cd7001e0bfdc4",
      "documentName": "sample_pdf",
      "businessProcessId": "620a0e238b2cd7001e0bfdc5",
      "signerId": "d2772c44-2f59-449f-b01c-77f0faa20d6b",
      "signerName": "Alicia Macaron",
      "signerEmail": "alicia@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/sign/620a0e238b2cd7001e0bfdc5/d2772c44-2f59-449f-b01c-77f0faa20d6b"
    },
    {
      "documentId": "620a0e238b2cd7001e0bfdc4",
      "documentName": "sample_pdf",
      "businessProcessId": "620a0e238b2cd7001e0bfdc5",
      "observerId": "a2380231-8e70-4ed7-991e-59f23f80fda6",
      "observerName": "Gordon Lieu",
      "observerEmail": "gordonlieu@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/observe/620a0e238b2cd7001e0bfdc5/a2380231-8e70-4ed7-991e-59f23f80fda6"
    },
    {
      "documentId": "620a0e238b2cd7001e0bfdc4",
      "documentName": "sample_pdf",
      "businessProcessId": "620a0e238b2cd7001e0bfdc5",
      "approverId": "b77780ca-515d-46cc-9d6a-99821fa19059",
      "approverName": "Samantha Tay",
      "approverEmail": "samanthatay@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/approve/620a0e238b2cd7001e0bfdc5/b77780ca-515d-46cc-9d6a-99821fa19059"
    }
  ]
}

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
}

  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • error is a string describing the type of error.

Response body for code 5xx:

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

  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • 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://api.stage.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:

{}

G. 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,
    "signer_nric": optional string,
    "sequence_number": number,
    "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
    }[]
}

An observers object:

{
    "id": string,
    "name": string,
    "email": string,
    "phone": string
}

An approvers object:

{
    "approver_id": string,
    "approver_email": string,
    "approver_name": string,
    "approver_phone": string,
    "sequence_number": number,
    "has_approved": boolean,
    "has_declined": boolean
}

A sequential_requirement object:

{
    "sequence_number": number,
    ["signer" | "approver"]: {
        ["signer" | "approver"]"_id": string,
        ["signer" | "approver"]"_name": string,
        ["signer" | "approver"]"_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.
observers object[] Array of objects. The structure of an object is given on the right.
approvers object[] Array of objects. The structure of an object is given on the right.
sequential_requirement object[] Array of objects. The structure of an object is given on the right.
Each signer or approver is only given one sequence number. Signers and approvers are only allowed to act after those with a lower sequence number have signed or approved. Only applicable to 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.
signers.signer_name string Name of the signer.
signers.signer_email string Email address of the signer.
signers.signer_phone string Phone number of the signer.
signers.signer_nric string Optional field. Last 4 characters of Signer's Singapore NRIC/FIN. Provide this field if signer is expected to Sign with Singpass that matches the given partial NRIC/FIN
signers.sequence_number number Sequence number of the signer if the business process requires signers and approvers to act 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.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 con t
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 contai n
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 Only “ndi” is accepted here. NDI refers to Sign with Singpass.
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 wi t
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 withi n
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” and "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 "initials" is used, users are allowed to draw or type out their initials.
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 l e
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
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 at which the custom text was received by Dedoco API.
observers.id string Identifier of the observer.
observers.name string Name of the observer.
observers.email string Email address of the observer.
observers.phone string Phone number of the observer.
approvers.approver_id string Identifier of the approver.
approvers.approver_name string Name of the approver.
approvers.approver_email string Email address of the approver.
approvers.approver_phone string Phone number of the approver.
approvers.sequence_number number Sequence number of the approver if the business process requires signers and approvers to act in a sequence. Starts from 1. 0 is used if there is no sequence.
approvers.has_approved boolean Boolean indicating whether or not the approver has approved the document for the business process.
approvers.has_declined boolean Boolean indicating whether or not the approver has declined the document for the business process.
sequential_requirement.sequence_number number Sequence number of the signer or approver listed within the object. Starts from 1.
sequential_requirement.[signer | approver]
.[signer_id | approver_id]
string Id of the signer or approver.
sequential_requirement.[signer | approver]
.[signer_name | approver_name]
string Name of the signer or approver.
sequential_requirement.[signer | approver]
.[signer_email | approver_email]
string Email address of the signer or approver.
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.

Endpoint: Get Business Process

GET /public/business-processes/{business_process_id} HTTP/1.1
Gets details of 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 details for. Required

Responses:

Response body for code 200:

{
    "id": string,
    "type": string,
    "dateCreated": number,
    "expirationTime": number,
    "documentId": string,
    "signers": {
        "id": string,
        "name": string,
        "email": string,
        "phone": string,
        "nric": string,
        "sequenceNumber": number,
        "hasSigned": boolean,
        "requireAuthentication": boolean,
        "verifyMethod": string,
        "signedTime": number,
        "customTexts": {
            "placement": {
                "page": number,
                "x": string,
                "y": string
            },
            "dimensions": {
                "width": string,
                "height": string
            },
            "type": string,
            "descriptor": string,
            "isMandatory": boolean,
            "value": string
        },
        "signatures": {
            "placement": {
                "page": number,
                "x": string,
                "y": string
            },
            "dimensions": {
                "width": string,
                "height": string
            },
            "type": "electronic" | "digital",
            "value": string
        }
    }[],
    "observers": {
      "id": string,
      "name": string,
      "email": string,
      "phone": string,
      "requireAuthentication": boolean,
      "verifyMethod": string
    }[],
    "approvers": {
      "id": string,
      "email": string,
      "name": string,
      "phone": string,
      "sequenceNumber": number,
      "hasApproved": boolean,
      "hasDeclined": boolean
    }[],
    "status": string
}

Response body for code 4xx:

{
    "statusCode": number,
    "message": string,
    "error": string
}
  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • error is a string describing the type of error.

Response body for code 5xx:

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

  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • error is a string describing the type of error.
Code Description
200 Business process details 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.
Child Attribute Type Description
id string Id of the business process retrieved.
type string Type of the business process. Only “signature” exists at the moment.
dateCreated number Unix time the business process was created.
expirationTime number Unix time by which the business process will expire. 0 indicates that the business process does not expire.
documentId string Id of the document the business process is attached to.
signers object[] Array of objects each representing a signer.
signers
.id
string Id of the signer.
signers
.name
string Name of the signer.
signers
.email
string Email address of the signer.
signers
.phone
string Phone number of the signer.
signers
.signer_nric
string Last 4 characters of the signer's Singapore NRIC/FIN.
signers
.sequenceNumber
number Sequence number of the signer if the business process requires signers and approvers to act in a sequence. Starts from 1. 0 is used if there is no sequence.
signers
.hasSigned
boolean Boolean indicating whether or not the signer has signed.
signers
.requireAuthentication
boolean Boolean indicating whether or not the signer requires to be authenticated.
signers
.verifyMethod
string String describing the mode of authentication. Possible values are "SMS", "EMAIL" and "NO_AUTHENTICATION".
signers
.signedTime
number Unix time the signer signed.
signers
.customTexts
object[] Array of objects each representing a custom text.
signers
.customTexts.placement
object Object containing information on where the custom text is placed on the file.
signers
.customTexts.placement.page
number Page number of the page on which the custom text is placed. Starts from 1.
signers
.customTexts.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.
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
.customTexts.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.
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
.customTexts.dimensions
object Object containing information on the size of the custom text on the file.
signers
.customTexts.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.
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
.customTexts.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.
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
.customTexts.descriptor
string Brief description of custom text.
signers
.customTexts.type
string String indicating the type of custom text. Possible values are “text”, “custom-date”, “actual-date” and "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 "initials" is used, users are allowed to draw or upload their initials.
signers
.customTexts.isMandatory
boolean Boolean indicating whether or not filling in the custom text is mandatory.
signers
.customTexts.value
string Value of custom text filled in by the signer.
signers
.signatures
object[] Array of objects each representing a signature.
signers
.signatures.placement
object Object containing information on where the signature is placed on the file.
signers
.signatures.placement.page
number Page number of the page on which the signature is placed. Starts from 1.
signers
.signatures.placement.x
string Float string which indicates the horizontal distance the top left corner of the 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.
Minimum represented float value is 0 and maximum represented float value (depends on the width of the signature box for the entire signature box to be contained within the page) is strictly less than 1.
signers
.signatures.placement.y
string Float string which indicates the vertical distance the top left corner of the 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.
Minimum represented float value is 0 and maximum represented float value (depends on the height of the signature box for the entire signature box to be contained within the page) is strictly less than 1.
signers
.signatures.dimensions
object Object containing information on the size of the signature on the file.
signers
.signatures.dimensions.width
string Float string which indicates the width of the signature box. The represented float value is a fraction (in decimal form) whose denominator is the width of the page.
Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the x-coordinate of the 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 signatures are displayed in a fixed height:width ratio (1:2 specifically) using signers.signatures.dimensions.height as reference.
signers
.signatures.dimensions.height
string Float string which indicates the height of the signature box. The represented float value is a fraction (in decimal form) whose denominator is the height of the page.
Minimum represented float value is strictly more than 0 and maximum represented float value (depends on the y-coordinate of the signature box for the entire signature box to be contained within the page) is less than 1.
signers
.signatures.type
string Type of signature. Values could be “electronic” or “digital”.
signers
.signatures.value
string The signature of the signer.
observers object[] Array of objects each representing an observer.
observers
.id
string Id of the observer.
observers.
name
string Name of the observer.
observers
.email
string Email address of the observer.
observers
.phone
string Phone number of the observer.
observers
.requireAuthentication
boolean Boolean indicating whether or not the observer requires to be authenticated.
observers
.verifyMethod
string String describing the mode of authentication. Possible values are "SMS", "EMAIL" and "NO_AUTHENTICATION".
approvers
.id
string Id of the approver.
approvers
.name
string Name of the approver.
approvers
.email
string Email address of the approver.
approvers
.phone
string Phone number of the approver.
approvers
.sequenceNumber
number Sequence number of the approver if the business process requires signers and approvers to act in a sequence. Starts from 1. 0 is used if there is no sequence.
approvers
.hasApproved
boolean Boolean indicating whether or not the approver has approved the document for the business process.
approvers.
hasDeclined
boolean Boolean indicating whether or not the approver has declined the document for the business process.
status string Current status of the business process. Possible values are "pending", "completed", "expired" and "voided".

Sample Request Header:

GET https://api.stage.dedoco.com/api/v1/public/business-processes/63118fb676c35a63f7f5da64 HTTP/1.1
Authorization: Bearer <token>

Sample Request Body:

{}

Sample Response Header:

HTTP/1.1 200 OK

Sample Response Body:

{
  "id": "63118fb676c35a63f7f5da64",
  "type": "signature",
  "dateCreated": 1616383852,
  "expirationTime": 0,
  "documentId": "63118fb676c35a63f7f5da63",
  "signers": [
    {
      "id": "e31a0fa5-40bb-4edd-bf49-16c9f1606c8d",
      "name": "Alice Tan",
      "email": "alice@gmail.com",
      "phone": "+6591234567",
      "sequenceNumber": 0,
      "hasSigned": true,
      "requireAuthentication": false,
      "signedTime": 1662095335,
      "customTexts": [
        {
          "placement": {
            "page": 1,
            "x": "0.123",
            "y": "0.123"
          },
          "dimensions": {
            "width": "0.1",
            "height": "0.05"
          },
          "type": "text",
          "descriptor": "NRIC",
          "isMandatory": true,
          "value": "S1234567D"
        }
      ],
      "signatures": [
        {
          "placement": {
            "page": 1,
            "x": "0.5",
            "y": "0.5"
          },
          "dimensions": {
            "width": "0.1",
            "height": "0.05"
          },
          "type": "electronic",
          "value": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA..."
        }
      ]
    }
  ],
  "observers": [],
  "approvers": [],
  "status": "completed"
}

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,
        ["signer" | "observer" | "approver"]"Id": string,
        ["signer" | "observer" | "approver"]"Name": string,
        ["signer" | "observer" | "approver"]"Email": string,
        "link": string
    }[]
}

Response body for code 4xx:

{
    "statusCode": number,
    "message": string,
    "error": string
}
  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • error is a string describing the type of error.

Response body for code 5xx:

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

  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • 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.
Child Attribute Type Description
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 links for each signer/observer/approver 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.[signer | observer | approver]Id string Id of the signer/observer/approver the link attribute in the same object is for.
links.[signer | observer | approver]Name string Name of the signer/observer/approver the link attribute in the same object is for.
links.[signer | observer | approver]Email string Email of the signer/observer/approver the link attribute in the same object is for.
links.link string The base URL of the link for the specified signer/observer/approver. To complete the 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. For business processes with a sequence defined, the client should send out the links in the same sequence (even though Dedoco enforces that signers and approvers must act according to their sequence numbers) and make sure that the appended URL retrieves the latest pdf with signatures (if any). For business processes without a sequence defined, the client can send out the links to all the signers and approvers 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 and approvers will receive the right pdf for signing or approving. Links for observers, on the other hand, can be sent out at any time without waiting for the signers and approvers to act.

Sample Request Header:

GET https://api.stage.dedoco.com/api/v1/public/business-processes/620a0e238b2cd7001e0bfdc5/links HTTP/1.1
Authorization: Bearer <token>

Sample Request Body:

{}

Sample Response Header:

HTTP/1.1 200 OK

Sample Response Body:

{
  "links": [
    {
      "documentId": "620a0e238b2cd7001e0bfdc4",
      "documentName": "sample_pdf",
      "businessProcessId": "620a0e238b2cd7001e0bfdc5",
      "signerId": "d2772c44-2f59-449f-b01c-77f0faa20d6b",
      "signerName": "Alicia Macaron",
      "signerEmail": "alicia@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/sign/620a0e238b2cd7001e0bfdc5/d2772c44-2f59-449f-b01c-77f0faa20d6b"
    },
    {
      "documentId": "620a0e238b2cd7001e0bfdc4",
      "documentName": "sample_pdf",
      "businessProcessId": "620a0e238b2cd7001e0bfdc5",
      "observerId": "a2380231-8e70-4ed7-991e-59f23f80fda6",
      "observerName": "Gordon Lieu",
      "observerEmail": "gordonlieu@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/observe/620a0e238b2cd7001e0bfdc5/a2380231-8e70-4ed7-991e-59f23f80fda6"
    },
    {
      "documentId": "620a0e238b2cd7001e0bfdc4",
      "documentName": "sample_pdf",
      "businessProcessId": "620a0e238b2cd7001e0bfdc5",
      "approverId": "b77780ca-515d-46cc-9d6a-99821fa19059",
      "approverName": "Samantha Tay",
      "approverEmail": "samanthatay@gmail.com",
      "link": "https://sign.stage.dedoco.com/public/approve/620a0e238b2cd7001e0bfdc5/b77780ca-515d-46cc-9d6a-99821fa19059"
    }
  ]
}

H. 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_id": string,
        "signer_email": string,
        "signer_name": string,
        "signer_phone": string,
        "sequence_number": number,
        "has_signed": boolean,
        "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
          }
        }[]
      }[],
      "observers": {
        "id": string,
        "email": string,
        "name": string,
        "phone": number
      }[],
      "approvers": {
        "approver_id": string,
        "approver_email": string,
        "approver_name": string,
        "approver_phone": string,
        "sequence_number": number,
        "has_approved": boolean,
        "has_declined": boolean
      }[],
      "sequential_requirement": {
        "sequence_number": number,
        ["signer" | "approver"]: {
            ["signer" | "approver"]"_id": string,
            ["signer" | "approver"]"_name": string,
            ["signer" | "approver"]"_email": string
        }
      }[],
      "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
      }[]
  }
}[]

  • 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.
  • 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
}
  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • error is a string describing the type of error.

Response body for code 5xx:

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

  • statusCode is the status code of the error.
  • message is a string describing the cause of error.
  • 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://api.stage.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"
      ],
      "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"
        }
      ]
    }
  }
]

I. Text Tags

When creating a project, the project creator may find it difficult to determine the values in the placement object for each field in business_processes.signers. (observers and approvers are not affected by text tags.)

With text tags, it is possible to let the API figure out the placement.

By placing reserved texts (AKA text tags) in the PDF, the placement values can be determined from the positions of those texts.

For example, if we want to position an E-signature field, we can add a text tag:

Alt text

The position of the text tags will be used to create the placement object. When the signer opens the signing page, the field will show at the correct position as illustrated below.

Alt text

Note that the text tag is left in the image for illustration purposes only. In actual signing, the Open API client should host a file that does not contain any text tags to allow the signing page to download.

IMPORTANT: Maintain 2 copies of the document

1) Original document without text tags: This copy is used to generate the document hash when creating a project. See Using Text Tags To Create Project. The base64 string received by the signers during signing is also generated using this copy of the document (e.g. {"file": "base64 string of document without text tags"})

2) Original document with text tags: This copy is used to determine the coordinates of signatures and custom texts. See Using Text Tags To Create Project

Available Text Tags

Text Tags Description
\esig_<id>\ E-Signature (esignatures)
\spsign_<id>\ SingPass signature (digi_signatures type : ndi)
\initials_<id>\ Initials (custom_texts type: initials)
\dnow_<id>\ Actual date (custom_texts type: actual-date)
\date_<id>\ Custom date (custom_texts type: custom-date)
\text_<id>\ Custom text (custom_texts type: text)

Signer ID <id>

The <id> field is the signer ID. It can be any positive non-zero integer. Text tags with the same signer ID belong to the same signer.

For example, \esig_1\ and \initials_1\ belongs to the same signer while \esig_1\ and \esig_2\ belongs to different signers.

The signer ID will be assigned to signers in an ascending order.

For example, if there are 2 signers in the business process,

Note that for convenience, the text tags signer IDs do not have to be consecutive. For example, if there are signer IDs 2, 5 and 8 in the document and there are 3 signers,

Using Text Tags To Create Projects

{
  "folder_name": "Test Folder",
  "date_created": 1616383852,
  "documents": [
    {
      "name": "sample_pdf",
      "file_type": "pdf",
      // Document with text tags
      "text_tagged_doc_base64": "JVBERi0xLjcKJb/3ov4KMSAwIG9i...",
      // Or provide the document download URL
      // If both are provided, URL will be ignored.
      "text_tagged_doc_url": "https://file-server.com/file-with-text-tags",
      // This hash is the hash of the document without text tags.
      "document_hash": "a3c124f1ae5d1e57a4a646512ca0471710e092ef0a39aa3a740da5447bcde237"
    }
  ],
  "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,
          "esignatures": [
            {
              // Placement is removed from the payload, to be determined by text tags.
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "digi_signatures": [],
          "custom_texts": [
            {
              "type": "text",
              "descriptor": "Name",
              "is_mandatory": true,
              // Placement is removed from the payload, to be determined by text tags.
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            },
            {
              "type": "text",
              "descriptor": "NRIC",
              "is_mandatory": true,
              // Placement is removed from the payload, to be determined by text tags.
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            },
            {
              "type": "initials",
              "descriptor": "Initials",
              "is_mandatory": true,
              // Placement is specified, text tag will have no effect.
              "placement": {
                "page": 1,
                "x": "0.6",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ]
        },
        {
          "signer_email": "bobbychia@gmail.com",
          "signer_name": "Bobby Chia",
          "signer_phone": "+6581234567",
          "sequence_number": 2,
          "esignatures": [
            {
              // Placement is specified, text tag will have no effect.
              "placement": {
                "page": 1,
                "x": "0.6",
                "y": "0.5"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.005"
              }
            }
          ],
          "digi_signatures": [],
          "custom_texts": [
            {
              "type": "text",
              "descriptor": "NRIC",
              "is_mandatory": true,
              // Placement is specified, text tag will have no effect.
              "placement": {
                "page": 1,
                "x": "0.223",
                "y": "0.223"
              },
              "dimensions": {
                "width": "0.01",
                "height": "0.05"
              }
            }
          ]
        }
      ],
      "observers": [],
      "approvers": [],
      "completion_requirement": {
        "min_number": 3
      }
    }
  ]
}

Let's take the folder creation payload on the right as an example.

In the payload we see that for Alice (the first signer) there are 4 fields:

and for Bobby (the second signer) there are 2 fields:

Since we need all fields to have placement, the missing placement information for Alice must be provided through text tags.

This means that the document that corresponds to the business process must specify either text_tagged_doc_base64 or text_tagged_doc_url to provide the file to the Open API service. If text_tagged_doc_url is used, make sure the endpoint serves the binary of the file. (i.e. Our server should receive the file bytes when a GET request is sent to the text_tagged_doc_url endpoint.)

In this case, the text_tagged_doc_base64 is provided.

Suppose we assign a text tag signer ID 1 to Alice and 2 to Bobby, the document provided through text_tagged_doc_base64 must have at least 1 \esig_1\ text tag and 2 \text_1\ text tags to provide the missing placement details.

If there are insufficient text tags in the document, the project creation will fail.

Repeated Text Tags

In our example, there are 2 repeated text tags for the text field. The Open API service will match the order of the text field in the payload to the order of the \text_1\ text tags in the document.

Text tags that appear higher in the document will be picked up first. If 2 text tags are on the same line, the one that is more to the left will be picked up first.

Extra Text Tags

Any extra text tags present in the document that is not assigned to any signer or field will be ignore.