API - An API For Your Finances | Help Center

API

An API For Your Finances

All Topics

Security Sync Accounts Budgets Forecast Insights Investments Rules Backups Access Control Pricing IOU (Split Bills)Login API Mobile Tags Transactions Upload

Help > API

< All topics

Our API provides a flexible interface to personalize and customize your financial information. Read the documentation below and get started with sample code in Ruby, Python, PHP or Perl.

API documentation

API calls follow the format:

https://www.buxfer.com/api/[command]?token=login_token[&params]

Valid values for command:

loginget a unique 'token' which must included on all future requests

transaction_addadd a transaction

transaction_editedit a transaction

transaction_deletedelete a transaction

upload_statementupload a bank or credit card statement

transactionslist of transactions

accountslist of accounts with balances

loanslist of your loans

tagslist of your transaction tags

budgetslist of your budgets

reminderslist of your reminders

groupslist of your groups

contactslist of your contacts

All commands, except the login command, must specify a token parameter returned by the login command in the event of a successful login.

The response element contains a status element which reports the status of the API call. If the call succeeded, it's content is OK, otherwise it is ERROR: [error_description].

login

This command only looks at POST parameters and discards GET parameters.

Before accessing any of the API commands, you must obtain a unique, ephemeral token by logging in to the API service.

On successful login, the command returns a token which must be included in all future API requests.

Login using email address and password

POST /api/login email=john@doe.com&password=dohdoh

See sample output

{
  "response": {
    "status":"OK",
    "token":"XXX"
  }
}

transaction_add

This command only looks at POST parameters and discards GET parameters.

The following parameters are accepted:

description
amount
accountId
fromAccountId
toAccountId
date: YYYY-MM-DD
tags: comma-separated tag names
type: expense | income | refund | payment | transfer | investment_buy | investment_sell | investment_dividend | capital_gain | capital_loss | sharedBill | paidForFriend | settlement | loan
status: cleared | pending

Parameters for type = sharedBill

payers: [{"email", "amount"}] JSON-formatted array
sharers: [{"email", "amount"}] JSON-formatted array
isEvenSplit: true | false

Parameters for type = loan

loanedBy: uid | email
borrowedBy: uid | email

Parameters for type = paidForFriend

paidBy: uid | email
paidFor: uid | email

Got a pending paycheck for $4000 into bank account

POST /api/transaction_add description=Paycheck&type=income&amount=4000&status=pending

Loaned $8 to a friend for lunch

POST /api/transaction_add description=Loan&amount=8&type=loan&loanedBy=myself@email.com&borrowedBy=myfrield@email.com

Shared grocery bill with roommates

POST /api/transaction_add description=Grocery&amount=126&type=sharedBill&sharers=[{"email":"myself@email.com"},{"email":"roommate.1@email.com"},{"email":"roommate.2@email.com"}]&payers=[{"email":"myself@email.com","amount":100},{"email":"roommate.1@email.com","amount":26}]

See sample output

{
  "response":
  {
    "id":152158153,
    "description":"Safeway",
    "date":"2021-02-22",
    "type":"income",
    "amount":222.32,
    "expenseAmount":-222.32,
    "accountId":1128931,
    "accountName":"Cash",
    "tags":"",
    "tagNames":[],
    "status":"cleared",
    "sortDate":"2021-02-22"
  }
}

transaction_edit

This command only looks at POST parameters and discards GET parameters.

The following parameters are accepted:

id
description
amount
accountId
fromAccountId
toAccountId
date: YYYY-MM-DD
tags: comma-separated tag names
type: income | expense | transfer | refund | sharedBill | paidForFriend | loan
status: cleared | pending

Parameters for type = sharedBill

payers: [{"email", "amount"}] JSON-formatted array
sharers: [{"email", "amount"}] JSON-formatted array
isEvenSplit: true | false

Parameters for type = loan

loanedBy: uid | email
borrowedBy: uid | email

Parameters for type = paidForFriend

paidBy: uid | email
paidFor: uid | email

Got a pending paycheck for $4000 into bank account

POST /api/transaction_edit id=18282&description=Paycheck&type=income&amount=4000&status=pending

Loaned $8 to a friend for lunch

POST /api/transaction_edit id=3281&description=Loan&amount=8&type=loan&loanedBy=myself@email.com&borrowedBy=myfrield@email.com

Shared grocery bill with roommates

POST /api/transaction_edit id=28329&description=Grocery&amount=126&type=sharedBill&sharers=[{"email":"myself@email.com"},{"email":"roommate.1@email.com"},{"email":"roommate.2@email.com"}]&payers=[{"email":"myself@email.com","amount":100},{"email":"roommate.1@email.com","amount":26}]

See sample output

{
  "response": {
    "id":152158153,
    "description":"Safeway",
    "date":"2021-02-22",
    "type":"income",
    "amount":222.32,
    "expenseAmount":-222.32,
    "accountId":1128931,
    "accountName":"Cash",
    "tags":"",
    "tagNames":[],
    "status":"cleared",
    "sortDate":"2021-02-22"
  }
}

transaction_delete

This command only looks at POST parameters and discards GET parameters.

The following parameters are accepted:

id

Delete a transaction by id

POST /api/transaction_delete id=18282

See sample output

{
  "response": {
  }
}

upload_statement

This command only looks at POST parameters and discards GET parameters.

Parameters:

accountId
statement: the text of the statement to be uploaded
dateFormat: (optional) date format used in the statement (one of "MM/DD/YYYY" or "DD/MM/YYYY")

See sample output

{
  "response": {
    "status": "OK",
    "uploaded": true,
    "balance": 1015.17
  }
}

transactions

You can restrict the set of transactions returned by specifying parameters. The permitted parameters are:

accountId OR accountName
tagId OR tagName
startDate AND endDate OR month: date can be specified as "10 feb 2008", or "2008-02-10". month can be specified as "feb08", "feb 08", or "feb 2008".
budgetId OR budgetName
contactId OR contactName
groupId OR groupName
status: pending | reconciled | cleared
page: paginate between results

Each call to this method returns at most 100 transactions matching the specified criteria. If there are more that 100 results, you can specify increasing values of the page parameter to page through the results.

Your most recent 100 transactions

GET /api/transactions

Previous 100 transactions

GET /api/transactions?page=2

Transactions for account 'Amex'

GET /api/transactions?accountName=Amex

Transactions for account id f32ade4

GET /api/transactions?accountId=f32ade4

Transactions for tag 'Grocery' for January 2008

GET /api/transactions?transactions?tagName=Grocery&month=jan08

See sample output

{
  "response": {
    "status": "OK",
    // These are the total #transactions matching the query
    "numTransactions": 1334,
    "transactions": [
        { 
            "id": "2d510c2696ec50d19a4e122129c455df",
            "description": "RECURRING TRANSFER REF #OPEQG7BT",
            "date": "21 Feb",
            "type": "income",
            "amount": 25,
            "accountId": "eca68525d89d2385dda040c3b5c571c2",
            "tags": "transfer",
        },
        {
            "id": "45fd72247572d026f165aa5256ffea6b",
            "description": "RECURRING TRANSFER REF #OPE7XXPW",
            "date": "20 Feb",
            "type": "expense",
            "amount": 25,
            "accountId": "eca68525d89d2385dda040c3b5c571c2",
            "tags": "transfer",
        },
        {
            "id": "bb4871250c00d240de54ed522e9adaf6",
            "description": "other world computing: universal hd adapter (ide/sata : usb 2)",
            "date": "17 Feb",
            "type": "sharedbill",
            "amount": 67.85,
            "accountId": "e7b9d4d7c6974ad1e9ee320ad302874d",
            "tags": "",
            "extraInfo": "This transaction is a shared expense of $67.85, paid by John, split equally between me and John.",
        },
    ],
  },
}

accounts

List of all your accounts

GET /api/accounts

See sample output

{
  "response": {
    "status": "OK",
    "accounts": [
      {
        "id": "e7b9d4d7c6974ad1e9ee320ad302874d",
        "name": "Wallet",
        "bank": "Your Wallet",
        "balance": -9543.16,
      },
      {
        "id": "96586dff416564f56baed7711ac3e61a",
        "name": "PersonalChk",
        "bank": "Bank of America - Banking",
        "balance": 8391.28,
        "lastSynced": "2008-02-13 11:37:54",
      },
      {
        "id": "7b48a3c070d96d768e0de3ee3ed0b0b0",
        "name": "Amex",
        "bank": "American Express - Credit Cards",
        "balance": 0,
        "lastSynced": "2007-11-22 10:51:52",
      },
      {
        "id": "57bd3b47d5ef2665ee1c96d88419f737",
        "name": "CitiMastercard",
        "bank": "Citibank - Credit Cards",
        "balance": -473.15,
        "lastSynced": "2008-02-18 12:03:06",
      },
    ],
  },
}

loans

List of all your loans with friends

GET /api/loans

See sample output

{
  "response": {
    "status": "OK",
    "loans": [
      {
        "entity": "Housemates",
        "type": "group",
        "balance": -54.99,
        "description": "you owe",
      },
      {
        "entity": "Jeff",
        "type": "contact",
        "balance": -4.5,
        "description": "you owe",
      },
      {
        "entity": "harshi",
        "type": "contact",
        "balance": 444.24,
        "description": "you receive",
      },
      {
        "entity": "Buxfer Inc",
        "type": "contact",
        "balance": 959,
        "description": "you receive",
      },
    ],
  },
}

tags

List of all your tags

GET /api/tags

See sample output

{
  "response": {
    "status": "OK",
    "tags": [
      {
        "id": "080ed5cb2aa1aaf7986d2cc58c5d7f1f",
        "name": "Home",
        "parentId": -1,
      },
      {
        "id": "7e4008367454d64628775faf78287b9b",
        "name": "Rent",
        "parentId": "080ed5cb2aa1aaf7986d2cc58c5d7f1f",
      },
    ],
  },
}

budgets

List of all your budgets

GET /api/budgets

See sample output

{
  "response": {
    "status": "OK",
    "budgets": [
      {
        "id": "0e51dc6749e3a8a7f724c131b30cf712",
        "name": "Food",
        "limit": "205",
        "remaining": -52.85,
        "period": "1 month",
        "currentPeriod": "Feb 08",
        "tags": "eatingOut",
        "keywords": [],
      },
    ],
  }
}

reminders

List of all your reminders

GET /api/reminders

See sample output

{
  "response": {
    "status": "OK",
    "reminders": [
      {
        "id": "ab6e5ef4c574eaac1b7c64223434713e",
        "name": "AT&T bill",
        "startDate": "2008-11-08",
        "period": "1 month",
        "amount": 50,
        "accountId": "8a0776e351983cd74bc014fde2f54935",
      },
    ],
  },
}

groups

List of all your groups

GET /api/groups

See sample output

{
  "response": {
    "status": "OK",
    "groups": [
      {
        "id": "74a31314a31ab59c938d6d18679ce773",
        "name": "Housemates",
        "consolidated": true,
        "members": {
          "member": {
            "id": "92fc6740165e7a1a7c578a916dc60444",
            "name": "John",
            "email": "...",
            "balance": 30.00,
          },
          "member": {
            "id": "41cd07723def2a26c6a51882bf8e31d3",
            "name": "Pete",
            "email": "...",
            "balance": -45.00,
          },
          "member": {
            "id": "fb69cc3d5295ad73f3f397e1a4e94e05",
            "name": "Emily",
            "email": "...",
            "balance": 20.00,
          },
          "member": {
            "id": "3d85d5f681ee2d80764dfc647393e802",
            "name": "Lisa",
            "email": "...",
            "balance": -5.00,
          },
        },
      },
    ],
  },
}

contacts

List of all your contacts

GET /api/contacts

See sample output

{
  "response": {
    "status": "OK",
    "contacts": [
      {
        "id": "3d85d5f681ee2d80764dfc647393e802",
        "name": "Pete",
        "email": "...",
        "balance": 959,
      },
      {
        "id": "15aa85c42ba084f0c183b1d35f6b9c1e",
        "name": "Lisa",
        "email": "...",
        "balance": 444.24,
      },
    ],
  },
}

Sample Code

You can get started with some sample code in some of the popular languages listed below. Each sample program logs in and retrieves the login token, downloads the list of your budgets, and prints the name, spending limit and available balance for the budget for the current period.

Perl: buxfer_api_client.pl (requires LWP and JSON modules)
Python: buxfer_api_client.py (requires the simplejson module)
Ruby: buxfer_api_client.rb (requires the json gem)
PHP: buxfer_api_client.php (uses the CURL and JSON modules, available by default with most PHP installations after 5.2.1)

Financial information is sensitive and so special care must be taken to make sure it is not inadvertently leaked in any way due to the use of Buxfer's API.

Buxfer's responsibility

We take the following steps to make sure your data stays secure and private:

Requiring login tokens for API requests: In order to foil Cross site request forgery attacks (which all HTTP-Basic-auth based APIs are vulnerable to), we require all API requests to be accompanied with unique, ephemeral tokens which are impossible to forge.
Never store any sensitive data: We do not store your banking credentials, real-life names, phone numbers, addresses or anything that will even remotely identify you. The only thing we store is "description, date and amount" for your transactions.
128-bit SSL: We use industry standard security channels so your data never gets exposed over the wire.

API client's responsibility

API clients must manage Buxfer passwords carefully, and must NOT store them in plain-text or in easily retrievable ways. Although Buxfer's API is RESTful and no state is maintained on the server, it is always recommended not to inadvertently expose any transaction information to external parties.