| Table of Contents | ||
|---|---|---|
|
API Key
You'll need your API key, so contact info@ondato.com if you don't have them.
Think of your key like a password:
Store it securely
Don't share it with anyone outside of your organization
Don't put it in source code
Include an x-api-key header in each request.
Environments
Sandbox hostname https://sandbox-esignature.ondato.com
Production hostname https://esignature.ondato.com
Smart-ID
Smart-ID is a universal, app-based strong authentication & digital signing solution.
Smart-ID levels
Smart-ID service is being offered on two levels:
Smart-ID Basic – User’s identity has been verified by a third party authentication and the identity details has been verified by national population registry;
Smart-ID – User’s identity has been verified by strong authentication, which is based on the government issued eID (ID-card, Mobile-ID) during the on-line registration or the government issued physical ID document has been verified by two RA employees during the on-site registration.
Test and production accounts has no access to Smart-ID Basic accounts.
Test accounts for automated testing
...
Country
...
National identity number
...
Certificate level
...
Response description
...
EE
...
30303039914
...
QUALIFIED
...
OK
...
LV
...
030303-10012
...
QUALIFIED
...
OK
...
LT
...
30303039914
...
QUALIFIED
...
OK
...
EE
...
30403039917
...
QUALIFIED
...
USER_REFUSED
...
LV
...
030403-10016
...
QUALIFIED
...
USER_REFUSED
...
LT
...
30403039917
...
QUALIFIED
...
USER_REFUSED
...
EE
...
30403039983
...
QUALIFIED
...
TIMEOUT
...
LV
...
030403-10083
...
QUALIFIED
...
TIMEOUT
...
LT
...
30403039983
...
QUALIFIED
...
TIMEOUT
POST Create Authentication Session
https://sandbox-esignature.ondato.com/smart-id/authentication
This method is the main entry point to authentication logic.
Request parameters
...
Parameter
...
Required
...
Description
...
country
...
Required
...
Country code here conforms to ISO 3166-1 alpha-2 code and as such must be in upper case ("LT", "LV", "EE").
...
nationalIdentityNumber
...
Required
...
National identification number
...
certificateLevel
...
Required
...
Level of certificate requested "QUALIFIED".
...
displayText
...
Optional
...
Text to display for authentication consent dialog on the mobile device. Limited to 60 characters or 128 bytes in UTF-8 encoding, whichever is reached first.
...
amlScreeningRequired
...
Optional
...
Do execute AML screening?
Response structure
...
Parameter
...
Required
...
Description
...
sessionId
...
Required
...
A string that can be used to request operation result.
...
verificationCode
...
Required
...
Verification code is needed, so that user can bind together the session on the browser and the authentication request on the Smart-ID app.
Body raw
| Code Block |
|---|
{
"countryCode": "LT",
"nationalIdentityNumber": "10101010005",
"certificateLevel": "QUALIFIED",
"displayText": "Please confirm transaction"
} |
GET Get Authentication Session Status
https://sandbox-esignature.ondato.com/smart-id/authentication/:sessionId
This method can be used to retrieve session result from Smart-ID backend.
This is a long poll method, meaning it might not return until a timeout expires.
Preconditions
Session is present in the system and the request is either running or has been completed less than 5 minutes ago. Timeout period is 120 seconds.
Response structure
...
Parameter
...
Required
...
Description
...
countryCode
...
Required
...
Country code
...
nationalIdentityNumber
...
Required
...
National identification number
...
name
...
Required
...
Person name
...
surname
...
Required
...
Person surname
...
isPep
...
Optional
...
If amlScreeningRequired was used in Create Authentication Session method
POST Create Signature Session
https://sandbox-esignature.ondato.com/smart-id/document-signature
This method is the main entry point to signing logic.
Request parameters
...
Parameter
...
Required
...
Description
...
countryCode
...
Required
...
Country code here conforms to ISO 3166-1 alpha-2 code and as such must be in upper case ("LT", "LV", "EE").
...
nationalIdentityNumber
...
Required
...
National identification number
...
displayText
...
Optional
...
Text to display for authentication consent dialog on the mobile device. Limited to 60 characters or 128 bytes in UTF-8 encoding, whichever is reached first.
...
file
...
Required
...
Data to sign
Response parameters
...
Parameter
...
Required
...
Description
...
sessionId
...
Required
...
A string that can be used to request operation result.
...
verificationCode
...
Required
...
Verification code is needed, so that user can bind together the session on the browser and the authentication request on the Smart-ID app.
Example
| Code Block | ||||
|---|---|---|---|---|
| ||||
curl --location --request POST 'https://sandbox-esignature.ondato.com/smart-id/document-signature/' \
--header 'x-api-key: {your-api-key}' \
--form 'countryCode="LT"' \
--form 'nationalIdentityNumber="30303039914"' \
--form 'displayText="Please confirm transaction"' \
--form 'file=@"/C:/Users/user/Downloads/document.pdf"' |
GET Get Signed Document
https://sandbox-esignature.ondato.com/smart-id/document-signature/:sessionId
This method can be used to retrieve session result from Smart-ID backend.
This is a long poll method, meaning it might not return until a timeout expires. Caller can tune the request parameters inside the bounds set by service operator.
Preconditions
Session is present in the system and the request is either running or has been completed less than 5 minutes ago.
Mobile-ID
Mobile-ID is a SIM card based digital signature solution (and requires a special Mobile-ID SIM card which your mobile operator will provide). It is recognised by governments and it grants access to online services in a similar manner to an ID card.
Test accounts for automated testing
...
Country
...
Phone number
...
National identity number
...
Response description
...
EE
...
+37200000766
...
60001019906
...
Successful signing and identification
...
LT
...
+37060000666
...
50001018865
...
Successful signing and identification
...
EE
...
+37200000266
...
60001019939
...
Mobile-ID user has no active certificates
...
LT
...
+37060000266
...
50001018832
...
Mobile-ID user has no active certificates
...
EE
...
+37207110066
...
60001019947
...
Sending authentication request to phone failed
...
LT
...
+37067110066
...
50001018843
...
Sending authentication request to phone failed
...
EE
...
+37201100266
...
60001019950
...
User cancelled authentication
...
LT
...
+37061100266
...
50001018854
...
User cancelled authentication
...
EE
...
+37200000666
...
60001019961
...
Created signature is not valid
...
LT
...
+37060000766
...
50001018800
...
Created signature is not valid
...
EE
...
+37201200266
...
60001019972
...
SIM application error
...
LT
...
+37061200266
...
50001018876
...
SIM application error
...
EE
...
+37213100266
...
60001019983
...
Phone is not in coverage area
...
LT
...
+37063100266
...
50001018887
...
Phone is not in coverage area
...
LT
...
+37066000266
...
50001018908
...
User does not react
...
Table of Contents
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
🔑 API Key
| Info |
|---|
|
| Note |
|---|
Think of your API key as a password:
|
...
☁️ Environments
Sandbox hostname: https://sandbox-esignature.ondato.com
Production hostname: https://esignature.ondato.com
...
🔷 Smart-ID
Smart-ID is a universal, app-based strong authentication & digital signing solution.
...
🎚️ Smart-ID levels
Smart-ID service is being offered on two levels:
Smart-ID Basic
User’s identity has been verified by a third party authentication and the identity details has been verified by national population registry;
Smart-ID
User’s identity has been verified by strong authentication, which is based on the government issued eID (ID-card, Mobile-ID) during the on-line registration or the government issued physical ID document has been verified by two RA employees during the on-site registration.
| Note |
|---|
Test and production accounts has no access to Smart-ID Basic accounts. |
| Info |
|---|
Learn more from the Smart-ID documentation. |
...
🧪 Test accounts for automated testing
Country | National identity number | Certificate level | Response description |
|---|---|---|---|
EE | 30303039914 | QUALIFIED | OK |
LV | 030303-10012 | QUALIFIED | OK |
LT | 30303039914 | QUALIFIED | OK |
EE | 30403039917 | QUALIFIED | USER_REFUSED |
LV | 030403-10016 | QUALIFIED | USER_REFUSED |
LT | 30403039917 | QUALIFIED | USER_REFUSED |
EE | 30403039983 | QUALIFIED | TIMEOUT |
LV | 030403-10083 | QUALIFIED | TIMEOUT |
LT | 30403039983 | QUALIFIED | TIMEOUT |
...
📍 Endpoints
| Status | ||||
|---|---|---|---|---|
|
https://sandbox-esignature.ondato.com/smart-id/authentication
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
This method is the main entry point to authentication logic. |
...
🎯 Request parameters
Parameter | Required | Description |
|---|---|---|
country | Required | Country code here conforms to ISO 3166-1 alpha-2 code and as such must be in upper case ("LT", "LV", "EE"). |
nationalIdentityNumber | Required | National identification number |
certificateLevel | Required | Level of certificate requested "QUALIFIED". |
displayText | Optional | Text to display for authentication consent dialog on the mobile device. Limited to 60 characters or 128 bytes in UTF-8 encoding, whichever is reached first. |
amlScreeningRequired | Optional | Do execute AML screening? |
...
🥫 Response structure
Parameter | Required | Description |
|---|---|---|
sessionId | Required | A string that can be used to request operation result. |
verificationCode | Required | Verification code is needed, so that user can bind together the session on the browser and the authentication request on the Smart-ID app. |
...
🗒️ Example
| Expand | |||||
|---|---|---|---|---|---|
| |||||
|
| Expand | ||
|---|---|---|
| ||
|
...
| Status | ||||
|---|---|---|---|---|
|
https://sandbox-esignature.ondato.com/smart-id/authentication/{sessionId}
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
This method can be used to retrieve session result from Smart-ID backend. This is a long poll method, meaning it might not return until a timeout expires. |
...
☝️ Preconditions
Session is present in the system and the request is either running or has been completed less than 5 minutes ago. Timeout period is 120 seconds.
...
🥫 Response structure
Parameter | Required | Description |
|---|---|---|
countryCode | Required | Country code |
nationalIdentityNumber | Required | National identification number |
name | Required | Person name |
surname | Required | Person surname |
...
🗒️ Example
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
|
...
| Status | ||||
|---|---|---|---|---|
|
https://sandbox-esignature.ondato.com/smart-id/document-signature
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
This method is the main entry point to signing logic. |
...
🎯 Request parameters
Parameter | Required | Description |
|---|---|---|
countryCode | Required | Country code here conforms to ISO 3166-1 alpha-2 code and as such must be in upper case ("LT", "LV", "EE"). |
nationalIdentityNumber | Required | National identification number |
displayText | Optional | Text to display for authentication consent dialog on the mobile device. Limited to 60 characters or 128 bytes in UTF-8 encoding, whichever is reached first. |
file | Required | Data to sign |
...
🥫 Response parameters
Parameter | Required | Description |
|---|---|---|
sessionId | Required | A string that can be used to request operation result. |
verificationCode | Required | Verification code is needed, so that user can bind together the session on the browser and the authentication request on the Smart-ID app. |
...
🗒️ Example
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
|
...
| Status | ||||
|---|---|---|---|---|
|
https://sandbox-esignature.ondato.com/smart-id/document-signature/{sessionId}
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
This method can be used to retrieve session result from Smart-ID backend. This is a long poll method, meaning it might not return until a timeout expires. Caller can tune the request parameters inside the bounds set by service operator. |
...
☝️ Preconditions
Session is present in the system and the request is either running or has been completed less than 5 minutes ago.
...
🗒️ Example
| Expand | ||
|---|---|---|
| ||
|
...
🔶 Mobile-ID
Mobile-ID is a SIM card based digital signature solution (and requires a special Mobile-ID SIM card which your mobile operator will provide). It is recognised by governments and it grants access to online services in a similar manner to an ID card.
| Info |
|---|
Learn more from the Mobile-ID documentation. |
...
🧪 Test accounts for automated testing
Country | Phone number | National identity number | Response description |
|---|---|---|---|
EE | +37200000766 | 60001019906 | Successful signing and identification |
LT | +37060000666 | 50001018865 | Successful signing and identification |
EE | +37200000266 | 60001019939 | Mobile-ID user has no active certificates |
LT | +37060000266 | 50001018832 | Mobile-ID user has no active certificates |
EE | +37207110066 | 60001019947 | Sending authentication request to phone failed |
LT | +37067110066 | 50001018843 | Sending authentication request to phone failed |
EE | +37201100266 | 60001019950 | User cancelled authentication |
LT | +37061100266 | 50001018854 | User cancelled authentication |
EE | +37200000666 | 60001019961 | Created signature is not valid |
LT | +37060000766 | 50001018800 | Created signature is not valid |
EE | +37201200266 | 60001019972 | SIM application error |
LT | +37061200266 | 50001018876 | SIM application error |
EE | +37213100266 | 60001019983 | Phone is not in coverage area |
LT | +37063100266 | 50001018887 | Phone is not in coverage area |
LT | +37066000266 | 50001018908 | User does not react |
...
📍 Endpoints
| Status | ||||
|---|---|---|---|---|
|
https://sandbox-esignature.ondato.com/mobile-id/authentication
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
This method is the main entry point to authentication logic. |
...
🎯 Request parameters
Parameter | Required | Description |
|---|---|---|
phoneNumber | Required | Phone number of the signer with the country code in the format of +xxxxxxxxx |
nationalIdentityNumber | Required | National identification number |
language | Required | Language for user dialog in mobile phone. 3-letters capitalized acronyms are used. Possible values: EST, ENG, RUS, LIT. NB! If you use language="LIT" to send to Estonian number (+372...) or you use language="EST" to send to Lithuanian number (+370...) then internally language is replaced with "ENG". |
displayText | Optional | Text to display for authentication consent dialog on the mobile device. Limited to 40 characters including up to 5 characters from extension table ( €[]^|{}\ ). |
...
🥫 Response parameters
Parameter | Required | Description |
|---|---|---|
sessionId | Required | A string that can be used to request operation result. |
verificationCode | Required | Verification code is needed, so that user can bind together the session on the browser and the authentication request on mobile device. |
...
🗒️ Example
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
|
...
| Status | ||||
|---|---|---|---|---|
|
https://sandbox-esignature.ondato.com/mobile-id/authentication
This method is the main entry point to authentication logic.
Request parameters
View More
...
Parameter
...
Required
...
Description
...
phoneNumber
...
Required
...
Phone number of the signer with the country code in the format of +xxxxxxxxx
...
nationalIdentityNumber
...
Required
...
National identification number
...
language
...
Required
...
Language for user dialog in mobile phone. 3-letters capitalized acronyms are used. Possible values: EST, ENG, RUS, LIT. NB! If you use language="LIT" to send to Estonian number (+372...) or you use language="EST" to send to Lithuanian number (+370...) then internally language is replaced with "ENG".
...
displayText
...
Optional
...
Text to display for authentication consent dialog on the mobile device. Limited to 40 characters including up to 5 characters from extension table ( €[]^|{}\ ).
...
amlScreeningRequired
...
Optional
...
Do execute AML screening?
Response parameters
...
Parameter
...
Required
...
Description
...
sessionId
...
Required
...
A string that can be used to request operation result.
...
verificationCode
...
Required
...
Verification code is needed, so that user can bind together the session on the browser and the authentication request on mobile device.
Body
| Code Block |
|---|
{
"phoneNumber": "+37060000666",
"nationalIdentityNumber": "50001018865",
"language": "ENG",
"displayText": "Please confirm transaction"
} |
GET Get Authentication Session Status
https://sandbox-esignature.ondato.com/mobile-id/authentication/:sessionId
Response parameters
...
Parameter
...
Required
...
Description
...
countryCode
...
Required
...
Country code
...
nationalIdentityNumber
...
Required
...
National identification number
...
name
...
Required
...
Person name
...
surname
...
Required
...
Person surname
...
isPep
...
Optional
...
If amlScreeningRequired was used in Create Authentication Session method
...
/{sessionId}
...
🥫 Response parameters
Parameter | Required | Description |
|---|---|---|
countryCode | Required | Country code |
nationalIdentityNumber | Required | National identification number |
name | Required | Person name |
surname | Required | Person surname |
🗒️ Example
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
|
...
| Status | ||||
|---|---|---|---|---|
|
https://sandbox-esignature.ondato.com/mobile-id/document-signature
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
This method is the main entry point to signing logic. |
...
🎯 Request parameters
Parameter | Required | Description |
|---|---|---|
phoneNumber | Required | Phone number of the signer with the country code in the format of +xxxxxxxxx |
nationalIdentityNumber | Required | National identification number |
language | Required | Language for user dialog in mobile phone. 3-letters capitalized acronyms are used. Possible values: EST, ENG, RUS, LIT. NB! If you use language="LIT" to send to Estonian number (+372...) or you use language="EST" to send to Lithuanian number (+370...) then internally language is replaced with "ENG". |
displayText | Optional | Text to display for authentication consent dialog on the mobile device. Limited to 60 characters or 128 bytes in UTF-8 encoding, whichever is reached first. |
file | Required | File to sign |
...
🥫 Response parameters
Parameter | Required | Description |
|---|---|---|
sessionId | Required | A string that can be used to request operation result. |
verificationCode | Required | Verification code is needed, so that user can bind together the session on the browser and the authentication request on mobile device. |
🗒️ Example
| Code Blockexpand | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
|
...
|
| Expand | ||
|---|---|---|
| ||
|
...
| Status | ||||
|---|---|---|---|---|
|
https://sandbox-esignature.ondato.com/mobile-id/document-signature/:sessionId{sessionId}
| Panel | ||||||
|---|---|---|---|---|---|---|
| ||||||
This method can be used to retrieve session result from Mobile-ID backend. This is a long poll method, meaning it might not return until a timeout expires. Caller can tune the request parameters inside the bounds set by service operator. |
...
☝️ Preconditions
Session is present in the system and the request is either running or has been completed less than 5 minutes ago.either running or has been completed less than 5 minutes ago.
...
🗒️ Example
Request
| Code Block |
|---|
curl --location 'https://sandbox-esignature.ondato.com/mobile-id/document-signature/{sessionId}' \
--header 'x-api-key: {your-api-key}' |