The Teller API

The Teller API enables you to build applications that integrate with your user's bank accounts across all of their banks using a single, thoughtfully-designed HTTP API.

Basics

Interacting with user's bank accounts can be broken down into these simple steps

Entrypoint

https://api.teller.io/

Response format

API responses are a single top-level JSON entity. Individual objects, e.g. a single bank account, are returned as JSON objects.

{
  "name": "Foo"
}

Collections are returned as an array of objects.

[
  {
    "name": "Foo"
  },
  {
    "name": "Bar"
  }
]

Error responses have a top-level `error` property that is a JSON object explaining the error condition.

{
  "error" : {
    "code": "forbidden"
    "message" : "Authorization token is invalid"
  }
}

If the error relates to invalid data submitted by the developer the error response will contain a `params` member enumerating the errors.

{
  "error" : {
    "code": "unprocessable_entity"
    "message" : "Please check and fix your errors"
    "params": {
      "account_number": ["can't be blank"],
      "amount": ["can't be blank"],
      "bank_code": ["has invalid format"]
    }
  }
}

Authentication

All requests to the Teller API must be authenticated. Teller authenticates the developer making the request using TLS client certificates issued to the them. The end user whose accounts the API request applies to is identified by an authorization token returned by the Teller Connect SDK

An example request using `curl`.

curl https://api.teller.io/accounts --cert cert.pem --key key.pem -H "Authorization: $TOKEN"

Hypermedia and linking

Each bank has different capabilities, e.g. some can be used to initiate payments, and others can't. You should not assume the availability of a particular type of functionality on any given account. You can discover what capabilities a given account supports by inspecting its links collection.

Resources

Bank Accounts

Collection

List all enrolled bank accounts.

GET /accounts
[
  {
    "account_number": "00000001",
    "routing_numbers": [
      {"type": "ach", "number": "0000000000"},
      {"type": "wire", "number": "1000000000"},
    ],
    "currency_code": "USD",
    "country_code": "US",
    "enrollment_id": "enr_xxxxxx",
    "id": "acc_xxxxxx",
    "institution": "test_bank",
    "links": {
       "self": "https://api.teller.io/accounts/acc_xxxxxx",
       "balances": "https://api.teller.io/accounts/acc_xxxxxx/balances"
       "transactions": "https://api.teller.io/accounts/acc_xxxxxx/transactions"
    },
    "name": "Everyday Value Checking"
  }
]

Individual Account

Return an individual bank account.

GET /accounts/:id
{
  "account_number": "00000001",
  "routing_numbers": [
    {"type": "ach", "number": "0000000000"},
    {"type": "wire", "number": "1000000000"},
  ],
  "currency_code": "USD",
  "country_code": "US",
  "enrollment_id": "enr_xxxxxx",
  "id": "acc_xxxxxx",
  "institution": "test_bank",
  "links": {
    "self": "https://api.teller.io/accounts/acc_xxxxxx",
    "balances": "https://api.teller.io/accounts/acc_xxxxxx/balances",
    "transactions": "https://api.teller.io/accounts/acc_xxxxxx/transactions"
  },
  "name": "Everyday Value Checking",
  "type": "bank_account"
}

Properties

NameDescription
account_numberThe bank account number
routing_numbersAn array of objects describing the routing numbers for the account
currency_codeThe ISO 4217 currency code of the account
country_codeThe ISO 3166-1 alpha-2 country code where the account is
enrollment_idThe id of the enrollment the account belongs to, e.g. accounts at the same bank. Inter-account transfers can be made between accounts belonging to the same enrollment
idThe unqiue Teller ID of the account
institutionThe name of the bank
links.selfThe URI of the account resource
links.balanceThe URI to the list of this account's balances
links.transactionsThe URI to the list of transactions on the account

Remember not all institutions support all capabilities. The canonical way to discover whether an account supports given functionality is to see whether it is linked to in the links collection.

Balances

List an account's various types of balances

GET /accounts/:id/balances
[
   {
      "type": "ledger",
      "amount": "100.00",
      "links": {
        "self": "https://api.teller.io/accounts/acc_xxxxxx",
        "account": "https://api.teller.io/accounts/acc_xxxxxx"
      },
   },
   {
      "type": "available",
      "amount": "100.00",
      "links": {
        "self": "https://api.teller.io/accounts/acc_xxxxxx",
        "account": "https://api.teller.io/accounts/acc_xxxxxx"
      },
   },
]
NameDescription
typeThe type of balance, e.g. ledger, or available
amountThe value of the balance
links.selfThe URI of the balance resource itself
links.accountThe URI of the account resource

Transactions

Collection

List all transactions on a specified bank account.

GET /accounts/:id/transactions
[
   {
      "amount": "-11.35",
      "counterparty": "MARKS&SPENCER PLC",
      "date": "2017-03-27",
      "description": "3903 24MAR17 CD , MARKS&SPENCER PLC , PANTHEON GB",
      "id": ":id",
      "links": {
         "self": "https://api.teller.io/accounts/:account_id/transactions/:id"
      },
      "type": "card_payment"
   },
   {
      "counterparty": "MARKS&SPENCER PLC",
      "amount": "-8.00",
      "date": "2017-03-27",
      "id": ":id",
      "links": {
         "self": "https://api.teller.io/accounts/:account_id/transactions/:id"
      },
      "type": "card_payment",
      "description": "3903 26MAR17 CD , MARKS&SPENCER PLC , PANTHEON GB"
   },
   {
      "id": ":id",
      "links": {
         "self": "https://api.teller.io/accounts/:account_id/transactions/:id"
      },
      "description": "3903 25MAR17 CD , HARE & TORTOISE , BRUNSW , LONDON GB",
      "type": "card_payment",
      "counterparty": "HARE & TORTOISE",
      "amount": "-22.55",
      "date": "2017-03-27"
   },
   ...
]

Individual Transaction

Returns an individual transaction

GET /accounts/:account_id/transactions/:id
{
  "amount": "-11.35",
  "counterparty": "MARKS&SPENCER PLC",
  "date": "2017-03-27",
  "description": "3903 24MAR17 CD , MARKS&SPENCER PLC , PANTHEON GB",
  "id": "txn_xxxxxxx",
  "links": {
     "self": "https://api.teller.io/accounts/:account_id/transactions/:id"
  },
  "type": "card_payment"
}

Properties

NameDescription
amountThe transaction amount denominated in the account currency
counterpartyThe transaction counterparty, e.g. a merchant, ATM, etc
dateThe ISO 8601 date when the transaction was posted to your account
descriptionA longer form description of the transaction
typeThe type of transaction, e.g. `card_payment`, `direct_debit`, etc
links.selfThe URI of the transactions