Data Sessions

A Data Session is the secure way to programmatically launch the client-side Ivy Data Session Flow that lets your users authenticate access to their their bank accounts.

Create a Data Session with the Ivy API

To create a data session using the Ivy API, call the POST /data/session/create endpoint. At a minimum, you can create a checkout with the following data:

Field	Type	required	Description
`referenceId`	`string`	`true`	A unique reference ID, usually your internal transfer ID.
`permissions`	`string[]`	`true`	The type of data, you want to retrieve from your user. Options: `balances`, `transactions` and `identity`
`returnUrl`	`string`	`true`	The user will be redirected to this URL when they return to your app.
`market`	`string`	`false`	The market of the user will be preselected when passing this field.
`customer`	`object`	`false`	You can pass the customer identifier of the Ivy returning customer network, either `email` or `customerId` here to increase returning customer conversion.

Example Payload

This is an example request payload to retrieve identity data of a user:

{
    "referenceId": "123456789",
    "permissions": ["identity"],
    "returnUrl": "https://example.com/callback/result",
}

The response is the data session object with the additional redirectUrl field:

Field	Type	Description
`id`	`string`	The unique Ivy id for this data session.
`referenceId`	`string`	A unique reference ID, usually your internal Id.
`permissions`	`string[]`	The type of data, you want to retrieve from your user. Options: `balances`, `transactions` and `identity`
`returnUrl`	`string`	The user will be redirected to this URL when they return to your app.
`market`	`string`	The market of the user will be preselected when passing this field.
`customer`	`object`	You can pass the customer identifier of the Ivy returning customer network, either `email` or `customerId` here to increase returning customer conversion.
`status`	`string`	The status of the data session. Possible values are `started`, `pending`, `failed`or `complete`. The data is available as soon as the status equals `complete`.
`data`	`object`	An object containing the requested data.
`redirectUrl`	`string`	The URL to which you need to redirect the user.

Redirect the User to the Data Session URL

After you receive the response from the Ivy API, you need to redirect the user to the redirectUrl that you received in the response.

Parameter	Type	Description
`id`	String	A unique identifier for the created data session.
`redirectUrl`	String	Send the user here to start the data session.

Retrieve Bank Data

After a user successfully finished authentication with their bank, Ivy adds the status pending which then results in either a complete or failed terminal status.

The user will be redirected to the returnUrl when the flow is done or cancelled. The following data is attached as query parameters to the return URLs.

Field	Type	Description
`referenceId`	`string`	The referenceId that you provided when creating the data session
`data-session-id`	`string`	The data session id.
`success`	`boolean`	`true` when the flow was successfully finished. Else, `false`.

In order to retrieve bank data, you can either poll the GET /data/session/retrieve endpoint or you can set up Webhooks to receive data session events.

Result for Identity

The identity object contains the following parameters:

Parameter	Type	Description
`name`	string	The name of the account holder.
`dateOfBirth`	string	Optional. The date of birth of the account holder.

Accounts

The accounts array contains the following parameters:

Parameter	Type	Description
`name`	string	The name of the account.
`financialAddress`	object	An object containing the identifier of the account.
`accountType`	string	The type of the account. Possible values are `checking`, `savings`, `credit`, `card`, `loan`, `investment`, `insurance`, `other`, `unknown`.

Financial Address

The financialAddress object contains the following parameters:

Parameter	Type	Description
`type`	string	The type of the financial address. Possible values are `iban`, `bank_code`.
`iban`	object	An object containing the IBAN and the account holder name.
`bankCode`	object	An object containing the bank code, the accountNumber and the account holder name.

Example

The result will be sent as a webhook of type data_session_completed. An example result payload for an identity request might look like this:

{
  "type": "data_session_completed",
  "payload": {
    "id": "abcdef1234567890",
    "referenceId": "123456789",
    "status": "complete",
    "data": {
      "bankName": "Example Bank",
      "identity": {
        "name": "John Doe",
        "dateOfBirth": "1980-01-01"
      },
      "accounts": [
        {
          "financialAddress": {
            "type": "iban",
            "iban": {
              "iban": "DE12345678901234567890",
              "accountHolderName": "John Doe"
            }
          },
          "accountType": "checking",
          "name": "Example Account"
        },
        {
          "financialAddress": {
            "type": "bankCode",
            "bankCode": {
              "accountNumber": "1234567890",
              "bankCode": "123456",
              "accountHolderName": "Dohn Joe"
            }
          },
          "accountType": "checking",
          "name": "Example Account"
        }
      ]
    }
  },
  "date": "2023-04-29T11:50:13.176Z"
}