Linking Accounts - Data API API Reference

Linking accounts is the process of connecting an end user's financial or energy accounts to your application. This enables you to access their data with their explicit consent.

The Account Linking Flow

The account linking process follows these steps:

Create an End User

First, create an end user in the Fiskil platform to represent your user.

curl --request POST \
  --url https://api.fiskil.com/v1/end-users \
  --header 'Authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{
    "email": "user@example.com",
    "name": "John Doe"
  }'

Start an Auth Session

Create an auth session for the end user. This generates a session ID that is used with the Link SDK to launch the consent flow.

curl --request POST \
  --url https://api.fiskil.com/v1/auth/session \
  --header 'Authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{
    "end_user_id": "482c0e2b-5866-46b1-b795-220b7bba45b5"
  }'

When using the Link SDK, you don't need to provide redirect_uri or cancel_uri — the SDK handles the flow result directly via a promise.

Launch the Link SDK

In your frontend, pass the auth_session_id from the response to the Link SDK's link() function. This opens the consent UI embedded in your application. The user will:

Select their institution (bank or energy provider)
Log in to their institution
Select which accounts to share
Confirm the consent

import { link } from '@fiskil/link';

const flow = link(authSession.session_id);

Handle the Result

When the consent flow completes, the SDK resolves with a consentID you can use to fetch data. If the user cancels or an error occurs, the promise rejects with a typed error.

try {
  const result = await flow;
  console.log('Consent ID:', result.consentID);
  // Use consentID to fetch data via Fiskil APIs
} catch (err) {
  console.error('Link error:', err.code);
}

Access Data

Once the consent is established, use the consentID to start accessing the user's data through the Banking and Energy API endpoints.

The Fiskil Link SDK supports both ESM/TypeScript and UMD/CDN usage, with options for timeout configuration, origin restrictions, and programmatic cancellation. For install instructions, full code examples, error codes, and a React integration example, see the Integrating the Link SDK guide.

Customizing the Flow

You can customize the consent flow experience through the Fiskil Console:

Branding: Add your logo and colors
Institution Selection: Control which institutions are displayed
Copy: Customize the text shown to users

Handling Multiple Consents

An end user can have multiple active consents:

Multiple consents to different institutions
Multiple consents to the same institution (e.g., different accounts)

Use the Consents API to manage and track all consents for an end user.

Best Practices

Handle Errors with Error Codes: The Link SDK rejects with typed LinkError objects containing specific error codes (e.g., LINK_USER_CANCELLED, CONSENT_ENDUSER_DENIED). Use these codes to provide meaningful feedback to your users. See Errors for a complete list.
Set allowedOrigin in Production: When calling link(), pass the allowedOrigin option to restrict postMessage communication to your domain. This is recommended for production deployments.
Pre-select the Institution: If you know which institution the user wants to connect, pass the institution_id in the auth session request to skip the institution selection step.
Monitor Consent Status: Consents can expire or be revoked. Use webhooks to stay informed about consent status changes.
Explain the Value: Before starting the consent flow, explain to users what data you need and why, to improve conversion rates.