Version: 2.3.0

Create or Update Employee

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

Purpose

Create a new employee or update an existing employee's information in the system, while automatically creating/updating the associated user account linked to that employee. This is the first step and must be performed before initializing a labor contract for the corresponding employee (see section 7.2).

Request URL: /api/employees/create-or-update
HTTP method: POST
HTTP content-type: application/json
Authorize: Bearer token
Parameters:

Key	Type	Description
`employeeCode`	string	[Required] Unique employee identifier (used to determine whether to create or update)
`fullName`	string	[Required] Employee's full name
`dateOfBirth`	string	[Required] Date of birth (format: `yyyy-MM-dd`)
`gender`	int	[Required] Gender, per system category: - 1: Male - 2: Female
`identityNumber`	string	[Required] National ID / Citizen ID number
`email`	string	[Required] Employee's email address
`phoneNumber`	string	[Required] Phone number
`socialInsuranceCode`	string	Social insurance book number
`status`	int	[Required] Employee status (1: Active)
`workingPosition`	int	[Required] Job position, per system category
`contractType`	int	[Required] Contract type (2: Fixed-term)
`contractReportType`	int	Contract reporting type
`contractSigningMethod`	int	[Required] Contract signing method (1: Electronic labor contract)
`jobTitle`	string	[Required] Job title
`salary`	number	[Required] Salary amount
`salaryAllowance`	number	Salary allowance
`contractEffectiveDate`	string	[Required] Effective date of the employee's current contract (format: `yyyy-MM-dd`)
`contractExpiredDate`	string	Contract expiration date (format: `yyyy-MM-dd`; pass `null` if the contract has no fixed term)
`contractNote`	string	Contract note
`user`	object	[Required] Login account information object { "code": "string", // [Required] Linked login account code "username": "string", // [Required] Login username (usually an email) "name": "string", // [Required] Display name of the account "generateSelfSignedCertEnabled": boolean // Automatically generate a self-signed certificate (true/false) }

note

The request body is an array, allowing multiple employees to be created/updated in a single call. If employeeCode already exists in the system, the corresponding record will be updated; otherwise, a new record will be created.

Sample Request

[
  {
    "employeeCode": "NVC20260805062149",
    "fullName": "Nguyen Van Cuong 2149",
    "dateOfBirth": "1997-02-17",
    "gender": 1,
    "identityNumber": "909218625041",
    "email": "nguyenvancuong20260805062149@example.com",
    "phoneNumber": "091****109",
    "socialInsuranceCode": "BH178591090921862504",
    "status": 1,
    "workingPosition": 1,
    "contractType": 2,
    "contractReportType": 1,
    "contractSigningMethod": 1,
    "jobTitle": "Business Specialist",
    "salary": 20000000,
    "salaryAllowance": 4,
    "contractEffectiveDate": "2026-01-15",
    "contractExpiredDate": null,
    "contractNote": "Fixed-term labor contract created via API",
    "user": {
      "code": "NVC20260805062149",
      "username": "nguyenvancuong20260805062149@example.com",
      "name": "Nguyen Van Cuong 2149",
      "generateSelfSignedCertEnabled": false
    }
  }
]

Sample Response — HTTP 200

{
  "data": [
    {
      "id": 1430,
      "createdDate": "2026-08-05T13:21:52.8949042+07:00",
      "userId": 70427,
      "user": {
        "id": 70427,
        "createdDate": "2026-08-05T13:21:51.9310169+07:00",
        "comId": 7354,
        "code": "NVC20260805062149",
        "username": "nguyenvancuong20260805062149@example.com",
        "name": "Nguyen Van Cuong 2149",
        "phone": "091****109",
        "email": "nguyenvancuong20260805062149@example.com",
        "identityVerificationStatus": {
          "value": 0,
          "description": "Not verified"
        },
        "identityVerifiedType": {
          "value": 0,
          "description": "Unknown"
        },
        "identityVerifiedSource": {
          "value": 0,
          "description": "Unknown"
        },
        "isValid": false,
        "signConfirmationEnabled": true,
        "isAccountLocked": false,
        "accountId": "5cf86e5e-b873-48a5-9c6b-eb9c3384dcda",
        "signMethod": {
          "value": 2,
          "description": "VNPT SmartCA"
        },
        "status": {
          "value": 1,
          "description": "Enabled"
        },
        "receiveOtpMethod": {
          "value": 1,
          "description": "Email"
        },
        "receiveNotificationMethod": {
          "value": 0,
          "description": "Email"
        },
        "usedMemory": 0,
        "waitingChangeRequest": false,
        "twoFactorEnabled": false
      },
      "employeeCode": "NVC20260805062149",
      "fullName": "Nguyen Van Cuong 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": "Business Specialist",
      "currentSalary": 20000000,
      "currentSalaryAllowance": 4,
      "currentContractType": 2,
      "currentReportType": 1,
      "currentContractEffectiveDate": "2026-01-15T00:00:00",
      "currentContractNote": "Fixed-term labor contract created via API",
      "currentContractSigningMethod": {
        "value": 1,
        "description": "Electronic Labor Contract"
      },
      "syncStatus": {
        "value": 1,
        "description": "Not Synced"
      },
      "currentContractNumber": ""
    }
  ],
  "success": true,
  "code": 0,
  "messages": [
    "Create 1 employee success, update 0 employee success."
  ]
}

info

Note: the messages field returned indicates the number of records successfully created/updated, e.g., "Create 1 employee success, update 0 employee success."

Response Parameters

Key	Type	Description
`data`	Array[object]	List of employees successfully created/updated
`success`	boolean	Request processing status (true: Success, false: Failed)
`code`	int	Response status code
`messages`	Array[string]	List of processing result messages from the system

Details of the `data` attributes:

Key	Type	Description
`id`	int	Employee record ID in the system
`createdDate`	string	Record creation time (ISO 8601 format)
`userId`	int	ID of the linked user account
`user`	object	Details of the linked login account (see below)
`employeeCode`	string	Unique employee identifier
`fullName`	string	Employee's 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's email address
`phoneNumber`	string	Phone number
`socialInsuranceCode`	string	Social insurance number
`status`	object	Employee status 1: Enabled -1: Disabled
`currentWorkingPosition`	int	Current job position
`currentJobTitle`	string	Job title
`currentSalary`	number	Current salary
`currentSalaryAllowance`	number	Salary allowance
`currentContractType`	int	Contract type 1: Indefinite-term Labor Contract 2: Fixed-term Labor Contract
`currentReportType`	int	Contract reporting type
`currentContractEffectiveDate`	string	Contract effective date (ISO 8601 format)
`currentContractNote`	string	Contract note
`currentContractSigningMethod`	object	Contract signing method 1: Electronic Labor Contract 2: Paper Labor Contract
`syncStatus`	object	Synchronization status 1: Not Synced 2: Synced 3: Failed
`currentContractNumber`	string	Current contract number

Details of the `user` object in the response:

Key	Type	Description
`id`	int	User account ID
`createdDate`	string	Account creation time (ISO 8601 format)
`comId`	int	Company/organization ID
`code`	string	User account code
`username`	string	Login username
`name`	string	Display name of the user
`phone`	string	Phone number
`email`	string	Email address
`identityVerificationStatus`	object	Identity verification status (0: Not verified)
`identityVerifiedType`	object	Identity verification type
`identityVerifiedSource`	object	Identity verification source
`isValid`	boolean	Account validity status
`signConfirmationEnabled`	boolean	Enable/disable sign confirmation
`isAccountLocked`	boolean	Account lock status
`accountId`	string	System account GUID
`signMethod`	object	Signing method (2: VNPT SmartCA)
`status`	object	Account status (1: Enabled)
`receiveOtpMethod`	object	OTP receiving method (1: Email)
`receiveNotificationMethod`	object	Notification receiving method (0: Email)
`usedMemory`	number	Storage capacity used
`waitingChangeRequest`	boolean	Whether there is a pending change request awaiting approval
`twoFactorEnabled`	boolean	Enable/disable two-factor authentication

Common Errors

`success`	`code`	`messages`	Meaning
`false`	`400`	`"Identity number already exists for another employee: 0123456XXXXX"`	This national ID / Citizen ID number is already used by another employee. Check the value or use a different one.
`false`	`0`	`"The user already exists with a different username. Please check again in the User list"`	The employee code (User Code) already exists in the system, linked to a different username. Check the User list and update the User Code.
`false`	`0`	`"Username example@email.com already exists in the company"`	This username/email already exists within the company. Use a different username.

Purpose​

Sample Request​

Sample Response — HTTP 200​

Response Parameters​

Details of the data attributes:​

Details of the user object in the response:​

Common Errors​