> 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/vsp-openapi/api-reference/create-envelope.md).

# Create Envelope

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

### API Endpoint

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

***

### Headers

<table><thead><tr><th>Name</th><th width="251">Type</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type<mark style="color:red;">*</mark></td><td>String</td><td>multipart/form-data</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>

***

### 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](broken://pages/X09XVwC9xhX6EaT7dmiK#api-description) endpoint to upload the file and obtain the document\_id. |
| creator\_email<mark style="color:red;">\*</mark>    | String      | Assign envelope to your member (email must be a registered member under the workspace)                                                                                                                                          |
| envelope\_details<mark style="color:red;">\*</mark> | JSON String | This is [payload](https://app.gitbook.com/o/HFo4Mq4hPbfFvhTREpfY/s/nMzCF4sPTjY3bXQjpH4P/~/changes/21/integration-methods/api/api-reference/envelope#envelope_details)                                                           |

<table><thead><tr><th width="230">Name</th><th width="118">Type</th><th>Description</th></tr></thead><tbody><tr><td>envelope_name<mark style="color:red;">*</mark></td><td>String</td><td>The envelope display name , length limit(1-255)</td></tr><tr><td>sign_order_type<mark style="color:red;">*</mark></td><td>String</td><td><p><br><code>SERIAL</code> : The signing will follow a set of order specified in <code>recipients[0].order</code>. The next signer will receive their turn to sign only if the current signer has finished signing.</p><p> </p><p><code>PARALLEL</code>: The signing will be done in parallel for all recipients<br><br>Default value: <code>PARALLEL</code></p></td></tr><tr><td>signature_type<mark style="color:red;">*</mark></td><td>String</td><td><p>The certificate type in which document need to be signed. <br>* <code>DIGITAL</code> <br>* <code>ESIGN</code></p><p></p><p>Use <code>DIGITAL</code> as the value unless specified otherwise.</p><p><br>Refer to (<a href="#signature-type-enum">Signature Type Enum</a> Table)<br><br>Default value: <code>DIGITAL</code></p></td></tr><tr><td>remind_interval_day</td><td>Int</td><td>The service will send a reminder email to the signer at the specified interval if the signature is not completed. <br><strong>Minimum value</strong>: 0 <br><strong>Maximum value</strong>: 90 <br>Defaul<strong>t value</strong>: 0 (No reminder email will be sent) <br><strong>Value of 1</strong>: Reminder sent every day <br><strong>Value of 2</strong>: Reminder sent every 2 days</td></tr><tr><td>separate_document_sign</td><td>Boolean</td><td>This field is required if you send >1 document inside an envelope<br><br>When set to <code>true</code>, the signed documents will be kept separated.<br><br>When set to <code>false</code>, all of the signed documents will be merged into 1 document. <br><br>Important: If your original document(s) have an existing digital signature, set this field to <code>true</code> to maintain the existing digital signature validity<br><br>(Defailt value: <code>true</code>)</td></tr><tr><td>expiration_days</td><td>Int</td><td>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 <code>DECLINED</code>. <br><strong>Minimum value</strong>: 1 <br><strong>Maximum value</strong>: 90 <br><strong>Default value</strong>: 90</td></tr><tr><td><strong>recipients</strong><mark style="color:red;">*</mark></td><td><strong>Array</strong></td><td></td></tr><tr><td><ul><li>recipients[0].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>recipients[0].order<mark style="color:red;">*</mark></li></ul></td><td>Int</td><td>The recipient will receive the email to sign the document in this chronological order, with a numerical value starting from 1.</td></tr><tr><td><ul><li>recipients[0].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><strong>fields</strong><mark style="color:red;">*</mark></td><td><strong>Array</strong></td><td></td></tr><tr><td><ul><li>fields[0].type<mark style="color:red;">*</mark></li></ul></td><td>String</td><td><p>VSP Open API supports placement for <code>Signature</code>, <code>QR</code>, <code>E-Meterai</code></p><p></p><p>Refer to <a href="#field-type-enum">Field Type enum</a> table</p></td></tr><tr><td><ul><li>fields[0].x</li></ul></td><td>Int</td><td>The X pixel coordinate of the field in the document<br><br>x=<code>0</code> starts at the left-side of document</td></tr><tr><td><ul><li>fields[0].y</li></ul></td><td>Int</td><td><p>The Y pixel coordinate of the field in the document</p><p><br>y=<code>0</code> starts at the top-side of document</p></td></tr><tr><td><ul><li>fields[0].height</li></ul></td><td>Int</td><td>The width of the signature field, in other words: X2 coordinate</td></tr><tr><td><ul><li>fields[0].width</li></ul></td><td>Int</td><td>The height of the signature field, in other words: Y2 coordinate</td></tr><tr><td><ul><li>fields[0].page_index</li></ul></td><td>Int</td><td>The page index in which the signature field needs to be placed. Index starts from 1.</td></tr><tr><td><ul><li>fields[0].recipient_email<mark style="color:red;">*</mark></li></ul></td><td>String</td><td>The signer email.</td></tr><tr><td><ul><li>fields[0].emeterai_doc_type</li></ul></td><td>String</td><td>Required for <code>fields[0].type = E-Meterai</code><br>Refer to <a data-mention href="/pages/I2whHtOyErXsZzbb2k5R#get-e-meterai-document-type-codes">/pages/I2whHtOyErXsZzbb2k5R#get-e-meterai-document-type-codes</a></td></tr></tbody></table>

#### Field Type Enum

<table><thead><tr><th width="142.5">Value</th><th>Description</th></tr></thead><tbody><tr><td>Signature</td><td>Signature refers to digital signature to be placed in the document.</td></tr><tr><td>QR</td><td>QR refers to QR code that can be scanned by anyone to view the envelope audit trail.<br><br>Note: QR size should be in <code>1:1</code> ratio. When using QR as field type, you do not need to specify <code>fields[0].recipient_email</code></td></tr><tr><td>E-Meterai</td><td><p>You can add an E-Meterai field to the document. The eMeterai stamping process starts when <a href="/pages/5ctbT8zOgg3TP1g0cTJk">Start Signature API</a> is hit, &#x26; that the stamping is asynchronous. Set up a <a href="/pages/tZZcV762PxBPMdwZcNpg">webhook </a>to get a real-time status update.</p><p></p><p>Note: eMeterai size is fixed at <code>100</code>x<code>100</code>px. When using eMeterai as field type, you do not need to specify <code>fields[0].recipient_email</code></p></td></tr></tbody></table>

#### Signature Type Enum

<table><thead><tr><th width="142.5"></th><th></th></tr></thead><tbody><tr><td>DIGITAL</td><td><code>DIGITAL</code> refers to signing document with the signer's valid certificate, issued by VIDA as an official PSrE (Penyelenggara Sertifikasi Elektronik)<br><br>This ceritificate is only issued after a successful signer verification/KYC. This means the certificate is <strong>legally-binding and non-repudiatory.</strong><br><br>Use this value as default unless specified otherwise</td></tr><tr><td>ESIGN</td><td><code>ESIGN</code> refers to signature without signer's valid ceriticate.</td></tr></tbody></table>

***

### Response Body

#### Envelope Created Successfully

HTTP Status Code: `200`

Status : `SUCCESS`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```json
{
    "code":"RE.205",
    "message":"Insufficient e-Meterai balance. Please top up or contact support@vida.id for more info."
}
```