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):

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"
}

Endpoint: Get Request Links

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.

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,

Text tags with signer ID 1 will be assigned to the first signer
Text tags with signer ID 2 will be assigned to the second signer

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,

Text tags with signer ID 2 will be assigned to the first signer
Text tags with signer ID 5 will be assigned to the second signer
Text tags with signer ID 8 will be assigned to the third signer

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:

1 E-Signature (No placement)
2 text fields (No placement)
1 initials field (placement is provided)

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

1 E-Signature (placement is provided)
1 text field (placement is provided)

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.

Introduction

Version History

A. API Developer Account

B. Sequence Diagram

C. Environments

Stage

Prod

D. Authentication

JWT Payload

Endpoint: Get JWT Token

E. Folders

Folder Attributes

Endpoint: Create Folder

F. Documents

Document Attributes

Endpoint: Add Document

Endpoint: Void Document

G. Business Processes

Business Process Attributes

Endpoint: Get Business Process

Endpoint: Get Request Links

H. Verification

Endpoint: Verify Own Document

I. Text Tags

IMPORTANT: Maintain 2 copies of the document

Available Text Tags

Signer ID <id>

Using Text Tags To Create Projects

Signer ID `<id>`