Create Envelope

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

API Endpoint

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

---

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	You can directly pass a single PDF to create an envelope (max 50 MB, 500 pages).
document_ids	Array	You can use multiple document_id to create an envelope (up to 10 are supported) Use a separate document upload endpoint to upload the file and obtain the document_id.
creator_email*	String	Assign envelope to your member (email must be a registered member under the workspace)
envelope_details*	JSON String	This is payload

Name	Type	Description
envelope_name*	String	The envelope display name , length limit(1-255)
sign_order_type*	String	SERIAL : The signing will follow a set of order specified in recipients[0].order. The next signer will receive their turn to sign only if the current signer has finished signing. PARALLEL: The signing will be done in parallel for all recipients Default value: PARALLEL
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
remind_interval_day	Int	The service will send a reminder email to the signer at the specified interval if the signature is not completed. Minimum value: 0 Maximum value: 90 Default value: 0 (No reminder email will be sent) Value of 1: Reminder sent every day Value of 2: Reminder sent every 2 days
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*	Array
recipients[0].email*	String	The recipient's email address, length limit(1-255)
recipients[0].order*	Int	The recipient will receive the email to sign the document in this chronological order, with a numerical value starting from 1.
recipients[0].name*	String	The recipient's name, length limit(1-255)
fields*	Array
fields[0].type*	String	VSP Open API supports placement for Signature, QR, E-Meterai Refer to Field Type enum table
fields[0].x	Int	The X pixel coordinate of the field in the document x=0 starts at the left-side of document
fields[0].y	Int	The Y pixel coordinate of the field in the document y=0 starts at the top-side of document
fields[0].height	Int	The width of the signature field, in other words: X2 coordinate
fields[0].width	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.
fields[0].emeterai_doc_type	String	Required for fields[0].type = E-Meterai Refer to

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
E-Meterai	You can add an E-Meterai field to the document. The eMeterai stamping process starts when Start Signature API is hit, & that the stamping is asynchronous. Set up a webhook to get a real-time status update. Note: eMeterai size is fixed at 100x100px. When using eMeterai as field type, you do not need to specify fields[0].recipient_email

Signature Type Enum

DIGITAL	DIGITAL refers 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.

---

Response Body

Envelope Created Successfully

HTTP Status Code: 200

Status : SUCCESS

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

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_ids` [%s] does 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 - 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 E-Meterai field must only one

The E-Meterai field must only one.

HTTP Status Code: 400

Status : ERROR

{
    "code":"ER.10112",
    "message":"The E-Meterai field must only one"
}

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 - e-Meterai quota exceeded

e-Meterai balance quota is exceeded and needs top up.

HTTP Status Code: 400

Status : ERROR

{
    "code":"RE.205",
    "message":"Insufficient e-Meterai balance. Please top up or contact [e-mail] for more info."
}