Create Envelope with Document Upload

The DirectSign API enables clients to initiate a signing request by creating an envelope with specified documents, recipients, and other requirements.

---

API Endpoint

If Signer is verified by VIDA

POST {environment-url}/core/external-api/rest/v1/envelope

If Signer is not verified by VIDA

POST {environment-url}/core/external-api/rest/v1/envelope/ra *

To use /ra endpoint, the client has to undergo Registration Authority assessment. Please contact VIDA team for more detail

Headers

Name	Type	Description
Content-Type*	String	multipart/form-data
Authorization*	String	Bearer Access Token Get the access token by calling the Authentication API

---

Request Body

Name	Type	Description
file	File	Use this field to send only 1 document per envelope. You can directly pass a single PDF to create an envelope (max 50 MB, 500 pages).
document_ids	Array	Use this field to send >1 document per envelope. You can use up to 10 document_id inside an envelope To obtain multiple document ID, Use a separate document upload endpoint.
creator_email*	String	Assign envelope to your member (email must be a registered member under the workspace).
envelope_details*	JSON String	This is a nested JSON. Please refer to envelope_details section below.

envelope_details

Name	Type	Description
envelope_name*	String	The envelope display name , length limit(1-255)
direct_sign*	Boolean	Set this field to true To enable direct sign mode, you must fill in field recipients.kyc_event_id
preview	Boolean	When set to true, signer can preview the document and signing field before doing authentication. When set to false, signer will only do authentication (Default value: true)
notify_email	Boolean	When set to true, a set of email notifications will be sent to the recipient email address. When set to false, only a successful signature usage email will be sent to the recipient email address. (Default value: true)
signature_type	String	The certificate type in which document need to be signed. * DIGITAL * ESIGN Use DIGITAL as the value unless specified otherwise. Refer to (Signature Type Enum Table) Default value: DIGITAL
separate_document_sign	Boolean	This field is required if you send >1 document inside an envelope When set to true, the signed documents will be kept separated. When set to false, all of the signed documents will be merged into 1 document. Important: If your original document(s) have an existing digital signature, set this field to true to maintain the existing digital signature validity (Defailt value: true)
expiration_days	Int	Specify the number of days before the signature link expires. If the signature is not completed within the defined timeframe, the envelope status will be set to DECLINED. Minimum value: 1 Maximum value: 90 Default value: 90
recipients*
recipients.email*	String	The recipient's email address, length limit(1-255)
recipients.name*	String	The recipient's name, length limit(1-255)
recipients.kyc_event_id	String	The kyc_event_id retrieved from a successful verification by VIDA. Skip this field if you do not verify the signer with VIDA Ensure that you only use a valid event ID.
recipients.registration_id	String	The registration_id retrieved from a succesful registration, where the signer is not verified by VIDA Skip this field if you already verify the signer with VIDA Ensure that you only use a valid Registration ID.
fields*	Array
fields[0].type*	String	The type of field to add to the document: Signature QR Refer to Fields Type Enum
fields[0].document_id	String	Required if the envelope leverages Upload Document API. Specify which document ID that requires the signature field
fields[0].x	Int	The X point coordinate value of the field in the document x=0 starts at the left-side of document
fields[0].y	Int	The Y point coordinate value of the field in the document y=0 starts at the top-side of document
fields[0].width	Int	The width of the signature field, in other words: X2 coordinate
fields[0].height	Int	The height of the signature field, in other words: Y2 coordinate
fields[0].page_index	Int	The page index in which the signature field needs to be placed. Index starts from 1.
fields[0].recipient_email*	String	The signer email.

Signature Type Enum

Value	Description
DIGITAL	DIGITALrefers to signing document with the signer's valid certificate, issued by VIDA as an official PSrE (Penyelenggara Sertifikasi Elektronik) This ceritificate is only issued after a successful signer verification/KYC. This means the certificate is legally-binding and non-repudiatory. Use this value as default unless specified otherwise
ESIGN	ESIGN refers to signature without signer's valid ceriticate.

Field Type Enum

Value	Description
Signature	Signature refers to digital signature to be placed in the document.
QR	QR refers to QR code that can be scanned by anyone to view the envelope audit trail. Note: QR size should be in 1:1 ratio. When using QR as field type, you do not need to specify fields[0].recipient_email

---

Response Body

Envelope Created Successfully

HTTP Status Code: 200

Status : SUCCESS

{
    "success": true,
    "data": {
        "id": "{envelope_id}"
    }
}

Bad Request - Invalid KYC Event ID

Bad Request invalid kyc_event_id or no PSRE certificate.

HTTP Status Code: 400

Status : ERROR

{
    "message": "The `kyc_event_id`: %s is invalid.",
    "code": "AS.10780"
}

Bad Request - PDF Doesn't exist

Bad Request Incase of the PDF file

HTTP Status Code: 400

Status : ERROR

{
    "message": "File is empty.",
    "code": "ES.10508"
}

Bad Request - The Document Doesn't exist

Bad Request Incase if the document does not exist

HTTP Status Code: 400

Status : ERROR

{
    "code":"MG.10668",
    "message":"Document is not exist"
}

Bad Request - Large file size

Bad request Incase of large file size

HTTP Status Code: 400

Status : ERROR

{
    "code":"ES.10509",
    "message":"File upload too large"
}

Bad Request -Document count limit exceeded

Document count should not be more than 10.

HTTP Status Code: 400

Status : ERROR

{
    "code":"AS.10778",
    "message":"Document count should not be more than 10"
}

Bad Request - Unsupported file type

Bad request Incase of unsupported file size

HTTP Status Code: 400

Status : ERROR

{
    "code":"ES.10505",
    "message":"Unsupported file types."
}

Bad Request - recipient list cannot be empty

The envelope should contain at least one recipient.

HTTP Status Code: 400

Status : ERROR

{
    "code":"MG.10319",
    "message":"At least one recipient."
}

Bad Request - Signer count limit exceeded

Signer count should not be more than 1 in the direct sign.

HTTP Status Code: 400

Status : ERROR

{
    "code":"AS.10779",
    "message":"Signer count should not be more than 1 in the direct sign"
}

Bad Request - File page count limit exceeded

File page count should not exceed 500.

HTTP Status Code: 400

Status : ERROR

{
    "code":"ES.1053",
    "message":"File page count should not be more than 500"
}

Bad Request - The recipient email are duplicated

The recipient email should not be the same.

HTTP Status Code: 400

Status : ERROR

{
    "message": "Recipient email are duplicated",
    "code": "ER.10111"
}

Bad Request - Invalid Parameter

Incorrect JSON format on envelope_details .

HTTP Status Code: 400

Status : ERROR

{
    "message": "The value of `envelope_details` parsing failed",
    "code": "MG.10303"
}

Bad Request - Invalid Parameter

Incase of the field recipient_email is not defined in recipients.

HTTP Status Code: 400

Status : ERROR

{
    "message": "The `fields`.`recipient_email` is not defined in `recipients`",
    "code": "MG.10303"
}

Bad Request - Invalid Parameter

Incase of invalid parameter. (eg: creator_email)

HTTP Status Code: 400

Status : ERROR

{
    "message": "Please enter a valid email address",
    "code": "MG.10303"
}

Bad Request - Invalid Data

The envelope_details and envelope_name values are invalid.

HTTP Status Code: 400

Status : ERROR

{
    "message": "`envelope_details`.`envelope_name` length must be at least 1.",
    "code": "MG.10303"
}

Bad Request - Invalid Data

The envelope_details and envelope_name length must be less than 255 characters.

HTTP Status Code: 400

Status : ERROR

{
    "message": "`envelope_details`.`envelope_name`.`name` length must not exceed 255.",
    "code": "MG.10303"
}

Bad Request - Invalid Data

The envelope_details and recipients values are invalid.

HTTP Status Code: 400

Status : ERROR

{
    "message": "`envelope_details`.`recipients`.`name` length must not exceed 255.",
    "code": "MG.10303"
}

Bad Request - Invalid Data

Invalid page_index value. Page index must be greater than or equal to 1, with 1 representing the first page.

HTTP Status Code: 400

Status : ERROR

{
    "message": "Invalid `fields`.`page_index` value. Page index must be greater than or equal to 1, with 1 representing the first page",
    "code": "MG.10303"
}

Bad Request - Invalid Data

Invalid page_index value. Page index cannot exceed the total number of pages in file, with 1 representing the first page.

HTTP Status Code: 400

Status : ERROR

{
    "message": "The `fields`.`page_index` cannot exceed the total number of pages in file, with 1 representing the first page",
    "code": "MG.10303"
}

Bad Request - Invalid Parameter

The email id in the creator_email parameter is not the member of the workspace.

HTTP Status Code: 400

Status : ERROR

{
    "message": "The `creator_email` is not a member of the current workspace.",
    "code": "MG.20707"
}

Bad Request - Invalid Data

Invalid QR field height value. The value must same with width value.

HTTP Status Code: 400

{
    "message": "Invalid QR field `height` value. The value must same with `width` value.",
    "code": "MG.10303"
}

Bad Request - Invalid Registration ID Format

Invalid registration ID format check

HTTP Status Code: 400

{
    "message": "`recipients[<email>]`.`registration_id` length must be at least 1.",
    "code": "MG.10303",
}

Bad Request - Invalid Registration ID

Invalid registration ID

HTTP Status Code: 400

{
    "message": "The `registration_id`: <id> is invalid.",
    "code": "AS.10781",
}

RA Endpoint Access Unauthorized

Error message if the access to RA endpoint is not granted

HTTP Status Code: 400

{
    "message": "Your RA setting not support registration ID",
    "code": "AS.12002",
    "data": null
}