Downloading session images

Before you start

• A current Python release and the requests package.
• Put the API address that came with your access into the environment variable API_BASE_URL. The samples never hard-code an address.
• Keep tokens and passwords out of the script and out of a repository. The samples read them from environment variables.

What you need

• A user token from user authorization, sent in the token header. A permanent API token does not work for images.
• The user must have the permission to view the images of KYC documents. Without it, as with an invalid token, the server answers 404.

How it works

1. Sign in and get the user token.
2. Find the session with filter sessions, searching by session.
3. Read the image links from the session object.
4. Fetch each link with the token header and write the bytes to a file.

The script

import os
import sys

import requests

API = os.environ["API_BASE_URL"]


def login(email: str, password: str) -> str:
    reply = requests.post(f"{API}/user/login", json={"email": email, "password": password}, timeout=30)
    if reply.status_code != 200:
        sys.exit(f"login refused: HTTP {reply.status_code}")
    return reply.json()["token"]


def find_session(token: str, session_id: str) -> dict:
    reply = requests.post(
        f"{API}/kyc/sessions/filter",
        headers={"token": token},
        json={"page": 1, "pageSize": 20, "filters": {"session": session_id}},
        timeout=30,
    )
    body = reply.json()
    if body.get("status") != "ok":
        sys.exit(f"search failed: status {body.get('status')}")
    for session in body["results"]["sessions"]:
        if session.get("sessionId") == session_id:
            return session
    sys.exit("session not found")


def document_links(session: dict) -> list[tuple[str, str]]:
    links = []
    for step_index, step in enumerate(session.get("results") or []):
        if step.get("type") == "document":
            for i, url in enumerate(step.get("images") or []):
                # The step index keeps the names of different document steps apart.
                links.append((url, f"step{step_index}_document_{i}.jpg"))
    return links


def download(token: str, session_id: str, out_dir: str) -> None:
    session = find_session(token, session_id)
    os.makedirs(out_dir, exist_ok=True)
    for url, name in document_links(session):
        reply = requests.get(url, headers={"token": token}, timeout=30)
        if reply.status_code != 200:
            print(f"{name}: HTTP {reply.status_code}")
            continue
        with open(os.path.join(out_dir, name), "wb") as f:
            f.write(reply.content)
        print(f"{name}: {len(reply.content)} bytes")


if __name__ == "__main__":
    token = login(os.environ["DASHBOARD_EMAIL"], os.environ["DASHBOARD_PASSWORD"])
    download(token, "00000000-0000-0000-0000-000000000000", "session_images")

The sample collects the document images. The selfie and liveness steps of the session object carry their own links in the same way. See the session object.

Notes

• Images are personal data. Store them with care and delete them when you no longer need them.
• When the images must be destroyed on request, use erase session personal data.