Create & Start Envelope with VSP Template

Template Creation

The template creation process involves designing a document template where signature and information fields can be dynamically filled by users.

Digital Sign

After setting up the template, you can generate a template_id by creating a digital signature session linked to this template. This template_id is essential for referencing the template in API requests that initiate the signing process.

Exported Payload for DirectSign API

The payload can be exported as JSON data structure, and can be sent to the DirectSign API to initialize the signing process for this template.

DirectSign API Call

The API handles document generation, field population, and initiating the signing workflow.

VSP Template endpoint executes both creating & starting envelope operation. You do not need to run Start Envelope Signature endpoint

---

API Endpoint

POST {environment-url}/core/external-api/rest/v1/template/{template_id}/start-signature

---

Headers

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

Path Parameters

Name	Type	Description
template_id*	UUID	The template Id generated during the Digital Sign Creation process

---

Request Body

{
	"creator_email":"{{creator_email}}",
	"direct_sign":true,
	"fields":[],
	"notify_email":false,
        "preview":false,
	"placeholders":[
		{
			"placeholder":"{{placeholder}}",
			"recipient_email":"{{recipient_email}}",
			"recipient_kyc_event_id":"{{kyc_event_id}}",
			"recipient_name":"{{recipient_name}}"
		}
	],
	"signature_type":"DIGITAL"
}

envelope_details

Name	Type	Description
creator_email*	String	Assign envelope to your member (email must be a registered member under the workspace)
signature_type*	String	The technology in which document need to be signed. * DIGITAL * ESIGN Refer to Signature Type Enum Table
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)
placeholders*	Array
placeholders[0].placeholder*	String	The placeholder name you used during VSP template creation.
placeholders[0].recipient_kyc_event_id	String	The kyc_event_id retrieved from a successful verification by VIDA. Ensure that you only use a valid event ID.
placeholders[0].recipient_email*	String	The recipient's email address, length limit(1-255)
placeholders[0].recipient_name*	String	The recipient's name, length limit(1-255)
fields*	Array
fields[0].type*	String	Textbox, Recipient_Textbox
fields[0].name*	String	The textbox field name, (You can copy from VSP template list page) Eg : "textbox-drag1"
fields[0].value*	String	The textbox content

---

Response Body

Envelope Created Successfully

HTTP Status Code: 200

Status : SUCCESS

{
    "success": true,
    "data": {
        "envelope_id": "{uuid}",
        "envelope_status": "PENDING",
        "signature_links": [
            {
                "email": "[e-mail]",
                "signature_link": "https://sign.vida.id/signEnvelope/{code}"
            },
            {
                "email": "[e-mail]",
                "signature_link": "https://sign.vida.id/signEnvelope/{code}"
            }
        ]
    }
}

Forbidden - Disbale Direct Sign Feature

You cannot use direct sign send endpoint

HTTP Status Code: 403

Status : ERROR

{
    "message": "You’re not allowed to send envelopes from DirectSign.",
    "code": "AS.11001"
}

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 - No Access to Create Envelope

Bad Request Incase the user does not have access to create envelope.

HTTP Status Code: 400

Status : ERROR

{
    "message": "User have not access to create envelope",
    "code": "AS.10519"
}

Bad Request - Invalid Parameter

Incase of invalid values for the parameter. (eg: placeholders)

HTTP Status Code: 400

Status : ERROR

{
    "message": "The `placeholders` does not match",
    "code": "MG.10303"
}

Bad Request - Invalid Data

Bad Request due to the invalid values for the fields .

HTTP Status Code: 400

Status : ERROR

{
    "message": "The `fields` does not match",
    "code": "MG.10303"
}

Bad Request - Invalid Data

The creator_email value is invalid.

HTTP Status Code: 400

Status : ERROR

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

Bad Request - Invalid Data

HTTP Status Code: 400

Status : ERROR

{
    "message": "Invalid envelope creator",
    "code": "MG.20707"
}

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