Table of Contents

🔑 Authorization

You'll need your API key. If you don't have it, please contact support@ondato.com.
Remember to include an x-api-key header in every request.

Think of your API key as a password:

Securely store it.
Refrain from sharing it with anyone outside of your organization.
Avoid placing it in the source code.

☁️ Environments

Environment	Swagger URL	Base URL
Sandbox	https://sandbox-esignature.ondato.com/swagger/index.html	`https://sandbox-esignature.ondato.com`
Production	https://esignature.ondato.com/swagger/index.html	`https://esignature.ondato.com`

🔷 Smart-ID

Smart-ID is a universal, app-based strong authentication and 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 have no access to Smart-ID Basic accounts.

Learn more from the Smart-ID documentation.

🧪 Test accounts for automated testing

Country	National identity number	Certificate level	Response description
EE \| 🇪🇪	30303039914	QUALIFIED	Successful signing and identification
LV \| 🇱🇻	030303-10012	QUALIFIED	Successful signing and identification
LT \| 🇱🇹	30303039914	QUALIFIED	Successful signing and identification
EE \| 🇪🇪	30403039917	QUALIFIED	User cancelled session
LV \| 🇱🇻	030403-10016	QUALIFIED	User cancelled session
LT \| 🇱🇹	30403039917	QUALIFIED	User cancelled session
EE \| 🇪🇪	30403039983	QUALIFIED	User does not react
LV \| 🇱🇻	030403-10083	QUALIFIED	User does not react
LT \| 🇱🇹	30403039983	QUALIFIED	User does not react

📍 Endpoints

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 or Optional?	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.

🥫 Response structure

Parameter	Required or Optional?	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

Request

curl --location 'https://sandbox-esignature.ondato.com/smart-id/authentication' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {apiKey}' \
--data '{
	"countryCode": "LT",
    "certificateLevel": "QUALIFIED",
	"nationalIdentityNumber": "30303039914",
	"displayText": "Please confirm transaction"
}'

Response

{
    "sessionId": "8c00e8b378b848bbbc3cd1e2c018ef39",
    "verificationCode": "0818"
}

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 or Optional?	Description
countryCode	Required	Country code
nationalIdentityNumber	Required	National identification number
name	Required	Person name
surname	Required	Person surname

🗒️ Example

Request

curl --location 'https://sandbox-esignature.ondato.com/smart-id/authentication/{sessionId}' \
--header 'x-api-key: {your-api-key}'

Response

{
    "countryCode": "LT",
    "name": "OK",
    "nationalIdentityNumber": "30303039914",
    "surname": "TESTNUMBER"
}

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 or Optional?	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 or Optional?	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

Request

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"'

Response

{
    "sessionId": "93d4194663584e2d9c008d8b79cbb227",
    "verificationCode": "5488"
}

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.

🗒️ Example

Request

curl --location 'https://sandbox-esignature.ondato.com/smart-id/document-signature/{sessionId}' \
--header 'x-api-key: {your-api-key}'

🔶 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.

Learn more from the Mobile-ID documentation.

🧪 Test accounts for automated testing

Country	Phone number	National identity number	Response description
EE \| 🇪🇪	+37269930366	51307149560	Successful signing and identification
LT \| 🇱🇹	+37069930366	60706225732	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
EE \| 🇪🇪	+37266000266	50001018908	User does not react
LT \| 🇱🇹	+37066000266	50001018908	User does not react

📍 Endpoints

POST Create Authentication Session

https://sandbox-esignature.ondato.com/mobile-id/authentication

This method is the main entry point to authentication logic.

🎯 Request parameters

Parameter	Required or Optional?	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 or Optional?	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

Request

curl --location 'https://sandbox-esignature.ondato.com/mobile-id/authentication' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your-api-key}' \
--data '{
    "phoneNumber": "+37060000666",
    "nationalIdentityNumber": "50001018865",
	"language": "ENG",
	"displayText": "Please confirm transaction"
}'

Response

{
    "sessionId": "e762aac179bd4aca877b12e3cfa5009e",
    "verificationCode": "5158"
}

GET Get Authentication Session Status

https://sandbox-esignature.ondato.com/mobile-id/authentication/{sessionId}

🥫 Response parameters

Parameter	Required or Optional?	Description
countryCode	Required	Country code
nationalIdentityNumber	Required	National identification number
name	Required	Person name
surname	Required	Person surname

🗒️ Example

Request

curl --location 'https://sandbox-esignature.ondato.com/mobile-id/authentication/{sessionId}' \
--header 'x-api-key: {your-api-key}'

Response

{
    "countryCode": "LT",
    "name": "MARY ÄNN",
    "nationalIdentityNumber": "50001018865",
    "surname": "O’CONNEŽ-ŠUSLIK TESTNUMBER"
}

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 or Optional?	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 or Optional?	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

Request

curl --location 'https://sandbox-esignature.ondato.com/mobile-id/document-signature' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {your-api-key}' \
--form 'phoneNumber="+37060000666"' \
--form 'nationalIdentityNumber="50001018865"' \
--form 'language="ENG"' \
--form 'displayText="Please sign"' \
--form 'file=@"/Users/user/Downloads/document.pdf"'

Response

{
    "sessionId": "90050e0ab55a4c099a55fb5c222aa3b8",
    "verificationCode": "3401"
}

GET Get Signed Document

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.

🗒️ Example

Request

curl --location 'https://sandbox-esignature.ondato.com/mobile-id/document-signature/{sessionId}' \
--header 'x-api-key: {your-api-key}'

E-Signature API

🔑 Authorization

☁️ Environments

🔷 Smart-ID

🎚️ Smart-ID levels

🧪 Test accounts for automated testing

📍 Endpoints

POST Create Authentication Session

🎯 Request parameters

🥫 Response structure

🗒️ Example

GET Get Authentication Session Status

☝️ Preconditions

🥫 Response structure

🗒️ Example

POST Create Signature Session

🎯 Request parameters

🥫 Response parameters

🗒️ Example

GET Get Signed Document

☝️ Preconditions

🗒️ Example

🔶 Mobile-ID

🧪 Test accounts for automated testing

📍 Endpoints

POST Create Authentication Session

🎯 Request parameters

🥫 Response parameters

🗒️ Example

GET Get Authentication Session Status

🥫 Response parameters

🗒️ Example

POST Create Signature Session

🎯 Request parameters

🥫 Response parameters

🗒️ Example

GET Get Signed Document

☝️ Preconditions

🗒️ Example

0 Comments