Creating your first connection

Connect a user to their bank and read the accounts and transactions they consent to share. All API calls below run on your backend; the user completes the bank approval in the browser.

User token → Create connection → Bank approval → Check collection → Read data

1. Get a user access token

Follow Access Tokens to obtain a token for a stable userId in your application. Use the same user identity when creating the connection and reading its data. Keep your clientSecret and API access token on your backend.

Token userId = connection owner userId = data-access token userId. Renew a token with that same identity; do not generate a different userId for later data reads.

Your credentials need create:connections, read:connections, read:accounts and read:transactions for this flow. See the token endpoint for the authentication request.

The examples use API_BASE=https://api.open-finance.ai/v2 and ACCESS_TOKEN containing that user's token. Use the API base configured for your integration.

2. Create a connection

Start with sandbox providers:

curl --request POST "$API_BASE/connections" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"includeFakeProviders":true,"refreshData":false,"redirectUrl":"https://your-app.example/bank-return"}'

A successful response is HTTP 201 with id and connectUrl. Save id as your CONNECTION_ID, associated with this user. Send the returned connectUrl to your frontend to start the journey.

See Create connection for additional options.

3. Let the user approve access

Open connectUrl in the user's browser. The user selects a provider and completes its consent process. For embedding options, see Connection Journey.

📘

Consent and data collection are separate

Returning to your application does not mean the data is ready. Collection continues asynchronously. Business accounts may require additional account owners to approve access.

4. Check collection progress

Configure connection webhooks and read the latest connection when notified or when the user returns:

curl "$API_BASE/connections/$CONNECTION_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

Wait for ACTIVE or COMPLETED before reading accounts or transactions. Check status, lastFetchedAt and lastFetchedDataDate together. Successful collection normally ends in COMPLETED with refreshData=false, or ACTIVE with refreshData=true. ACTIVE can also precede the first collection after additional account owners approve access; status alone is insufficient.

Before displaying data as available, check for a collection timestamp, inspect any error, and read the accounts. A timestamp can also be updated on failure; it is not proof of success. For a refresh, compare freshness with the previous value. An earlier collection timestamp does not prove a new refresh has finished. See connection states for failures and consent changes.

5. Read accounts and transactions

Use the same user's token and filter by the saved connection:

curl --get "$API_BASE/data/accounts" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "connectionId=$CONNECTION_ID" \
  --data-urlencode "limit=100"

curl --get "$API_BASE/data/transactions" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "connectionId=$CONNECTION_ID" \
  --data-urlencode "limit=100"

Each response contains items, count and nextPage. Follow every page using Reading account data; the first page may not contain all records.

Initial collection after a new consent uses a one-year lookback; normal ongoing refreshes revisit an overlapping week. Read all history available in Open Finance when building or replacing your account's local copy.

When storing the results, follow Saving and synchronizing transactions to reflect updates and deletions. An insert-only integration can retain replaced records and inflate totals.

Before using real bank data

Confirm production access with Open Finance, disable includeFakeProviders, and select a supported real provider. Test consent rejection, additional approvals, collection errors and expired consent as well as the successful path. Available accounts and history depend on the bank and the user's consent.