Version: 2.3.0

Batch Import Labor Contracts

Last updated: August 18, 2026
Updated by: VNPT eContract's team

Purpose

Allows bulk creation of labor contracts (along with documents and workflow configurations for signing) in a single API call, based on a pre-defined document template — ideal for batch importing large numbers of labor contracts instead of sequentially invoking individual creation APIs.

Request URL: /api/batch-imports/labor-contracts
HTTP method: POST
HTTP content-type: application/json
Authorization: Bearer token
Parameter (Top-level):

Key	Type	Required	Description
`departmentId`	int	Yes	Issuing department ID
`documentTemplateId`	int	Yes	Document template ID used to render labor contract content
`documentTypeId`	int	Yes	Document type ID (e.g., 8950 = Labor Contract)
`name`	string	Yes	Name of the import batch
`laborContracts`	array	Yes	List of contracts to import — each item contains 4 groups: `contract`, `employee`, `workflow`, and `parameters` (detailed below)

Detailed structure of objects inside `laborContracts` array:

1. contract Group (Contract Information):

Key	Type	Required	Description
`no`	string	Yes	Labor contract number
`workingPosition`	int	Yes	Job position according to system master data
`type`	int	Yes	Contract type (2: Fixed-term)
`reportType`	int	No	Report type (1: Declaration)
`jobTitle`	string	Yes	Job title
`salary`	number	Yes	Salary amount
`positionAllowance`	number	No	Position allowance
`seniorityAllowancePercent`	number	No	Seniority allowance percentage (%)
`professionalSeniorityPercent`	number	No	Professional seniority allowance percentage (%)
`salaryAllowance`	number	No	Salary allowance
`additionalCompensation`	number	No	Additional compensation
`hazardousWorkFromDate`	string	No	Start date for strenuous, toxic, or hazardous work (format: `yyyy-MM-dd`)
`hazardousWorkToDate`	string	No	End date for strenuous, toxic, or hazardous work (format: `yyyy-MM-dd`)
`effectiveDate`	string	Yes	Contract effective date (format: `yyyy-MM-dd`)
`expiredDate`	string	No	Contract expiration date (format: `yyyy-MM-dd`)
`socialInsuranceStartDate`	string	No	Social insurance contribution start date (format: `yyyy-MM-dd`)
`socialInsuranceEndDate`	string	No	Social insurance contribution end date (format: `yyyy-MM-dd`)
`note`	string	No	Contract note
`signingMethod`	int	Yes	Signing method (1: Electronic Labor Contract)

2. employee, workflow, and parameters Groups:

Key	Type	Required	Description
`employee.code`	string	Yes	Employee code — must be created beforehand using the API in section 7.1
`workflow.processInOrder`	boolean	Yes	Determines whether the signing workflow is processed sequentially (`true`) or in parallel (`false`)
`workflow.templateId`	int	No	Existing workflow template ID; set to `null` if manually assigning recipients via `recipients`
`workflow.recipients[].code`	string	Yes	User code assigned to process the document
`workflow.recipients[].accessPermission`	string	Yes	Processing permission code (e.g., "DR", "D" — based on the system document processing permission catalog; confirm the complete list with the development team)
`parameters`	object	Yes	Dynamic key-value object containing variables to populate the contract template — matching predefined placeholders in the template file (e.g., `DIACHILV`, `BOPHAN`, ...)

Sample Request

{
  "departmentId": 9855,
  "documentTemplateId": 8132,
  "documentTypeId": 8950,
  "name": "Import lô HĐLĐ xác định thời hạn HDLD-NVC-20260805062154B",
  "laborContracts": [
    {
      "contract": {
        "no": "HDLD-NVC-20260805062154B",
        "workingPosition": 2,
        "type": 2,
        "reportType": 1,
        "jobTitle": "Chuyên viên kinh doanh",
        "salary": 20000000,
        "positionAllowance": 1500000,
        "seniorityAllowancePercent": 5,
        "professionalSeniorityPercent": 6,
        "salaryAllowance": 700000,
        "additionalCompensation": 500000,
        "hazardousWorkFromDate": null,
        "hazardousWorkToDate": null,
        "effectiveDate": "2026-02-01",
        "expiredDate": "2027-06-24",
        "socialInsuranceStartDate": "2026-02-01",
        "socialInsuranceEndDate": null,
        "note": "Hợp đồng lao động xác định thời hạn 12 tháng",
        "signingMethod": 1
      },
      "employee": {
        "code": "NVC20260805062154B"
      },
      "workflow": {
        "processInOrder": true,
        "templateId": null,
        "recipients": [
          {
            "code": "BAOTH",
            "accessPermission": "DR"
          },
          {
            "code": "TRINHTTV",
            "accessPermission": "D"
          }
        ]
      },
      "parameters": {
        "DIACHILV": "Tầng 10 toà nhà VNPT, Hà Nội",
        "BOPHAN": "Nhân Sự",
        "GIOLAMVIEC": "08:00-17:00 từ Thứ 2 đến Thứ 6",
        "DVTIEN": "VND",
        "NGAYCAP_CCCD": "2019-08-20",
        "NOICAP_CCCD": "Công an TP Hà Nội",
        "HKTT": "123 Phố Huế, Hai Bà Trưng, Hà Nội"
      }
    }
  ]
}

Sample Response — HTTP 200

{
  "data": {
    "id": 22945,
    "createdDate": "2026-08-05T13:21:56.0319878+07:00",
    "uploadedByUserId": 27938,
    "numberOfRecords": 1,
    "name": "Import lô HĐLĐ xác định thời hạn HDLD-NVC-20260805062154B",
    "status": {
      "value": 1,
      "description": "Processing"
    },
    "documents": [],
    "errors": [],
    "importType": {
      "value": 3,
      "description": "Labor contracts created from templates"
    }
  },
  "success": true,
  "code": 200,
  "messages": [
    "Create labor contract batch import successfully"
  ]
}

info

Note: data.id is the BatchImportId — save this ID to use in the Batch Workflow Execution API (section 7.5) or to query the processing status of the import batch. The status field returns "Processing" and documents is initially empty because contract and document creation within the batch is processed asynchronously in the background.

Response Parameters

Key	Type	Description
`data`	object	Detailed information of the created import batch (see details below)
`success`	boolean	Request processing status (true: Success, false: Failure)
`code`	int	Response status code (200: Success)
`messages`	array	List of processing result messages from the system

Detailed structure of `data` object in Response:

Key	Type	Description
`id`	int	Import batch ID (`BatchImportId`) — used as a parameter for the API in section 7.5
`createdDate`	string	Batch creation time (ISO 8601 format)
`uploadedByUserId`	int	ID of the user who uploaded the batch import
`numberOfRecords`	int	Total number of labor contract records in the import batch
`name`	string	Name of the import batch
`status`	object	Batch processing status (1: Processing — Asynchronous background processing)
`documents`	array	List of successfully created documents (empty upon initial creation)
`errors`	array	List of error messages occurred during processing (if any)
`importType`	object	Import type (3: Labor contracts created from templates)

Common Errors (Batch Import)

`success`	`messages`	Description
`false`	`"Document number 'doc_no' already exists"`	Document number `doc_no` already exists in the system. Please change the document number in the import file.
`false`	`"Employee code 'empl_code' already has a labor contract that is not terminated"`	Employee code `empl_code` already has an active (non-terminated) labor contract. Please verify the contract information again.

Purpose​

Detailed structure of objects inside laborContracts array:​

Sample Request​

Sample Response — HTTP 200​

Response Parameters​

Detailed structure of data object in Response:​

Common Errors (Batch Import)​