Skip to content

Getting Session Data via API

This page outlines the most common procedure for programmatically receiving and analyzing session data triggered by a system webhook event.

Authorization

To access session data, use an authorization method. We recommend using application keys for seamless API integration.

For a detailed understanding of all authentication methods, refer to the Authorization page.

We recommend creating an application key with the All Session: READ permission:

Adding API key

This grants the key the necessary rights to retrieve data for any session.

Session Data Structure

A session serves as a container for all information collected during the workflow. It consists of two primary types of data, which are dynamic and depend entirely on the specific workflow used for data capture:

Data type Key Description Retrieval method
Session properties properties Structured data (for example, extracted fields, metadata) received during the workflow. Directly available in the session JSON response.
Session files files Unstructured data (for example, images, binary files, HTTP request/response). Each file has a unique, retrievable URL within the session response.

Use Case: Retrieving Passport Data

This example demonstrates how to combine the elements above to retrieve a specific piece of data, such as a scanned passport image, upon receiving a webhook notification.

  1. Obtain API key: Secure an application key with the required All Session: READ permission to access the platform programmatically.

  2. Configure Webhook: Set up your webhook to deliver the sessionId to your endpoint when an event occurs.

  3. Retrieve Session Data: On receiving the webhook event, execute a GET request to the Session API endpoint to retrieve the full session data.

API request example

Use the following cURL command structure to fetch the session data:

curl '<base_url>/api/sessions/<id>' \
  -H 'accept: application/json' \
  -H 'authorization: Apikey <apikey>'
  • Replace <base_url> with the base URL of the IDV Platform.
  • Replace <id> with the sessionId received from the webhook.
  • Replace <apikey> with your application key.

Extracting specific data

Once you have the session data, you can look for the specific file you need. Data captured during a document reading action will typically be referenced under an action called DOCREADER_SCENARIO within the Session Files.

Locate the corresponding file entry in the session response and use its unique URL to download the actual image or file content:

Extracting specific data