Smart-ID signing

Smart-ID creates certificate-based electronic signatures through the Sign API v2 PKISIGNING flow. This guide details how to configure and invoke Smart-ID for signing.

Supported capabilities

Capability	Support
Vendor	`SMARTID`
Signing flow	`PKISIGNING`
Input format	PDF (`application/pdf`)
Result format	PAdES-BASELINE-LT (`application/pdf`)
Multiple documents	Supported; one signed PDF is produced for each input PDF.
Packaging with `packageTo`	Not supported.
Custom intent text	Not supported (see Limitations).
Signer personal data prefill	Not supported.

Account and signature level

The signer must have a full-access Qualified Smart-ID account. Smart-ID Basic and other non-qualified Smart-ID accounts cannot be used for document signing.

Smart-ID PKISIGNING produces a Qualified Electronic Signature (QES) in PAdES-BASELINE-LT format:

The signed PDF embeds an authoritative signature timestamp.
Validation material (certificates and revocation data) is embedded directly to enable long-term (LT) validation.

Signing setup

To request Smart-ID, use the following signingSetup configuration in your HTTP POST request to the Signing sessions endpoint:

"signingSetup": [
  {
    "vendor": "SMARTID",
    "signingFlow": "PKISIGNING",
    "identityProviders": [],
    "requestedAttributes": [
      "nin",
      "dateOfBirth"
    ]
  }
]

Signer attributes

The signer name and identity provider name are returned by default. You can request additional attributes in the requestedAttributes array.

Requested value	Output field	Description
`nin`	`output.userInfo.nin`	National identity number returned by Smart-ID.
`dateOfBirth`	`output.userInfo.dateOfBirth`	Date of birth derived from the signing certificate, in `YYYY-MM-DD` format.

Attribute response

The retrieved attributes will be available in the output.userInfo object when the session is complete:

Output field	Description
`signingTime`	Signature time in ISO 8601 format, including an offset when available.
`fullName`, `firstName`, `lastName`	Verified signer name.
`idpName`	`smartid`
`nin`	National identity number.
`dateOfBirth`	Date of birth in `YYYY-MM-DD` format.
`uniqueId`	ETSI EN 319 412-1 natural-person identifier in the format `<type><country>-<identifier>`, where `type` is a three-character identity type and `country` is an ISO 3166-1 alpha-2 country code (for example, `PNOEE-40504040001`).
`extra`	Values under `extra`, including client IP and user agent.

Restrict signing to a known person

To require a particular national identity number, request the nin attribute and configure signer validation as shown below:

{
  "signer": {
    "nationalIdentificationNumber": "49001010033",
    "prefill": [],
    "validations": ["NATIONAL_IDENTIFICATION_NUMBER"]
  },
  "signingSetup": [
    {
      "vendor": "SMARTID",
      "signingFlow": "PKISIGNING",
      "identityProviders": [],
      "requestedAttributes": ["nin"]
    }
  ]
}

The session is rejected if the national identity number returned by Smart-ID differs from the configured value. Setting nationalIdentificationNumber without "validations": ["NATIONAL_IDENTIFICATION_NUMBER"] does not enforce a match.

Note

Smart-ID identity prefill is not currently supported; the signer will always enter their identity during the Smart-ID ceremony.

Signing result

A completed session contains one PAdES result (PAdES-BASELINE-LT) for each signed input document:

{
  "lifecycle": {
    "state": "SIGNED",
    "stateIsFinal": true
  },
  "output": {
    "signatures": [
      {
        "resultDocumentId": "019ff016-75fc-739e-ab04-5ca7b56d0178",
        "originalDocumentId": "019ff013-ce14-7523-a706-165e3260a5f8",
        "signatureType": "PADES"
      }
    ],
    "packages": [],
    "userInfo": {
      "signingTime": "2026-08-11T12:10:09+03:00",
      "fullName": "Mari Tamm",
      "dateOfBirth": "2005-04-04",
      "idpName": "smartid",
      "nin": "40504040001",
      "uniqueId": "PNOEE-40504040001",
      "firstName": "Mari",
      "lastName": "Tamm",
      "extra": {
        "client-ip": "203.0.113.42",
        "user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/148.0.0.0 Safari/537.36"
      }
    },
    "seals": []
  }
}

Use resultDocumentId to retrieve the signed PDF. For multiple documents, match each result to its input using originalDocumentId rather than array order.

Limitations

A full-access Qualified Smart-ID account is required. Smart-ID Basic is not supported.
Only PDF documents are supported.
packageTo cannot be used with Smart-ID PKISIGNING.
Signer identity prefill is not supported.
Custom intent text is not supported. Smart-ID presents a hardcoded intention text on the Confirm action screen in the mobile app, meaning that custom messages cannot be displayed.

Test accounts

You can test Smart-ID signing using the official SK ID Solutions test accounts. For a full list of test identities and additional success/error scenarios, refer to the Smart-ID test-account list.

Supported capabilities​

Account and signature level​

Signing setup​

Signer attributes​

Attribute response​

Restrict signing to a known person​

Signing result​

Limitations​

Test accounts​