Introduction

The Teller API is organized around REST. Resources have predictable, self-describing URLs and contain links to related resources. Our API accepts form-encoded requests and returns JSON encoded responses. It uses standard HTTP status codes, authentication, and methods in their usual ways.

You can use the Teller API in sandbox mode, which is free, does not call out to any real banks, and does not affect your live data. The access token you use determines whether your request is handled in the live or sandbox enviroments.

Access tokens for the live environment are obtained using Teller Connect when a user successfully connects a bank account to your Teller application.

Take a look at the Teller Connect integration guide to learn how to integrate Teller Connect into your application.

https://api.teller.io/
test_BgBfDDILBbSBE5PGLQK_RQ

Authentication

The Teller API uses TLS client certificates to authenticate your API requests. Secondly it uses access tokens to identify the user whose bank accounts your API call operates on. Access tokens are tied to your application, they are useless without your client certificate and its private key.

Client certificates are necessary for live production API calls. In the interests of getting up and running as quickly as possible they're not required in the sandbox environment. We recommend using client certificates as soon as possible in order to become familiarised with them.

It's of paramount importance that you keep your private key confidential, anyone that knows it is able to make API requests as you. If you suspect your private key has been compromised, immediately revoke it and request a new certificate from the certificate dashboard. Your new certificate will have a new private key.

Access tokens are encoded using HTTP Basic Auth. The access token is given as the username value, the password field should be left empty and is ignored by the API server. Teller uses access tokens to identify the resource owner and determine that your application has their consent to operate on their resources, i.e., their bank accounts.

http https://api.teller.io/accounts --auth test_BgBfDDILBbSBE5PGLQK_RQ:

Errors

Teller uses standard HTTP response status codes to indicate the success or failure of a request. Status codes in the 2xx denote a successful request. Status codes in the 4xx range denote a client error, e.g. not using a client certificate to make the request, a problem with the user access token, etc. Status codes in the 5xx range denote a problem on our end, e.g. a bank is unavailable and it's not possible or otherwise doesn't make sense to gracefully handle the exception.

error
object
An object describing the error condition.
error.code
string
The error condition.
error.message
string
A human readable string describing the error and how to resolve it.
OK A successful request.
Accepted A payment instruction was accepted by the financial institution for processing.
Bad Request The request was unacceptable. This status is used when a request that must be made with a Teller client certificate is made without one.
Unauthorized A request was made without an access token where one was required.
Forbidden A request was made with an invalid or revoked access token.
Unprocessable Entity A request was made with an invalid request body.
Bad Gateway A 500 level response was received when making a request to a financial institution where a graceful fallback is not possible, e.g. a payment instruction.

Accounts

The Accounts resource represents a collection of the user's bank accounts. Each Account resource exposes its ledger and available balances, account number, ACH routing number and if different, its wire routing number.

account_number
string
The account number.
balances
object
An object containing the different types of balance the account has.
balances.available
string
The account's available balance, i.e. the ledger balance net of any pending debits or credits.
balances.ledger
string
The account's ledger balance, i.e. the sum of all transactions posted to the ledger.
currency_code
string
The ISO 4217 currency code of the account.
id
string
The id of the account itself.
institution
string
The snake_cased name of the bank that holds the account.
links
object
An object containing links to related resources.
links.self
string
A self link to the account.
links.transactions
string
A link to the account's ledger transactions.
name
string
The account's name.
routing_numbers
object
An object containing the account's routing numbers.
routing_numbers.ach
string
The account's routing number for ACH transactions.
routing_numbers.wire
string
The account's routing number for domestic transactions (if different from its ACH routing number).
  • GET /accounts
  • GET /accounts/:id
{
  "account_number": "9271247198",
  "balances": {
    "available": "3742.70",
    "ledger": "3742.70"
  },
  "currency_code": "USD",
  "enrollment_id": "test_enr_rlbWn8WC",
  "id": "test_acc_xOM3jB2v",
  "institution": {
    "id": "silicon_valley_bank",
    "name": "Silicon Valley Bank"
  },
  "links": {
    "self": "https://api.teller.io/accounts/test_acc_xOM3jB2v",
    "transactions": "https://api.teller.io/accounts/test_acc_xOM3jB2v/transactions"
  },
  "name": "Teller API Sandbox Checking",
  "routing_numbers": {
    "ach": "059781958"
  },
  "subtype": "checking",
  "type": "depository"
}

Transactions

The Transactions resource represents the known transactions on the account. Each individual Transaction resource represents an individual transaction on the account either posted or pending.

account_id
string
The id of the account that the transaction belongs to.
amount
string
The signed amount of the transaction as a string.
date
string
The ISO 8601 currency code of the account.
description
string
The unstructured transaction description as it appears on the bank statement.
id
string
The id of the transaction itself.
links
object
An object containing links to related resources.
links.self
string
A self link to the account.
links.account
string
A link to the account that the transaction belongs to.
running_balance
string
The running balance of the account that the transaction belongs to.
type
string
The type code transaction, e.g. card_payment.

Pagination

The Transactions list resource 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 minimising the amount of data going over the wire the transactions list resource supports pagination controls.

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

GET /accounts/:account_id/transactions?count=5&from_id=txn_test

count
integer
The maximum number of transactions to return in the API response.
from_id
string
The transaction from where to start the page. The first transaction in the API response will be the one immediately before the transaction in the ledger with this id.
  • GET /accounts/:account_id/transactions
  • GET /accounts/:account_id/transactions/:id
{
  "account_id": "test_acc_xOM3jB2v",
  "amount": "-7.41",
  "date": "2020-07-13",
  "description": "Rite Aid",
  "id": "test_txn_m1grmJSH",
  "links": {
    "account": "https://api.teller.io/accounts/test_acc_xOM3jB2v",
    "self": "https://api.teller.io/accounts/test_acc_xOM3jB2v/transactions/test_txn_m1grmJSH"
  },
  "running_balance": "3742.70",
  "type": "card_payment"
}