> 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-envelope-with-document-upload.md).

# 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

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

#### If Signer is not verified by VIDA

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

{% hint style="info" %}
To use `/ra` endpoint, the client has to undergo Registration Authority assessment. Please contact VIDA team for more detail
{% endhint %}

### Headers

<table><thead><tr><th width="197">Name</th><th width="151">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

<table><thead><tr><th width="200">Name</th><th width="123">Type</th><th>Description</th></tr></thead><tbody><tr><td>file</td><td>File</td><td><p>Use this field to send only 1 document per envelope.</p><p></p><p>You can directly pass a single PDF to create an envelope (max 50 MB, 500 pages).</p></td></tr><tr><td>document_ids</td><td>Array</td><td><p>Use this field to send >1 document per envelope.</p><p></p><p>You can use up to 10 document_id inside an envelope</p><p></p><p>To obtain multiple document ID, Use a separate <a href="/pages/3z3suskjhgclPc2wVfmO#upload-document">document upload </a>endpoint.</p></td></tr><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>envelope_details<mark style="color:red;">*</mark></td><td>JSON String</td><td>This is a nested JSON. Please refer to <a href="#envelope_details">envelope_details</a> section below.</td></tr></tbody></table>

#### envelope\_details

<table><thead><tr><th width="189">Name</th><th width="133">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>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>signature_type</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><br>Use <code>DIGITAL</code> as the value unless specified otherwise.</p><p></p><p>Refer to (<a href="#signature-type-enum">Signature Type Enum</a> Table)<br>Default value: <code>DIGITAL</code></p></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;"><strong>*</strong></mark></td><td></td><td></td></tr><tr><td><ul><li>recipients.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.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><ul><li>recipients.kyc_event_id</li></ul><p></p></td><td>String</td><td><p>The <code>kyc_event_id</code> retrieved from a successful verification by VIDA.</p><p></p><p>Skip this field if you do not verify the signer with VIDA</p><p></p><p>Ensure that you only use a valid event ID.</p></td></tr><tr><td><ul><li>recipients.registration_id</li></ul></td><td>String</td><td>The <code>registration_id</code> retrieved from a succesful registration, where the signer is not verified by VIDA<br><br>Skip this field if you already verify the signer with VIDA<br><br>Ensure that you only use a valid Registration ID.</td></tr><tr><td><strong>fields</strong><mark style="color:red;"><strong>*</strong></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><p>The type of field to add to the document:</p><ul><li><code>Signature</code> </li><li><code>QR</code></li></ul><p>Refer to Fields Type Enum</p></td></tr><tr><td><ul><li>fields[0].document_id</li></ul></td><td>String</td><td>Required if the envelope leverages Upload Document API.<br><br>Specify which document ID that requires the signature field</td></tr><tr><td><ul><li>fields[0].x</li></ul></td><td>Int</td><td>The X point coordinate value 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 point coordinate value 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].width</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].height</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></tbody></table>

#### Signature Type Enum

<table><thead><tr><th width="191">Value</th><th>Description</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 legally-binding and non-repudiatory.<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>

#### Field Type Enum

<table><thead><tr><th width="166.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></tbody></table>

***

### Response Body

#### Envelope Created Successfully

HTTP Status Code: `200`

Status : `SUCCESS`

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

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

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

#### 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 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 - Invalid Registration ID Format

Invalid registration ID format check

HTTP Status Code: `400`

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

#### Bad Request - Invalid Registration ID

Invalid registration ID&#x20;

HTTP Status Code: `400`

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

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