Data API in detail

Data API endpoints

Authenticate your users:

Work with user documents:

Get Token

📘
Required input
BODY PARAMS

grant_type (string) should be "authorization_code"

code (string) should be the code that you receive as url parameter after scanning authentication QR code

redirect_uri (string) should be your desired redirect point

HEADERS

Authorization (string) generated HMAC_STRING for particular request.
Content-Type (string) should be "application/json"

📘
Expected output
access_token (string) HERMES_TOKEN
status (string) response status

🚧
Be aware!

After receiving HERMES_TOKEN it's valid only for particular period of time

Default is 30min

Contact [email protected] for changes in token validity

Use correct subdomain:

core-hermes - production environment

hermes-dev - testing environment

Example request:

curl https://core-hermes.zealid.com/mediator/api/orpheus/v2.0/api/get_token
    -X POST
    -H "Content-type: application/json"
    -H "Authorization: HMAC <HMAC_STRING>"
    -d @- << EOF
{
    "grant_type": "authorization_code",
    "code": "<HERMES_CODE>",
    "redirect_uri": "<https://example.com>"
}
EOF

Example response:

{
    "access_token": "hermes_token_el1gLMbW_qVhIwZeDvuF7Epk9ZxYYqbL7_cWdbYryGI",
    "status": "OK"
}

Get Data

API reference for developers

📘
Required input
BODY PARAMS

token (string) HERMES_TOKEN that you receive from get_token endpoint

HEADERS

Authorization (string) generated HMAC_STRING for particular request.
Content-Type (string) should be "application/json"

📘
Expected output
Default output of get_data call includes:
customer_id (string) your customer_id
data (dictionary) personal data which is configurable eg.:
-first_name (string) name or the person
-last_name (string) surname of the person
-serial_number (string) serial number according to ETSI 319 412-1 5.1.3 (Natural person semantics identifier)
-document_expiration_date (string/optional) expiration date of the document
-personal_number (string/optional) personal number
-address (string/optional) address of the person
-city (string/optional) city
-postcode (string/optional) postcode
-birth_date (string/optional) birth date of the person
-phone_number (string/optional) phone number
-email (string/optional) email
status (string) response status
success (bool) response success flag

🚧
About response attributes

The customer_id is required in every call related to actions with documents (upload, sign, retrieve)

Data field is configurable, but depends on the data retrieved from user's bank (sometimes can be empty fields).

Default data fields are: first_name, last_name, serial_number

Possible optional data fields: personal_number, document_expiration_date, address, birth_date, city, postcode, email, phone_number

Contact [email protected] regarding customised data fields in response

🚧
Use correct subdomain:

core-hermes - production environment

hermes-dev - testing environment

Example request:

curl https://core-hermes.zealid.com/mediator/api/orpheus/v2.0/api/get_data
    -X POST
    -H "Content-type: application/json"
    -H "Authorization: HMAC <HMAC_STRING>"
    -d @- << EOF
{
    "token": "<HERMES_TOKEN>"
}
EOF

Example response:

{
    "customer_id": "cust_uGgWMSI_JKBFsNsXh9UTY14A-zxPnZ_5mPkk2A6-U_U",
    "data": {
        "first_name": "Žošuą",
        "last_name": "Ķūņpala",
        "serial_number": "PNOLT-39010101111",
        "address": null,
        "birth_date": "1990-10-10",
        "city": null,
        "document_expiration_date": "05-05-2025",
        "email": "[email protected]",
        "personal_number": "39010101111",
        "phone_number": "+37060000000",
        "postcode": null,
    },
    "status": "success",
    "success": true
}

Get Documents

API reference for developers

📘
Required input
BODY PARAMS

customer_id (string) your customer_id that you receive from get_data endpoint

HEADERS

Authorization (string) generated HMAC_STRING for particular request.
Content-Type (string) should be "application/json"

📘
Expected output
Returns array of all user documents uploaded/signed with user customer_id including terms&conditions document.
created (timestamp with time zone) timestamp when document was uploaded
id (string) document id
name (string) document name
status (string) document signing status
type (string) document type
signed (dictionary) - optional- info about the signed document:
-expires (timestamp UTC) expiration time for document url
-title (string) document title
-url (string) document url

🚧
Be aware!

We do not provide document storage service!

All documents have expiration time - 30 days

All documents older than 30 days are removed from our storage - make sure to download your documents before expiration time

Use correct subdomain:

core-hermes - production environment

hermes-dev - testing environment

Example request:

curl https://core-hermes.zealid.com/mediator/api/orpheus/v2.0/api/user/cust_uGgWMSI_JKBFsNsXh9UTY14A-zxPnZ_5mPkk2A6-U_U/documents
    -X GET
    -H "Content-type: application/json"
    -H "Authorization: HMAC <HMAC_STRING>"

Example response:

[
    {
        "created": "2022-08-13 08:11:07",
        "id": "7872e574-7454-4f76-bd67-d79b1dc9de36",
        "name": "myamazingfile.pdf",
        "status": "pending",
        "type": "pdf"
    },
    {
        "created": "2023-03-27 07:44:14",
        "id": "d772e574-7454-4f76-bd67-d79b1dre211q",
        "name": "my_document.pdf",
        "status": "signed",
      	"signed": {
            "expires": 1680266807,
            "title": "Sign via orpheus",
            "url": "https://some_document_url"
        },
        "status": "signed",
        "stored_until": "2023-04-26",
        "type": "pdf"
    }
]

Get Document by ID

API reference for developers

📘
Required input
BODY PARAMS

customer_id (string) your customer_id that you receive from get_data endpoint

id (string) document id

HEADERS

Authorization (string) generated HMAC_STRING for particular request.
Content-Type (string) should be "application/json"

📘
Expected output
Returns requested user document by id:
created (timestamp with time zone) timestamp when document was uploaded
id (string) document id
name (string) document name
status (string) document signing status
type (string) document type
signed (dictionary) - optional- info about the signed document:
-expires (timestamp UTC) expiration time for document url
-title (string) document title
-url (string) document url

🚧
Be aware!

We do not provide document storage service!

All documents have expiration time - 30 days

All documents older than 30 days are removed from our storage - make sure to download your documents before expiration time

Use correct subdomain:

core-hermes - production environment

hermes-dev - testing environment

Example request:

curl https://core-hermes.zealid.com/mediator/api/orpheus/v2.0/api/user/cust_uGgWMSI_JKBFsNsXh9UTY14A-zxPnZ_5mPkk2A6-U_U/documents/7872e574-7454-4f76-bd67-d79b1dc9de36
    -X GET
    -H "Content-type: application/json"
    -H "Authorization: HMAC <HMAC_STRING>"

Example response

{
        "created": "2023-03-27 07:44:14",
        "id": "d772e574-7454-4f76-bd67-d79b1dre211q",
        "name": "my_document.pdf",
        "status": "signed",
      	"signed": {
            "expires": 1680266807,
            "title": "Sign via orpheus",
            "url": "https://some_document_url"
        },
        "status": "signed",
        "stored_until": "2023-04-26",
        "type": "pdf"
}

Get Upload URL

API reference for developers

📘
Required input
BODY PARAMS

filename (string) should be your desired filename with ".pdf" extension

PATH PARAMS

customer_id (string) your customer id that you receive from get_data endpoint

HEADERS

Authorization (string) generated HMAC_STRING for particular request.
Content-Type (string) should be "application/json"

📘
Expected output
expires (timestamp UTC) expiration time for upload URL
id (string) uploaded file id
put_url (string) URL to upload pdf file using PUT request
success (bool) upload success flag

🚧
Be aware!

Use correct subdomain:

core-hermes - production environment

hermes-dev - testing environment

Example request:

curl https://core-hermes.zealid.com/mediator/api/orpheus/v2.0/api/upload_url/cust_uGgWMSI_JKBFsNsXh9UTY14A-zxPnZ_5mPkk2A6-U_U
    -X POST
    -H "Content-type: application/json"
    -H "Authorization: HMAC <HMAC_STRING>"
    -d @- << EOF
{
    "filename": "my_document.pdf"
}
EOF

Example response:

{
  	"expires": 1640163134,
    "id": "d7d8c763-75b5-42ec-a42c-849cbbc6fdda",
    "put_url": "https://onboarding-api-dev.zealid.com/temporary_document_storage/documents.tmp/d7d8c763-75b5-42ec-a42c-849cbbc6fdda.pdf?AWSAccessKeyId=accesskey&Signature=aqwertyqwerty%2BZ8%3D&Expires=1640163134"
    "success": true
}

Upload File

API reference for developers

📘
Required input
BODY PARAMS

PDF itself should be added as a binary file in a request body

📘
Expected output
empty response

🚧
Be aware!

There exists file size limit which currently stand at 30Mb

If you have a need to work with bigger files please contact our support!

Use correct subdomain:

core-hermes - production environment

hermes-dev - testing environment

curl -T my_document.pdf "https://onboarding-api-dev.zealid.com/temporary_document_storage/documents.tmp/d7d8c763-75b5-42ec-a42c-849cbbc6fdda.pdf?AWSAccessKeyId=accesskey&Signature=aqwertyqwerty%2BZ8%3D&Expires=1640163134"

Sign

API reference for developers

📘
Required input
BODY PARAMS

document_id (string) id of document that you want to sign (after uploading document you retrieve it's id in response)

title (string) document title as it will appear in the ZealiD app when signing

redirect_uri (string) should be your preferred redirect url where you will be redirected after scanning QR code in your browser

customer_id (string) should be your customer id which you receive during get_data response

HEADERS

Authorization (string) generated HMAC_STRING for particular request.
Content-Type (string) should be "application/json"

📘
Expected output
HTML template including QR code that you need to scan with your ZealiD app to confirm signing transaction

🚧
Be aware!

Use correct subdomain:

core-hermes - production environment

hermes-dev - testing environment

NOTE: as "document" we refer to uploaded PDF

Example request:

curl https://core-hermes.zealid.com/mediator/api/orpheus/v2.0/api/sign
    -X POST
    -H "Content-type: application/json"
    -H "Authorization: HMAC <HMAC_STRING>"
    -d @- << EOF
{
    "document_id": "d7d8c763-75b5-42ec-a42c-849cbbc6fdda",
    "title": "my_first_signing",
    "redirect_url": "https://example.com",
    "customer_id": "cust_uGgWMSI_JKBFsNsXh9UTY14A-zxPnZ_5mPkk2A6-U_U"
}
EOF

Example response:

<!doctype html>\n<html>\n<head>\n<meta charset="utf-8">\n<meta name="viewport" content="width=device-width; initial-scale=1.0; maximum-scale=1.0; user-scalable=0;" />\n\n<style>\n    html, body {\n        height: 100%;\n        margin: 0;         /* Reset default margin on the body element */\n    }\n    iframe {\n        display: block;       /* iframes are inline by default */\n        background: #fff;\n        border: none;         /* Reset default border */\n        width: 100%;\n        height: 100%;\n    }\n</style>\n\n<script type=text/javascript src="/static/jquery.js"></script>\n\n<script type="text/javascript">\nrunScript();\n\nfunction runScript() {\n    if(window.$) {\n        $(function () {\n            var redirectLink = \'\';\n            var checkStatusTime = 1000.0;\n            var requestTimeout = 5000.0;\n            var redirectIn = 0;\n            var redirectToUrl = function() {\n                document.location = redirectLink;\n            };\n            var request_additional_session_data = false;\n            var have_additional_session_data = false;\n            var cookies;\n            var cookie;\n            var cookie_domain;\n            var url = "";\n            var key = "";\n\n            var worker = function () {\n                url = \'https://hermes-dev.zealid.com/mediator/api/auth_link/remote_session_status/g6SyUEe--Ar3I9IkexBE7gh2uOYcAISOj9iSQ642QkU\';\n\n                $.ajax({\n                    url: url,\n                    timeout: requestTimeout,\n                    success: function(data) {\n                        console.log("DATA: " + data);\n                        console.log("Status: " + data.status);\n\n                        if ("redirect_url" in data && data.redirect_url != false) {\n                            console.log("Redirecting to: " + data.redirect_url);\n                            redirectLink = data.redirect_url;\n                            parent.postMessage(redirectLink, "*");\n                            redirectIn = data.redirect_in * 1000.0;\n                            setTimeout(redirectToUrl, redirectIn);\n                        } else {\n                            setTimeout(worker, checkStatusTime);\n                        }\n                    },\n                    failed: function() {\n                        setTimeout(worker, checkStatusTime);\n                    },\n                    error: function() {\n                        setTimeout(worker, checkStatusTime);\n                    }\n                });\n            };\n\n            worker();\n\n            $(\'.cancel-button\').on(\'click\', function () {\n                document.location = \'\';\n            });\n        });\n    } else {\n        window.setTimeout(runScript, 100);\n    }\n}\n</script>\n\n</head>\n\n<body>\n        <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAcIAAAHCAQAAAABUY/ToAAAEBklEQVR4nO2cUYrjOBCGv1oZ+qXBgjlA5mEPsCcY53EfFuZIQzMnapgD2CeYK2wfoEGGfWmwqX2QZMtJJ1myyUycqf/B3dj6sGUqqiqVZFHOU/fbmSAYaaSRRhpppJFG3h4pSRV0HmTbi8gWoBOR1LTPrbYXuaeR90Kiqqo0qqoaXDq0gLY4pZnOxcPUuF1XP428Hlmlv72H5hnoPr8J4AZpwge08w4BF1sJuOEnPq2Rt0hWe2f6BwVGURiQJnjR7vOr7M0BrKufRl6P3LUhoQ75/94DtSLUIM3zpe5p5H2Re/FQm89pW6tCPWDxkJFHFc0iKQXRBw65ldmQkaWiL9sJdrTbvEkcgrrNAJ136G6rdfXTyOuTvUg8dB4Ap+ncpE4qZHvJexp5H2QR+6jqQI6CVLXFpXPxECBeUPNlRpbK8VAZNc/2QpOv7jYxGzIyK6VawcXRB+qBlI3pQD6XrakJ08i1rn4aeT0yj0PReUGRwkdrArStsy+LGZrZkJGl8jgENDowOy9tYwOX0rHJfMyGjFxqHnNUA8zl1hRTh1x9nRya+TIjlypsqJ2ioCYfyinqOeI2GzKyVE7EkstKYU+2lOS3psxfwy8XU+9XpRc6sh59Xf38v6RInJhWlS1Ote133twokM/J9iL3NHItZIfvR3+K1LZ/UJqXipiNdZsBlAD0FfLlZZ6iziH2kd/nX7/zMXw752lP6TDpvhPOI8HLscHmMNkT9PHP8+55XIfJxy3884Pf7SnFlyfUr5JrY68VUA18+v43VVxJ1IPSA9RveSXR4df+7ePXPx5dOHHP9yQevDv1tO/p0zGnwq39su+LzNFNnokmpvVTSWMKp1PSH8PuXykeOkzOC9B/3D1vkVys/Vgk+CmZD+Q5ozmwNhsyslRR62iCU23roZhtjCXYdEE15ftmQ0aWShZR5ynqWBEL5ZaO2K4oeJgNGfkemRYM6dNGVbaMok9+lBhEx3nHlwel81NettJ+GnlxshiHUiQdynEoOq+2nur2s5NbVz+NvB5ZZMsC1SDNsxskLQB5E+g/qIBA5wN0/jUn0evqp5HXI6d9HXOBjFw0mzdyzOGRWt3eyF0V9bJiD4emPD75sqn1ZEhmQ0ZO0qXSFqAcGRVq5hHJbMjIPXLx3Q+nNC8iIp4UZ8d1+rHmOsqC/BlPa+Rtkfv7XGtNSxin6aLFEkbLy4zcVeHB0qQixOJ9owPE3RxFOSQ7PbMhIw+QIpsUROuThxQe9SK7G6Zv4mmNvAVybzVF046Qdt6Paa90/OpQPwowVjY/ZORS+/FQ2l9WjjkwzWJbbm/k+2QnKREDcq2j2+RJoqheRMSP9j1GI5fa/77Zf5R949xII4000kgjjbwT8l9p2q+s5kF1XQAAAABJRU5ErkJggg==" alt="Discovery QR" />\n</body>\n</html>

📘
Webhook after file is signed
ZealID can send webhook to client after the file is signed.
Webhook contains authenticated information, signed by JWT with client's secret key:

timestamp - utc timestamp when transaction was created

document_id - id of signed document

customer_id - id of the user who signed the file

session_id - transaction session id

status - signing status (can be completed or failed)

exp - identifies the expiration time after which the JWT is NOT accepted for processing

NOTES

The request method is POST

The Content-Type is application/json

Webhook url must be https, so that the data is secured via transport encryption

Contact [email protected] if you want to register your webhook url.

Webhook example:

{
  'timestamp': 1624443832.888235, 
  'document_id': 'some_document_id', 
  'customer_id': 'cust_VksdicvIP9-uOEeUNY8wiszlFyEgs', 
  'session_id': 'S4JIlDOjZgyAp8_01A2jrs1pB8', 
  'status': 'completed', 
  'exp': 1624433092
}

Data API in detail

Data API endpoints

Get Token

📘
Required input

📘
Expected output

🚧
Be aware!

Get Data

📘
Required input

📘
Expected output

🚧
About response attributes

🚧
Use correct subdomain:

Get Documents

📘
Required input

📘
Expected output

🚧
Be aware!

Get Document by ID

📘
Required input

📘
Expected output

🚧
Be aware!

Get Upload URL

📘
Required input

📘
Expected output

🚧
Be aware!

Upload File

📘
Required input

📘
Expected output

🚧
Be aware!

Sign

📘
Required input

📘
Expected output

🚧
Be aware!

📘
Webhook after file is signed

Data API endpoints

Get Token

📘Required input

📘Expected output

🚧Be aware!

Get Data

📘Required input

📘Expected output

🚧About response attributes

🚧Use correct subdomain:

Get Documents

📘Required input

📘Expected output

🚧Be aware!

Get Document by ID

📘Required input

📘Expected output

🚧Be aware!

Get Upload URL

📘Required input

📘Expected output

🚧Be aware!

Upload File

📘Required input

📘Expected output

🚧Be aware!

Sign

📘Required input

📘Expected output

🚧Be aware!

📘Webhook after file is signed

📘
Required input

📘
Expected output

🚧
Be aware!

📘
Required input

📘
Expected output

🚧
About response attributes

🚧
Use correct subdomain:

📘
Required input

📘
Expected output

🚧
Be aware!

📘
Required input

📘
Expected output

🚧
Be aware!

📘
Required input

📘
Expected output

🚧
Be aware!

📘
Required input

📘
Expected output

🚧
Be aware!

📘
Required input

📘
Expected output

🚧
Be aware!

📘
Webhook after file is signed