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
{
"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
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/TEST PDF.pdf"'
GET Get Signature Session Status
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.
Response parameters
Parameter | Required | Description |
|---|---|---|
nationalIdentityNumber | Required | National identification number |
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 |
POST Create Authentication Session
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
{
"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 |
POST Create Signature Session
https://sandbox-esignature.ondato.com/mobile-id/document-signature
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
curl --location --request POST 'https://sandbox-esignature.ondato.com/mobile-id/document-signature/' \
--header 'x-api-key: {your-api-key}' \
--form 'phoneNumber="37060000666"' \
--form 'nationalIdentityNumber="50001018865"' \
--form 'language="ENG"' \
--form 'displayText="Please confirm transaction"' \
--form 'file=@"/C:/Users/user/Downloads/TEST PDF.pdf"'
GET Get Signature Session Status
https://sandbox-esignature.ondato.com/mobile-id/document-signature/:sessionId
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.
Response parameters
Parameter | Required | Description |
|---|---|---|
nationalIdentityNumber | Required | National identification number |
Add Comment