​
Prerequisites

Before you begin, make sure you have:

  • A developer account with us
  • API Key and Webhook Signing Secret
  • Basic understanding of RESTful APIs

​
Step-by-Step Guide

You can either use our SDK or make direct API requests. Check out the API Reference for more information on using the API directly.

1

Install the SDK

We currently support Node.js and Python. Ask us if you need support for other languages.

npm install @getivy/node-sdk
2

Initialize the Client

import Ivy from '@getivy/node-sdk';

const client = new Ivy({
  apiKey: 'YOUR_IVY_API_KEY',
  environment: 'sandbox', // defaults to 'production'
})
3

Create Data Session

Create a new data session. The response will contain a redirectUrl that you can use to redirect the customer to their bank’s authentication flow. After successful authentication, the customer will be redirected to the callbackUrl.

TypeScript
const dataSession = await client.data.sessions.create({
  permissions: ['accounts', 'transactions', 'balances', 'holders'],
  referenceId: 'your-unique-id',
  customer: {
    email: 'john.doe@example.com',
  },
  metadata: {
    'merchant-id': '1234567890',
    'random-key': 'random-value',
  },
  locale: 'en',
  market: 'de',
  callbackUrl: 'https://your-app.com/callback'
})

// Redirect the customer to the redirectUrl in the Client
res.send(dataSession.redirectUrl)
4

Pull Account Data

After the user finished the authentication flow and returned to the redirectUrl, you can start making API requests:

TypeScript
// Retrieve the customer's account
const account = await client.data.accounts.retrieve({
  accountId: dataSession.accounts[0].id,
})

// Get account transactions
const transactions = await client.data.transactions.list({
  accountId: account.id,
})

// Get account balances
const balances = await client.data.balances.list({
  accountId: account.id,
})

// Get account holders
const holders = await client.data.holders.list({
  accountId: account.id,
})

​
Authentication

Our API uses API Key authentication for secure access. Make sure to securely store your credentials and never expose them in client-side code.

​
Available Account Data

You can request the following data from your customer’s bank:

PermissionDescription
accountsAccess account data
balancesAccess balance data
transactionsAccess transaction data
holdersAccess account holder data

​
Testing

We provide a sandbox environment for testing your integration:

BASE_URL=https://api.sand.getivy.de

​
Next Steps

IntroductionData Sessions