Platform API overview

The Lunch Flow Platform API lets you embed financial data into your own product. Register users, connect their bank accounts, and read their transaction, balance, and holdings data.

If you only need to access your own data, check out the simpler Personal API.

Base URL

https://www.lunchflow.app/api/platform/v1

Authentication

Scheme	Credentials	Used for
Basic Auth	`client_id` : `client_secret`	Managing users (create, update, delete)
Bearer Token	`access_token`	Accessing user data, portal sessions

Your client_id and client_secret come from the Developer Dashboard. The access_token is returned when you register a user or when a user completes the OAuth flow.

Refresh expired tokens via POST /oauth/token with grant_type=refresh_token.

You can choose for the end user to pay the subscription, or you can pay for their subscription. The integration process follows a very similar flow in both cases: Share a link with your end users to connect their banks, redirect to your website, and access data server-side. The only difference is whether users get a checkout form (when they're paying) or go directly to connect a number of bank accounts that you control (when you pay).

Create an app

Go to the Developer Dashboard and create an app to get your client_id and client_secret. Add a redirect URI.

Register a user

Call POST /users with Basic Auth. You get back an access_token and refresh_token.

curl -X POST https://www.lunchflow.app/api/platform/v1/users \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Connect bank via OAuth

Redirect the user to the authorize endpoint. They sign in, connect their bank, and are redirected back with a code.

GET https://www.lunchflow.app/api/platform/oauth/authorize
  ?client_id=$CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &email=user@example.com
  &state=$RANDOM_STATE

Exchange the code for tokens:

curl -X POST https://www.lunchflow.app/api/platform/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "$AUTH_CODE",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "$CLIENT_ID",
    "client_secret": "$CLIENT_SECRET"
  }'

Access data

Once the user has linked their bank, read their accounts, transactions, balances, and holdings.

curl https://www.lunchflow.app/api/platform/v1/accounts \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Refreshing tokens

Access tokens expire after 1 hour. Use the refresh token to get a new pair:

curl -X POST https://www.lunchflow.app/api/platform/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "$REFRESH_TOKEN",
    "client_id": "$CLIENT_ID",
    "client_secret": "$CLIENT_SECRET"
  }'

For public (self-hosted) clients, omit the client_secret.

Endpoints

Browse the interactive reference for each endpoint in the Users and Accounts sections of the sidebar.

Raw provider data

Every account and transaction is normalized into the same fields whichever bank data provider it came from. When you need something those fields don't carry, such as a provider's category, counterparty details or booking codes, add include_raw=true to GET /accounts or GET /accounts/:id/transactions. Each item then includes a raw object holding the unmodified data Lunch Flow received, keyed by provider:

curl "https://www.lunchflow.app/api/platform/v1/accounts/123/transactions?include_raw=true" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": "tx_abc",
  "accountId": 123,
  "amount": -12.5,
  "currency": "GBP",
  "date": "2026-10-01",
  "merchant": "Coffee Shop",
  "raw": {
    "gocardless": { "transactionId": "...", "bookingDate": "2026-10-01", "...": "..." }
  }
}

The key is the provider that connected the account, not the bank. For example, an American Express card connected through GoCardless appears under gocardless. A transaction's raw is fetched along with the transaction. An account's raw is the account record Lunch Flow stored when the account was connected, so it may not reflect the bank's latest state (use /balance for current balances).

Raw data is passed through as-is. Its shape is defined by each provider and can change without notice, so prefer the normalized fields and treat anything under raw as optional. It can also contain more personal data than the normalized fields, such as account numbers and counterparty names, and makes responses considerably larger.

Support

Questions or issues? Email hello@lunchflow.app.

How is this guide?