Skip to content

Feed data to BI systems

Integrate Mosaic with external analytics system in order to enrich your BI analytics data. By feeding identity verification events into your SIEMs (Security Information and Event Management), you'll be able to keep track of security events in real-time while collecting business analytics data needed to improve your app UX and better understand customer behavior patterns.

Below you'll find instructions on how to set up event streaming using Mosaic APIs and a reference of the parameters available for IDV events.

  1. Collect events
  2. Feed to BI tool
  3. Review events

1. Collect events

Leverage Event streaming APIs to collect identity verification activity.

  1. Enable event collection as described below.
import fetch from 'node-fetch';

async function run() {
  const query = new URLSearchParams({
    type: 'verify',
  }).toString();

  const resp = await fetch(
    `https://api.transmitsecurity.io/activities/v1/activities/start-collect?${query}`,
    {
      method: 'PUT',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>' // Client access token
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();
  1. Create an event stream for identity verification events. Make sure to provide an ID to identify the stream. The stream ID should be a continuous string, without spaces, and unique for each stream.
import fetch from 'node-fetch';

async function run() {
  const query = new URLSearchParams({
    type: 'verify', //
    stream_id: '<YOUR_STREAM_ID>', // Unique stream ID, without spaces
  }).toString();

  const resp = await fetch(
    `https://api.transmitsecurity.io/activities/v1/activities/stream?${query}`,
    {
      method: 'PUT',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>' // Client access token
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();

2. Feed to BI tool

Depending on the BI analytics tool you use, you might need to configure it to pull events from Mosaic or implement a job that retrieves events from Mosaic and forwards them to your BI system. To retrieve events, query the following endpoint as described below:

import fetch from 'node-fetch';

async function run() {
  const query = new URLSearchParams({
    type: 'verify', // Event type. One of cis, admin, risk, verify
    stream_id: '<YOUR_STREAM_ID>', // Unique stream ID
    batch_size: '100' // The number of events to return in each batch
  }).toString();

  const resp = await fetch(
    `https://api.transmitsecurity.io/activities/v1/activities/collect?${query}`,
    {
      method: 'POST',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN_HERE>'  // Client access token
      }
    }
  );

  const data = await resp.text();
  console.log(data);
}

run();

3. Review events

Below is example of identity verification event.

{
  "activity": "page_loaded",
  "appId": "gGyeOFH8LUdjefuwPei5JIl",
  "userId": "fHDV8gsIdJoid1br",
  "ip": "54.220.197.207",
  "userAgent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Mobile Safari/537.36",
  "timestamp": 1727005080107,
  "additionalParams": {
    "sessionId": "fHDV8gsIdJoid1br",
    "pageName": "document_front",
    "sdkVersion": "1.3.37",
    "platform": "web-sdk",
    "osVersion": "6.0",
    "deviceModel": "Nexus 5",
    "browser": "Chrome"
  }
}

Each activity event returned by Event Streaming APIs contains basic fields such as activity, appId, etc. Note that userId is populated with identity verification session ID (sessionID). Below are activity types related to identity verification and additional parameters returned for these activity types.

ActivityDescriptionAdditional parameters
page_loadedIndicates a page load.sessionId ,platform sdkVersion, osVersion ,deviceModel, browser, pageName
user_action_performedIndicates an action was performed by the user, such as a button click.sessionId ,platform sdkVersion, osVersion ,deviceModel, browser, pageName, userActionType
image_uploaded_infoIndicates an image upload, including metadata information (processing time, etc.).sessionId ,platform sdkVersion, osVersion ,deviceModel, browser, processResult, requestProcessingTimeMs, imageType
errorIndicates an error on frontend, such as "something went wrong" page.sessionId ,platform sdkVersion, osVersion ,deviceModel, browser,error, errorDescription
redirectIndicates redirection to callback URL.sessionId ,platform sdkVersion, osVersion ,deviceModel, browser, redirectUrl
session_createdIndicates creating a new verification session.
session_startedIndicates starting a verification session.
consent_approvedIndicates saving a consent info.
check_image_qualityIndicates checking the image quality after capturing an image.imageType, checkResult
verification_status_updatedIndicates the status of the internal verification process.result
allow_by_restriction_criterionIndicates the verification can continue according to the restriction criteria.
deny_by_restriction_criterionIndicates the verification was rejected based on restriction criteria.
session_deletedIndicates a session deletion (via API or by retention).

For identity verification events, Mosaic also returns additional parameters depending on specific activity type. View below available additional parameters and their values.

ParameterDescription
sessionIdIdentity verification session ID.
sdkVersionSDK version used by the app.
osVersionOperating system version of the device that generated the event.
platformThe platform the event originated from, for example web-sdk.
deviceModelThe model of the physical device used for verification.
browserThe browser name.
pageNameThe name of the page in the identity verification flow. One of: intro, qr, consent, timeout, permission_denied, permission_denied_no_refresh_button, document_back, document_front, selfie, instructions_screen, verification_completed_screen, error.
userActionTypeThe action performed by user. One of: cancel, capture_image, accept_and_start_clicked, consent_checked, start_button_clicked.
processResultThe result of image processing. One of: success, failure.
requestProcessingTimeMsThe time it took to process the image.
imageTypeThe type of image. One of: back, front, selfie.
redirectUrlThe redirect URI for this flow.
resultThe identity verification result. One of:
- Success: verification completed successfully
- Pending: verification in progress (after all images have been captured)
- Rejected: verification completed as rejected
- Resubmit: verification could not completed, the user has to resubmit (recapture)
- Error: an error occurred during verification
- Uncertain: a resubmission was requested due to uncertain result
checkResultThe result of the checking procedure.
errorNameThe name or type of the error.
errorDescriptionError description.