Import advanced batch of documents
Updated date: 01/07/2026
Updated by: VNPT eContract's team
Purpose
Perform bulk creation of documents using a pre-prepared document template, refer to Document Template Management
Or download the sample document template here.
- Request URL:
/api/v2/batch-imports/create-advanced - HTTP method:
POST - HTTP content-type:
application/json - Authorize:
Bearer token - Parameter:
| Key | Type | Description |
|---|---|---|
name | string | [Required] Name of batch |
departmentId | int | [Required] Id of department |
documentTypeId | int | [Required] Id of document type |
documentTemplateId | int | [Required] Id of document template |
parameters | List<string> | [Required] Parameters |
rows | List<List<string>> | [Required] Data list |
tip
accessPermissionCode is access permissions:
- V is view only
- D is digital sign
- E is e-sign
- EKYC is eKYC sign
- DR is sign draw
- A is approve
- F is fill data
- C is coordinate
caution
- F allways placed before D, E, EKYC and DR in sequential processing
- Refer to the variable
{{#items}}if you want to pass data in an array format - Use the
\ncharacter to insert a line break (see the example in the variable{{generalTerms}}) - The default length of variables is 2000 characters.
- Each item in
rowsmust have the same number of values as theparameterslist, and values are mapped by index. - Date values for document fields such as
{{D.ExpiryDate}},{{D.ValidFrom}}, and{{D.ValidTo}}must use the validdd/MM/yyyyformat. {{D.No}}is required and must be unique.
Data validation
| Field / rule | Description |
|---|---|
parameters and rows | Each row must contain the same number of values as parameters; otherwise the request fails. |
{{D.No}} | Document number is required and must not already exist. |
| Date fields | Date values must be valid and use dd/MM/yyyy, for example 22/12/2028. |
{{P.Code}} and {{P.AccessPermission}} | Processors are passed as repeated pairs. Add another pair to add another processor. |
| Template variables | Template variables are resolved by exact parameter name and row position. |
Sample request
{
"name": "[DEMO] Batch import 02/2023",
"departmentId": 1,
"documentTypeId": 1,
"documentTemplateId": 2,
"parameters": [
"{{D.FileName}}", // File name
"{{D.No}}", // Required | Document code
"{{D.Subject}}", // Required | Document title
"{{D.ExpiryDate}}", // Document processing expiry date
"{{D.CusCode}}", // Customer code
"{{D.CusName}}", // Customer name
"{{D.ContractValue}}", // Contract value
"{{D.ValidFrom}}", // Contract effective from date
"{{D.ValidTo}}", // Contract effective to date
"{{D.RefDocs}}", // Related document codes, multiple codes separated by ;
"{{D.Description}}", // Document description
"{{D.IsOrder}}", // Workflow | Sequential processing: Y, non-sequential processing: N
"{{D.FixedPosition}}", // Workflow | Fixed signing position: Y, None fixed signing position: N (default)
"{{P.Code}}", // Workflow | Code of the 1st document processing user
"{{P.AccessPermission}}", // Workflow | Access permission of the 1st user
"{{P.Code}}", // Workflow | Code of the 2nd document processing user
"{{P.AccessPermission}}", // Workflow | Access permission of the 2nd user; add more processors using the {{P.Code}} and {{P.AccessPermission}} data pair
"{{day}}", // Variable retrieved from the document template
"{{month}}", // Variable retrieved from the document template
"{{year}}", // Variable retrieved from the document template
"{{fullname}}", // Variable retrieved from the document template
"{{birthday}}", // Variable retrieved from the document template
"{{generalTerms}}", // Variable retrieved from the document template
"{{#items}}" // Variable retrieved from the document template
],
"rows": [
[
"filename.01",
"HDTN.01",
"Hợp đồng thuê nhà ông Nguyễn Văn A",
"22/12/2028",
"CustomerCode",
"Công ty TNHH ABC",
"250000000",
"22/12/2022",
"22/12/2030",
"MATT20.086",
"Đây là nội dung mô tả hợp đồng",
"Y",
"N",
"NVBINH",
"DR",
"NGUYENVANA",
"D",
"17",
"02",
"2022",
"Nguyễn Văn A",
"15/06/2000",
"- Tuân thủ quy định về việc sử dụng trang thiết bị, máy móc, vật tư của người lao động.\n- Chấp hành quy định về trang phục, tác phong, thái độ làm việc của người lao động.\n- Chấp hành quy định về an toàn, vệ sinh lao động trong môi trường làm việc.",
"[ {\"no\": \"1\",\"name\": \"Quy trinh\",\"creator\": \"Ngo Thuy Trinh\",\"year\": \"2025\"}, {\"no\": \"2\",\"name\": \"Quy dinh\",\"creator\": \"Thuy Trinh\",\"year\": \"2020\"} ]"
],
[
"HDTN.02",
"HDTN.02",
"Hợp đồng thuê nhà ông Trần Thùy Trinh",
"22/12/2028",
"",
"",
"250000000",
"22/12/2022",
"22/12/2030",
"MATT20.086",
"Đây là nội dung mô tả hợp đồng",
"Y",
"Y",
"NVBINH",
"DR",
"TRINHTL1",
"D",
"20",
"02",
"2022",
"Tran Thuy Trinh",
"15/02/1990",
"- Tuân thủ quy định về bảo vệ bí mật kinh doanh, bí mật công nghệ của doanh nghiệp.\n- Chấp hành quy định về an toàn, vệ sinh lao động trong môi trường làm việc.",
"[ {\"no\": \"1\",\"name\": \"Quy trinh phong A\",\"creator\": \"Ngo Thuy Trinh\",\"year\": \"04.2025\"}, {\"no\": \"2\",\"name\": \"Quy dinh\",\"creator\": \"Thuy Trinh\",\"year\": \"2020\"} ]"
]
]
}
Error response body
When the batch is created but one or more records fail validation, the API returns success: false, the batch status is Error, and detailed row-level errors are returned in data.errors. These details are the same errors displayed from the Error button in the batch import list.
{
"data": {
"id": 8820,
"createdDate": "2026-07-07T10:19:13.1868649+07:00",
"uploadedByUserId": 2060,
"numberOfRecords": 2,
"name": "1. Hợp đồng thuê mô hình tiền thuê cố định",
"status": {
"value": -1,
"description": "Error"
},
"documents": [],
"errors": [
{
"row": 1,
"message": "Document no 'HDTN.011' has already been used"
},
{
"row": 1,
"message": "Expiry date '22/12/2028s' is invalid"
},
{
"row": 2,
"message": "Document no 'HDTN.021' has already been used"
}
],
"importType": {
"value": 1,
"description": "Documents created from templates"
}
},
"success": false,
"code": 0,
"messages": [
"An error occurred while creating the document batch. Check the detailed error by clicking the [Error] button in the batch import list"
]
}
If the row structure is invalid, the API may reject the request before creating a batch. In this case, data.errors is not returned.
{
"success": false,
"code": 0,
"messages": [
"All length of row must equal length of parameter"
]
}
Error description
| Error message pattern | Cause | Where to check |
|---|---|---|
All length of row must equal length of parameter | At least one item in rows has a different length from parameters. | messages |
Document no '{value}' has already been used | The document number already exists. | data.errors[].message |
Document no '' is invalid | The required document number is empty or invalid. | data.errors[].message |
{Field name} '{value}' is invalid | A field value is invalid, for example an invalid date value. | data.errors[].message |
row | The 1-based index of the row that caused the validation error. | data.errors[].row |
Sample response body
{
"data": {
"id": 8817,
"createdDate": "2026-07-01T09:09:03.711771+07:00",
"uploadedByUserId": 2060,
"numberOfRecords": 2,
"name": "[DEMO] Batch import 02/2023",
"status": {
"value": 1,
"description": "Processing"
},
"documents": [
{
"id": "a1308132-c333-4e77-3be0-08dedbcc7d3b",
"createdDate": "2026-07-01T09:09:03.7235086+07:00",
"lastModifiedDate": "2026-07-01T09:09:03.7235082+07:00",
"expiryDate": "2028-12-22T00:00:00",
"validFrom": "2022-12-22T00:00:00",
"validTo": "2030-12-22T00:00:00",
"contractValue": 250000000,
"customerCode": "CustomerCode",
"customerInformation": "Công ty TNHH ABC",
"no": "HDTN.011",
"subject": "Hợp đồng thuê nhà ông Nguyễn Văn A",
"hasVerified": false,
"hasVerify": false,
"status": {
"value": 1,
"description": "New"
},
"contractStatus": {
"value": 1,
"description": "Contract valid"
},
"description": "Nội dung mô tả hợp đồng",
"createdByUserId": 2060,
"processRecipientCount": 2,
"waitingProcesses": [],
"processInOrder": true,
"isWaitToSignDraw": false,
"isWaitToSignDigital": false,
"isWaitToApprove": false,
"isWaitToFillData": false,
"isWaitToCoordinate": false,
"isWaitToESign": false,
"isWaitToEkyc": false,
"isFillable": false,
"batchImportId": 8817,
"processes": [
{
"id": "f85f3a42-3c39-484e-7f28-08dedbcc7d5b",
"createdDate": "2026-07-01T09:09:03.7234518+07:00",
"comId": 2211,
"isOrder": true,
"orderNo": 1,
"displayType": {
"value": 2,
"description": "Text and image"
},
"accessPermission": {
"value": 2,
"description": "Sign draw"
},
"status": {
"value": 1,
"description": "Waiting"
},
"processedByUserId": 2060,
"documentId": "a1308132-c333-4e77-3be0-08dedbcc7d3b",
"fillingItems": [],
"attachments": []
},
{
"id": "fdf3008a-7fc2-4b68-7f29-08dedbcc7d5b",
"createdDate": "2026-07-01T09:09:03.7234727+07:00",
"comId": 2211,
"isOrder": true,
"orderNo": 2,
"displayType": {
"value": 2,
"description": "Text and image"
},
"accessPermission": {
"value": 4,
"description": "Sign digital"
},
"status": {
"value": 1,
"description": "Waiting"
},
"processedByUserId": 16156,
"documentId": "a1308132-c333-4e77-3be0-08dedbcc7d3b",
"fillingItems": [],
"attachments": []
}
],
"accessibleViewProcesses": [],
"histories": [],
"attachments": [],
"relatedDocuments": [
null
],
"linkedDocuments": [],
"messages": [],
"downloadUrl": "{HOST}/Api/Download?token=DeDfL...",
"downloadOriginalUrl": "{HOST}/Api/Download?token=rM6C5...",
"downloadWatermarkMetadataUrl": "{HOST}/Api/Download?token=vfp1...",
"fillingItems": [],
"sharedUsers": [],
"isMarkStar": false,
"requiresSealSendConfirmation": false
},
{
"id": "242d03f5-42c9-4747-3be1-08dedbcc7d3b",
"createdDate": "2026-07-01T09:09:03.7235923+07:00",
"lastModifiedDate": "2026-07-01T09:09:03.7235923+07:00",
"expiryDate": "2028-12-22T00:00:00",
"validFrom": "2022-12-22T00:00:00",
"validTo": "2030-12-22T00:00:00",
"contractValue": 250000000,
"customerCode": "",
"customerInformation": "",
"no": "HDTN.021",
"subject": "Hợp đồng thuê nhà ông Trần Thùy Trinh",
"hasVerified": false,
"hasVerify": false,
"status": {
"value": 1,
"description": "New"
},
"contractStatus": {
"value": 1,
"description": "Contract valid"
},
"description": "Nội dung mô tả hợp đồng",
"createdByUserId": 2060,
"processRecipientCount": 2,
"waitingProcesses": [],
"processInOrder": true,
"isWaitToSignDraw": false,
"isWaitToSignDigital": false,
"isWaitToApprove": false,
"isWaitToFillData": false,
"isWaitToCoordinate": false,
"isWaitToESign": false,
"isWaitToEkyc": false,
"isFillable": false,
"batchImportId": 8817,
"processes": [
{
"id": "c6baab9c-51fd-4d7f-7f2a-08dedbcc7d5b",
"createdDate": "2026-07-01T09:09:03.7235639+07:00",
"comId": 2211,
"isOrder": true,
"orderNo": 1,
"displayType": {
"value": 2,
"description": "Text and image"
},
"accessPermission": {
"value": 2,
"description": "Sign draw"
},
"status": {
"value": 1,
"description": "Waiting"
},
"processedByUserId": 2060,
"documentId": "242d03f5-42c9-4747-3be1-08dedbcc7d3b",
"fillingItems": [],
"attachments": []
},
{
"id": "cb9982ee-5f27-4ba7-7f2b-08dedbcc7d5b",
"createdDate": "2026-07-01T09:09:03.7235663+07:00",
"comId": 2211,
"isOrder": true,
"orderNo": 2,
"displayType": {
"value": 2,
"description": "Text and image"
},
"accessPermission": {
"value": 4,
"description": "Sign digital"
},
"status": {
"value": 1,
"description": "Waiting"
},
"processedByUserId": 6199,
"documentId": "242d03f5-42c9-4747-3be1-08dedbcc7d3b",
"fillingItems": [],
"attachments": []
}
],
"accessibleViewProcesses": [],
"histories": [],
"attachments": [],
"relatedDocuments": [
null
],
"linkedDocuments": [],
"messages": [],
"downloadUrl": "{HOST}/Api/Download?token=Z6LgAW4...",
"downloadOriginalUrl": "{HOST}/Api/Download?token=dLnA...",
"downloadWatermarkMetadataUrl": "{HOST}/Api/Download?token=bJv6...",
"fillingItems": [],
"sharedUsers": [],
"isMarkStar": false,
"requiresSealSendConfirmation": false
}
],
"errors": [],
"importType": {
"value": 1,
"description": "Documents created from templates"
}
},
"success": true,
"code": 0,
"messages": [
"Import batch document success"
]
}