Transactions

The transactions API exposes the ledger transactions of a financial account.

The initial call to the transactions API can sometimes time out with accounts that have an abnormally large number of transactions. Should this happen wait a few seconds and try again.

Properties

Name
account_id
Type
string
Description
The id of the account that the transaction belongs to.
Name
amount
Type
string
Description
The signed amount of the transaction as a string.
Name
date
Type
string
Description
The ISO 8601 date of the transaction.
Name
description
Type
string
Description
The unprocessed transaction description as it appears on the bank statement.
Name
details
Type
object
Description
An object containing additional information regarding the transaction added by Teller's transaction enrichment.
- Name
  processing_status
  Type
  string
  Description
  Indicates the transaction enrichment processing status. Either pending or complete.
- Name
  category
  Type
  string (nullable)
  Description
  The category that the transaction belongs to. Teller uses the following values for categorization: accommodation, advertising, bar, charity, clothing, dining, education, electronics, entertainment, fuel, general, groceries, health, home, income, insurance, investment, loan, office, phone, service, shopping, software, sport, tax, transport, transportation, and utilities.
- Name
  counterparty
  Type
  object
  Description
  An object containing information regarding the transaction's recipient
  Name
  name
  Type
  string (nullable)
  Description
  The processed counterparty name.
  Name
  type
  Type
  string (nullable)
  Description
  The counterparty type: organization or person.
Name
status
Type
string
Description
The transaction's status: posted or pending.
Name
id
Type
string
Description
The id of the transaction itself.
Name
links
Type
object
Description
An object containing links to related resources. A link indicates the enrollment supports that type of resource. Not every institution implements all of the capabilities that Teller supports. Your application should reflect on the contents of this object to determine what is supported by the financial institution.
- Name
  self
  Type
  string
  Description
  A self link to the transaction.
- Name
  account
  Type
  string
  Description
  A link to the account that the transaction belongs to.
Name
running_balance
Type
string (nullable)
Description
The running balance of the account that the transaction belongs to. Running balance is only present on transactions with a posted status.
Name
type
Type
string
Description
The type code transaction, e.g. card_payment.

GET/accounts/:account_id/transactions

List Transactions

Returns a list of all transactions belonging to the account.

Pagination

The Transactions endpoint returns all transactions for the given account. Usually this does not represent a large amount of data transfer, but if your application has specific requirements of minimizing the amount of data going over the wire the transactions list endpoint supports pagination controls.

Pagination controls are given as query params on the request URL.

Name
count
Type
integer
Description
The maximum number of transactions to return in the API response.
Name
from_id
Type
string
Description
Paginate backward from this transaction. Returns transactions older than the one with this ID. For recent activity, use date ranges or webhooks.
Name
start_date
Type
string
Description
Filter transactions to include only those on or after this date (inclusive). Must be in ISO 8601 format, for example 2025-01-01.
Name
end_date
Type
string
Description
Filter transactions to include only those on or before this date (inclusive). Must be in ISO 8601 format, for example 2025-01-31.

Request

curl https://api.teller.io/accounts/acc_oiin624kqjrg2mp2ea000/transactions \
  -u test_token_ky6igyqi3qxa4:

Response

[
  {
    "details" : {
      "processing_status" : "complete",
      "category" : "general",
      "counterparty" : {
          "name" : "YOURSELF",
          "type" : "person"
      }
    },
    "running_balance" : null,
    "description" : "Transfer to Checking",
    "id" : "txn_oiluj93igokseo0i3a000",
    "date" : "2023-07-15",
    "account_id" : "acc_oiin624kqjrg2mp2ea000",
    "links" : {
      "account" : "https://api.teller.io/accounts/acc_oiin624kqjrg2mp2ea000",
      "self" : "https://api.teller.io/accounts/acc_oiin624kqjrg2mp2ea000/transactions/txn_oiluj93igokseo0i3a000"
    },
    "amount" : "86.46",
    "type" : "transfer",
    "status" : "pending"
  },
  ...
]

GET/accounts/:account_id/transactions/:transaction_id

Get Transaction

Returns an individual transaction.

Request

curl https://api.teller.io/accounts/acc_oiin624kqjrg2mp2ea000/transactions/txn_oiluj93igokseo0i3a005 \
  -u test_token_ky6igyqi3qxa4:

Response

{
  "running_balance" : null,
  "details" : {
     "category" : "service",
     "counterparty" : {
        "type" : "organization",
        "name" : "CARDTRONICS"
     },
     "processing_status" : "complete"
  },
  "description" : "ATM Withdrawal",
  "account_id" : "acc_oiin624kqjrg2mp2ea000",
  "date" : "2023-07-13",
  "id" : "txn_oiluj93igokseo0i3a005",
  "links" : {
     "account" : "https://api.teller.io/accounts/acc_oiin624kqjrg2mp2ea000",
     "self" : "https://api.teller.io/accounts/acc_oiin624kqjrg2mp2ea000/transactions/txn_oiluj93igokseo0i3a005"
  },
  "amount" : "42.47",
  "type" : "atm",
  "status" : "posted"
},

Syncing Transactions

Use these patterns to fetch only new transactions without re-downloading your full history.

Using date ranges

Use start_date and end_date to bound your sync window; both dates are inclusive. Expand the window 7-10 days beyond your last sync to capture transactions that shift dates when moving from pending to posted.

When a pending transaction posts, its date often changes to the posting date. If you only query from your last sync date forward, you may miss these transactions.

Request

curl -G "https://api.teller.io/accounts/acc_oiin624kqjrg2mp2ea000/transactions" \
  -d "start_date=2025-01-01" \
  -d "end_date=2025-01-31" \
  -u test_token_ky6igyqi3qxa4:

Your expanded window will return transactions you've already stored. Reconcile by matching on transaction ID: insert new records and update existing ones. If the date range returns more than count transactions, use from_id to paginate through the rest of the window.

Teller maintains stable transaction IDs. Occasionally, when a pending transaction changes significantly upon posting and cannot be matched to the original, it's created as a new record with a new ID. Account for this in your reconciliation.

Using webhooks

Subscribe to transactions.processed to receive notifications when new transactions are available. Teller refreshes your enrollments at least once per day. When new transactions are found, this webhook fires, and you call the transactions API to retrieve them.