Data Session Object

The Data Session object represents a session for connecting to financial institutions and retrieving account data. It allows you to request access to a user’s accounts and permissions, and to retrieve the data for those accounts.

Properties

id
string
required

Unique identifier for the session

permissions
array
required

List of permissions requested for this session: - accounts - Access to account data - transactions - Access to transaction data - balances - Access to balance data - holders - Access to account holder data

referenceId
string

Your unique identifier for this session

customer
object
metadata
object

Key-value pairs that can be used to store additional information about the session

locale
string

The language to display the interface in (e.g., ‘en’)

market
string

The market where the session is created (e.g., ‘de’)

callbackUrl
string

The URL to redirect to after the session is completed

status
enum
required

The status of the session: - active - Session is currently active - completed - Session completed successfully - expired - Session has expired

accounts
array

List of account IDs that were connected during this session

expiresAt
timestamp
required

The time at which the session will expire

createdAt
timestamp
required

Time at which the session was created

Endpoints

Create Session

Creates a new data session for connecting to financial institutions.

POST /api/services/data/sessions/create

Request

permissions
array
required

List of permissions to request: - accounts - Access to account data - transactions - Access to transaction data - balances - Access to balance data - holders - Access to account holder data

referenceId
string

Your unique identifier for this session

customer
object
metadata
object

Key-value pairs that can be used to store additional information about the session

locale
string

The language to display the interface in (e.g., ‘en’)

market
string

The market where the session is created (e.g., ‘de’)

callbackUrl
string

The URL to redirect to after the session is completed

Response
{
  "id": "ds_12345",
  "permissions": ["accounts", "transactions", "balances", "holders"],
  "referenceId": "your-unique-id",
  "customer": {
    "email": "john.doe@example.com",
    "id": "cust_123"
  },
  "metadata": {
    "merchant-id": "1234567890",
    "random-key": "random-value"
  },
  "locale": "en",
  "market": "de",
  "callbackUrl": "https://your-app.com/callback",
  "status": "active",
  "accounts": [],
  "expiresAt": "2024-01-27T11:00:00Z",
  "createdAt": "2024-01-27T10:00:00Z"
}

Retrieve Session

Retrieves a data session by its ID.

POST /api/services/data/sessions/retrieve

Request

id
string
required

The ID of the session to retrieve

Response
{
  "id": "ds_12345",
  "permissions": ["accounts", "transactions", "balances", "holders"],
  "referenceId": "your-unique-id",
  "customer": {
    "email": "john.doe@example.com",
    "id": "cust_123"
  },
  "metadata": {
    "merchant-id": "1234567890",
    "random-key": "random-value"
  },
  "locale": "en",
  "market": "de",
  "callbackUrl": "https://your-app.com/callback",
  "status": "completed",
  "accounts": ["acc_12345", "acc_12346"],
  "expiresAt": "2024-01-27T11:00:00Z",
  "createdAt": "2024-01-27T10:00:00Z"
}