Sessions API

Overview

The Sessions API allows EdgeScore clients to retrieve a history of Instant Bank Verification (IBV) widget events associated with a specific consumer.

This endpoint provides visibility into a consumer's interactions with the Edge Connect widget, including session initiation, bank login attempts, connection progress, and other events throughout the verification process.

Clients can use the Sessions API to monitor consumer activity, troubleshoot connection issues, and better understand where consumers are in the bank verification process.

Endpoint

Method: GET

URL:
https://api.edgescore.com/api/v1/sessions

Authentication

All requests must include a valid EdgeScore API key in the x-api-key header.

Query Parameters

Important: The client_id value remains constant for your organization and must be included in every request. Unlike client_id, the consumer_id should be updated to identify the consumer whose events you want to retrieve.

Example Request

curl --location --get \
  'https://api.edgescore.com/api/v1/sessions' \
  --data-urlencode 'consumer_id=YOUR_CONSUMER_ID' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Accept: application/json'

Replace the placeholder values with:

• YOUR_CONSUMER_ID: The consumer identifier provided by your organization.
• YOUR_CLIENT_ID: Your organization's static client identifier, provided by EdgeScore Support.
• YOUR_API_KEY: Your EdgeScore API key.

Example Response

The following example illustrates a successful consumer session containing three events: the widget was opened, the consumer began logging into their financial institution, and authentication succeeded.

The successful login event is illustrative; its exact technical category and description should be verified against a successful API response.

{
  "message": "events available",
  "count": 3,
  "max_page_count": 100,
  "events": [
    {
      "created_at": "2026-10-27T16:38:16Z",
      "who": "edge",
      "session_cycle": "attempt_login",
      "technical_category": "login_success",
      "description": "Consumer successfully logged in",
      "product_request": "IBV73AD762E30426750A938",
      "product_name": "ibv_analysis_report",
      "institution": "Example Credit Union"
    },
    {
      "created_at": "2026-10-27T16:38:05Z",
      "who": "edge",
      "session_cycle": "attempt_login",
      "technical_category": "login_in_progress",
      "description": "Consumer must log in to bank",
      "product_request": "IBV73AD762E30426750A938",
      "product_name": "ibv_analysis_report",
      "institution": "Example Credit Union"
    },
    {
      "created_at": "2026-10-27T16:38:02Z",
      "who": "edge",
      "session_cycle": "start_session",
      "technical_category": "created",
      "description": "Session start; consumer sees the widget",
      "product_request": "IBV73AD762E30426750A938",
      "product_name": "ibv_analysis_report",
      "institution": "Example Credit Union"
    }
  ]
}

Response Fields

Top-Level Fields

Event Fields

Each object within the events array represents an individual event recorded during the consumer's IBV journey.

Understanding Session Events

The Sessions API provides a history of events associated with a consumer's Instant Bank Verification (IBV) journey.

Each event identifies the stage of the process, the event status, and a description of the activity that occurred. These events can help clients track consumer progress, identify unsuccessful connection attempts, and monitor report generation.

For a complete list of supported event types, statuses, and their descriptions, refer to the Consumer Event Glossary.

Integration Considerations

• Consumer identification: Use the same consumer_id originally provided to EdgeScore when initiating the IBV request.
• Static client identifier: Store the assigned client_id in your integration configuration and include it with each request.
• Event history: Multiple events may be returned for the same consumer, including repeated login attempts or widget sessions.
• Event ordering: Events in the supplied response are ordered from most recent to oldest. Use the created_at timestamp when processing events chronologically.
• Event timestamps: Timestamps are returned in UTC and can be converted to your application's preferred time zone.
• Request association: Use the product_request field to identify events associated with a particular EdgeScore product request.
• Security: API keys should be stored securely and used only in server-side requests. Avoid exposing credentials in browser-side code or application logs.

Common Use Cases

Consumer Activity Tracking

Determine whether a consumer has opened the IBV widget, attempted to connect to a financial institution, or progressed through the verification process.

Troubleshooting Connection Issues

Review the consumer's event history to identify unsuccessful login attempts, connection failures, or other events that may have prevented the consumer from completing the IBV process.

Customer Support

Provide support teams with visibility into the consumer's interactions with the Edge Connect widget, helping them identify where a consumer may have encountered difficulties.

Session Analysis

Review repeated widget interactions, login attempts, and other consumer activity to better understand the consumer's verification journey.