Data API in detail

Here you can find every call explained in detail with sample requests and responses

Data API endpoints

Authenticate your users:

Work with user documents:

Get Token

API reference for developers

📘

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

  • 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) name or the person
-last_name (string) surname of the person
-serial_number (string) serial number of the document (according to ETSI)
-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/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-39010101111",
        "address": null,
        "birth_date": "1990-10-10",
        "city": null,
        "document_expiration_date": "05-05-2025",
        "email": "[email protected]",
        "personal_number": "39010101111",
        "phone_number": "+37084854494",
        "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/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>

📘

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
}