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.

Please contact help@teller.io if you get stuck or have questions.

Getting Started

Follow these easy steps to begin making API calls on your own bank acounts in less than five minutes.

Basics

Entry Point

https://api.teller.io/

The Teller API is HTTPS ONLY. The API server does not listen on HTTP port 80 so there is no way for you to send sensitive data over the wire.

If you're having trouble connecting to the API server, check you're connecting to the correct port (443).

Live Data

All requests will receive live data synchronously from the bank. We do our best to make this as fast as possible, but if you want to return cached data after already making a live request in a session you can append live=false as a query string. Cached data is always returned lightning fast.

Responses

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"
  }
]

Unsuccessful responses have a top-level key error whose value is a JSON object explaining the error condition

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

Authentication

All requests to the Teller API must be authenticated. There are two methods of authentication:

Personal Access Tokens

As a developer you can make read-only requests on your own bank accounts using your personal access token.

To authenticate using this methods add an Authorization header to your request with your personal access token value.

Authorization: Bearer personal_access_token

TAuth

If you need to make write requests to your own accounts, e.g. moving money, or you want to make your app available for anyone else to use, all requests must be authenticated with TAuth.

TAuth is essentially OAuth 2.0 implicit grant where the client authenticates using SSL client certificate. It's far simpler than a 3-legged OAuth flow, and has none of the security problems OAuth greatly suffers from.

TAuth Client certificates

You can generate your TAuth certificate and private key on the Teller web interface application page in one click.

TAuth web flow

  1. Your app displays the Teller TAuth button
  2. The user clicks the button, is redirected to, and authenticates with Teller
  3. Teller redirects back to your app with a TAuth access token
  4. Your app makes requests to the Teller API using TAuth client certificates and access tokens

Hypermedia and linking

Each bank exposes different capabilities, e.g. some show standing orders, and others don'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 support by inspecting its links collection.

Resources

Bank Accounts

Collection

List all enrolled bank accounts.

GET /accounts 
[
  {
    "account_number" : "00000001",
    "balance" : "123.45",
    "bank_code" : "00-00-00",
    "currency" : "GBP",
    "enrollment_id" : "00000000-0000-0000-0000-000000000000",
    "id" : "00000000-0000-0000-0000-000000000000",
    "institution" : "test_bank",
    "links" : {
       "direct_debits" : "https://api.teller.io/accounts/00000000-0000-0000-0000-000000000000/direct_debits",
       "payees" : "https://api.teller.io/accounts/00000000-0000-0000-0000-000000000000/payees",
       "self" : "https://api.teller.io/accounts/00000000-0000-0000-0000-000000000000",
       "standing_orders" : "https://api.teller.io/accounts/00000000-0000-0000-0000-000000000000/standing_orders",
       "transactions" : "https://api.teller.io/accounts/00000000-0000-0000-0000-000000000000/transactions"
    },
    "name" : "TEST ACCOUNT"
  }
]

Individual Account

Return an individual bank account.

GET /accounts/:uuid
{
  "account_number" : "00000001",
  "balance" : "123.45",
  "bank_code" : "00-00-00",
  "currency" : "GBP",
  "enrollment_id" : "00000000-0000-0000-0000-000000000000",
  "id" : "00000000-0000-0000-0000-000000000000",
  "institution" : "test_bank",
  "links" : {
     "direct_debits" : "https://api.teller.io/accounts/00000000-0000-0000-0000-000000000000/direct_debits",
     "payees" : "https://api.teller.io/accounts/00000000-0000-0000-0000-000000000000/payees",
     "self" : "https://api.teller.io/accounts/00000000-0000-0000-0000-000000000000",
     "standing_orders" : "https://api.teller.io/accounts/00000000-0000-0000-0000-000000000000/standing_orders",
     "transactions" : "https://api.teller.io/accounts/00000000-0000-0000-0000-000000000000/transactions"
  },
  "name" : "TEST ACCOUNT"
}

Properties

NameDescription
account_numberThe bank account number
balanceThe current ledger balance of the account
bank_codeThe bank/branch code of the bank, e.g. UK bank account sort code
currencyISO 4217 currency code of the account
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 UUID of the account
institutionThe name of the bank
links.direct_debitsThe URI to the list of this account's Direct Debits
links.payeesThe URI to the list of 3rd parties payees for this account
links.selfThe URI of the account resource
links.standing_ordersThe URI to the list of this account's standing orders
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.

Transactions

Collection

List all transactions on a specified bank account.

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

Individual Transaction

Returns an individual transaction

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

Properties

NameDescription
amountThe tranaaction 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

Direct Debits

Direct Debits are recurring payments set up by a 3rd party via the Direct Debit scheme.

Collection

List all Direct Debit mandates on a specified bank account.

GET /accounts/:account_uuid/direct_debits
[
  {
      "last_requested" : "2017-03-08",
      "links" : {
         "self" : "https://api.teller.io/accounts/00000-0000-0000-0000-000000000000/direct_debits/00000000-0000-0000-0000-000000000000"
      },
      "id" : "00000000-0000-0000-0000-000000000000",
      "currency" : "GBP",
      "amount" : "28.00",
      "reference" : "938449760902",
      "originator_name" : "H3G"
   },
   ...
]

Individiual Direct Debit

Returns an individual Direct Debit

GET /accounts/:account_uuid/direct_debits/:uuid
[
  {
      "last_requested" : "2017-03-08",
      "links" : {
         "self" : "https://api.teller.io/accounts/00000-0000-0000-0000-000000000000/direct_debits/00000000-0000-0000-0000-000000000000"
      },
      "id" : "00000000-0000-0000-0000-000000000000",
      "currency" : "GBP",
      "amount" : "28.00",
      "reference" : "123456",
      "originator_name" : "H3G"
   },
   ...
]

Properties

NameDescription
originator_nameThe name of the Direct Debit originator
referenceThe originator's reference to this mandate
amountThe amount of the last payment
currencyThe currency of the last payment
idThe unique Teller UUID of the transaction
last_requestedThe date this mandate was last used
links.selfThe URI of the Direct Debit mandate

Standing Orders

Standing orders are recurring payments set up by the account owner

Collection

List all standing orders on a specific bank account.

GET /accounts/:account_uuid/standing_orders
[
   {
      "amount" : "0.01",
      "beneficiary" : {
         "name" : "JOE BLOGGS",
         "bank_code" : "00-00-00",
         "account_number" : "00000000"
      },
      "frequency" : "weekly",
      "currency" : "GBP",
      "id" : "00000-0000-0000-0000-000000000000",
      "links" : {
         "self" : "https://api.teller.io/accounts/00000-0000-0000-0000-000000000000/standing_orders/00000-0000-0000-0000-000000000000"
      },
      "reference" : "LOL"
   }
]

Individual Standing Order

Return an individual standing order

GET /accounts/:account_uuid/standing_orders/:uuid
{
  "amount" : "0.01",
  "beneficiary" : {
    "name" : "JOE BLOGGS",
    "bank_code" : "00-00-00",
    "account_number" : "00000000"
  },
  "currency" : "GBP",
  "frequency" : "weekly",
  "id" : "00000-0000-0000-0000-000000000000",
  "links" : {
    "self" : "https://api.teller.io/accounts/00000-0000-0000-0000-000000000000/standing_orders/00000-0000-0000-0000-000000000000"
  },
  "reference" : "LOL"
}

Properties

NameDescription
beneficiary.nameThe name of the beneficiary
beneficiary.bank_codeThe beneficary's bank code, e.g. sort code
beneficiary.account_numberThe beneficiary's bank account number
currencyThe currency of the standing order
idThe unique Teller UUID of the standing order
links.selfThe standing order's URI
referenceThe payment reference

Payees

Payees are 3rd parties who can receive payments from a given account. Payees are set up by the account owner.

Collection

List all payees on a specific bank account

GET /accounts/:account_uuid/payees
[
   {
      "account_number" : "0000000",
      "bank_code" : "00-00-00",
      "id" : "00000-0000-0000-0000-000000000000",
      "links" : {
         "self" : "https://api.teller.io/accounts/00000-0000-0000-0000-000000000000/payees/00000-0000-0000-0000-000000000000"
      },
      "reference" : "TELLER RTHGZDGGIZT",
      "name" : "JOE BLOGGS"
   },
   ...
]

Individual Payee

Return an individual payee

GET /accounts/:account_uuid/payees/:uuid
[
   {
      "account_number" : "0000000",
      "bank_code" : "00-00-00",
      "id" : "00000-0000-0000-0000-000000000000",
      "links" : {
         "self" : "https://api.teller.io/accounts/00000-0000-0000-0000-000000000000/payees/00000-0000-0000-0000-000000000000"
      },
      "reference" : "TELLER RTHGZDGGIZT",
      "name" : "JOE BLOGGS"
   },
   ...
]

Properties

NameDescription
account_numberThe beneficiary's bank account number
bank_codeThe beneficary's bank code, e.g. sort code
idThe unique Teller UUID of the payee
links.selfThe payee's URI
referenceThe payee reference that appears on the statement
nameThe name of the beneficiary