How does the cursor work?

The cursor is an opaque, item-scoped position in that item's change stream. Omit it and you receive the full history as added. Send the previous next_cursor and you receive only what changed since. Persist the cursor after you have applied a page, not before: if you crash in between, the next call re-delivers the same page, which is harmless as long as you upsert on transaction_id. Cursors do not expire; an unknown or foreign cursor returns invalid_request with code invalid_cursor, and you recover by syncing from scratch into a fresh table.

What is the amount sign convention?

Positive is money leaving the account, negative is money arriving, in major units with an iso_currency_code alongside. Dates are YYYY-MM-DD strings. Money is stored as a decimal and only becomes a number at the API edge, so there is no float arithmetic in the path that produces the figure you read.

How fresh are balances?

accounts/get serves the cached balances from the last sync. accounts/balance/get checks the item first: if the last successful sync is older than 15 minutes it refreshes through the connector before answering, and if the institution cannot be reached it returns provider_error with code refresh_failed while the cached balances stay readable through accounts/get.

How do I know when there is new data?

Subscribe to the transactions.sync_updates_available webhook and re-sync from your stored cursor when it arrives. Deliveries are signed with an HMAC over the timestamp and raw body, and retried at 0s, 1m, 5m, 30m, and 2h. Polling on a timer works too — it is just more expensive.

What if the user did not consent to a product?

The read fails loudly rather than returning an empty result: permission_error with code product_not_consented. Consent is captured on the Link consent screen from the products array in your link token and stored on the item, so the enforcement point is the same one the user saw.

How much history is there?

In the sandbox, 24 months per item, generated deterministically from the item id so the same item always produces the same data — and new transactions arrive as real time passes. In live mode the history is whatever the upstream connector returns for that institution, which varies by provider.

core data

Bank data, in the shape you were going to normalize it into anyway.

Accounts, balances, and transactions on one access token, with a cursor that survives restarts and a transaction object stable enough to store directly. Identity, liabilities, and a net-worth report sit on the same connection.

Get a sandbox key Transactions reference

endpoints

Eight calls cover the data plane.

All POST + JSON, all bearer-authenticated, all metered the same way.

POST/v1/transactions/syncIncremental feed: added, modified, removed, next_cursor, has_more. The endpoint you build on.
POST/v1/transactions/getDate-range read with count/offset paging and optional account filtering, for one-off queries.
POST/v1/accounts/getAccounts with cached balances, plus the item they belong to.
POST/v1/accounts/balance/getBalances, refreshed through the connector when the last sync is older than 15 minutes.
POST/v1/identity/getAccount-holder names, emails, phones, and addresses on file at the institution.
POST/v1/liabilities/getCard and loan terms: APR, minimum payment, next due date, original principal.
POST/v1/assets/getA point-in-time report: total assets, total liabilities, net worth, and the breakdown behind them.
POST/v1/items/getConnection state: connector, status, error, consented products, last successful sync.

transactions/sync

The loop you write once.

Page size is 1–500 and defaults to 100. Loop while has_more is true, then keep the final cursor.

# First call: omit the cursor to receive the item's full history as "added".
curl https://connect.feels.money/v1/transactions/sync \
  -H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "fc_at_your_item_token",
    "count": 500
  }'

added — rows you have not seen. On a first sync, that is the entire history.
modified — rows you already hold that changed. The common case is a pending authorization posting, where the amount, date, and name can all move. Upsert on transaction_id, which survives the pending → posted transition.
removed — ids to delete, typically an authorization that never posted. A removal is never announced for a row you were never sent.
next_cursor and has_more — the position to persist, and whether another page is waiting right now.

the transaction object

Twelve fields, stable across every connector.

Whichever upstream served the data, the shape you store is this one.

Field	What it is
transaction_id	Stable id, `txn_…`. Survives the pending → posted transition, so it is a safe primary key.
account_id	The owning account on the same item.
date	`YYYY-MM-DD` posted date — the authorization date while the row is still pending.
authorized_datetime	ISO-8601 authorization time when the institution reports one, else null.
name	The raw statement descriptor, unmodified.
merchant_name	Cleaned merchant when resolvable — the deterministic descriptor table runs on ingest, not as a separate paid call.
amount	Major units. Positive is money out, negative is money in.
iso_currency_code	ISO-4217 code for the amount.
pending	True until the transaction posts.
category / category_detailed	Primary and detailed labels from the platform taxonomy — the same strings `/v1/categories/get` returns. See transaction enrichment.
payment_channel	`online`, `in_store`, `transfer`, or `other`.

on the same token

What else the connection carries.

No second integration, no second credential — the same access token, gated by the consent the user gave.

Identity — names, emails, phones, and addresses on file. Items whose identity sync degraded return the empty identity shape rather than an error. Reference.
Liabilities — APR, minimum payment, next payment due, and original principal per credit or loan account. Reference.
Assets — total assets, total liabilities, and net worth, computed from balances with holdings standing in only where a balance cannot be trusted, so invested value is never counted twice. Reference.
Recurring streams — subscriptions, bills, and payroll detected from the transactions the connector returned, which means they work on any connector that returns transactions at all. How detection works.
Investments and crypto — holdings, securities, and trade history where the connector supports them. The full product surface.

What live coverage actually depends on

FeelConnect does not hold bank connections of its own. Every institution in the catalog carries an ordered chain of connectors, and live traffic goes to the first one whose credentials are present in the deployment you are calling.

Some connectors an operator can switch on alone in minutes — GoCardless Bank Account Data (UK and EU banks, free self-signup under their PSD2 licence), Coinbase, Kraken, PayPal, public-address crypto wallets, and CSV / OFX / QFX import. Others need a signed business relationship before they will serve production data, including Plaid, MX, Finicity, Akoya, and Stripe Financial Connections. Where an institution has no enabled connector, a live call returns provider_error rather than pretending.

The sandbox is the exception and it is always on: test keys resolve to the simulated network regardless of credentials, so the full integration is buildable on day one. See going live for the provider-by-provider breakdown.

in production

The parts you have to handle.

Stated plainly so they are not a surprise on launch day.

Rate limits. A token bucket per key, bursting to 3×, with X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on every response. Exhaustion returns 429 rate_limit_error. Per-second limits and monthly quotas are per plan — see pricing.

Errors. Every non-2xx response is { error: { type, code, message, request_id } }. The request id is also on the successful path, in the dashboard’s request log, so support conversations start from the same row. Error reference.

Broken logins. Items enter login_required or error, fire an item.error webhook, and are repaired by reopening Link in update mode. Build that path before you need it.

faq

Questions developers actually ask.

keep reading