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

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/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)
-last_name (string)
-serial_number (string)
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/get_data
    -X POST
    -H "Content-type: application/json"
    -H "Authorization: HMAC <HMAC_STRING>"
    -d @- << EOF
{
    "token": "<hermes_token_el1gLMbW_qVhIwZeDvuF7Epk9ZxYYqbL7_cWdbYryGI>"
}
EOF

Example response:

{
    "customer_id": "cust_uGgWMSI_JKBFsNsXh9UTY14A-zxPnZ_5mPkk2A6-U_U",
    "data": {
        "first_name": "Matas",
        "last_name": "Balcaitis",
        "serial_number": "PNOLT-39412161111"
    },
    "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/user/cust_uGgWMSI_JKBFsNsXh9UTY14A-zxPnZ_5mPkk2A6-U_U/documents
    -X GET
    -H "Content-type: application/json"
    -H "Authorization: HMAC <HMAC_STRING>"

Example response:

[
    {
        "created": "2020-08-13 08:11:07",
        "id": "7872e574-7454-4f76-bd67-d79b1dc9de36",
        "name": "myamazingfile.pdf",
        "status": "pending",
        "type": "pdf"
    },
    {
        "created": "2020-08-13 08:11:31",
        "id": "abc77afa-0d4e-4d36-9dac-a05f4a614a88",
        "name": "hash_to_sign.p7s",
        "status": "pending",
        "type": "hash"
    },
    {
        "created": "2020-08-13 08:11:36",
        "id": "8b1016dc-7eb4-44d1-bf0c-8a8ba132cc66",
        "name": "hash_to_sign.p7s",
        "status": "signing",
        "type": "hash"
    }
]

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/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": "2020-08-13 08:11:07",
    "id": "7872e574-7454-4f76-bd67-d79b1dc9de36",
    "name": "myamazingfile.pdf",
    "status": "pending",
    "type": "pdf",
    "signed": {
        "expires": 1618840648,
        "title": "myamazingfile.pdf",
        "url": "https://some_document_url"
    }
}

Upload File

API reference for developers

📘
Required input
BODY PARAMS

content (string) should be base64 string of your pdf file content

digest (string) should be sha1 string of your pdf file content

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
id (string) uploaded file id
success (bool) upload success flag

🚧
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

Example request:

curl https://core-hermes.zealid.com/mediator/api/upload/cust_uGgWMSI_JKBFsNsXh9UTY14A-zxPnZ_5mPkk2A6-U_U
    -X POST
    -H "Content-type: application/json"
    -H "Authorization: HMAC <HMAC_STRING>"
    -d @- << EOF
{
    "content": "base64...",
    "digest": "sha1...",
    "filename": "my_document.pdf"
}
EOF

Example response:

{
    "id": "d7d8c763-75b5-42ec-a42c-849cbbc6fdda",
    "success": true
}

Upload Hash

API reference for developers

📘
Required input
BODY PARAMS

content (string) should be the SHA256 hash you want to sign (base64 encoded)

hashname (string) name how you want to call your hash

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
id (string) uploaded hash id
success (bool) upload success flag

🚧
Be aware!

Use correct subdomain:

core-hermes - production environment

hermes-dev - testing environment

curl https://core-hermes.zealid.com/mediator/api/upload/hash/cust_uGgWMSI_JKBFsNsXh9UTY14A-zxPnZ_5mPkk2A6-U_U
    -X POST
    -H "Content-type: application/json"
    -H "Authorization: HMAC <HMAC_STRING>"
    -d @- << EOF
{
    "content": "any_hash_you_want_to_sign",
    "hashname": "my_first_hash"
}
EOF

{
    "id": "d7d8c763-1234-42ec-a42c-849cbbc6fdda",
    "success": true
}

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 either to uploaded PDF or HASH

Example request:

curl https://core-hermes.zealid.com/mediator/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>

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!

Upload File

📘
Required input

📘
Expected output

🚧
Be aware!

Upload Hash

📘
Required input

📘
Expected output

🚧
Be aware!

Sign

📘
Required input

📘
Expected output

🚧
Be aware!

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!

Upload File

📘Required input

📘Expected output

🚧Be aware!

Upload Hash

📘Required input

📘Expected output

🚧Be aware!

Sign

📘Required input

📘Expected output

🚧Be aware!

📘
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!