Features

A capability reference for the Transactions Service, organized by domain. For architecture and data flow details see Architecture.

Items

A Plaid item represents a user’s connection to a financial institution. It holds the Plaid access_token used for all subsequent data retrieval.

  • Create a new item for a user by exchanging a Plaid public_token for an access_token (v2 preferred)

  • List all items for a user, with optional filters for status, accounts, logos, and liabilities

  • Get a specific item by item ID

  • Update the main account within an item

  • Remove an item — checks for active floats; v2 skips legacy employment validation

  • Force-remove an item (admin override)

  • Check if a user is allowed to change their item (respects active float and cooldown period)

  • Persist an item by removing its TTL (prevents automatic cleanup)

  • Remine an item — queues it for a fresh transaction and account fetch from Plaid

See Item Lifecycle for status transitions and flow details. See Plaid: Items for the data model.

Accounts & Balances

Accounts are the individual financial accounts within a Plaid item (checking, savings, credit cards, etc.).

  • Get all accounts for a user (cached from DynamoDB, or live from Plaid)

  • Get a specific account by account ID

  • Get account balance history for a user and account, scoped to a date range

  • Get all accounts directly from Plaid (live, bypasses cache; error-state item accounts excluded)

See Plaid: Accounts & Balances and Plaid: Balance History for the data model.

Transactions

Transaction records are fetched from Plaid, refined into FloatMe’s format, and cached in DynamoDB.

  • Get cached transaction history for a user, with optional filters for account, category, date range, pending status, and pagination

  • Get transactions directly from Plaid (bypasses cache)

  • Get transactions for a specific account directly from Plaid

  • Get deposit transactions for a specific account directly from Plaid

  • Get per-account transactions scoped to an item

See Plaid: Transactions for the data model. See Plaid Mining Pipeline for how transactions are fetched and refined.

Link

Plaid Link is used to initiate new bank connections and to update existing ones.

  • Get a link token for a new item connection

  • Get a link token in update mode for a specific existing item (to re-authenticate or add accounts)

  • Get a Plaid Layer session token (for the Plaid Layer onboarding flow)

  • Fetch account information from a Plaid Layer session

  • Create items from a Plaid Layer stub (for new users connecting via Layer)

Categories

Transactions are categorized using Plaid’s category taxonomy.

  • Get all distinct categories present in a user’s transactions

  • Get all Plaid personal finance categories with metadata (name, color, icon)

See Plaid: Transactions for how category IDs are stored on transaction records.

Institutions

Institution records hold metadata about financial institutions, including connection health information from Plaid.

  • Get institution connectivity status (item login success rate, transaction update health, auth health) directly from Plaid

See Plaid: Institutions for the data model and the weekly sync job.

Liabilities

Liabilities represent debt accounts (credit cards, mortgages, student loans) within a connected item.

  • Get all current liabilities for a user by item ID

  • Get a specific liability by item ID and account ID

  • Get liability history for an account

See Plaid: Liabilities for the data model and type-specific field details.

KYC (Identity Verification)

KYC (Know Your Customer) uses Plaid Identity Verification to confirm user identity during onboarding.

  • Create a new KYC session, or a retry session for a user

  • Get the most recent KYC session for a user

  • Get a Plaid link token to launch the in-app KYC flow

  • Mark a KYC session as completed after the user finishes the in-app steps

See KYC (Identity Verification) for the full session lifecycle and flow.

Auth

Provides ACH account and routing numbers for a connected account via Plaid Auth.

  • Get account and routing numbers by item ID and account ID (payments-api only)

  • Get account and routing numbers by account ID (payments-api only)

Processor Tokens

Processor tokens allow third-party processors to access Plaid account data.

  • Create a processor token for a given item and account (returns existing token if already created)

Summary

Provides an aggregated spending summary across a user’s accounts and categories.

  • Get a transaction summary for a user scoped to a date range — returns per-account and per-category spending breakdowns

Bank Icon

  • Get the bank name and logo for a user’s primary linked institution

QA / Test Endpoints

Test-environment-only endpoints for setting up test state:

  • Seed account balance history for a user

  • Reset a sandbox item to ITEM_LOGIN_REQUIRED state

  • Create a KYC record for a user directly (bypasses session creation flow)

  • Get legacy Plaid item history for a user

Plaid Mining

The mining pipeline runs automatically in response to Plaid webhooks and Auth0 login events.

  • Handle TRANSACTION webhooks: DEFAULT_UPDATE, HISTORICAL_UPDATE, INITIAL_UPDATE, TRANSACTIONS_REMOVED

  • Handle ITEM webhooks: LOGIN_REPAIRED, ERROR, USER_PERMISSION_REVOKED, WEBHOOK_UPDATE_ACKNOWLEDGED

  • Re-mine user data when a login is detected but transactions are stale (listener Lambda)

  • Sync institution metadata weekly (institution Lambda)

  • Output raw Plaid and refined FloatMe data to Kinesis streams

See Plaid Mining Pipeline for end-to-end flow details.