> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/sign/digital-signature/directsign-api/api-reference/create-envelope/create-and-start-envelope-with-vsp-template.md).

# 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.

{% hint style="info" %}
VSP Template endpoint executes both creating & starting envelope operation. You do not need to run [Start Envelope Signature](broken://pages/2NBkWBiaj1C8uYXEYIMt) endpoint
{% endhint %}

***

### API Endpoint

<mark style="color:green;">`POST`</mark>` ``{environment-url}/core/external-api/rest/v1/template/{template_id}/start-signature`

***

### Headers

<table><thead><tr><th width="192">Name</th><th width="120">Type</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type<mark style="color:red;">*</mark></td><td>String</td><td>application/json</td></tr><tr><td>Authorization<mark style="color:red;">*</mark></td><td>String</td><td><p>Bearer Access Token<br></p><p>Get the access token by calling the</p><p><a href="/pages/XOKnwALziwtzopCd8Bb1#api-description"><strong>Authentication</strong></a> API</p></td></tr></tbody></table>

#### Path Parameters

<table><thead><tr><th width="193">Name</th><th width="125">Type</th><th>Description</th></tr></thead><tbody><tr><td>template_id<mark style="color:red;">*</mark></td><td>UUID</td><td>The template Id generated during the <a href="#digital-sign-creation"><strong>Digital Sign Creation</strong></a> process</td></tr></tbody></table>

***

### Request Body

```json
{
	"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

<table><thead><tr><th width="223">Name</th><th width="176">Type</th><th>Description</th></tr></thead><tbody><tr><td>creator_email<mark style="color:red;">*</mark></td><td>String </td><td>Assign envelope to your member (email must be a registered member under the workspace)</td></tr><tr><td>signature_type<mark style="color:red;">*</mark></td><td>String</td><td>The technology in which document  need to be signed. <br>* <code>DIGITAL</code> <br>* <code>ESIGN</code><br><br>Refer to <a href="/pages/9YHIZIPcURKmgL7xGJIV#signature-type-enum">Signature Type Enum</a> Table</td></tr><tr><td>direct_sign<mark style="color:red;">*</mark></td><td>Boolean</td><td><p>Set this field to <code>true</code></p><p></p><p>To enable direct sign mode, you must fill in field <code>recipients.kyc_event_id</code></p></td></tr><tr><td>preview</td><td>Boolean</td><td><p>When set to <code>true</code>, signer can preview the document and signing field before doing authentication.</p><p></p><p>When set to <code>false</code>, signer will only do authentication<br>(Default value: <code>true</code>)</p></td></tr><tr><td>notify_email</td><td>Boolean</td><td><p>When set to <code>true</code>, a set of email notifications will be sent to the recipient email address. </p><p></p><p>When set to <code>false</code>, only a successful signature usage email will be sent to the recipient email address.</p><p></p><p>(Default value: <code>true</code>)</p></td></tr><tr><td>placeholders<mark style="color:red;">*</mark></td><td>Array</td><td></td></tr><tr><td><ul><li>placeholders[0].placeholder<mark style="color:red;">*</mark></li></ul></td><td>String</td><td>The placeholder name you used during VSP template creation.</td></tr><tr><td><ul><li>placeholders[0].recipient_kyc_event_id</li></ul></td><td>String</td><td><p>The <code>kyc_event_id</code> retrieved from a successful verification by VIDA.</p><p></p><p>Ensure that you only use a valid event ID.</p></td></tr><tr><td><ul><li>placeholders[0].recipient_email<mark style="color:red;">*</mark></li></ul></td><td>String</td><td>The recipient's email address, length limit(1-255)</td></tr><tr><td><ul><li>placeholders[0].recipient_name<mark style="color:red;">*</mark></li></ul></td><td>String</td><td>The recipient's name, length limit(1-255)</td></tr><tr><td>fields<mark style="color:red;">*</mark></td><td>Array</td><td></td></tr><tr><td><ul><li>fields[0].type<mark style="color:red;">*</mark></li></ul></td><td>String</td><td><code>Textbox, Recipient_Textbox</code></td></tr><tr><td><ul><li>fields[0].name<mark style="color:red;">*</mark></li></ul></td><td>String</td><td>The textbox field name,<br>(You can copy from VSP template list page) <br>Eg : "textbox-drag1"</td></tr><tr><td><ul><li>fields[0].value<mark style="color:red;">*</mark></li></ul></td><td>String</td><td>The textbox content</td></tr></tbody></table>

***

### Response Body

#### Envelope Created Successfully

HTTP Status Code: `200`

Status : `SUCCESS`

```json
{
    "success": true,
    "data": {
        "envelope_id": "{uuid}",
        "envelope_status": "PENDING",
        "signature_links": [
            {
                "email": "example1@email.com",
                "signature_link": "https://sign.vida.id/signEnvelope/{code}"
            },
            {
                "email": "example2@email.com",
                "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`

```json
{
    "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`

```json
{
    "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`

```json
{
    "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`

```json
{
    "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`

```json
{
    "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`

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

#### Bad Request - Invalid Data

HTTP Status Code: `400`

Status : `ERROR`

```json
{
    "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`

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