Version: 2.3.0

Create or Update Labor Contract

Updated Date: August 18, 2026
Updated By: VNPT eContract's team

Purpose

Initialize (or update) a labor contract associated with an existing employee in the system (identified via EmployeeCode, created in API section 7.1). The API returns LaborContractId (in GUID format) — this value must be saved to be used as an input parameter for the API Creating Documents for Labor Contract (section 7.3).

Request URL: /api/labor-contracts/create-or-update
HTTP method: POST
HTTP content-type: application/json
Authorize: Bearer token
Parameter:

Key	Type	Required	Description
`EmployeeCode`	string	Yes	Employee code created in API section 7.1
`ContractNumber`	string	Yes	Labor contract number
`JobTitle`	string	Yes	Job title
`Salary`	number	Yes	Salary level
`WorkingPosition`	int	Yes	Job position based on system catalog
`ContractType`	int	Yes	Contract type (2: Fixed-term)
`ReportType`	int	No	Reporting method (1: Declaration)
`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	Other additional compensation
`EffectiveDate`	string	Yes	Contract effective date (format: `yyyy-MM-dd`)
`ExpiredDate`	string	No	Contract expiration date (format: `yyyy-MM-dd`)
`Note`	string	No	Contract note
`SigningMethod`	int	Yes	Signing method (1: Electronic Labor Contract)
`File`	string	No	Path/filename of the contract template used to render contract content

caution

Note: In test data, the File field is passed as a local path on the machine running the test. When integrating in production, partners should confirm with the development team regarding the official mechanism for passing contract files (e.g., pre-uploading via a file upload API, or referencing an existing contract template on the system).

Sample Request

{
  "EmployeeCode": "NVC20260805062149",
  "ContractNumber": "HDLD-NVC-20260805062149",
  "JobTitle": "Chuyên viên kinh doanh",
  "Salary": 20000000,
  "WorkingPosition": 2,
  "ContractType": 2,
  "ReportType": 1,
  "PositionAllowance": 1000000,
  "SeniorityAllowancePercent": 0,
  "ProfessionalSeniorityPercent": 0,
  "SalaryAllowance": 500000,
  "AdditionalCompensation": 500000,
  "EffectiveDate": "2026-06-24",
  "ExpiredDate": "2027-06-24",
  "Note": "Hợp đồng lao động xác định thời hạn 12 tháng",
  "SigningMethod": 1,
  "File": "D:\...\Hop-dong-lao-dong-xac-dinh-thoi-han.pdf"
}

Sample Response — HTTP 200

{
  "data": {
    "id": "969bfc9a-570f-4d4e-a98b-42361a73f7e8",
    "createdDate": "2026-08-05T13:21:53.7572904+07:00",
    "employee": {
      "id": 1430,
      "createdDate": "2026-08-05T13:21:52.8949042",
      "userId": 70427,
      "employeeCode": "NVC20260805062149",
      "fullName": "Nguyễn Văn Cường 2149",
      "dateOfBirth": "1997-02-17T00:00:00",
      "gender": 1,
      "identityNumber": "909218625041",
      "email": "nguyenvancuong20260805062149@example.com",
      "phoneNumber": "091****109",
      "socialInsuranceCode": "BH178591090921862504",
      "status": {
        "value": 1,
        "description": "Enabled"
      },
      "currentWorkingPosition": 1,
      "currentJobTitle": "Chuyên viên kinh doanh",
      "currentSalary": 20000000,
      "currentSalaryAllowance": 4,
      "currentContractType": 2,
      "currentReportType": 1,
      "currentContractEffectiveDate": "2026-01-15T00:00:00",
      "currentContractNote": "Hợp đồng lao động xác định thời hạn tạo qua API",
      "currentContractSigningMethod": {
        "value": 1,
        "description": "Electronic Labor Contract"
      },
      "syncStatus": {
        "value": 1,
        "description": "Not Synced"
      },
      "currentContractNumber": "HDLD-NVC-20260805062149"
    },
    "employeeFullName": "Nguyễn Văn Cường 2149",
    "contractNumber": "HDLD-NVC-20260805062149",
    "contractName": "Employment contract Nguyễn Văn Cường 2149",
    "status": {
      "value": 0,
      "description": "Draft"
    },
    "currentRevisionId": "7a2d74b5-140f-4893-8b4b-fc409077e289",
    "currentRevision": {
      "id": "7a2d74b5-140f-4893-8b4b-fc409077e289",
      "createdDate": "2026-08-05T13:21:53.7994921+07:00",
      "laborContractId": "969bfc9a-570f-4d4e-a98b-42361a73f7e8",
      "version": 1,
      "status": {
        "value": 0,
        "description": "Draft"
      },
      "actionType": {
        "value": 0,
        "description": "Initialization"
      },
      "currentLaborContractRenderId": "576b48e7-5472-4278-9168-11e23b7bec45",
      "employeeFullName": "Nguyễn Văn Cường 2149",
      "employeeDateOfBirth": "1997-02-17T00:00:00",
      "employeeGender": {
        "value": 1,
        "description": "Male"
      },
      "employeeIdentityNumber": "909218625041",
      "employeeSocialInsuranceNumber": "BH178591090921862504",
      "employeeEmail": "nguyenvancuong20260805062149@example.com",
      "employeePhoneNumber": "091****109",
      "contractNumber": "HDLD-NVC-20260805062149",
      "contractName": "Employment contract Nguyễn Văn Cường 2149",
      "contractType": {
        "value": 2,
        "description": "Fixed-term"
      },
      "jobTitle": "Chuyên viên kinh doanh",
      "workingPosition": {
        "value": 2,
        "description": "High-level Technical Specialist"
      },
      "salary": 20000000,
      "positionAllowance": 1000000,
      "seniorityAllowancePercent": 0,
      "professionalSeniorityPercent": 0,
      "salaryAllowance": 500000,
      "additionalCompensation": 500000,
      "effectiveDate": "2026-06-24T00:00:00",
      "expiredDate": "2027-06-24T00:00:00",
      "signingMethod": {
        "value": 1,
        "description": "Electronic Labor Contract"
      },
      "reportType": {
        "value": 1,
        "description": "Declaration"
      },
      "syncStatus": {
        "value": 1,
        "description": "Not Synced"
      },
      "downloadUrl": "{HOST}/Api/Download?token=...",
      "contractFile": {
        "fileName": "Hop-dong-lao-dong-xac-dinh-thoi-han.pdf",
        "fileSize": 358043
      }
    },
    "totalDocumentCount": 0
  },
  "success": true,
  "code": 0,
  "messages": [
    "Create labor contract success"
  ]
}

info

Note: data.id is the LaborContractId — it must be saved to use for Creating Documents for Labor Contract (section 7.3). The newly created contract has status = "Draft" until the corresponding document is created and sent to the signing workflow.

Response Parameter

Key	Type	Description
`data`	object	Detailed information of the newly created/updated labor contract (see below)
`success`	boolean	Request processing status (true: Success, false: Failure)
`code`	int	Response status code
`messages`	array	List of processing response messages from the system

Details of `data` Object in Response:

Key	Type	Description
`id`	string	Labor contract ID (GUID) — used as `LaborContractId` for the next step
`createdDate`	string	Contract creation time (ISO 8601 format)
`employee`	object	Detailed information of the linked employee (see below)
`employeeFullName`	string	Full name of the employee
`contractNumber`	string	Labor contract number
`contractName`	string	Labor contract name
`status`	object	Contract status 0: Draft 1: Pending Signature 2: Signing 3: Signed 4: Effective 5: Expired 6: Terminated 7: Cancelled 8: Rejected 9: Correcting
`currentRevisionId`	string	GUID of the current contract revision
`currentRevision`	object	Detailed information of the contract revision (see below)
`totalDocumentCount`	int	Total count of related documents created

Details of `employee` Object in Response:

Key	Type	Description
`id`	int	Employee ID
`createdDate`	string	Record creation time (ISO 8601 format)
`userId`	int	ID of the linked user account
`employeeCode`	string	Employee code
`fullName`	string	Employee full name
`dateOfBirth`	string	Date of birth (ISO 8601 format)
`gender`	int	Gender (1: Male, 2: Female)
`identityNumber`	string	National ID / Citizen ID number
`email`	string	Employee email address
`phoneNumber`	string	Phone number
`socialInsuranceCode`	string	Social insurance code
`status`	object	Employee status (1: Enabled)
`currentWorkingPosition`	int	Current job position
`currentJobTitle`	string	Current job title
`currentSalary`	number	Current salary level
`currentSalaryAllowance`	number	Current salary allowance
`currentContractType`	int	Current contract type (2: Fixed-term)
`currentReportType`	int	Contract reporting method
`currentContractEffectiveDate`	string	Effective date of current contract (ISO 8601 format)
`currentContractNote`	string	Note for current contract
`currentContractSigningMethod`	object	Contract signing method (1: Electronic Labor Contract)
`syncStatus`	object	Synchronization status (1: Not Synced)
`currentContractNumber`	string	Current contract number

Details of `currentRevision` Object in Response:

Key	Type	Description
`id`	string	Revision GUID
`createdDate`	string	Revision creation time (ISO 8601 format)
`laborContractId`	string	Labor contract GUID
`version`	int	Contract revision version number
`status`	object	Revision status 0: Draft 1: Pending Signature 2: Signing 3: Signed 4: Effective 5: Expired 6: Terminated 7: Cancelled 8: Rejected 9: Correcting
`actionType`	object	Action type 0: Initialization 1: Salary Adjustment 2: Renew Contract 3: Terminate Contract 4: Change Position 5: Update Social Insurance Information 20: Recreate
`currentLaborContractRenderId`	string	Contract render record GUID
`employeeFullName`	string	Employee full name
`employeeDateOfBirth`	string	Employee date of birth (ISO 8601 format)
`employeeGender`	object	Gender (1: Male)
`employeeIdentityNumber`	string	National ID / Citizen ID number
`employeeSocialInsuranceNumber`	string	Social insurance code
`employeeEmail`	string	Employee email address
`employeePhoneNumber`	string	Phone number
`contractNumber`	string	Contract number
`contractName`	string	Contract name
`contractType`	object	Contract type (2: Fixed-term)
`jobTitle`	string	Job title
`workingPosition`	object	Job position (2: High-level Technical Specialist)
`salary`	number	Salary level
`positionAllowance`	number	Position allowance
`seniorityAllowancePercent`	number	Seniority allowance percentage (%)
`professionalSeniorityPercent`	number	Professional seniority allowance percentage (%)
`salaryAllowance`	number	Salary allowance
`additionalCompensation`	number	Other additional compensation
`effectiveDate`	string	Effective date (ISO 8601 format)
`expiredDate`	string	Expiration date (ISO 8601 format)
`signingMethod`	object	Signing method (1: Electronic Labor Contract)
`reportType`	object	Reporting method (1: Declaration)
`syncStatus`	object	Synchronization status (1: Not Synced)
`downloadUrl`	string	Download URL for draft contract file
`contractFile`	object	Contract file info (`fileName`, `fileSize`)

Common Errors

`success`	`code`	`messages`	Meaning
`false`	`0`	`"Cannot create a new labor contract because the employee already has a labor contract that has not been terminated"`	This employee already has an active labor contract (not yet liquidated/terminated). You need to pass the contract `Id` to perform an update.
`false`	`0`	`"Employee of an existing labor contract cannot be changed"`	Cannot change employee details for an existing labor contract.
`false`	`0`	`"Document number 'TEST.2026.001' has been used."`	This document number/code is already in use on the system. Please enter a different document number.

Purpose​

Sample Request​

Sample Response — HTTP 200​

Response Parameter​

Details of data Object in Response:​

Details of employee Object in Response:​

Details of currentRevision Object in Response:​

Common Errors​