Add new SmartCA digital signature

Updated date: 18/08/2026
Updated by: VNPT eContract's team

---

Purpose

Add a new SmartCA digital signature for the user. You can add all digital certificates of a user or add a specific certificate based on a given serial number.

• Request URL: /api/users/smart-ca/add
• HTTP method: POST
• HTTP content-type: application/json
• Authorize: Bearer token
• Parameter:

Key	Type	Description
userId	int	[Required] Id of user
username	string	[Required] CCCD/HC/MST of SmartCA account
serialNumber	string	Serial of digital signature

Sample request

{
    "userId": 1234,
    "userName": "08009000000",
    "serialNumber": "540101014e4653549c5a6fdcb9c89999"
}

Sample response body

{
    "data": {
        "id": 1234,
        "createdDate": "2021-01-06T17:06:07.2893325",
        "comId": 16,
        "code": "USER01",
        "username": "your_username",
        "name": "Nguyen Van A",
        "phone": "0919XXXXXX",
        "email": "email_address",
        "isValid": true,
        "signConfirmationEnabled": false,
        "isAccountLocked": false,
        "accountId": "c59125a9-5fee-44e2-b0ff-b229634bf0b2",
        "signatureText": "Sign by: {{SubjectDN.CN}} / {{SubjectDN.O}} / {{SubjectDN.OU}} / {{SubjectDN.UID}}\r\nPosition: {{SubjectDN.T}}\r\nSign date: {{SignTime}}",
        "roles": [
            {
                "id": "29e1138e-833e-4b3a-897a-08da9c3dd633",
                "code": "Admin",
                "name": "Admin manages the company",
                "description": "Admin account manages the company"
            }
        ],
        "signMethod": {
            "value": 2,
            "description": "VNPT SmartCA"
        },
        "status": {
            "value": 1,
            "description": "Enabled"
        },
        "receiveOtpMethod": {
            "value": 1,
            "description": "Email"
        },
        "receiveNotificationMethod": {
            "value": 0,
            "description": "Email"
        },
        "personalCertificateId": 22105,
        "smartCaId": 19843,
        "extraValues": [
        ],
        "usedMemory": 0,
        "defaultSmartCa": {
            "id": 37666,
            "name": "Nguyen Van A 2026",
            "commonName": "Nguyễn Văn A",
            "uid": "08009000000",
            "validFrom": "2025-03-07T08:56:16Z",
            "validTo": "2026-03-07T08:56:16Z",
            "serialNumber": "540101014e4653549c5a6fdcb9c89999",
            "subjectDN": "UID=CCCD:08009000000,CN=Nguyễn Văn A,L=Quận 3,ST=Hồ Chí Minh,C=VN",
            "status": {
                "value": 1,
                "description": "Active"
            },
            "smartCaServiceName": "TEST_CÁ NHÂN ĐỐI TÁC",
            "smartCaSignMethod": {
                "value": 1,
                "description": "Normal"
            },
            "smartCaAccountType": {
                "value": 1,
                "description": "Personal"
            },
            "smartCaUsername": "08009000000",
            "isValid": true,
            "provider": {
                "value": 1,
                "description": "VNPT SmartCA"
            },
            "createdDate": "2025-03-17T08:56:42.4886305+07:00",
            "isBusinessSmartCaAccount": false,
            "ownerId": 6,
            "createdByUserId": 6
        },
        "userCertificates": [
            {
                "id": 37666,
                "name": "Nguyen Van A 2026",
                "commonName": "Nguyễn Văn A",
                "uid": "08009000000",
                "validFrom": "2025-03-07T08:56:16Z",
                "validTo": "2026-03-07T08:56:16Z",
                "serialNumber": "540101014e4653549c5a6fdcb9c89999",
                "subjectDN": "UID=CCCD:08009000000,CN=Nguyễn Văn A,L=Quận 3,ST=Hồ Chí Minh,C=VN",
                "status": {
                    "value": 1,
                    "description": "Active"
                },
                "smartCaServiceName": "TEST_CÁ NHÂN ĐỐI TÁC",
                "smartCaSignMethod": {
                    "value": 1,
                    "description": "Normal"
                },
                "smartCaAccountType": {
                    "value": 1,
                    "description": "Personal"
                },
                "smartCaUsername": "08009000000",
                "isValid": true,
                "provider": {
                    "value": 1,
                    "description": "VNPT SmartCA"
                },
                "createdDate": "2025-03-17T08:56:42.4886305+07:00",
                "isBusinessSmartCaAccount": false,
                "ownerId": 6,
                "createdByUserId": 6
            }
        ],
        "smartCaGroups": [
        ]
    },
    "success": true,
    "code": 0,
    "messages": [
        "Add SmartCA certificate successfully"
    ]
}

Response Body Description

Key	Type	Description
success	boolean	Request processing status (true: Success, false: Failed)
code	int	Response code from the system
messages	array	List of messages returned by the system (e.g., ["Add SmartCA certificate successfully"])
data	object	Object containing detailed user information along with the list of SmartCA certificates after the addition (see details below)

note

Data has been simplified to show only the most important fields. To see detailed user information, please refer to API to get user information by ID

Details of the defaultSmartCa object:

Key	Type	Description
id	int	ID of the default SmartCA certificate
name	string	Friendly name of the digital certificate
commonName	string	Subject name of the digital certificate (CN)
uid	string	Personal identifier / citizen ID number of the certificate owner
validFrom	string	Start date of the certificate's validity period (ISO 8601/UTC format)
validTo	string	Expiration date of the certificate (ISO 8601/UTC format)
serialNumber	string	Unique serial number of the digital certificate
subjectDN	string	Subject Distinguished Name string
status	object	Digital certificate status: {"value": int, "description": string} 1: Active
smartCaServiceName	string	Name of the applied SmartCA service package
smartCaSignMethod	object	SmartCA signing method: {"value": int, "description": string} (e.g., Normal, etc.)
smartCaAccountType	object	SmartCA account type: {"value": int, "description": string} (e.g., Personal, etc.)
smartCaUsername	string	SmartCA login username (usually the citizen ID number or tax code)
isValid	boolean	Current validity status of the certificate (true: Valid, false: Invalid/Expired)
provider	object	Digital certificate service provider: {"value": int, "description": string} (e.g., VNPT SmartCA, etc.)
createdDate	string	Date the certificate was created in the system (ISO 8601 format)
isBusinessSmartCaAccount	boolean	Whether this is a business SmartCA account (true: Business, false: Personal)
ownerId	int	ID of the certificate owner
createdByUserId	int	ID of the user who created/assigned this certificate