NAV Navbar
Big g
shell ruby csharp

Overview

Geezeo's integration platform is designed to allow partners flexibility in designing and deploying Geezeo features into existing financial platforms.

There are three major areas of integration with Geezeo.

Data Source

Geezeo's enrichment platform processes streams of financial transactions and provide valuable insights, tools and reporting for end users and institutions. The components that connect to partners and retrieve transactional data are Data Sources.

Geezeo has a library of existing Data Source connectors that are available for new implementations.

Geezeo also provides a number of standard Data Source options which institutions can implement. They are defined here.

UI Integration

Geezeo provides three levels of UI integration, all of which are responsive across screen sizes and configurable to match the look and feel of existing solutions.

Single Page Deployment

Geezeo provides a link to one page that end users can use for all of Geezeo's features. This single page includes a Navigation Bar to enable end users to navigate between features.

This deployment method is ideal for redirection or full screen iframe deployments. More details about deployment can be found here.

Integrated

Geezeo features are available as pages that can be directly deployed into existing partner applications. This model integrates Geezeo features into existing navigation constructs.

This deployment model provides a more seamless integration, enabling Geezeo features to feel more native in partner apps.

With this deployment model parters place Geezeo screens in resizable iframes, and handle the navigation between features. More details about Integrated can be found here

Responsive Tiles

Geezeo provides UI Components to enable deeply integrating features in partner applications.

Responsive Tiles are asynchronous JavaScript components that can be embedded into any existing html document.

Responsive Tiles require adding the Geezeo JavaScript SDK to the active application, providing a JWT key that was generated on the partners platform, and invoking methods that will render components into existing DOM elements. More details about Responsive Tiles can be found here.

API Integration

Geezeo provides APIs for all features, and uses the same API available to partners for product development.

Geezeo also provides SDKs for a number of popular platforms. These SDKs all generate JWT keys, and provide some additional mapping features or convenience methods.

If you have an idea for a product to build on the Geezeo API talk to your account representative to schedule a walk through.

Geezeo's various API resources are defined on the left.

API Authentication

Geezeo provides an API that exposes all of our platform features. The API address is the same as your SSO relay state, and referred to as partner.url in these documentations.

Geezeo provides two means of API authentication :

API Key authentication

curl -X "GET" "http://partner.url/api/v2/resource" -u "%geezeo-api-key%"

API Key authentication allows a partner's platform to call the API on behalf of all users, as well as call system API calls. API Key authentication is only appropriate for secure platform to platform communications.

Authentication with API key is done through Basic http Authentication. Using the API as the username, generate and attach a standard Basic Authentication header.

JWT Authentication

curl "https://regions-hackathon-2017.geezeo.com/api/v2/users/regions-hackathon-2017-01/accounts" -H "authorization: Bearer valid.jwt.token"

JSON Web Tokens provide a scope and time limited means of access to the API. A partner uses their API key and some other key information to generate a token that allows for time limited access to the API for a single user. JWT authentication cannot be used for system API calls.

The format and details of the Geezeo tokens can be are found in the JWT section. Platform SDKs are available for all major platforms to generate tokens.

New Platform

Geezeo New Platform is the new, upgraded version, of our existing online banking solutions.

Currently New Platform for mobile is complete and supported.

Integrating New Platform is very similar to previous versions of Geezeo Mobile and PFM.

Deployment Options

Single page

New Platform offers a Single Page deployment method with built in navigation. This deployment model is ideal for Clients that want to redirect, shell, or completely frame Geezeo New Platform experience.

Single Page New Platform provides a single SSO page that has all of Geezeo's features available in a white label product with navigation included.

Upgrading Geezeo Mobile to New Platform requires no changes on the partner's side. Contact your Geezeo representative to schedule an upgrade.

Integrated

New Platform also offers an Integrated deployment option without feature navigation. Geezeo provides Clients a simple way to deeply integrate Geezeo features into their existing banking solution.

Geezeo New Platform provides individual features that are deep linked to. New Platform does not provide navigation between features, but relies on the host application native navigation, which provides a much more integrated and customizable user experience.

If you have integrated Geezeo's navless mobile upgrading to New Platform requires changing the deep link urls after your Geezeo Representative has enabled updated mobile.

Integrated Page Integrated Mobile V2 URLS Old URL
Dashboard https://partner.url/m2?nav=false https://partner.url/m?nav=false#/
Accounts https://partner.url/m2?nav=false#/accounts https://partner.url/m?nav=false#/user1/accounts
Transactions https://partner.url/m2?nav=false#/transactions/search https://partner.url/m?nav=false#/transactionsearch/transactionsearchhome
Cashflow https://partner.url/m2?nav=false#/cashflow https://partner.url/m?nav=false#/cashflow/cashflowhome
Budget https://partner.url/m2?nav=false#/budgets https://partner.url/m?nav=false#/budget/budgethome
Goals https://partner.url/m2?nav=false#/goals https://partner.url/m?nav=false#/goals/goalshome
Networth https://partner.url/m2?nav=false#/networth https://partner.url/m?nav=false#/networth/networthhome
Alerts https://partner.url/m2?nav=false#/alerts https://partner.url/m?nav=false#/alerts/alertshome
Help https://partner.url/m2?nav=false#/help https://partner.url/m?nav=false#/help/helphome
Aggregation https://partner.url/m2?nav=false#/aggregation https://partner.url/m?nav=false#/aggregation/aggregationAdd

SAML technically supports an Integrated Deployment however the recommended approach of JWT/cookie-less is documented below.

Implementation

SAML Implementation

Geezeo SSO SAML is the recommended implementation method for the single page deployment method. This implementation is exactly the same the previous Geezeo Mobile implementations: use 'Mobile' as your potion in the platform field of the Geezeo SSO SAML token and the Geezeo platform will redirect the user to the mobile experience.

While this method does support both Single Page and Integrated deployment it is not recommended for Integrated.

JWT Implementation

A JWT, or cookie-less, implementation is recommended and the default implementation for an Integrated deployment. There are many benefits to using JWT such as:

A more detailed look at how Geezeo implements JWT requirements can be found here.

In addition a bootstrap page is expected to be added to our host system, and sample code is provided to bootstrap and configure New Platform. Valid JWT assertions are expected to be generated on the host platform and sent to the New Platform implementation via an HTML data element.

Keep Alive New Platform

window.addEventListener("message", function(event) {
  if (event.data["geezeo-keep-alive"]) {
    var http = new XMLHttpRequest();
    http.open("GET", event.data["geezeo-keep-alive"], true);
    try {
      http.send(null);
    } catch(e) {
      // Intentionally caught and ignored, do not react to keepalive failure
    }
  }
});

When implementing new platform in an iframe keep alive is needed. Since iframes have no access to parent cookies an HTTP POST is used to inform the container to keep the session alive with the partner provided 'keepalive url' during implementation.

Responsive Tile Implementation

Getting Started

Script example

<script>
window.geezeo = (function(d, s, id) {
  var js, fjs = d.getElementsByTagName(s)[0], g = window.geezeo || {};
  if (d.getElementById(id)) return g; js = d.createElement(s);
  js.id = id; js.src = 'partner.url/geezeo-tiles/env/v2/tiles.js'; fjs.parentNode.insertBefore(js, fjs);
  g._e = []; g.ready = function(f) { g._e.push(f); }; return g;
}(document, 'script', 'geezeo-tiles'));
</script>

Geezeo's Responsive Tiles are a set of JavaScript components used to render Geezeo features into partner applications.

Responsive Tiles are exposed as methods on the Geezeo JavaScript SDK. The JavaScript SDK is intended to be added to the page once, and will reuse data where appropriate to optimize User Experience and Bandwidth.

To get started, the host page will need add the following HTML snippet to the web page. This will retrieve the SDK and setup the global geezeo object.

Please note, each institution will receive their own JavaScript location during implementation. This location will vary based on Geezeo environment, and should be implemented as a configuration setting if possible.

The token

The partner will generate a JWT via a Geezeo SDK (or via their own means) and set it using the setAuth() method. All platform SDK’s have a JWT generation method added to them. Please work with your Geezeo implementation team to get the appropriate platform SDK.

Please see the JWT section of our documentation for detailed information regarding JWT.

Geezeo has made an online JWT generator you may use for testing purposes.

Note: Since JWT's can technically be generated anywhere including on the client side it would be a huge security risk to do so as they require an API key to create. All JWT generation should be done server side.

Tiles Implementation

Responsive Tiles API

JavaScript example

geezeo.ready(function() {
  geezeo.tiles.createSpending(document.getElementById('tile'));
});

jQuery example

$(function () {
  geezeo.ready(function() {
    geezeo.tiles.createSpending($('#tile')[0]);
  });
});

Promise example

function isGeezeoReady() {
  return new Promise(function(resolve, reject) {
    geezeo.ready(resolve);
  });
}

isGeezeoReady()
  .then(function() {
    geezeo.tiles.createSpending(document.getElementById('tile'));
  });

Responsive Tiles are ready to be rendered into the dom after the Geezeo ready callback has been called as shown here.

Tiles will render with sample data if no security token has been provided. Tiles can also have custom data injected for demo purposes, contact Geezeo to learn more.

Tiles will render a user's data when provided a JWT key. If a JWT key is provided, no demo data will be displayed. Use setAuth from methods to authenticate a user.

Tiles support a number of other methods for various purposes, for example setting a marketing image when a user does not exist yet, or trapping a click to initiate another tile.

Tiles support a number of white label and configuration options. These options are outlined below, and passed in as a parameter to a tile's create method.

Tile Mapping

Responsive Tile Function
Accounts createAccounts
Aggregation createAggregation
Budgets createBudgets
Cashflow createCashflow
Goals createGoals
Networth createNetworth
Spending createSpending
Spending-Wheel createSpendingWheel
Transactions createTransactions

Tile Options

While using tiles an options object may be used to modify the tile.

Tiles will attempt to grow to fit their container and some tiles will change their appearance at certain widths. If you need tiles to be a certain size use standard CSS to constrain the container elements to fit your use cases.

Spending example with options

geezeo.ready(function() {
  geezeo.tiles.createSpending(document.getElementById('tile'), {
    palette: {
      primary: {
        main: '#006699'
      }
    }
  });  
});

Implementing White Label Options

Geezeo tile colors can be white labeled to match your website's color scheme. this will work with most tiles.

Example of an options object

var options = {

  showHeader         : true,
  showProductHeader  : true,
  showCloseButton    : true,
  donutSize          : 250,  
  enableSettings     : true,
  showAdvancedSearch : true,
  hideTitle          : true,

  typography: {
    fontFamily   : '"Comic Sans MS", cursive, sans-serif',
    htmlFontSize : 10
  },

  palette: {
    primary: {
      main         : '#000000',
      light        : '#000000',
      dark         : '#000000',
      contrastText : '#000000'
    },
    secondary: {
      main         : '#000000',
      light        : '#000000',
      dark         : '#000000',
      contrastText : '#000000'
    },
    custom: {
      positive : '#000000',
      negative : '#000000',
      success  : '#000000',
      error    : '#000000',
      warning  : '#000000',
      header   : '#000000',
      tag      : '#000000',
      tagText  : '#000000'
    },
  }
}

Colors

If you want to stick with a default option you can omit the attribute.

*Note: Not all color options are supported with every tile. If you include a color option for a tile where it is not supported the tile will still render.

Note: If primary.dark/primary.light or secondary.light/secondary.dark are not passed they are based off of primary.main and secondary.main respectively

palette: {
  primary: {
    main         : '#000000',
    light        : '#000000',
    dark         : '#000000',
    contrastText : '#000000'
  },
  secondary: {
    main         : '#000000',
    light        : '#000000',
    dark         : '#000000',
    contrastText : '#000000'
  }
}

Custom Colors

custom: {
  positive : '#000000',
  negative : '#000000',
  success  : '#000000',
  error    : '#000000',
  warning  : '#000000',
  header   : '#000000',
  tag      : '#000000',
  tagText  : '#000000'
}
Property Desc
positive used on positive numbers in some areas (normally a dark green)
negative used on negative numbers in some areas (normally a dark red)
success used as success color in meters (normally green)
error used as error color in meters (normally error)
warning used as warning color in meters (normally yellow)
header used on the color of the header
tag used for the color of the transaction tag
tagText used for the color of the text on transaction tags

Fonts

typography: {
  fontFamily   : '"Comic Sans MS", cursive, sans-serif',
  htmlFontSize : 10
}
Property Desc
fontFamily what font family to use
htmlFontSize the font size on the html element which is used to adjust tile fonts that use REM units. Some UI frameworks alter this, so this property is supportedd to adjust the font size within tiles. Refer to CSS REM units for more info.

Misc

{
  showHeader         : true,
  showProductHeader  : true,
  showCloseButton    : true,
  containerHeight    : 400,
  donutSize          : 250,
  enableSettings     : true,
  showAdvancedSearch : true,
  hideTitle          : true
}

Property Value Desc
showHeader boolean the header containing the screen title
showProductHeader boolean the header containing the product name
showCloseButton boolean whether to show the close button on the screen header (close will always show on full screen dialogs)
donutSize number the pixel size of the donut visualization in the spending wheel
enableSettings boolean whether to show the settings icon on the spending wheel tile
showAdvancedSearch boolean whether to show the advanced search features within the transaction search
hideTitle boolean used to hide the title in app bar, only applies to some routes with titleHideable = true (typically top level pages, so that the partner can apply their own title)

Methods

geezeo.setAuth(token): This method is used to use a JWT with tiles. Please see the JWT section for additional information on JWT.

Param Type Description
token string The JWT token

setAuth() example

<div id="tile"></div>
<script>
geezeo.ready(function () {

  // example of setting a JWT token
  geezeo.setAuth('eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIxIiwiYXVkIjoiZ2VlejNvLmdlZXplby5jb20iLCJzdWIiOiJhYXJvbnRlc3QxIiwiaWF0IjoxNDg2NzU1NjM4LCJleHAiOjE0ODY3NTkyMzh9.RZIEzHmQv-BMwHV6vp1H-DOKajDQCU6lpJRxxJSbkQo');

  var el = document.getElementById('tile');
  geezeo.tiles.createSpending(el, {
    palette: {
      primary: {
        main: '#006699'
      }
    }
  });

});
</script>

geezeo.ready(fn): Any functions called within the ready function won't be called until the tiles library is fully loaded. This ensures functions aren't run too early and prevents unnecessary errors.

Param Type Description
fn function The function you want to run after the tiles library is fully loaded

geezeo.on(eventName, listener): This function is used to support event callback registration.

Param Type Description
eventName string The event that will trigger the function
listener function The result of the trigger (aka a function)

geezeo.create(): Used to create a specific tile.

tile.setErrorHandler(): Allows the FI to set and customize what happens when there is an error within the tile. In the case of the example to the side if an image url is returned the tile will replace itself with the provided image. If no image is returned a generic error message will be displayed.

tile.setInvalidUserHandler(): This is triggered when the system gets a 404 due to the user being requested does not exist.

setErrorHandler(), and ready() example

geezeo.ready(function () {
  var el = document.getElementById('tile');
  tile = geezeo.tiles.createSpending(el);
  tile.setErrorHandler(function (error) {
    return 'http://url-to-image-to-display.jpg';
  });
});

Supported Events

on() and close event example switching between the spending wheel and transactions tile:

function loadSpendingWheel() {
  geezeo.tiles
    .createSpendingWheel(element)
    .on('click', loadTransactions);
}

function loadTransactions(data) {
  geezeo.tiles
    .createTransactions(element, {
      showHeader   : true,
      accounts     : data.accounts
      tags         : data.tags,
      dateRange    : data.dateRange,
      showUntagged : data.tags.includes('')
    })
    .on('close', loadSpendingWheel);
}

Keep Alive

Geezeo products can detect user interaction, and participate in Online Banking and Mobile keep alive. During implementation provide a keep alive url and an interval, and the Geezeo products will call that keep alive after the specified number of minutes if the user has interacted with it.

Handling keepalive in Frames

If Geezeo is running in an iframe the keep alive call will not include cookies from the parent page. Cookies are the most common form of session management, therefore keep alive does not work with this model. In this case, Geezeo products will detect if they are in a frame and create an (postMessage)https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage for the container app to catch. The consumer application is required to catch this message, and make the keepalive call on behalf of Geezeo. The example code here can be used to catch, and make keepalive calls. Add this to your web application only once anywhere to catch and make keepalive calls to the configured url.

window.addEventListener("message", function (event) {
    if (event.data["geezeo-keep-alive"]) {
        var http = new XMLHttpRequest();
        http.open("GET", event.data["geezeo-keep-alive"], true);
        try {
            http.send(null);
        } catch (e) {
            // Intentionally caught and ignored, do not react to keepalive failure
        }
    }
});

Accounts

Account Types

Group Account Types
Cash checking, savings, money market
Debt autos creditline home loan student_loans
Investment investment
Asset asset cd
Credit card cards
Bill bill

Get Accounts

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/accounts" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/accounts')
key = '%geezeo-api-key%'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var accounts = sdk.GetAccounts();

Response payload

{
  "accounts": [
    {
      "id": 42,
      "name": "eChecking",
      "balance": "300.54",
      "reference_id": "789274930",
      "aggregation_type": "cashedge",
      "state": "active",
      "harvest_updated_at": "2013-03-05T12:00:00Z",
      "account_type": "checking",
      "display_account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "fi": {
        "id": 2,
        "name": "CashEdge Test Bank (Agg) - Retail Non 2FA"
      },
      "error": {
        "message": "There was an error.",
        "code": "300",
        "actionable": true
      },
      "cashedge_account_type": {
        "name": "Savings",
        "acct_type": "SDA",
        "ext_type": "SDA",
        "group": "Cash"
      },
      "other_balances" : {
        "balance_type": "current",
        "balance" : "300.54"
      }
    }
  ]
}

Return a list of accounts for the given user (this will exclude non-classified CashEdge accounts).

GET /api/v2/users/:user_id:/accounts

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get All Accounts

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/accounts/all" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/accounts/all')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id"
var sdk = new SDK(apiKey, url, userId);
var accounts = sdk.GetAllAccounts();

Response payload

{
  "accounts": [
    {
      "id": 42,
      "name": "eChecking",
      "balance": "300.54",
      "reference_id": "789274930",
      "aggregation_type": "cashedge",
      "state": "active",
      "harvest_updated_at": "2013-03-05T12:00:00Z",
      "account_type": "checking",
      "display_account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "fi": {
        "id": 2,
        "name": "CashEdge Test Bank (Agg) - Retail Non 2FA"
      },
      "error": {
        "message": "There was an error.",
        "code": "300",
        "actionable": true
      },
      "cashedge_account_type": {
        "name": "Savings",
        "acct_type": "SDA",
        "ext_type": "SDA",
        "group": "Cash"
      }
    }
  ]
}

Return a list of accounts for the given user (this will exclude non-classified CashEdge accounts).

GET /api/v2/users/:user_id:/accounts/all

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Potential Cashflow Accounts

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/accounts/potential_cashflow" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/accounts/potential_cashflow')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var accounts = sdk.GetPotentialCashflowAccounts();

Response payload

{
  "accounts": [
    {
      "id": 42,
      "name": "eChecking",
      "balance": "300.54",
      "reference_id": "789274930",
      "aggregation_type": "cashedge",
      "state": "active",
      "harvest_updated_at": "2013-03-05T12:00:00Z",
      "account_type": "checking",
      "display_account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "fi": {
        "id": 2,
        "name": "CashEdge Test Bank (Agg) - Retail Non 2FA"
      },
      "error": {
        "message": "There was an error.",
        "code": "300",
        "actionable": true
      },
      "cashedge_account_type": {
        "name": "Savings",
        "acct_type": "SDA",
        "ext_type": "SDA",
        "group": "Cash"
      }
    }
  ]
}

Return a list of accounts for the given user (this will exclude non-classified CashEdge accounts).

GET /api/v2/users/:user_id:/accounts

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Account

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/accounts/:account_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/accounts/:account_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
int accountId = account_id;
var sdk = new SDK(apiKey, url, userId);
var accounts = sdk.GetAccountById(accountId);

Response payload

{
  "accounts": [
    {
      "id": 42,
      "name": "eChecking",
      "balance": "300.54",
      "reference_id": "789274930",
      "aggregation_type": "partner",
      "state": "active",
      "harvest_updated_at": "2013-03-05T12:00:00Z",
      "account_type": "checking",
      "display_account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "fi": {
        "id": 2,
        "name": "CashEdge Test Bank (Agg) - Retail Non 2FA"
      },
      "cashedge_account_type": {
        "name": "Savings",
        "acct_type": "SDA",
        "ext_type": "SDA",
        "group": "Cash"
      }
    }
  ]
}

Return a list of accounts for the given user (this will exclude non-classified CashEdge accounts).

GET /api/v2/users/:user_id:/accounts/:account_id:

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Account Investments

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/accounts/:account_id:/investments" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/accounts/:account_id:/investments')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
int accountId = account_id;
var sdk = new SDK(apiKey, url, userId);
var accounts = sdk.GetInvestmentsByAccountId(accountId);

Response payload

{
  "other_balances": [
    {
      "balance_type": "Mmf",
      "description": "MMF",
      "balance": "234.12"
    }
  ],
  "positions": [
    {
      "shares": "1.0",
      "price": "485.63",
      "market_value": "485.63",
      "ticker": {
        "symbol": "AAPL",
        "name": "Apple Inc."
      }
    }
  ]
}

Return investment data for the given account.

GET /api/v2/users/:user_id:/accounts/:account_id:/investments

Balance Types

Type Description
TotalBrokerageAccountValue Total Brokerage Account Value
Securities Securities
Cash Cash
Mmf MMF
BuyingPower Buying Power
MarginBalance Margin Balance
CurrentVestedBalance Current Vested Balance
TotalAmountOfCompanyMatch Company Matching Amount
TotalAmountOfContributions Total Contributions
DeferralPercentage Deferral Percentage
LoanAmount Loan Amount
DeathBenefit Death Benefit
CashSurrenderValue Cash Surrender Value
InsurancePremium Insurance Premium
EmployerProfitsSharing Employer Profits Sharing
DailyChange Daily Change
PercentageChange Percentage Change
ContinuousYears Continuous Years
InterestRate Interest Rate

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Update Account

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/accounts/:account_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/accounts/:account_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
int accountId = account_id;
var sdk = new SDK(apiKey, url, userId);
var accountToUpdate = new Account
{
    Name = "Renamed Checking"
};

var accountRequest = new AccountRequestModel {Account = accountToUpdate};

bool response = sdk.UpdateAccount(accountId, accountRequest); //returns a bool indicating whether delete was successful


Request Payload

{
  "account": {
    "name": "Joint Checking"
  }
}

Update an account for the given user.

Parameters

Parameter Description
name The name of the account.
'account_type' Account type from closed list
'display_account_type' What the user sees for the account type

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Delete Account

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:/accounts/:account_id:" -u "%geezeo-api-key%""
uri = URI('https://partner.url/api/v2/users/:user_id:/accounts/:account_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
int accountId = account_id;
var sdk = new SDK(apiKey, url, userId);
bool deleted = sdk.DeleteAccount(accountId); //returns a bool indicating whether delete was successful

Delete an account for the given user.

Request

DELETE /api/v2/users/:user_id:/accounts/:account_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Error Codes

In the event you run into an error code for an account refer to the following error codes.

User Failure

Failure Category Error Code Description
Login Failure
300 Login Failure
301 Login Failure - Invalid Login Credentials
305 Invalid Client or Account Identifier
306 Incorrect FI Selection
307 Account Locked
701 Add attempt did not retrieve any accounts
MFA Failure
303 Additional information required for authentication
304 Incorrect answer provided for challenge questions
Account Classification Failure
209 Incorrect Account Type classification
Account Identification Failure
201 Site Change - Account maintenance needed
203 Account not found
204 Account no longer exists
User Attention Required at FI
302 Website Attention required

FI Website Failure

Failure Category Error Code Description
FI Website Failure
103 Un-existing URL (or) network failure
104 Time out error
105 Target server error or server down
106 Connection failed
107 SSL Error
108 Server error (FI website intense)
109 Client error
110 Account Information unavailable

Script / Software Failure

Failure Category Error Code Description
Layout Failure
100 Internal software error
200 Site change
202 Account identification failure - multiple matches
205 Account identification failure - no accounts
311 Harvest failure
Software Failure
400 Database update failure
999 Internal software error - unknown error
Account Not Updated
121 Account is not updated

Ads

Get Ads

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/ads" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/ads')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var searchCriteria = new AdSearchCriteria{
    CampaignLocation = "campaign location",
    AdDimensions = "ad dimensions",
    Count = 1
};
// use new AdSearchCriteria() to return all relevant ads
var adsResponse = new AdsApi(_apiKey).GetAds(UserId, searchCriteria);

Response payload

{
  "campaign_impressions": [{
    "id": 270,
    "ad_target": "http://www.example.com/api/v2/users/42/campaign_impressions/270/click",
    "links": {"marketing_campaign": 338}
  }],
  "marketing_campaigns": [{
    "id": 338,
    "campaign_location": null,
    "marketing_campaign_image": "http://www.example.com/lorem.jpg",
    "title": "title"
  }]
}

Return ads that are relevant to a user. This registers an impression for each returned ad, so API clients are expected to display all ads returned.

GET /api/v2/users/:user_id:/ads GET /api/v2/users/:user_id:/ads?parameters

Parameters

Parameter Description
campaign_location Limit results to this campaign location.
count Retrieve at most this many campaign impressions. Defaults to 1.
ad_dimensions Retrieve only ads with the requested ad_dimensions.
Description ad_dimensions campaign_location
Alert Ad 650_100 Alert
Budget Ad 650_100 Budget
Cashflow Ad 650_100 Cashflow
Goal Ad 650_100 SavingsGoal
Large Banner Ad 650_100 n/a
Left Sidebar Ad 225_225 n/a
Mobile Ad 320_80 Mobile
Net Worth Ad 650_100 Networth
Right Sidebar Ad 200_200 n/a
Small Right Sidebar Ad 95 _95 n/a
Transaction Feed Ad 425_100 n/a

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Ad Zones

There are several locations advertisements can be located in PFM. A full breakdown of where these ad zones are located and their resolutions can be found here

Alerts

Get Alerts

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/alerts" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertContainer = sdk.GetAlerts();

/*
AlertContainer contains the following public fields:

        public List<AccountThresholdAlertResponse> AccountThresholdAlerts;
        public List<GoalAlertResponse> GoalAlerts;
        public List<MerchantNameAlertResponse> MerchantNameAlerts;
        public List<SpendingTargetAlertResponse> SpendingTargetAlerts;
        public List<TransactionLimitAlertResponse> TransactionLimitAlerts;
        public List<UpcomingBillAlertResponse> UpcomingBillAlerts;

*/

Response payload

{
  "alerts": [
    {
      "id": 170,
      "options": {
        "threshold_amount": 0.0,
        "threshold_type": "minimum"
      },
      "email_delivery": true,
      "sms_delivery": true,
      "source_type": "Account",
      "source_id": "2944",
      "type": "AccountThresholdAlert",
      "source": {
        "id": 2944,
        "name": "eChecking",
        "balance": "300.54",
        "reference_id": "789274930",
        "aggregation_type": "partner",
        "state": "active",
        "harvest_updated_at": "2013-03-05T12:00:00Z",
        "account_type": "checking",
        "include_in_expenses": true,
        "include_in_budget": true,
        "include_in_cashflow": true,
        "include_in_dashboard": true,
        "include_in_goals": true,
        "include_in_networth": true,
        "fi": {
          "id": 2,
          "name": "CashEdge Test Bank (Agg) - Retail Non 2FA"
        },
        "cashedge_account_type": {
          "name": "Savings",
          "acct_type": "SDA",
          "ext_type": "SDA",
          "group": "Cash"
        }
      }
    },
    {
      "id": 171,
      "options": {
        "percentage": 50
      },
      "email_delivery": true,
      "sms_delivery": true,
      "source_type": "PayoffGoal",
      "source_id": 583,
      "type": "GoalAlert",
      "source": {
        "id": 583,
        "name": "Payoff a car",
        "image_name": "car.jpg",
        "state": "active",
        "status": "risk",
        "initial_value": "10.00",
        "current_value": "200.00",
        "target_value": "0.00",
        "monthly_contribution": "50.00",
        "percent_complete": 5,
        "complete": false,
        "target_completion_on": "2014-05-21",
        "created_at": "2013-01-01T16:54:15Z",
        "updated_at": "2013-10-01T20:21:01Z",
        "links": {
          "accounts": [2944]
        }
      }
    }
  ]
}

Return a list of all alerts for a user.

GET /api/v2/users/:user_id:/alerts

For c#, the response is wrapped in the AlertContainer class which contains a list of each alert type.

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Alert

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/alerts/:alert_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/:alert_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertId = 12345;
var alertContainer = sdk.GetAlertById(alertId);

Response payload

{
  "alerts": [
    {
      "id": 170,
      "options": {
        "threshold_amount": 0.0,
        "threshold_type": "minimum"
      },
      "email_delivery": true,
      "sms_delivery": true,
      "source_type": "Account",
      "source_id": "2944",
      "type": "AccountThresholdAlert",
      "source": {
        "id": 2944,
        "name": "eChecking",
        "balance": "300.54",
        "reference_id": "789274930",
        "aggregation_type": "partner",
        "state": "active",
        "harvest_updated_at": "2013-03-05T12:00:00Z",
        "account_type": "checking",
        "include_in_expenses": true,
        "include_in_budget": true,
        "include_in_cashflow": true,
        "include_in_dashboard": true,
        "include_in_goals": true,
        "include_in_networth": true,
        "fi": {
          "id": 2,
          "name": "CashEdge Test Bank (Agg) - Retail Non 2FA"
        },
        "cashedge_account_type": {
          "name": "Savings",
          "acct_type": "SDA",
          "ext_type": "SDA",
          "group": "Cash"
        }
      }
    }
  ]
}

Return an alert for the given user.

GET /api/v2/users/:user_id:/alerts/:alert_id:

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Delete Alert

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:/alerts/:alert_id:" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/:alert_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertId = 12345;
var alertContainer = sdk.DeleteAlert(alertId);

Delete an alert for the given user.

DELETE /api/v2/users/:user_id:/alerts/:alert_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Create Account Threshold Alert

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/alerts/account_thresholds" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/account_thresholds')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end


var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);

var thresholdAlert = new ThresholdAlertRequestModel{
    Alert = new ThresholdAlertModel{
        AccountId = 4394163,
        ThresholdType = ThresholdType.Minimum,
        ThresholdAmount = 80,
        EmailDelivery = true,
        SMSDelivery = false
    }
};

var response = sdk.CreateThresholdAlert(thresholdAlert);

Request payload

{
  "alert": {
    "account_id": 42,
    "threshold_amount": 100,
    "threshold_type": "minimum",
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Create an account threshold alert for the given user.

POST /api/v2/users/:user_id:/alerts/account_thresholds

Parameters

Parameter name Parameter Description
account_id The account that this alert should monitor. Required
threshold_amount The amount, in dollars, at which the alert will be triggered. Required
threshold_type Trigger the alert by going above the (maximum) or below the (minimum) alert[threshold_amount]. Valid values are maximum and minimum. Required
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Account Threshold Alert

curl -X "PUT" "http://partner.url/api/v2/users/alerts/account_thresholds/:alert_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/alerts/account_thresholds/:alert_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertId = 12345;

var thresholdAlert = new ThresholdAlertRequestModel{
    Alert = new ThresholdAlertModel{
        AccountId = 4394163,
        ThresholdType = ThresholdType.Minimum,
        ThresholdAmount = 80,
        EmailDelivery = true,
        SMSDelivery = false
    }
};

var updated = sdk.UpdateThresholdAlert(alertId, thresholdAlert);

Request payload

{
  "alert": {
    "threshold_amount": 100,
    "threshold_type": "minimum",
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Update an account threshold alert for the given user.

PUT /api/v2/users/:user_id:/alerts/account_thresholds/:alert_id:

Parameters

Parameter Description
account_id The account that this alert should monitor.
threshold_amount The amount, in dollars, at which the alert will be triggered.
threshold_type Trigger the alert by going above the (maximum) or below the (minimum) threshold_amount. Valid values are maximum and minimum.
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Create Goal Alert

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/alerts/goals" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/goals')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

//create Savings Goal

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertRequest = new SavingsGoalAlertRequestModel
{
    Alert = new SavingsGoalAlertModel
    {
        Percentage = 85,
        SavingsGoalId = 3998,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var createdAlert = sdk.CreateSavingsGoalAlert(alertRequest);

// Create Payoff Goal

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertRequest = new PayoffGoalAlertRequestModel
{
    Alert = new PayoffGoalAlertModel
    {
        Percentage = 85,
        PayoffGoalId = 3998,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var createdAlert = sdk.UpdateSavingsGoalAlert(alertRequest);

Request payload

{
  "alert": {
    "percentage": 95,
    "payoff_goal_id": 432,
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Create a goal alert for the given user.

POST /api/v2/users/:user_id:/alerts/goals

Parameters

Parameter Description
percentage The percent completion at which to trigger the alert. Required
payoff_goal_id The ID of the payoff goal to monitor. This or savings_goal_id is required to be present.
savings_goal_id The ID of the savings goal to monitor. This or payoff_goal_id is required to be present.
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Goal Alert

curl -X "PUT" "http://partner.url/api/v2/users/alerts/goals/:alert_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/alerts/goals/:alert_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end


var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertRequest = new GoalAlertRequestModel
{
    Alert = new GoalAlertModel
    {
        Percentage = 85,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var createdAlert = sdk.UpdateGoalAlert(alertRequest);

Request payload

{
  "alert": {
    "percentage": 95,
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Update a goal alert for the given user.

PUT /api/v2/users/:user_id:/alerts/goals/:alert_id:

Parameters

Parameter Description
percentage The percent completion at which to trigger the alert.
payoff_goal_id The ID of the payoff goal to monitor. This or savings_goal_id is required to be present.
savings_goal_id The ID of the savings goal to monitor. This or payoff_goal_id is required to be present.
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Response

The response body will be empty.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity` returned when the parameters given were invalid

Create Merchant Name Alert

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/alerts/merchant_names" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/merchant_names')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end


var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var merchantName = "test mart";
var alertRequest = new MerchantNameAlertRequestModel
{
    Alert = new MerchantNameAlertModel
    {
        Name = name,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var createdAlert = sdk.CreateMerchantNameAlert(alertRequest);

Request payload

{
  "alert": {
    "name": "Starbucks",
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Create a merchant name alert for the given user.

POST /api/v2/users/:user_id:/alerts/merchant_names

Parameters

Parameter Description
name The name of the merchant that when found in a transaction will trigger the alert Required.
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Merchant Name Alert

curl -X "PUT" "http://partner.url/api/v2/users/alerts/merchant_names/:alert_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/alerts/merchant_names/:alert_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end


var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertId = 12345;
var merchantName = "test mart";
var alertRequest = new MerchantNameAlertRequestModel
{
    Alert = new MerchantNameAlertModel
    {
        Name = name,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var updated = sdk.UpdateMerchantNameAlert(alertId, alertRequest);

Request payload

{
  "alert": {
    "name": "Starbucks",
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Update a merchant name alert for the given user.

PUT /api/v2/users/:user_id:/alerts/merchant_names/:alert_id:

Parameters

Parameter Description
name The name of the merchant that when found in a transaction will trigger the alert.
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Create Spending Target Alert

Request payload

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/alerts/spending_targets" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/spending_targets')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end


var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var budgetId = 56789;
var percentage = 70;
var alertRequest = new SpendingTargetAlertRequestModel
{
    Alert = new SpendingTargetAlertModel
    {
        BudgetId = budgetId,
        Percentage = percentage,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var createdAlert = sdk.CreateSpendingTargetAlert(alertRequest);
{
  "alert": {
    "budget_id": 2213,
    "percentage": 70,
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Create a spending target alert for the given user.

POST /api/v2/users/:user_id:/alerts/spending_targets

Parameters

Parameter Description
budget_id The ID of the budget to add the alert to. Required
percentage The integer percentage of the budget that when exceeded will trigger the alert. Required
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Spending Target Alert

curl -X "PUT" "http://partner.url/api/v2/users/alerts/spending_targets/:alert_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/alerts/spending_targets/:alert_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end


var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertId = 12345;
var budgetId = 56789;
var percentage = 70;
var alertRequest = new SpendingTargetAlertRequestModel
{
    Alert = new SpendingTargetAlertModel
    {
        BudgetId = budgetId,
        Percentage = percentage,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var updated = sdk.UpdateSpendingTargetAlert(alertId, alertRequest);

Request payload

{
  "alert": {
    "budget_id": 2213,
    "percentage": 70,
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Update a spending target alert for the given user.

PUT /api/v2/users/:user_id:/alerts/spending_targets/:alert_id:

Parameters

Parameter Description
budget_id The budget ID of the alert.
percentage The integer percentage of the budget that when exceeded will trigger the alert.
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Create Transaction Limit Alert

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/alerts/transaction_limits" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/transaction_limits')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end


var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var accountId = 56789;
var limit = 100;
var alertRequest = new TransactionLimitAlertRequestModel
{
    Alert = new TransactionLimitAlertModel
    {
        AccountId = accountId,
        Limit = limit,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var createdAlert = sdk.CreateTransactionLimitAlert(alertRequest);

Request payload

{
  "alert": {
    "account_id": 42,
    "limit": 100,
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Create a transaction limit alert for the given user.

POST /api/v2/users/:user_id:/alerts/transaction_limits

Parameters

Parameter Description
account_id The account ID of the alert. Required
limit The integer amount (in dollars) of a transaction that when exceeded will trigger the alert. Required
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Transaction Limit Alert

curl -X "PUT" "http://partner.url/api/v2/users/alerts/transaction_limits/:alert_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/alerts/transaction_limits/:alert_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end


var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertId = 12345;
var accountId = 56789;
var limit = 100;
var alertRequest = new TransactionLimitAlertRequestModel
{
    Alert = new TransactionLimitAlertModel
    {
        AccountId = accountId,
        Limit = limit,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var updated = sdk.UpdateTransactionLimitAlert(alertId, alertRequest);

Request payload

{
  "alert": {
    "account_id": 42,
    "limit": 100,
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Update a transaction limit alert for the given user.

PUT /api/v2/users/:user_id:/alerts/transaction_limits/:alert_id:

Parameters

Parameter Description
account_id The account ID of the alert.
limit The integer amount (in dollars) of a transaction that when exceeded will trigger the alert.
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Create Upcoming Bill Alert

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/alerts/upcoming_bills" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/upcoming_bills')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end


var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var cashflowTransactionId = 56789;
var days = 10;
var alertRequest = new UpcomingBillAlertRequestModel
{
    Alert = new UpcomingBillAlertModel
    {
        CashflowTransactionId = cashflowTransactionId,
        Days = days,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var createdAlert = sdk.CreateUpcomingBillAlert(alertRequest);

Request payload

{
  "alert": {
    "cashflow_transaction_id": 2213,
    "days": 2,
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Create an upcoming bill alert for the given user.

POST /api/v2/users/:user_id:/alerts/upcoming_bills

Parameters

Parameter Description
cashflow_transaction_id The ID of the cashflow transaction to associate this bill to. Required
days The integer number of days before the bill that this alert should be triggered (must be between 0 and 21 days). Required
email_delivery Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Upcoming Bill Alert

curl -X "PUT" "http://partner.url/api/v2/users/alerts/upcoming_bills/:alert_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/alerts/upcoming_bills/:alert_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var alertId = 12345;
var cashflowTransactionId = 56789;
var days = 10;
var alertRequest = new UpcomingBillAlertRequestModel
{
    Alert = new UpcomingBillAlertModel
    {
        CashflowTransactionId = cashflowTransactionId,
        Days = days,
        EmailDelivery = true,
        SmsDelivery = false
    }
};

var updated = sdk.UpdateUpcomingBillAlert(alertId, alertRequest);

Request payload

{
  "alert": {
    "cashflow_transaction_id": 2213,
    "days": 2,
    "email_delivery": 1,
    "sms_delivery": 1
  }
}

Update an upcoming bill alert for the given user.

PUT /api/v2/users/:user_id:/alerts/upcoming_bills/:alert_id:

Parameters

Parameter Description
cashflow_transaction_id The cashflow transaction ID of this bill.
days The integer number of days before the bill that this alert should be triggered (must be between 0 and 21 days).
email_delivery] Send an email when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.
sms_delivery Send an SMS message when the alert is triggered. Valid values are 0 (false) and 1 (true). Defaults to 0.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Get Notifications

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/alerts/notifications" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/notifications')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var notifications = sdk.GetNotifications();

Response payload

{
  "notifications": [
    {
      "id": 50,
      "message": "Your account balance has fallen below $500.",
      "alert_type": "AccountThresholdAlert",
      "created_at": "2013-01-01T16:54:15Z"
    },
    {
      "id": 51,
      "message": "Your savings balance has fallen below $1000.",
      "alert_type": "AccountThresholdAlert",
      "created_at": "2013-01-01T16:54:15Z"
    }
  ]
}

Return a list of notifications created by triggered alerts.

GET /api/v2/users/:user_id:/alerts/notifications

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Notification

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/alerts/notifications/:notification_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/notifications/:notification_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var notificationId = 12345;
var notification = sdk.GetNotificationById(notificationId);

Response payload

{
  "notifications": [
    {
      "id": 50,
      "message": "Your account balance has fallen below $500.",
      "alert_type": "AccountThresholdAlert"
    }
  ]
}

Return a notification.

GET /api/v2/users/:user_id:/alerts/notifications/:notification_id:

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Delete Notification

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:/alerts/notifications/:notification_id:" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/notifications/:notification_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var notificationId = 12345;
var deleted = sdk.DeleteAlertNotification(notificationId);

Delete/dismiss a notification.

DELETE /api/v2/users/:user_id:/alerts/notifications/:notification_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Destinations

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/alerts/destinations" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/alerts/destinations')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var destinations = sdk.GetAlertDestinations();

Response payload

{
  "meta": {
    "partner_sms_enabled": true
  },
  "destinations": {
    "email_address": "user@example.com",
    "sms_number": "5555551234"
  }
}

Return alerts destination data.

GET /api/v2/users/:user_id:/alerts/destinations

Alerts will not be delivered for partners that have not enabled sms alerts (indicated by partner_sms_enabled).

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Update Destinations

curl -X "PUT" "http://partner.url/api/v2/users/alerts/destinations" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/alerts/destinations')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);

var email = "myemail@geezeo.com";
var smsNumber = "1238765432";

var destinationRequest = new AlertDestinationsRequestModel
{
     Destinations = new AlertDestinationsModel
     {
          EmailAddress = email,
          SmsNumber = smsNumber
     }
};

var updated = sdk.UpdateAlertDestination(destinationRequest);

Request payload

{
  "destinations": {
    "email_address": "user@example.com",
    "sms_number": "5555551234"
  }
}

Update alerts destination data.

PUT /api/v2/users/:user_id:/alerts/destinations

Parameters

Parameter Description
email_address Email address for alert delivery.
sms_number SMS number for alert delivery (10-digit, no spaces or separators e.g. 5555551234).

Response

Response body will be empty.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Aggregation

Aggregation API docs are availale for existing integrations only. If you are revewing this documentation for a new implementation, please review aggregation SDKs.

Geezeo uses CashEdge aggregation services to allow users to view their entire financial portfolio. Accounts are grouped in 4 categories: Cash, Credit Cards, Debts, and Investments. A user can edit each account listed under a category to change the exact account type, update their account credentials or view single account transactions.

The Aggregation API is currently a synchronous API. Any calls that result in a query to a third party will block the return of the API call. Timeouts should be set high (most likely upwards of 120s), accordingly.

The functionality that is supported is:

Overview

The process of adding new aggregated accounts to a user is a multi-step one. Briefly, the user will search for the FI, either by name or URL. The particular login parameters specific to that FI will be retrieved from the API, and displayed to the user. The user input will be submitted and processed. If the credentials are valid, a list of accounts and account types will be returned, along with all valid account types for that FI. The user then has the opportunity to rename and reclassify any or all accounts, as well as ignoring any or all accounts. Those choices will be sent back via the API, and the accounts will be added and updated.

Common Responses

Message Example

{
  "response": {
    "message": "Harvest complete",
    "data": {
      "key": "value"
    }
  }
}

Error Example

{
  "error":
  {
    "message": "Something unexpected happened"
  }
}

There are two common responses that may be returned when a request does not return the expected data, Message and Error.

The Error response indicates that something went wrong with the request, and provides the message received from the backend services.

The Message response usually will indicate that the response conditionally succeeded, but requires more data to continue processing. An example of this is adding a FI that requires a MFA answer. The response from the "Add FI" request will be a Message, containing the necessary data to continue processing the request.

Get FIs

curl -X "GET" "http://partner.url/api/v2/ce_fis" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/ce_fis')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response payload

{
  "meta": {
    "current_page": 1,
    "total_pages": 2
  },
  "ce_fis": [
    {
      "id": 42,
      "name": "CashEdge Test Bank (Agg) - Retail Non 2FA",
      "url": "https://cashbank.cashedge.com/cashedgeBank/CashedgeBankSite/LoginPage.jsp",
      "ce_login_parameters": {
        "id": 2,
        "parameter_id": "42971",
        "parameter_caption": "Username",
        "parameter_type": "login",
        "parameter_max_length": 20
      },
      "ce_accounts": [

        {
        "name": "Savings",
        "acct_type": "SDA",
        "ext_type": "SDA",
        "group": "Cash"
      },
      {
      "name": "Savings Two",
      "acct_type": "SDA",
      "ext_type": "SDA",
      "group": "Cash"
    }
    ]
    }
  ]
}

Return a paginated list of all CE-FIs

If the user desires to reclassify any or all accounts, the full list of supported account types for the FI can be retrieved via the API.

A user may wish to reclassify accounts if the initial account type is incorrect (for example: Savings selected for a Checking account).

The account types control how the transaction and balance data for the account are processed, and choosing an incorrect account type may result in invalid data being returned.

When classifying an account, the user should be presented with the name and value of the cashedge_account_type data structure. The acct_type and ext_type values will be joined with a comma and provided back to the API.

GET /api/v2/ce_fis

Parameters

Parameter Description
page Return subsequent pages of results.

ce_accounts is a list of all supported account types. The data is the same returned in the account list response.

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided

Get an FI

curl -X "GET" "http://partner.url/api/v2/ce_fis/:ce_fi_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/ce_fis/:ce_fi_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response Payload

{
  "ce_fis": [
    {
      "id": 42,
      "name": "CashEdge Test Bank (Agg) - Retail Non 2FA",
      "url": "https://cashbank.cashedge.com/cashedgeBank/CashedgeBankSite/LoginPage.jsp",
      "ce_login_parameters": {
        "id": 2,
        "parameter_id": "42971",
        "parameter_caption": "Username",
        "parameter_type": "login",
        "parameter_max_length": 20
      },
      "ce_accounts": [

        {
        "name": "Savings",
        "acct_type": "SDA",
        "ext_type": "SDA",
        "group": "Cash"
      },
      {
      "name": "Savings Two",
      "acct_type": "SDA",
      "ext_type": "SDA",
      "group": "Cash"
    }
    ]
    }
  ]
}

Return the requested CashEdge Financial Institution

GET /api/v2/ce_fis/:ce_fi_id:

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided

Search for an FI

curl -X "GET" "http://partner.url/api/v2/ce_fis/search?:parameters:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/ce_fis/search?:parameters:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response Payload

{
  "meta": {
    "current_page": 1,
    "total_pages": 2
  },
  "ce_fis": [
    {
      "id": 2,
      "fi_id": 20349,
      "name": "CashEdge Test Bank (Agg) - Retail Non 2FA",
      "url": "https://cashbank.cashedge.com/cashedgeBank/CashedgeBankSite/LoginPage.jsp",
      "ce_login_parameters": [
        {
          "id": 3,
          "parameter_id": "42971",
          "parameter_caption": "UserName",
          "parameter_type": "login",
          "parameter_max_length": 20
        },
        {
          "id": 4,
          "parameter_id": "42972",
          "parameter_caption": "Password",
          "parameter_type": "password",
          "parameter_max_length": 20
        }
      ]
    }
  ]
}

Search for an FI.

GET /api/v2/ce_fis/search?q=CashEdge+Test+Bank+%28Agg%29+-+Retail+Non+2FA

Parameters

Parameter Description
q The search string for a Financial Institution (FI).
scope The FI attribute that the search should be restricted to. Valid values are name and url.
page Return subsequent pages of results.

The ce_login_parameters are necessary to actually add the FI. Each parameter must be presented to the user, and their response captured.

Validate FI login credentials

curl -X "POST" "http://partner.url/api/v2/:user_id:/ce_fis" -u "%geezeo-api-key%" -d ":payload:"
uri = URI('https://partner.url/api/v2/ce_fis/search?:parameters:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :body:

  response = http.request request

  puts response.body
end

Request payload

credentials[login_params][42971]=script1&credentials[login_params][42972]=cashedge1&id=2

Response payload

{
  "accounts": [
    {
      "id": 657,
      "name": "Banking",
      "balance": "3897.52",
      "reference_id": null,
      "aggregation_type": "cashedge",
      "state": "active",
      "account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "cashedge_account_type": {
        "name": "Savings",
        "acct_type": "SDA",
        "ext_type": "SDA",
        "group": "Cash"
      }
    },
    {
      "id": 658,
      "name": "Red Wing Shoe Company, Inc. 401k Profit Sharing Plan",
      "balance": "21099.0",
      "reference_id": null,
      "aggregation_type": "cashedge",
      "state": "active",
      "account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "cashedge_account_type": {
        "name": "Investment",
        "acct_type": "INV",
        "ext_type": "INV",
        "group": "Investment"
      }
    }
  ]
}

POST /api/v2/users/pcid/ce_fis

Here, the user supplied credentials are submitted. The integer keys are the values in the previous response parameter_id fields. The parameter_caption values are what the fields should be labeled as when presented to the user.

In this case, the UserName value is script1, and the Password value is cashedge1.

Classifying accounts

Request payload

accounts[657][type_code]=SDA,SDA&accounts[658][type_code]=ignore

Response payload

{
  "accounts": [
    {
      "id": 657,
      "name": "My Checking",
      "balance": "3897.52",
      "reference_id": null,
      "aggregation_type": "cashedge",
      "state": "active",
      "account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "cashedge_account_type": {
        "name": "Savings",
        "acct_type": "SDA",
        "ext_type": "SDA",
        "group": "Cash"
      }
    }
  ]
}

This is required even if the user does not wish to reclassify their accounts. In that case, the existing acct_type and ext_type must be supplied back to the API. If this step is omitted, the accounts will not actually be added to the users account. Additionally, the account can be renamed at this step by providing the details parameter.

PUT /api/v2/users/:user_id:/accounts/classify

Parameters

Parameter Description
accounts[657] The integer portion of this key is the id value from the account details in the previous POST /api/v2/users/pcid/ce_fis request.
accounts[657][type_code] A value is made up of the concatenated acct_type and ext_type, joined by a comma (ie: SDA,SDA). This is our best guess as to what the account is. Submitting a value of ignore will omit the account from aggregation.

Multi-Factor Authentication

GET /api/v2/ce_fis/?query=CashEdge+Test+Bank+%28Agg%29+-+Retail+2FA

Response payload

{
  "ce_fis": [
    {
      "id": 1,
      "fi_id": 20404,
      "name": "CashEdge Test Bank (Agg) - Retail 2FA",
      "url": "https://cashbank.cashedge.com/cashedgeBank/aggrretail2FA/cashedge_login.html",
      "ce_login_parameters": [
        {
          "id": 1,
          "parameter_id": "42969",
          "parameter_caption": "User ID",
          "parameter_type": "login",
          "parameter_max_length": 30
        },
        {
          "id": 2,
          "parameter_id": "42970",
          "parameter_caption": "Password",
          "parameter_type": "password",
          "parameter_max_length": 30
        }
      ]
    }
  ]
}

POST /api/v2/users/:user_id:/ce_fis

Request payload

credentials[login_params][42969]=test&credentials

Response payload

{
  "response": {
    "message": "The account requires further authentication",
    "data": {
      "mfa_parameters": [
        {
          "ce_login_parameter": {
            "ce_fi_id": null,
            "parameter_caption": "What is your favorite color?",
            "parameter_id": "answer",
            "parameter_max_length": null,
            "parameter_type": "password"
          }
        }
      ],
      "session_key": "464a674e7367646e2b77665576726947426b627879413d3d",
      "harvest_id": "123770714",
      "login_id": "19349692"
    }
  }
}

PUT /api/v2/users/:user_id:/ce_fis/1

Request payload

harvest_id=123770714&login_id=19349692&mfa_responses[answer]=red&session_key=464a674e7367646e2b77665576726947426b627879413d3d

Response payload

{
  "accounts": [
    {
      "id": 658,
      "name": "Checking",
      "balance": "70.0",
      "reference_id": null,
      "aggregation_type": "cashedge",
      "state": "active",
      "account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "cashedge_account_type": {
        "name": "Checking",
        "acct_type": "DDA",
        "ext_type": "DDA",
        "group": "Cash"
      }
    },
    {
      "id": 659,
      "name": "Checking1",
      "balance": "150.0",
      "reference_id": null,
      "aggregation_type": "cashedge",
      "state": "active",
      "account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "cashedge_account_type": {
        "name": "Checking",
        "acct_type": "DDA",
        "ext_type": "DDA",
        "group": "Cash"
      }
    }
  ]
}

PUT /api/v2/users/:user_id:/accounts/classify

Request Payload

accounts[658][type_code]=DDA,DDA&accounts[658][details]=My+Checking&accounts[659][type_code]=ignore

Response payload

{
  "accounts": [
    {
      "id": 658,
      "name": "My Checking",
      "balance": "70.0",
      "reference_id": null,
      "aggregation_type": "cashedge",
      "state": "active",
      "account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "cashedge_account_type": {
        "name": "Checking",
        "acct_type": "DDA",
        "ext_type": "DDA",
        "group": "Cash"
      }
    }
  ]
}

MFA (Multi-Factor Authentication) is a method of identify verification that some FIs require. After the normal username/password credentials, there is a 2nd verification step. This step differs for each FI. The aggregation API returns the appropriate prompts, and accepts them for verification.

The overall process is the same as a non-MFA FI, with a fork for the secondary verification step. After the "Validating FI login credentials" step in the non-MFA steps, instead of returning a list of accounts at the FI, the API will return an error response with the necessary MFA prompts and parameters to continue adding the FI.

Example Flow to right

Pending Accounts

Response payload

 {      
   "pending_accounts": [        
     {      
       "id": 2,     
       "name": "CashEdge Test Bank (Agg) - Retail Non 2FA",     
       "account_ids": [     
         "19435010"     
       ]        
     }      
   ]        
 }      

In the event of an abandoned aggregation attempt it is possible that accounts involved will be added at the aggregator, but not
finalized/classified, leaving the account in an inconsistent state. These
accounts can be viewed by checking pending_accounts.

We reccommend that on a user session start to delete all pending accounts to avoid potential complicationss.

GET /api/v2/users/:user_id:/:pending_accounts

Removing Pending Accounts

DELETE /api/v2/users/:user_id:/pending_accounts/:pending_account_id:

MFA Responses with Option Parameters

Response payload

{
  "response": {
    "message": "The account requires further authentication",
    "data": {
      "mfa_parameters": [
        {
          "ce_login_parameter": {
            "ce_fi_id": null,
            "parameter_caption": "Please enter the option for receiving an authentication code",
            "parameter_id": "answer",
            "parameter_max_length": null,
            "parameter_options":[
              { "value": "8", "caption": "Phone - Text : xxx-xxx-6251"},
              { "value": "9", "caption": "Email Address - : a...e@gmail.com"},
              { "value": "0", "caption": "I already have an Identification Code"}
            ],
            "parameter_type": "select"
          }
        }
      ],
      "session_key": "464a674e7367646e2b77665576726947426b627879413d3d",
      "harvest_id": "123770714",
      "login_id": "19349692"
    }
  }
}

Some users may receive a multiple choice selection to continue their MFA sign-in process. For example, a user may select a preferred location to receive security questions or codes. In such a case, the response will include the choices as selections, and the value of the selection must be submitted as the choice.

Example flow to right

Update credentials for an FI

This is for changing the login credentials for the FI account used by the aggregator. This can also be used to respond to new MFA challenges issued by the FI.

Non-MFA Example

Non MFA Request payload

credentials[login_params][1234]=username&credentials[login_params][1235]=newpassword

Non MFA Response payload

{
  "accounts": [
    {
      "id":86,
      "name":"account-name",
      "balance":"42.5",
      "reference_id":"42",
      "aggregation_type":"cashedge",
      "state":"active",
      "harvest_updated_at":"2013-03-07T14:42:00Z",
      "account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "cashedge_account_type":{
        "name":"Checking",
        "acct_type":"DDA",
        "ext_type":"DDA",
        "group":null
      },
      "fi":{
        "id":99,
        "name":"FI"
      }
    }
  ]
}

PUT /api/v2/users/:user_id:/accounts/:account_id/update_credentials

Non MFA Request Payload

credentials[login_params][1234]=username&credentials[login_params][1235]=newpassword

Parameters

The new login credentials are in the same form as when adding the FI initially. * credentials[login_params][:login_parameter_id:] * credentials[login_params][:password_parameter_id:]

Response

On success, the response will be the json of the account that has been updated. When an MFA challenge occurs, the challenge will be returned so the answer may be resubmitted. On error, a message describing the error will be returned.

Example

PUT /api/v2/users/:user_id:/accounts/:account_id/update_credentials

MFA Example

Initial Request/Response

PUT /api/v2/users/:user_id:/accounts/:account_id/update_credentials

MFA Request payload

credentials[login_params][1234]=username&credentials[login_params][1235]=newpassword

MFA Response payload

{
  "response":"The account requires further authentication",
  "data":{
    "mfa_parameters":[
      {
        "ce_login_parameter":{
          "ce_fi_id":null,
          "parameter_caption":"What is your favorite color?",
          "parameter_id":"answer",
          "parameter_max_length":null,
          "parameter_type":"password"
        }
      }
    ],
    "session_key":"464a674e7367646e2b77665576726947426b627879413d3d",
    "harvest_id":"123770714",
    "login_id":"19349692"
  }
}

The answer to the MFA challenge can then be submitted to continue the process. These paramaters are required for this request: * mfa_responses[answer] The answer to the MFA challenge. * harvest_id From the previous request. * login_id From the previous request. * session_key From the previous request.

Followup Request/Response

PUT /api/v2/users/:user_id:/accounts/:account_id/update_credentials

Followup Request

mfa_responses[answer]=red&harvest_id=123770714&login_id=19349692&session_key=464a674e7367646e2b77665576726947426b627879413d3d

Follwup Response

{
  "accounts": [
    {
      "id":86,
      "name":"account-name",
      "balance":"42.5",
      "reference_id":"42",
      "aggregation_type":"cashedge",
      "state":"active",
      "harvest_updated_at":"2013-03-07T14:42:00Z",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "cashedge_account_type":{
        "name":"Checking",
        "acct_type":"DDA",
        "ext_type":"DDA",
        "group":null
      },
      "fi":{
        "fi_id":99,
        "name":"FI"
      }
    }
  ]
}

Error Response

{
  "error": {
    "message":"Something unexpected happened.",
    "data":{}
  }
}

Budgets

Get Budgets

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/budgets" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/budgets')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);

var budgets = sdk.GetBudgets();

Response payload

{
  "meta": {
    "state": "under",
    "total_budget": 300,
    "total_spent": 0,
    "total_remaining": 300,
    "total_percentage": 0.0
  },
  "budgets": [
    {
      "id": 284,
      "name": "Food",
      "month": 7,
      "year": 2013,
      "tag_names": [
        "Diningout"
      ],
      "spent": 0,
      "state": "under",
      "budget_amount": 300,
      "links": {
        "accounts": [396]
      }
    }
  ],
  "accounts": [
    {
      "id": 396,
      "name": "eChecking",
      "balance": "300.54",
      "reference_id": "789274930",
      "aggregation_type": "partner",
      "state": "active",
      "harvest_updated_at": "2013-03-05T12:00:00Z",
      "account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "fi": {
        "id": 2,
        "name": "CashEdge Test Bank (Agg) - Retail Non 2FA"
      },
      "cashedge_account_type": {
        "name": "Savings",
        "acct_type": "SDA",
        "ext_type": "SDA",
        "group": "Cash"
      }
    }
  ]
}

Return a list of budgets for the given user.

The state attribute will be one of over, risk, or under. A value of risk means that the current spending on the budget is over the spending limit, prorated for the current month.

'GET /api/v2/users/:user_id:/budgets'

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Budget

Return a budget for the given user.

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/budgets/:budget_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/budgets/:budget_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var budgetId = 12345;
var budget = sdk.GetBudgetById(budgetId);

Response payload

{
  "budgets": [
    {
      "id": 1234,
      "name": "Food",
      "month": 9,
      "year": 2013,
      "tag_names": [
        "Diningout"
      ],
      "spent": 0,
      "state": "under",
      "budget_amount": 300,
      "links": {
        "accounts": [396],
        "budget_histories": [2468, 2469]
      }
    }
  ],
  "accounts": [
    {
      "id": 396,
      "name": "eChecking",
      "balance": "300.54",
      "reference_id": "789274930",
      "aggregation_type": "partner",
      "state": "active",
      "harvest_updated_at": "2013-03-05T12:00:00Z",
      "account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "fi": {
        "id": 2,
        "name": "CashEdge Test Bank (Agg) - Retail Non 2FA"
      },
      "cashedge_account_type": {
        "name": "Savings",
        "acct_type": "SDA",
        "ext_type": "SDA",
        "group": "Cash"
      }
    }
  ],
  "budget_histories": [
    {
      "id": 2468,
      "budget_amount": 300,
      "month": 8,
      "spent": 0,
      "state": "under",
      "year": 2013
    },
    {
      "id": 2469,
      "budget_amount": 300,
      "month": 7,
      "spent": 0,
      "state": "under",
      "year": 2013
    }
  ]
}

For budget histories, the state attribute will be either over or under. For budgets, the state attribute will be one of over, risk, or under. A value of risk means that the current spending on the budget is over the spending limit, prorated for the current month.

'GET /api/v2/users/:user_id:/budgets/:budget_id:'

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Create Budget

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/budgets" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/budgets')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var budgetRequest = new BudgetRequestModel{
    Budget = new BudgetModel{
        BudgetAmount = 300,
        Name = "house budget",
        ShowOnDashboard = false,
        TagNames = new List<string>{"house"}
    }
};

var budgetResponse = sdk.CreateBudget(budgetRequest);

var budgets = sdk.GetBudgets();

Request Payload

{
  "budget": {
    "name": "Bike parts",
    "budget_amount": 200,
    "show_on_dashboard": true,
    "tag_names": [
      "Bikes"
    ],
    "account_list":[
      396,397
    ]
  }
}

Create a budget for the given user.

POST /api/v2/users/:user_id:/budgets

Parameters

Parameter Description
name The name of the new budget. Required
budget_amount The amount of the new budget. Required
tag_names A list of tags to track. Required
account_list A list of Geezeo account ids to track.
'show_on_dashboard' Display this budget on the dashboard.
'other' Only track unbudgeted expenses.

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Budget

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/budgets" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/budgets')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var budgetId = 12345;
var budgetRequest = new BudgetRequestModel{
    Budget = new BudgetModel{
        BudgetAmount = 500,
        Name = "new house budget",
        ShowOnDashboard = false,
        TagNames = new List<string>{"house"}
    }
};

var updated = sdk.UpdateBudget(budgetId, budgetRequest);

Request Payload

{
  "budget": {
    "name": "Bike parts",
    "budget_amount": 200,
    "show_on_dashboard": true,
    "tag_names": [
      "Bikes"
    ],
     "account_list":[
       396,397
     ]
  }
}

Update a budget for the given user.

PUT /api/v2/users/:user_id:/budgets/:budget_id:

Parameters

Parameter Description
name The name of the new budget. Required
budget_amount The amount of the new budget. Required
tag_names A list of tags to track. Required
account_list A list of Geezeo account ids to track.
show_on_dashboard Display this budget on the dashboard.
other Only track unbudgeted expenses.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Delete Budget

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:/budgets/:budget_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/budgets/:budget_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var budgetResponse = sdk.CreateBudget(budgetRequest);
var budgetId = 12345;
var deleted = sdk.DeleteBudget(budgetId);

Delete a budget for the given user.

DELETE /api/v2/users/:user_id:/budgets/:budget_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Cashflow Bills

Get Cashflow Bills

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/cashflow/bills" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/bills')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var billsResponse = sdk.GetCashflowBills();

Response payload

{
  "bills": [
    {
      "id": 387,
      "amount": "-100.0",
      "frequency": "Weekly",
      "name": "Electric Bill",
      "start_date": "2013-07-16",
      "stopped_on": "2013-07-17"
    }
  ]
}

Return a list of all cashflow bills defined for a user.

GET /api/v2/users/:user_id:/cashflow/bills

Frequency

Frequency will be one of the values defined below.

Frequency
Daily Every four weeks Every other week
Every six months Monthly Once
Quarterly Twice a month Weekly
Yearly

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Cashflow Bill

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var billId = 12345;
var billsResponse = sdk.GetCashflowBill(billId);

Response payload

{
  "bills": [
    {
      "id": 387,
      "amount": "-100.0",
      "frequency": "Weekly",
      "name": "Electric Bill",
      "start_date": "2013-07-16",
      "stopped_on": "2013-07-17"
    }
  ]
}

Return complete information for a cashflow bill.

GET /api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:

Frequency

Frequency will be one of the values defined below.

Frequency
Daily Every four weeks Every other week
Every six months Monthly Once
Quarterly Twice a month Weekly
Yearly

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user or bill is specified

Create Cashflow Bill

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/cashflow/bills" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/bills')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var billRequest = new BillRequestModel{
    Bill = new BillModel{
        Amount = 200f,
        Frequency = Frequency.Daily,
        Name = "Test Bill",
        StartDate = new DateTime(2015, 7, 1)
    }
};

var billResponse = sdk.CreateBill(billRequest);

Request Payload

{
  "bill": {
    "amount": -100.0,
    "frequency": "Weekly",
    "name": "Electric Bill",
    "start_date": "2013-07-17"
  }
}

Response payload

{
  "bills": [
    {
      "id": 387,
      "amount": "-100.0",
      "frequency": "Weekly",
      "name": "Electric Bill",
      "start_date": "2013-07-17",
      "stopped_on": null
    }
  ]
}

Create a new cashflow bill.

POST /api/v2/users/:user_id:/cashflow/bills

Parameters

Parameter Description
amount The bill's amount. If positive, it will be converted to a negative number. Required
frequency How often the bill recurs. Required
name The bill's payee. Required
start_date The bill's start date, in ISO-8601 format. Required

Frequency

Frequency will be one of the values defined below.

Frequency
Daily Every four weeks Every other week
Every six months Monthly Once
Quarterly Twice a month Weekly
Yearly

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Cashflow Bill

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var billId = 12345;
var billRequest = new BillRequestModel{
    Bill = new BillModel{
        Amount = 200f,
        Frequency = Frequency.Daily,
        Name = "Test Bill",
        StartDate = new DateTime(2015, 7, 1)
    }
};

var updated = sdk.UpdateBill(billId, billRequest);

Request payload

{
  "bill": {
    "amount": -100.0,
    "frequency": "Weekly",
    "name": "Electric Bill",
    "start_date": "2013-07-17"
  }
}

Update an existing cashflow bill.

PUT /api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:

Parameters

Parameter Description
amount The bill's amount. If positive, it will be converted to a negative number. Required
frequency How often the bill recurs. Required
name The bill's payee. Required
start_date The bill's start date, in ISO-8601 format. Required

Frequency

Frequency will be one of the values defined below.

Frequency
Daily Every four weeks Every other week
Every six months Monthly Once
Quarterly Twice a month Weekly
Yearly

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user or bill is specified
422 Unprocessable Entity returned when the parameters given were invalid

Stop Cashflow Bill

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:/stop" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:/stop')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var billId = 12345;

var stopped = sdk.StopBill(billId);

Stop a cashflow bill.

PUT /api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:/stop

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user or bill is specified

Delete Cashflow Bill

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var billId = 12345;
sdk.DeleteBill(billId);

Delete a cashflow bill.

DELETE /api/v2/users/:user_id:/cashflow/bills/:cashflow_bill_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user or bill is specified

Cashflow Events

A cashflow event is the individual occurrence of a bill or income.

Get Cashflow Events

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/cashflow/events" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/events')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var events = sdk.GetEvents();

Response payload

{
  "events": [
    {
      "id": 599,
      "amount": "-100.0",
      "memo": "memo",
      "name": "name",
      "paid": true,
      "scheduled_date": "2013-07-18",
      "links": {
        "bill": 273,
        "income": 441
      }
    }
  ],
  "balances": [
    {
      "balance": 0,
      "date": "2013-07-24"
    }
  ],
  "bills": [
    {
      "id": 273,
      "amount": "-100.0",
      "frequency": "Once",
      "name": "name",
      "start_date": "2013-07-16",
      "stopped_on": "2013-07-17"
    }
  ],
  "incomes": [
    {
      "id": 441,
      "amount": "100.0",
      "frequency": "Once",
      "name": "name",
      "start_date": "2013-07-16",
      "stopped_on": "2013-07-17"
    }
  ]
}

Return a list of all cashflow events for a user during a specified date range.

GET /api/v2/users/:user_id:/cashflow/events

Parameters

Parameter Description
begin_on Limit results to after this date (inclusive), in ISO-8601 format. Defaults to today if end_on is not provided, or 31 days before end_on if end_on is provided.
end_on Limit results to before this date (inclusive), in ISO-8601 format. Defaults to 31 days after begin_on.

Note: Daily cashflow balances are calculated based on current account balances. These daily balances are only available for the current and future cashflow dates.

Request with specific dates

GET /api/v2/users/:user_id:/cashflow/events?begin_on=2013-10-18&end_on=2013-11-18

Update Cashflow Event

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/cashflow/events/:cashflow_event_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/events/bills/:cashflow_event_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var eventId = 12345;
var eventRequest = new EventRequestModel{
    Event = new EventModel{
        Memo = "memo",
        Paid = true
    }
};

var updated = sdk.UpdateEvent(eventId, eventRequest);

Request payload

{
  "event": {
    "memo": "memo",
    "paid": true
  }
}

Update an existing cashflow event.

PUT /api/v2/users/:user_id:/cashflow/events/:cashflow_event_id:

Parameters

Parameter Description
memo The event's memo.
paid True if the event has been paid; false otherwise.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Delete Cashflow Event

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:/cashflow/events/:cashflow_event_id:" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/events/:cashflow_event_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var eventId = 12345;
var deleted = sdk.DeleteEvent(eventId);

Delete a cashflow event.

DELETE /api/v2/users/:user_id:/cashflow/events/:cashflow_event_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Cashflow Incomes

Get Cashflow Incomes

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/cashflow/incomes" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/incomes')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var incomes = sdk.GetIncomes();

Response payload

{
  "incomes": [
    {
      "id": 387,
      "amount": "-100.0",
      "frequency": "Every other week",
      "name": "Paycheck",
      "start_date": "2013-07-16",
      "stopped_on": "2013-07-17"
    }
  ]
}

Return a list of all cashflow incomes defined for a user.

GET /api/v2/users/:user_id:/cashflow/incomes

Frequency

Frequency will be one of the values defined below.

Frequency
Daily Every four weeks Every other week
Every six months Monthly Once
Quarterly Twice a month Weekly
Yearly

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Cashflow Income

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/cashflow/bills/:cashflow_income_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/bills/:cashflow_income_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var incomeId = 12345;
var incomesResponse = sdk.GetIncome(incomeId);

Response payload

{
  "incomes": [
    {
      "id": 387,
      "amount": "-100.0",
      "frequency": "Every other week",
      "name": "Paycheck",
      "start_date": "2013-07-16",
      "stopped_on": "2013-07-17"
    }
  ]
}

Return complete information for a cashflow income.

GET /api/v2/users/:user_id:/cashflow/incomes/:cashflow_income_id:

Frequency

Frequency will be one of the values defined below.

Frequency
Daily Every four weeks Every other week
Every six months Monthly Once
Quarterly Twice a month Weekly
Yearly

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user or income is specified

Create Cashflow Income

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/cashflow/incomes" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/incomes')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var incomeRequest = new IncomeRequestModel{
    Income = new IncomeModel{
        Amount = 200f,
        Frequency = Frequency.Daily,
        Name = "Test Income",
        StartDate = new Datetime(2015, 7, 1)
    }
};
var incomeResponse = sdk.CreateIncome(incomeRequest);

Request payload

{
  "income": {
    "amount": 100.0,
    "frequency": "Every other week",
    "name": "Paycheck",
    "start_date": "2013-07-17"
  }
}

Response payload

{
  "incomes": [
    {
      "id": 387,
      "amount": "-100.0",
      "frequency": "Every other week",
      "name": "Paycheck",
      "start_date": "2013-07-17",
      "stopped_on": null
    }
  ]
}

Create a new cashflow income.

POST /api/v2/users/:user_id:/cashflow/incomes

Parameters

Parameter Description
amount The bill's amount. If positive, it will be converted to a negative number. Required
frequency How often the bill recurs. Required
name The bill's payee. Required
start_date The bill's start date, in ISO-8601 format. Required

Frequency

Frequency will be one of the values defined below.

Frequency
Daily Every four weeks Every other week
Every six months Monthly Once
Quarterly Twice a month Weekly
Yearly

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Cashflow Income

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/cashflow/incomes/:cashflow_income_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/incomes/:cashflow_income_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var incomeId = 12345;

var incomeRequest = new IncomeRequestModel{
    Income = new IncomeModel{
        Amount = 200f,
        Frequency = Frequency.Daily,
        Name = "Test Income",
        StartDate = new Datetime(2015, 7, 1)
    }
};
var updated = sdk.CreateIncome(incomeId, incomeRequest);

Request payload

{
  "income": {
    "amount": -100.0,
    "frequency": "Every other week",
    "name": "Paycheck",
    "start_date": "2013-07-17"
  }
}

Update an existing cashflow income.

PUT /api/v2/users/:user_id:/cashflow/incomes/:cashflow_income_id:

Parameters

Parameter Description
amount The bill's amount. If positive, it will be converted to a negative number. Required
frequency How often the bill recurs. Required
name The bill's payee. Required
start_date The bill's start date, in ISO-8601 format. Required

Frequency

Frequency will be one of the values defined below.

Frequency
Daily Every four weeks Every other week
Every six months Monthly Once
Quarterly Twice a month Weekly
Yearly

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user or income is specified
422 Unprocessable Entity returned when the parameters given were invalid

Stop Cashflow Income

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/cashflow/incomes/:cashflow_income_id:/stop" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/incomes/:cashflow_income_id:/stop')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var incomeId = 12345;
var stopped = sdk.StopIncome(incomeId);

Stop a cashflow income.

PUT /api/v2/users/:user_id:/cashflow/incomes/:cashflow_income_id:/stop

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user or income is specified

Delete Cashflow Income

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:/cashflow/incomes/:cashflow_income_id:" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow/incomes/:cashflow_income_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var incomeId = 12345;
var deleted = sdk.DeleteIncome(incomeId);

Delete a cashflow income.

DELETE /api/v2/users/:user_id:/cashflow/incomes/:cashflow_income_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user or income is specified

Cashflows

Get Cashflows Configuration

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/cashflow" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response payload

{
  "cashflows": [
    {
      "id": 42,
      "links": {
        "accounts": [
          854
        ]
      }
    }
  ],
  "accounts": [
    {
      "id": 854,
      "name": "eChecking",
      "balance": "300.54",
      "reference_id": "789274930",
      "aggregation_type": "partner",
      "state": "active",
      "harvest_updated_at": "2013-03-05T12:00:00Z",
      "account_type": "checking",
      "include_in_expenses": true,
      "include_in_budget": true,
      "include_in_cashflow": true,
      "include_in_dashboard": true,
      "include_in_goals": true,
      "include_in_networth": true,
      "fi": null,
      "cashedge_account_type": null
    }
  ]
}

Return a user's cashflow configuration and all accounts included in the cashflow calculation.

GET /api/v2/users/:user_id:/cashflow

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Update Cashflow

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/cashflow" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/cashflow')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

Request payload

{
  "cashflow": {
    "account_ids": [
      854
    ]
  }
}

Update a user's cashflow configuration.

PUT /api/v2/users/:user_id:/cashflow

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Current Partner

Get Current Partner

curl -X "GET" "http://partner.url/api/v2/partners/current" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/partners/current')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response payload

{
  "partners": [
    {
      "id": 42,
      "domain": "pfm.example.com",
      "product_name": "Money Manager",
      "modules": {
        "mobile": {
          "name": "Mobile Money Manager",
          "logout_url": "https://www.example.com/logout",
          "back_to_online_banking_url": "https://www.example.com/back_to_olb",
          "back_to_online_banking_label": "Back to Online Banking"
        }
      }
    }
  ]
}

Return information about the current partner.

GET /api/v2/partners/current

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided

Current User

This endpoint operates on the currently authenticated user (OAuth user authentication is required).

Get Current User

curl -X "GET" "http://partner.url/api/v2/users/current" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/current')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response payload

{
  "users": [
    {
      "id": "42",
      "login": "jsmith42",
      "first_name": "Alice",
      "last_name": "Smith",
      "email": "user@example.com",
      "login_count": 1,
      "last_login_at": "2013-09-29T15:16:36Z",
      "postal_code": "06252",
      "birth_year": 1980,
      "sex": "Male",
      "custom_tags": []
    }
  ]
}

Return information about the currently authenticated user.

GET /api/v2/users/current

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided

Update Current User

curl -X "PUT" "http://partner.url/api/v2/users/current" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/current')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

Request payload

{
  "user": {
    "login": "bsmith24",
    "first_name": "B",
    "last_name": "Smith",
    "email": "user@example.com",
    "postal_code": 06252,
    "birth_year": 1980,
    "sex": "Male",
    "custom_tags": ["Coffee", "Food"]
  }
}

Response payload

{
  "users": [
    {
      "id": "42",
      "href": "http://example.com/api/v2/users/42",
      "login": "bsmith42",
      "first_name": "B",
      "last_name": "Smith",
      "email": "user@example.com",
      "login_count": 1,
      "last_login_at": "2013-09-29T15:16:36Z",
      "postal_code": "06252",
      "birth_year": 1980,
      "sex": "Male",
      "custom_tags": ["Coffee", "Food"]
    }
  ]
}

Update the currently authenticated user.

PUT /api/v2/users/current

Parameters

Parameter Description
id The user's partner customer id. Required
email The user's email address. Required
first_name The user's first name. Required
last_name The user's last name. Required
login The user's login for the PFM.
postal_code The user's postal code.
birth_year The year the user was born.
sex The sex of the user. Either "Male" or "Female".
custom_tags A list of tags the user has added.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
422 Unprocessable Entity returned when the parameters given were invalid

Delete Current User

curl -X "DELETE" "http://partner.url/api/v2/users/current" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/current')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Delete the currently authenticated user.

DELETE /api/v2/users/current

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided

Expenses

Get Expenses

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/expenses" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/expenses')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var expenses = sdk.GetExpenses(null) //pass in either a null or empty search criteria object (new ExpenseSearchCriteriaModel())

Response payload

{
  "expenses": [
    {
      "tag": "Utilities",
      "amount": "1291.96"
    },
    {
      "tag": "Personal",
      "amount": "325.00"
    },
    {
      "tag": "Other",
      "amount": "95.02"
    },
  ]
}

Return expenses calculated by tag for the given user.

GET /api/v2/users/:user_id:/expenses

Parameters

Parameter Description
begin_on The start date to begin calculating expenses (default: thirty days ago).
end_on The end date to begin calculating expenses (default: today).
threshold The percentage of the remaining expenses that are grouped into an 'other' tag (default: 80).

Request with Threshold

`GET /api/v2/users/:user_id:/expenses?threshold=100

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
// Criteria model also has BeginOn and EndOn parameters
var searchCriteria = new ExpenseSearchCriteriaModel{
    Threshold = 100
};

var expenses = sdk.GetExpenses(searchCriteria);

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided

Helpers

Get Last Month

Return expenses from last month for the given user.

GET /api/v2/users/:user_id:/expenses/last_month

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var expenses = sdk.GetExpensesForLastMonth();

Get This Month

Return expenses from this month for the given user.

GET /api/v2/users/:user_id:/expenses/this_month

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var expenses = sdk.GetExpensesForThisMonth();

Get Last 30 Days

Return expenses from last thirty days for the given user.

GET /api/v2/users/:user_id:/expenses/last_thirty_days

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var expenses = sdk.GetExpensesForLastThirtyDays();

Harvests

Get Harvest Status

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/harvest" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/harvest')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response payload

{
  "harvests": [
    {
      "status": "complete"
    }
  ]
}

Return the status of a harvest for the given user. It will return working while harvesting, and change to complete when finished.

GET /api/v2/users/:user_id:/harvest

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Create Harvest

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/harvest" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/harvest')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Post.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response payload

{
  "harvests": [
    {
      "status": "working",
      "href": "http://example.com/api/v2/users/42/harvest"
    }
  ]
}

Start a new harvest for the given user. A new harvest will not be started if one is already in progress.

POST /api/v2/users/:user_id:/harvest

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Networth

Get Networth

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/networth" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/networth')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var networth = sdk.GetNetworth();

Response payload

{
  "meta": {
    "net_worth": "1000.0",
    "net_worth_change": "2000.0",
    "total_assets": "3000.0",
    "total_debts": "2000.0"
  },
  "assets": [
    {
      "id": 42,
      "balance": "1000.0",
      "name": "Savings",
      "additional_networth_account": false
    },
    {
      "id": 43,
      "balance": "2000.0",
      "name": "Coffee Beans",
      "additional_networth_account": true
    }
  ],
  "debts": [
    {
      "id": 44,
      "balance": "2000.0",
      "name": "Car Loan",
      "additional_networth_account": true
    }
  ],
  "networth_histories": [
    {
      "total": "-1000.0",
      "total_asset": "1000.0",
      "total_debt": "2000.0",
      "month": 08,
      "year": 2013,
      "since_last_month": "-1000.0"
    }
  ]
}

Return a user's networth.

GET /api/v2/users/:user_id:/networth

Networth Types

By default all accounts will be included in the networth calculations. These are the default classifications for accounts as they apply to a user's networth.

Type Default Value
checkings asset
savings asset
investment asset
asset asset
money_market asset
cd asset
certificates asset
autos debt
home debt
loan debt
student_loans debt
creditline debt

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Create Networth Account

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/networth/accounts" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/networth/accounts')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var networth = new NetworthAccountRequestModel{
    Networth = new NetworthAccountModel{
        AccountType = AccountType.Debt,
        Balance = 1000,
        Name = "House"
    }
}
var networthAccountsResponse = sdk.CreateNetworth(networth);

Request payload

{
  "networth_account": {
    "account_type": "debt",
    "balance": 1000,
    "name": "House"
  }
}

Create a networth account.

POST /api/v2/users/:user_id:/networth/accounts

Parameters

Parameter Description
account_type Account type ("debt" or "asset"). Required
balance Account balance. Required
name Account name. Required

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Networth Account

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/networth/accounts/:account_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/networth/accounts/:account_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var networthId = 12345;
var networth = new NetworthAccountRequestModel{
    Networth = new NetworthAccountModel{
        AccountType = AccountType.Debt,
        Balance = 1000,
        Name = "House"
    }
}
var updated = sdk.UpdateNetworth(networthId, networth);

Request payload

{
  "networth_account": {
        "account_type": "debt",
        "balance": 1000,
        "name": "House"
  }
}

Update a networth account.

PUT /api/v2/users/:user_id:/networth/accounts/:account_id:

Parameters

Parameter Description
account_type Account type ("debt" or "asset"). Required
balance Account balance. Required
name Account name. Required

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Delete Networth Account

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:/networth/accounts/:account_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/networth/accounts/:account_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var networthId = 12345;
var deleted = sdk.DeleteNetworth(networthId);

Delete a networth account.

DELETE /api/v2/users/:user_id:/networth/accounts/:account_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Payoff Goals

Payoff Goal States

State Description
active The goal is being updated and is capable of generating alerts.
archived The goal is no longer being updated or generating alerts.

Payoff Goal Statuses

Status Description
complete The goal has been accomplished.
over The goal's target completion date has passed.
risk The goal is not on target for completion on time. (Its current value is less than 80% of its expected current value).
under The goal is on target for completion on time.

Payoff Goal Contributions

Attribute Description
monthly_contribution The average monthly conrtibution (rounded to the nearest ten).
target_contribution The amount that will be contributed to this goal every month.

Get Payoff Goal Images

curl -X "GET" "http://partner.url/api/v2/payoff_goals" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/payoff_goals')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var payoffGoalImages = sdk.GetPayoffGoalImages();

Response payload

{
  "payoff_goal_images": [
    {
      "id": "credit_card.jpg",
      "name": "Pay off a credit card",
      "url": "http://www.example.com/images/standard_goal_images/credit_card.jpg?1368824034"
    }
  ]
}

Return a list of pre-defined payoff goal images.

GET /api/v2/payoff_goals

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided

Get Payoff Goals

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/payoff_goals" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/payoff_goals')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var payoffGoalsResponse = sdk.GetPayoffGoals();

Response payload

{
  "payoff_goals": [
    {
      "id": 583,
      "name": "Payoff a car",
      "image_name": "car.jpg",
      "image_url": "https://example.com/images/car.jpg",
      "state": "active",
      "status": "risk",
      "initial_value": "10.00",
      "current_value": "200.00",
      "target_value": "0.00",
      "monthly_contribution": "50.00",
      "percent_complete": 2,
      "complete": false,
      "target_completion_on": "2014-05-21",
      "target_contribution": "50.00",
      "created_at": "2013-01-01T16:54:15Z",
      "updated_at": "2013-10-01T20:21:01Z",
      "links": {
        "accounts": [2944]
      }
    }
  ]
}

Return a list of payoff goals for the given user.

GET /api/v2/users/:user_id:/payoff_goals

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Payoff Goal

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/payoff_goals/:payoff_goals_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/payoff_goals/:payoff_goals_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var payoffGoalId = 12345;
var payoffGoalsResponse = sdk.GetPayoffGoal(payoffGoalId);

Response payload

{
  "payoff_goals": [
    {
      "id": 583,
      "name": "Payoff a car",
      "image_name": "car.jpg",
      "image_url": "https://example.com/images/car.jpg",
      "state": "active",
      "status": "risk",
      "initial_value": "10000.00",
      "current_value": "200.00",
      "target_value": "0.00",
      "monthly_contribution": "50.00",
      "percent_complete": 2,
      "complete": false,
      "target_completion_on": "2014-05-21",
      "target_contribution": "50.00",
      "created_at": "2013-01-01T16:54:15Z",
      "updated_at": "2013-10-01T20:21:01Z",
      "links": {
        "accounts": [2944]
      }
    }
  ]
}

Return a payoff goal for the given user.

The initial_value field represents the total amount to pay off for this goal.

GET /api/v2/users/:user_id:/payoff_goals/:payoff_goals_id:

Create Payoff Goal

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/payoff_goals" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/payoff_goals')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Post.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var payoffGoalRequest = new PayoffGoalRequest{
    PayoffGoal = new PayoffGoalModel{
        ImageName = "house.jpg",
       Name = GoalName,
       TargetCompletionOn = DateTime.Now.Add(new TimeSpan(30,0,0,0)),
       TargetContribution = 50.00,
       AccountIds = new List<int> {4394169}
    }
};

var payoffGoalsResponse = sdk.CreatePayoffGoal(payoffGoalRequest);

Request payload

{
  "payoff_goal": {
    "image_name": "car.jpg",
    "name": "Payoff a car",
    "target_contribution": "50.00",
    "account_ids": [
      2189
    ]
  }
}

Response payload

{
  "payoff_goals": [
    {
      "id": 583,
      "name": "Payoff a car",
      "image_name": "car.jpg",
      "image_url": "https://example.com/images/car.jpg",
      "state": "active",
      "status": "risk",
      "initial_value": "10.00",
      "current_value": "200.00",
      "target_value": "0.00",
      "monthly_contribution": "50.00",
      "percent_complete": 2,
      "complete": false,
      "target_completion_on": "2014-05-21",
      "created_at": "2013-01-01T16:54:15Z",
      "updated_at": "2013-10-01T20:21:01Z",
      "links": {
        "accounts": [2189]
      }
    }
  ]
}

Create a payoff goal for the given user.

POST /api/v2/users/:user_id:/payoff_goals

Parameters

Parameter Description
image_name The image that represents this payoff goal on the Geezeo dashboard. Required
name Short name describing this goal. Required
target_contribution The amount that will be contributed to this goal every month. Required unless target_completion_on is included
target_completion_on The date at which this goal should be obtained. Required unless target_completion_on is included
account_ids The IDs of the Geezeo accounts that this payoff goal should be applied to. (The loan being paid-off has also been added to Geezeo) Required

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Payoff Goal

curl -X "PUT" "http://partner.url/api/v2/users/payoff_goals/:payoff_goal_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/payoff_goals/:payoff_goal_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var payoffGoalId = 12345;
var payoffGoalRequest = new PayoffGoalRequest{
    PayoffGoal = new PayoffGoalModel{
        ImageName = "house.jpg",
       Name = GoalName,
       TargetCompletionOn = DateTime.Now.Add(new TimeSpan(30,0,0,0)),
       TargetContribution = 50.00,
       AccountIds = new List<int> {4394169}
    }
};

var updated = sdk.UpdatePayoffGoal(payoffGoalId, payoffGoalRequest);

Request payload

{
  "payoff_goal": {
    "image_name": "car.jpg",
    "name": "Payoff a car",
    "target_contribution": "50.00",
    "account_ids": [
      2189
    ]
  }
}

Update a payoff goal for the given user.

PUT /api/v2/users/:user_id:/payoff_goals/:payoff_goal_id:

Parameters

Parameter Description
image_name The image that represents this payoff goal on the Geezeo dashboard. Required
name Short name describing this goal. Required
target_contribution The amount that will be contributed to this goal every month. Required unless target_completion_on is included
target_completion_on The date at which this goal should be obtained. Required unless target_completion_on is included
account_ids The IDs of the Geezeo accounts that this payoff goal should be applied to. (The loan being paid-off has also been added to Geezeo) Required

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Delete Payoff Goal

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:/payoff_goals/:payoff_goal_id:" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/:user_id:/payoff_goals/:payoff_goal_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var payoffGoalId = 12345;
var deleted = sdk.DeletePayoffGoal(payoffGoalId);

Delete a payoff goal for the given user.

DELETE /api/v2/users/:user_id:/payoff_goals/:payoff_goal_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Archive Payoff Goal

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/payoff_goals/:payoff_goal_id:/archive" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/payoff_goals/:payoff_goal_id:/archive')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var payoffGoalId = 12345;
var archived = sdk.ArchivePayoffGoal(payoffGoalId);

Archive a payoff goal for the given user.

PUT /api/v2/users/:user_id:/payoff_goals/:payoff_goal_id:/archive

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Ping

Get Ping

curl -X "GET" "http://partner.url/api/v2/ping" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/ping')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var pingResponse = sdk.Ping();
//response object includes a bool value indicating success

Response payload

{
  "response": "PONG"
}

Verify connectivity to the API.

GET /api/v2/ping

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided

Savings Goals

Savings Goal States

State Description
active The goal is being updated and is capable of generating alerts.
archived The goal is no longer being updated or generating alerts.

Savings Goal Statuses

Status Description
complete The goal has been accomplished.
over The goal's target completion date has passed.
risk The goal is not on target for completion on time. (Its current value is less than 80% of its expected current value).
under The goal is on target for completion on time.

Savings Goal Contributions

Attribute Description
monthly_contribution The average monthly conrtibution (rounded to the nearest ten).
target_contribution The amount that will be contributed to this goal every month.

Get Savings Goal Images

curl -X "GET" "http://partner.url/api/v2/savings_goals" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/savings_goals')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var SavigsGoalImages = sdk.GetSavingsGoalImages();

Response payload

{
  "savings_goal_images": [
    {
      "id": "baby.jpg",
      "name": "Save for a baby",
      "url": "http://www.example.com/images/standard_goal_images/baby.jpg?1368824034"
    }
  ]
}

Return a list of pre-defined savings goal images.

GET /api/v2/savings_goals

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided

Get Savings Goals

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/savings_goals" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/savings_goals')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var savingsGoalsResponse = sdk.GetSavingsGoals();

Response payload

{
  "savings_goals": [
    {
      "id": 583,
      "name": "Save for a Baby",
      "image_name": "baby.jpg",
      "image_url": "https://example.com/images/baby.jpg",
      "state": "active",
      "status": "risk",
      "initial_value": "10.00",
      "current_value": "200.00",
      "target_value": "2000.00",
      "monthly_contribution": "50.00",
      "percent_complete": 2,
      "complete": false,
      "target_completion_on": "2014-05-21",
      "target_contribution": "50.00",
      "created_at": "2013-01-01T16:54:15Z",
      "updated_at": "2013-10-01T20:21:01Z",
      "links": {
        "accounts": [2944]
      }
    }
  ]
}

Return a list of all savings goals for the given user.

GET /api/v2/users/:user_id:/savings_goals

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Savings Goal

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/savings_goals/:savings_goals_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/savings_goals/:savings_goals_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var savingsGoalId = 12345;
var savingsGoalsResponse = sdk.GetSavingsGoal(savingsGoalId);

Response payload

{
  "savings_goals": [
    {
      "id": 583,
      "name": "Save for a Baby",
      "image_name": "baby.jpg",
      "image_url": "https://example.com/images/baby.jpg",
      "state": "active",
      "status": "risk",
      "initial_value": "10.00",
      "current_value": "200.00",
      "target_value": "2000.00",
      "monthly_contribution": "50.00",
      "percent_complete": 2,
      "complete": false,
      "target_completion_on": "2014-05-21",
      "target_contribution": "50.00",
      "created_at": "2013-01-01T16:54:15Z",
      "updated_at": "2013-10-01T20:21:01Z",
      "links": {
        "accounts": [2944]
      }
    }
  ]
}

Return a savings goal for the given user.

GET /api/v2/users/:user_id:/savings_goals/:savings_goals_id:

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Create Savings Goal

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/savings_goals" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/savings_goals')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Post.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var savingsGoalRequest = new SavingsGoalRequest{
    SavingsGoal = new SavingsGoalModel{
       AccountId = 4394169,
       ImageName = "house.jpg",
       Name = GoalName,
       LockedBalance = 200.00,
       TargetContribution = 50.00,
       TargetValue = 2000.00
    }
};

var savingsGoalsResponse = sdk.CreateSavingsGoal(savingsGoalRequest);

Request payload

{
  "savings_goal": {
    "account_id": 2189,
    "image_name": "baby.jpg",
    "name": "Save for a Baby",
    "locked_balance": "200.00",
    "target_contribution": "50.00",
    "target_value": "2000.00"
  }
}

Create a savings goal for the given user.

POST /api/v2/users/:user_id:/savings_goals

Parameters

Parameter Description
image_name The image that represents this payoff goal on the Geezeo dashboard. Required
name Short name describing this goal. Required
locked_balance The amount to reserve in the account (that will not apply to the goal)
target_contribution The amount that will be contributed to this goal every month. Required unless target_completion_on is included
target_completion_on The date at which the target_value should be obtained. Required unless target_completion_on is included
target_value The total amount to be saved for this goal. Required
account_id The ID of the account that this savings goal should be added to. Required

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Update Savings Goal

curl -X "PUT" "http://partner.url/api/v2/users/savings_goals/:savings_goal_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/savings_goals/:savings_goal_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var savingsGoalId = 12345;
var savingsGoalRequest = new SavingsGoalRequest{
    SavingsGoal = new SavingsGoalModel{
       AccountId = 4394169,
       ImageName = "house.jpg",
       Name = GoalName,
       LockedBalance = 200.00,
       TargetContribution = 50.00,
       TargetValue = 2000.00
    }
};

var updated = sdk.UpdateSavingsGoal(savingsGoalId, savingsGoalRequest);

Request payload

{
  "savings_goal": {
    "account_id": 2189,
    "image_name": "baby.jpg",
    "name": "Save for a Baby",
    "locked_balance": "200.00",
    "target_contribution": "50.00",
    "target_value": "2000.00"
  }
}

Update a savings goal for the given user.

PUT /api/v2/users/:user_id:/savings_goals/:savings_goals_id:

Parameters

Parameter Description
image_name The image that represents this payoff goal on the Geezeo dashboard. Required
name Short name describing this goal. Required
locked_balance The amount to reserve in the account (that will not apply to the goal)
target_contribution The amount that will be contributed to this goal every month. Required unless target_completion_on is included
target_completion_on The date at which the target_value should be obtained. Required unless target_completion_on is included
target_value The total amount to be saved for this goal. Required
account_id The ID of the account that this savings goal should be added to. Required

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Delete Savings Goal

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:/savings_goals/:savings_goal_id:" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/:user_id:/savings_goals/:savings_goal_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var savingsGoalId = 12345;
var savingsGoalRequest = new SavingsGoalRequest{
    SavingsGoal = new SavingsGoalModel{
       AccountId = 4394169,
       ImageName = "house.jpg",
       Name = GoalName,
       LockedBalance = 200.00,
       TargetContribution = 50.00,
       TargetValue = 2000.00
    }
};

var deleted = sdk.DeleteSavingsGoal(savingsGoalId);

Delete a savings goal for the given user.

DELETE /api/v2/users/:user_id:/savings_goals/:savings_goals_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Archive Savings Goal

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/savings_goals/:savings_goal_id:/archive" -u "%geezeo-api-key%" 
uri = URI('https://partner.url/api/v2/users/savings_goals/:savings_goal_id:/archive')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var savingsGoalId = 12345;
var archived = sdk.ArchiveSavingsGoal(savingsGoalId);

Archive a savings goal for the given user.

PUT /api/v2/users/:user_id:/savings_goals/:savings_goals_id:/archive

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Tags

Get Default Tags

curl -X "GET" "http://partner.url/api/v2/tags" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/tags')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response payload

{
  "tags": [
    "Clothing",
    "Education",
    "Entertainment",
    "Diningout",
    "Groceries",
    "Fees",
    "Health",
    "Home",
    "Income",
    "Personal",
    "Payment",
    "Savings",
    "Transfer",
    "Transportation",
    "Travel",
    "Utilities"
  ]
}

Return the default tags available to all users.

GET /api/v2/tags

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided

Get User Tags

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/tags" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/tags')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response payload

{
  "tags": [
    "Coffee",
    "Shoes",
    "Clothing",
    "Education",
    "Entertainment",
    "Diningout",
    "Groceries",
    "Fees",
    "Health",
    "Home",
    "Income",
    "Personal",
    "Payment",
    "Savings",
    "Transfer",
    "Transportation",
    "Travel",
    "Utilities"
  ]
}

Return all custom tags a user has entered in addition to the default tags.

GET /api/v2/users/:user_id:/tags

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Tickets

Create Support Ticket

curl -X "POST" "http://partner.url/api/v2/users/:user_id:/tickets" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/tickets')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Post.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

Request payload

{
  "ticket": {
    "description": "How do I create a new Goal?",
    "problem_type": "faq",
    "requester_email": "user@example.com"
  }
}

Create a support ticket for the given user.

POST /api/v2/users/:user_id:/tickets

Problem types

Description Type
"I want to request a feature" feature_request
"I'm not sure how something works" faq
"Something isn't working as intended" gzo_defect
"I want to request a financial institution so I can add it" bank_request
"Other" gzo_defect

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Transactions

Get User Transactions

curl -X "GET" "http://partner.url/api/v2/:user_id:/transactions" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/:user_id:/transactions')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var TransactionsResponse = sdk.GetTransactions();

Response payload

{
  "meta": {
    "current_page": 1,
    "total_pages": 2
  },
  "accounts": [
    {
      "id": 42,
      "name": "eChecking"
    }
  ],
  "transactions": [

    {
        "id": "f8f89b46-35d1-44a5-bf14-4c64d74ca88b",
        "reference_id": "42",
        "transaction_type": "Debit",
        "memo": "GAMESTOP MAIN ST",
        "balance": 12.69,
        "posted_at": "2016-02-19T00:00:00.000+00:00",
        "created_at": "2016-02-20T05:58:46.158+00:00",
        "nickname": "GameStop",
        "original_name": "GAMESTOP 14 MAIN ST 123 123 2223123 23",
        "check_number": null,
        "tags": [
          {
            "name": "Entertainment",
            "balance": 12.69
          }
        ],
        "links": {
          "account": 2
        }
    }
  ]
}

Return a paginated list of all transactions for the given user.

GET /api/v2/users/:user_id:/transactions

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var pageNumber = 2;
var TransactionsResponse = sdk.GetTransactionsByPage(pageNumber);

Parameters

Parameter Description
page Return subsequent pages of results.

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Get Account Transactions

curl -X "GET" "http://partner.url/api/v2/accounts/:account_id:/transactions" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/accounts/:account_id:/transactions')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var accountId = 12345;
var TransactionsResponse = sdk.GetTransactionsByAccount(accountId);

Response payload

{
  "meta": {
    "current_page": 1,
    "total_pages": 2
  },
  "accounts": [
    {
      "id": 42,
      "name": "eChecking"
    }
  ],
  "transactions": [
    {
        "id": "f8f89b46-35d1-44a5-bf14-4c64d74ca88b",
        "reference_id": "42",
        "transaction_type": "Debit",
        "memo": "GAMESTOP MAIN ST",
        "balance": 12.69,
        "posted_at": "2016-02-19T00:00:00.000+00:00",
        "created_at": "2016-02-20T05:58:46.158+00:00",
        "nickname": "GameStop",
        "original_name": "GAMESTOP 14 MAIN ST 123 123 2223123 23",
        "check_number": null,
        "tags": [
          {
            "name": "Entertainment",
            "balance": 12.69
          }
        ],
        "links": {
          "account": 2
        }
    }
  ]
}

Return a paginated list of all transactions for the given account.

GET /api/v2/users/:user_id:/accounts/:account_id:/transactions

To view additional transactions call /api/v2/users/:user_id:/accounts/:account_id:/transactions?page=:page_number:

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user or account is specified

Get Budget Transactions

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/budgets/:budget_id:/transactions" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/budgets/:budget_id:/transactions')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var budgetId = 12345;
var TransactionsResponse = sdk.GetTransactionsByBudget(budgetId);

Response payload

{
  "accounts": [
    {
      "id": 42,
      "name": "eChecking"
    }
  ],
  "transactions": [
    {
        "id": "f8f89b46-35d1-44a5-bf14-4c64d74ca88b",
        "reference_id": "42",
        "transaction_type": "Debit",
        "memo": "GAMESTOP MAIN ST",
        "balance": 12.69,
        "posted_at": "2016-02-19T00:00:00.000+00:00",
        "created_at": "2016-02-20T05:58:46.158+00:00",
        "nickname": "GameStop",
        "original_name": "GAMESTOP 14 MAIN ST 123 123 2223123 23",
        "check_number": null,
        "tags": [
          {
            "name": "Entertainment",
            "balance": 12.69
          }
        ],
        "links": {
          "account": 2
        }
    }
  ]
}

Return a list of all transactions for the given budget (for the current month).

GET /api/v2/users/:user_id:/budgets/:budget_id:/transactions

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user or account is specified

Search Transactions

curl -X "GET" "http://partner.url/api/v2/users/:user_id:/transactions/search?q=GameStop&untagged=0&begin_on=2013-01-01&end_on=2013-06-01" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:/transactions/search?q=GameStop&untagged=0&begin_on=2013-01-01&end_on=2013-06-01')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var searchCriteria = new TransactionSearchCriteriaModel{
    Query = "GameStop",
    Untagged = false,
    BeginOn = new DateTime(2013, 1, 1),
    EndOn = new DateTime(2013, 6, 1),
    AccountIds = new List<int>{12345, 67890},
    Tags = new List<string>{"Personal", "Transportation"}
};
var TransactionsResponse = sdk.SearchTransactions(searchCriteria);

Response payload

{
  "accounts": [
    {
      "id": 42,
      "name": "eChecking"
    }
  ],
  "transactions": [
    {
        "id": "f8f89b46-35d1-44a5-bf14-4c64d74ca88b",
        "reference_id": "42",
        "transaction_type": "Debit",
        "memo": "GAMESTOP MAIN ST",
        "balance": 12.69,
        "posted_at": "2016-02-19T00:00:00.000+00:00",
        "created_at": "2016-02-20T05:58:46.158+00:00",
        "nickname": "GameStop",
        "original_name": "GAMESTOP 14 MAIN ST 123 123 2223123 23",
        "check_number": null,
        "tags": [
          {
            "name": "Entertainment",
            "balance": 12.69
          }
        ],
        "links": {
          "account": 2
        }
    }
  ]
}

Search transactions for the given user.

GET /api/v2/users/:user_id:/transactions/search?q=GameStop&untagged=0&begin_on=2013-01-01&end_on=2013-06-01

Parameters

Parameter Description
q The search term.
account_ids Limit search results to accounts.
untagged Limit search results to untagged transactions. Should be 1 for true; 0 for false.
tags[] Limit search results to tagged transactions.
begin_on Limit search results to after this date (inclusive).
end_on Limit search results to before this date (inclusive).

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Updating transactions

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:/transactions/:transaction_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:/transactions/:transaction_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var requestModel = new TransactionRequestModel{
    Transaction = new TransactionModel{
        Nickname = "Starbucks"
    },
    Tagging = new TaggingModel{
        Type = TaggingType.Regular,
        Regular = new List<string> {"Coffee"}
    }
};
var transactionId = "85b20186-b367-4feb-8acd-d5378e7b4d94";
var updated = sdk.UpdateTransaction(transactionId, requestModel);

Request payload single tag

{
  "transaction": {
    "nickname": "Starbucks"
  },
  "tagging": {
    "type": "regular",
    "regular": ["Coffee"]
  }
}

var requestModel = new TransactionRequestModel{
    Transaction = new TransactionModel{
        Nickname = "Starbucks"
    },
    Tagging = new TaggingModel{
        Type = TaggingType.Regular,
        Regular = new List<string> {"Coffee"}
    }
};

Request payload split tag

{
  "transaction": {
    "nickname": "Starbucks"
  },
  "tagging": {
    "type": "split",
    "split": [
      { "name": "Entertainment", "value": 3 },
      { "name": "Coffee", "value": 2.50 }
    ]
  }
}
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);
var requestModel = new SplitTransactionRequestModel{
    Transaction = new TransactionModel{
        Nickname = "Starbucks"
    },
    Tagging = new SplitTaggingModel{
        Type = TaggingType.Split,
        Split = new List<TagRequest> {
            new TagRequest{Name = "Entertainment", Value = 3},
            new TagRequest{Name = "Coffee", Value = 2.50}
        }
    }
};
var transactionId = "85b20186-b367-4feb-8acd-d5378e7b4d94";
var updated = sdk.SplitTransaction(transactionId, requestModel);


Request payload with adding a rule

{
  "transaction": {
    "nickname": "Starbucks"
  },
  "tagging": {
    "type": "regular",
    "regular": ["Coffee"],
    "repeat": true
  }
}
var apiKey = "geezeo-api-key";
var url = "partner.url";
var userId = "user_id";
var sdk = new SDK(apiKey, url, userId);

var requestModel = new TransactionRuleRequestModel{
    Transaction = new TransactionModel{
        Nickname = "Starbucks"
    },
    Tagging = new TaggingRuleModel{
        Type = TaggingType.Regular,
        Regular = new List<string> {"Coffee"},
        Repeat = true,
        Account = TaggingAccount.CurrentAccount,
        PostedAt = TaggingPostedAt.AnyDate
    }
};
var transactionId = "85b20186-b367-4feb-8acd-d5378e7b4d94";
var updated = sdk.UpdateTransactionRule(transactionId, requestModel);

Error response payload

{
  "error": {
    "message": "Error in transaction",
    "data": ["Specific error message"]
  }
}
//Typical Error object format returned from SDK
{
      var error = new GeezeoSdkException{ //base class
                        GeezeoError = new GeezeoError{
                                Error = new InternalError{
                                    Message = "Error in transaction"
                                    Data = new List<string>{
                                        "Specific Error Message"
                                    }
                                },
                                Message = "Error in transaction"
                            },
                         ExceptionType = ExceptionType.InternalServer
                        }
}

//Typical Error object format returned from SDK when error is unprocessable entity
{
      var error = new GeezeoSdkException{ //base class
                        GeezeoError = new GeezeoError{
                                Error = new InternalError{
                                    Message = "Error in transaction"
                                    Data = new Dictionary<string, object>{
                                        "Specific property", "error message"
                                    }
                                }
                            },
                         ExceptionType = ExceptionType.UnprocessableEntity
                        }
}

Transaction nicknames and tags can be changed.

Tags can be a single tag, or split a transactions into multiple tags.

Rules can be added by adding a repeat node to the json. Once a rule is added the platform will ensure future matching transactions receive that tag and nickname.

Split tags are not supported by rules as they are specific to an exact amount.

PUT /api/v2/users/:user_id:/transactions/:transaction_id:

Parameters

Parameter Description
nickname The nickname to give this transaction.
type Type of tag(s) being set. Required if tags are being set. Should be regular or split.
regular The regular tag being applied to this transaction.
split A list of key/value pairs, where name is the name of the tag and value is the amount.
repeat Should this tag be applied to similar transactions. Default false.
account The account(s) where the rule should be applied. Should be current_account or all_accounts. Default all_accounts.
posted_at When the rule should start being applied. Should be any_date or future_date. Default any_date. Note that if this field is not set to within 180 days the system will not accept the transaction.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified
422 Unprocessable Entity returned when the parameters given were invalid

Users

NOTE

This section does NOT work with JWT. This section is for administrative purposes.

To get the current user please use the current user

Get Users

curl -X "GET" "http://partner.url/api/v2/users" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

GET /api/v2/users

Response payload

Return a paginated list of all users.

Parameters

Parameter Description
page Return subsequent pages of results.

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided

Get User

curl -X "GET" "http://partner.url/api/v2/users/:user_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Get.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Response payload

{
  "users": [
    {
      "id": "42",
      "login": "jsmith42",
      "first_name": "Alice",
      "last_name": "Smith",
      "email": "user@example.com",
      "login_count": 1,
      "last_login_at": "2013-09-29T15:16:36Z",
      "postal_code": "06252",
      "birth_year": 1980,
      "sex": "Male",
      "custom_tags": []
    }
  ]
}

Return information about a user.

GET /api/v2/users/:user_id:

Status Codes

Status Description
200 OK returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Create User

curl -X "POST" "http://partner.url/api/v2/users" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Post.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

Request payload

{
  "user": {
    "id": "42",
    "login": "bsmith24",
    "first_name": "B",
    "last_name": "Smith",
    "email": "user@example.com",
    "postal_code": "06252",
    "birth_year": 1980,
    "sex": "Male",
    "custom_tags": ["Coffee", "Food"]
  }
}

Response payload

{
  "users": [
    {
      "id": "42",
      "href": "http://example.com/api/v2/users/42",
      "login": "bsmith42",
      "first_name": "B",
      "last_name": "Smith",
      "email": "user@example.com",
      "login_count": 0,
      "last_login_at": null,
      "postal_code": "06252",
      "birth_year": 1980,
      "sex": "Male",
      "custom_tags": [
        "Coffee",
        "Food"
      ]
    }
  ]
}

Create a new user. POST /api/v2/users

Parameters

Parameter Description
id The user's partner customer id. Required
email The user's email address. Required
first_name The user's first name. Required
last_name The user's last name. Required
login The user's login for the PFM.
postal_code The user's postal code.
birth_year The year the user was born.
sex The sex of the user. Either "Male" or "Female".
custom_tags A list of tags the user has added.

Status Codes

Status Description
201 Created returned when successful
401 Not Authorized returned when invalid credentials are provided
422 Unprocessable Entity returned when the parameters given were invalid

Update User

curl -X "PUT" "http://partner.url/api/v2/users/:user_id:" -u "%geezeo-api-key%" -d ":request_payload:"
uri = URI('https://partner.url/api/v2/users/:user_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Put.new uri.request_uri
  request.basic_auth key,''
  request.body = :request_payload:

  response = http.request request

  puts response.body
end

Request payload

{
  "user": {
    "id": 42,
    "login": "bsmith24",
    "first_name": "B",
    "last_name": "Smith",
    "email": "user@example.com",
    "postal_code": "06252",
    "birth_year": 1980,
    "sex": "Male",
    "custom_tags": ["Coffee", "Food"]
  }
}

Response payload

{
  "users": [
    {
      "id": "42",
      "href": "http://example.com/api/v2/users/42",
      "login": "bsmith42",
      "first_name": "B",
      "last_name": "Smith",
      "email": "user@example.com",
      "login_count": 1,
      "last_login_at": "2013-09-29T15:16:36Z",
      "postal_code": "06252",
      "birth_year": 1980,
      "sex": "Male",
      "custom_tags": [
        "Coffee",
        "Food"
      ]
    }
  ]
}

Update an existing user.

PUT /api/v2/users/:user_id:

Parameters

Parameter Description
id The user's partner customer id.
login The user's login for the PFM.
first_name The user's first name.
last_name The user's last name.
email The user's email address.
postal_code The user's postal code.
birth_year The year the user was born.
sex The sex of the user. Either "Male" or "Female".
custom_tags A list of tags the user has added.

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
422 Unprocessable Entity returned when the parameters given were invalid

Delete User

curl -X "DELETE" "http://partner.url/api/v2/users/:user_id:" -u "%geezeo-api-key%"
uri = URI('https://partner.url/api/v2/users/:user_id:')
key = ':geezeo-aip-key:'

Net::HTTP.start(uri.host, uri.port,
  :use_ssl => uri.scheme == 'https') do |http|

  request = Net::HTTP::Delete.new uri.request_uri
  request.basic_auth key,''

  response = http.request request

  puts response.body
end

Delete a user.

DELETE /api/v2/users/:user_id:

Status Codes

Status Description
204 No Content returned when successful
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when an invalid user is specified

Data Source Setup

Geezeo provides robust transaction enrichment for partner and aggregated accounts. The first step in any implementation is connecting the platform to a data source for all partner accounts.

Geezeo provides a standard XML specification for harvesting transactions and accounts. Partners must provide an endpoint that meets the XML specifications below to provide data.

The Geezeo platform will harvest users data based on a predefined schedule.

Geezeo also provides a file transfer using the same XML spec. File transfers are often used in larger implementations for bulk data. This format is similar to the RequestResponse format but with a slight variation.

If a data source is setup to pull by date and the user has no transactions stored at Geezeo we will harvest exactly 90 days worth. If the user does have transactions Geezeo will harvest all transactions after the day before the account's latest transaction even if this time is greater than 90 days. In the event that the user has transactions that are more than 180 days old Geezeo will not create, modify, or delete said transactions.

Customer User data format

Users Request XML

<PartnerRequest
    signature="PartnerSignature"        
    id="2"
    sso_partner_id="abc122">
  <UserList>
    <Users>
      <User>
        <PartnerCustomerId>1234</PartnerCustomerId>
      </User>
    </Users>
  </UserList>
</PartnerRequest>

Users Response XML

<PartnerResponse
    signature="PartnerSignature"
    request_id="2">
  <Users>
    <User>
      <Action>New</Action>
      <PartnerCustomerId>123</PartnerCustomerId>
      <FirstName>FirstName</FirstName>
      <LastName>LastName</LastName>
      <Email>flastname@geezeo.com</Email>
      <ZipCode>06000</ZipCode>
      <UserExperience>pfm</UserExperience>
    </User>
  </Users>
</PartnerResponse>

Users XML File Example

<?xml version="1.0" encoding="utf-8"?>
<Users>
  <User>
    <Details>
      <Action>New</Action>
      <PartnerCustomerId>322079353</PartnerCustomerId>
      <FirstName>RITA                </FirstName>
      <LastName>WILLIAMS                                </LastName>
      <Email>rita@williams.us</Email>
      <ZipCode>19975-3918</ZipCode>
    </Details>

  </User>
  <User>
    <Details>
      <PartnerCustomerId>322079353</PartnerCustomerId>
      <FirstName>JOE</FirstName>
      <LastName>MOMMA</LastName>
      <Email>jmomma@badjoke.com</Email>
      <ZipCode>20171     </ZipCode>
    </Details>

  </User>
  <User>
    <Details>
      <Action>Delete</Action>
      <PartnerCustomerId>322079353</PartnerCustomerId>
      <FirstName>WILLIAM</FirstName>
      <LastName>HOUSES</LastName>
      <Email>whouses@aol.com</Email>
      <ZipCode>20110     </ZipCode>
    </Details>

  </User>
</Users>

Geezeo will request a list of users by sending User elements containing only their PartnerCustomerIds.

Validating a Partner Signature Request and generating a Partner Signature Response.

Tag Type Usage Description
<Users> Container Required Contains all <User> records in the set
<User> Container Required Contains data defining a single customer
<Action> Enum Required If this element is left out, Geezeo will attempt to update the record, or add it if it does not exist; specify “Delete" if the account is to be deleted
<PartnerCustomerId> String (255) Required; Unique Unique alphanumeric ID; used to identify the customer and match accounts to it
<FirstName> String (255) Optional Customer's first name
<LastName> String (255) Optional Customer's last name
<Email> String (255) Optional Customer's email address; should be a properly formatted email address
<ZipCode> String (255) Required Customer's zip code; should be a valid US postal code
<UserExperience> String (255) Optional Customer user experience (PFM or TruBiz)

Customer Account data format

Accounts Request XML

<PartnerRequest
    signature="PartnerSignature"
    id="2"
    sso_partner_id="abc122">
  <AccountList>
      <Accounts>
        <Account>
          <PartnerCustomerId>4453</PartnerCustomerId>
        </Account>
      </Accounts>
    </AccountList>
</PartnerRequest>

Accounts Response XML

<PartnerResponse
    signature="PartnerSignature"
    request_id="2">
  <Accounts>
    <Account>
      <Action>NEW</Action>
      <PartnerCustomerId>12345</PartnerCustomerId>
      <AccountId>999</AccountId>
      <AccountFiName>JOHN Q PUBLIC</AccountFiName>
      <AccountNickname>John's Savings</AccountNickname>
      <AccountType>Savings</AccountType>
      <AccountBalances>
        <AccountBalance>
          <BalanceType>Current</BalanceType>
          <BalanceAmount>1999.99</BalanceAmount>
          <CurrencyCode>USD</CurrencyCode>
        </AccountBalance>
      </AccountBalances>
      <AccountExperience>pfm</AccountExperience>
    </Account>
  </Accounts>
</PartnerResponse>

Accounts XML File example

<?xml version="1.0" encoding="utf-8"?>
<Accounts>

      <Account>
        <Details>
          <Action>New</Action>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000129251-S0011</AccountId>
          <AccountFiName>SUPER MONEY MARKET            </AccountFiName>
          <AccountType>savings</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>430947.36</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>
      </Account>
</Accounts>

Geezeo will request a list of accounts belonging to a user by sending an Account element containing only the user's PartnerCustomerId. You may optionally respond with updated account information instead of all account information. We will create any accounts that do not exist in the Geezeo database, update any accounts that do exist, and mark as closed any accounts that are in the Geezeo database but not in the response.

Validating a Partner Signature Request and generating a Partner Signature Response.

Tag Type Usage Description
<Accounts> Container Required Contains all <Account> records in the set
<Account> Container Required Contains data defining a single account
<Action> Enum Optional If this element is left out, Geezeo will attempt to update the record, or add it if it does not exist; specify “Delete" if the account is to be deleted
<PartnerCustomerId> String (255) Required Matches the account with the proper customer
<AccountId> String (255) Required; Unique
<AccountNumber> String (255) Optional Further identifying information show to the user in certain circumstances to help identify the account to them. Full credit card numbers must not be supplied.
<AccountFiName> String (255) Required Account name as provided by partner
<AccountNickname> String (255) Optional Account nickname if set by partner
<AccountType> Enum Required Account type from closed list
<AccountBalances> Container Required Contains [<AccountBalance>(#AccountBalance) elements
<Properties> Container Optional Contains <Property> elements
<AccountExperience> String (255) Optional Account experience (PFM or Trubiz)

AccountBalance Type Usage Description
<BalanceType> Enum Required The type of balance
<BalanceAmount> Decimal Required The relative value of the balance type to two decimal places, e.g. 505.12 or -1110.56; a negative number should be preceded by a minus sign. Two decimal places are always required, even for .00 amounts.
<CurrencyCode> Enum Required The currency code (currently only USD or CAD)

Account Types

AccountType BalanceType
cd deposit
checking deposit
savings deposit
investment deposit
asset deposit
money_market deposit
cards credit
student_loans credit
loans credit
autos credit
home credit
loan credit
creditline credit

For deposit AccountTypes these are the possible balance types. All deposit accounts must have at least the BalanceType 'Current' with additional BalanceTypes being optional.

BalanceType (Deposit Accounts)

Value Name Usage Description
Current Required The amount currently in the account without any holds
Available Optional The amount after any holds; the effective balance

For credit AccountTypes these are the possible balance types. All credit accounts must have at least the BalanceType 'Outstanding' with additional BalanceTypes being optional.

BalanceType (Credit Accounts)

Value Name Usage Description
CurrentLimit Optional Current charge limit
AvailableCredit Optional Amount left to spend after any charges
Outstanding Required Amount currently charged to card
CashAdvanceLimit Optional Limit on cash advances
MinimumPaymentDue Optional Current minimum payment due
PreviousAmountDue Optional Previous minimum payment due
PastDueAmount Optional Past due amount
FinanceCharges Optional Finance charges for current bill

Properties Container

The properties container is used to define non-balance based information and statistics. For example, in the future, items such as reward points, airline miles, and special promotion information would be provided through the properties container.

Tag Type Usage Description
<Property> Container Required Contains property information
<PropertyType> Element Required The type of property in the record
<PropertyValue> String (255) Required The property's value

Property Types

Tag Type Usage Description
PurchasesApr Decimal Optional APR for Purchase with one decimal of precision; e.g. 24.5% would be 25.5, not .255
PaymentDueDate DateTime Optional Due date for current pay period
InternalTransaction String (255) Optional Add type to internal transaction with these possible options: “bill pay", “transfer"; added for clarity to user

Customer Transaction data format

Transactions Request XML

<PartnerRequest
    signature="PartnerSignature"
    id="2"
    sso_partner_id="abc122">
 <TransactionList>
    <AccountId>12345</AccountId>
    <LastTransactionId>9876</LastTransactionId>
  </TransactionList>
</PartnerRequest>

Trasactions Response XML

<PartnerResponse
    signature="PartnerSignature"
    request_id="2">
  <Transactions>
    <Transaction>
      <TransactionId>12345</TransactionId>
      <AccountId>9999901</AccountId>
      <TransactionType>Debit</TransactionType>
      <PostedDate>2009-03-19T11:40:50-04:00</PostedDate>
      <OriginationDate>2009-03-19T15:31:36-04:00</OriginationDate>
      <Amount>112.03</Amount>
      <Memo>DUNKINDONUTS*100094</Memo>
    </Transaction>
  </Transactions>

</PartnerResponse>

Transactions XML File example

<Transactions>

          <Transaction>
            <TransactionId>85</TransactionId>
            <AccountId>0000129251-S0011</AccountId>
            <TransactionType>Credit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>20.00</Amount>
            <Memo>AMAZON</Memo>
          </Transaction>
</Transactions>

Geezeo will request a list of transactions belonging to a particular account by sending a TransactionList element containing an AccountId. We may provide you with the last TransactionId that we received. In that case, please respond with only transactions newer than that transaction. If we do not provide a TransactionId (for example when adding a new user), simply respond with all transactions.

Tag Type Usage Description
<Transactions> Container Required Contains all <Transaction> records in the file
<Transaction> Container Required Contains data defining a single transaction
<Action> Enum Required If this element is left out, Geezeo will attempt to update the record, or add it if it does not exist; specify “Delete" if the transaction is to be deleted
<TransactionId> String (255) Required; Unique Unique alphanumeric ID; used to identify the transaction. This must be unique within each account, and never change.
<AccountId> String(255) Required Used to match the transaction with its account
<TransactionType> Closed List Required “Debit" for a negative transaction, “Credit" for a positive transaction
<PostedDate> DateTime Required The time that the transaction posted to the user's account
<OriginationDate> DateTime Optional The time the transaction actually occurred
<Amount> Decimal Required The absolute value of the transaction; do not use a dash to indicate a negative number. Two decimal places are required, even if they amount is even (5.00).
<Memo> String (255) Required The transaction description. What is provided in this field should match what's shown on the users statement, and/or in the FIs OLB
<CheckNumber> String (255) Optional If the transaction is a check, a check number may be included in this field.

Partner Request

Request Format

<PartnerRequest
    signature="PartnerSignature"
    id="2"
    sso_partner_id="abc122">
    <!-- Payload -->
</PartnerRequest>

All requests will come within a Partner Request.

Attribute Type Element Description
signature String(128) PartnerRequest, PartnerResponse Contains authentication data
id Integer PartnerRequest An integer to identify the request. These request IDs will be unique per day, but no tracking or verification is necessary.
sso_partner_id String(128) PartnerRequest This value is identical to the partner_id value submitted in the SSO assertion. It can be used by Resellers that use a single end point for all related FIs as a differentiator, if the PartnerCustomerId values are not globally unique.
request_id Integer PartnerResponse The value of this attribute must be the value of the “id" attribute from the corresponding PartnerRequest.

Validating a Request Signature

Signature Verification

  1. Retrieve the signature from the signature attribute of the <PartnerResponse> XML tag
  2. Extract the inner body of the <PartnerResponse> XML tag
  3. Generate a signature for this portion of the body, using the same steps as generating the signature for the response
  4. Ensure the signature generated matches the signature provided by the request

In order for the partner to authenticate Geezeo's requests, and for Geezeo to authenticate the partner's responses, the partner will be issued an API key. This key will never be included in any request or response, rather it will be used as a “shared secret" to generate a signature for each request and response.

The API key may also be used to identify the partner that the request is targeted at if necessary; for instance, if multiple partners are served through the same partner API.

Each request from Geezeo, as well as each response from the partner, will include a signature that is calculated the exact same way. The steps for signature generation and verification are outlined below.

Partner Response

Request Format

<PartnerResponse
    signature="PartnerSignature"
    request_id="2">
    <!-- Payload -->
</PartnerResponse>

All responses should be come in the form of a PartnerResponse.

Attribute Type Element Description
signature String(128) PartnerRequest, PartnerResponse Contains authentication data
id Integer PartnerRequest An integer to identify the request. These request IDs will be unique per day, but no tracking or verification is necessary.
sso_partner_id String(128) PartnerRequest This value is identical to the partner_id value submitted in the SSO assertion. It can be used by Resellers that use a single end point for all related FIs as a differentiator, if the PartnerCustomerId values are not globally unique.
request_id Integer PartnerResponse The value of this attribute must be the value of the “id" attribute from the corresponding PartnerRequest.

Generating a Response Signature

In order for the partner to authenticate Geezeo's requests, and for Geezeo to authenticate the partner's responses, the partner will be issued an API key. This key will never be included in any request or response, rather it will be used as a “shared secret" to generate a signature for each request and response.

The API key may also be used to identify the partner that the request is targeted at if necessary; for instance, if multiple partners are served through the same partner API.

Each request from Geezeo, as well as each response from the partner, will include a signature that is calculated the exact same way. The steps for signature generation and verification are outlined below.

Signature Generation

  1. Generate the inner portion of the <PartnerResponse> XML tag
  2. Remove any leading and trailing whitespace from each line, and then remove any newline characters
  3. Generate a SHA512 hash of this body
  4. Decode the partner's API key from a string to hexadecimal bytes. For example, "3ab4" would be the byte array 58,180.
  5. XOR the bytes of the xml hash with the decoded API key. Both the hash and the key should have the same number of bytes.
  6. The converted result to hexadecimal (low nibble first) should be the signature. Once a signature has been generated, place it in the “signature" attribute of the top level XML element, which will be PartnerRequest or PartnerResponse.

Signature Example

Example Partner Request

 <PartnerRequest        
     signature="eef7055a0942e5d4692ef74de3482e777b54aad196ce49c5f01e707d041e0e9638d31a1582148458ca191bc1d3be04954cd29f8f62d3ee77485a06c998a564d6"
     id="1"     
     sso_partner_id="abc123">       
   <AccountList>        
     <Accounts>     
       <Account>        
         <PartnerCustomerId>2358475</PartnerCustomerId>     
       </Account>       
     </Accounts>        
   </AccountList>       
 </PartnerRequest>      

Example payload - note : no spaces or line feeds

 <AccountList><Accounts><Account><PartnerCustomerId>2358475</PartnerCustomerId></Account></Accounts></AccountList>

Example api key

 c70b5dd9ebfb6f51d09d4132b7170c9d20750a7852f00680f65658f0310e810056e6763c34c9a00b0e940076f54495c169fc2302cceb312039271c43469507dc

Example payload SHA512

 29fc5883e2b98a85b9b3b67f545f22ea5b21a0a9c43e4f450648288d35108f966e356c29b6dd2453c48d1bb726fa9154252ebc8dae38df57717d1a8ade30630a

Example generated payload signature

 eef7055a0942e5d4692ef74de3482e777b54aad196ce49c5f01e707d041e0e9638d31a1582148458ca191bc1d3be04954cd29f8f62d3ee77485a06c998a564d6

Using the example to the right. The payload should be used for the signature.

The payload is the actual request body inside the PartnerRequest.

The SHA512 of the xml payload.

XOR'ing the bytes of the key and payload hash gives us the signature.

Flat File

Geezeo also accepts a flat file transfer using a similar XML spec. Flat file transfers are often used in larger implementations for bulk data. When sending data using this method all data should be put into one file. The format for a flat file is similar to the standard format for the Geezeo API but has some slight differences. All elements explained in the Users, Accounts, and Transactions sections apply to the flat file as well. See provided example.

When you have finished uploading a file to our SFTP server you can notify us of the new file by sending a simple POST request to an API endpoint.

The URL for this endpoint is, https://partner.url/api/v2/uploads/received, and it takes several query string parameters:

api_key={API_KEY}

filenames={FILENAME_1},{FILENAME_2},...

hashes={MD5_HASH_FILE_1},{MD5_HASH_FILE_2},...

[optional] types={FILE_1_TYPE},{FILE_2_TYPE}....

Types are combined, accounts, users, or transactions

The completed URL should look something like: https://partner.url/api/v2/uploads/received?api_key=abc123&filenames=data.xml,data2.xml&hash=hash1,hash1&types=account,user

Where API_KEY is your Geezeo API key, the filenames are the names of the file you uploaded to the SFTP server (flatfiler.gzo), the MD5 are the full md5 hash of the files you uploaded (in respective order) and the types are the account types of each file in respective order.

If you mark a filetype as accounts the system will only import account data and will ignore transactions and users.

Flat File XML Example

<?xml version="1.0" encoding="utf-8"?>
<Users>
  <User>
    <Details>
      <PartnerCustomerId>322079353</PartnerCustomerId>
      <FirstName>RITA                </FirstName>
      <LastName>WILLIAMS                                </LastName>
      <Email>rita@williams.us</Email>
      <ZipCode>19975-3918</ZipCode>
    </Details>

      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000129251-S0000</AccountId>
          <AccountFiName>REGULAR SAVINGS               </AccountFiName>
          <AccountType>savings</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>5.13</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000129251-S0011</AccountId>
          <AccountFiName>SUPER MONEY MARKET            </AccountFiName>
          <AccountType>savings</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>430947.36</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

          <Transaction>
            <TransactionId>83</TransactionId>
            <AccountId>0000129251-S0011</AccountId>
            <TransactionType>Debit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>-10.00</Amount>
            <Memo>Dunkin Donuts</Memo>
          </Transaction>
          <Transaction>
            <TransactionId>85</TransactionId>
            <AccountId>0000129251-S0011</AccountId>
            <TransactionType>Credit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>20.00</Amount>
            <Memo>AMAZON</Memo>
          </Transaction>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000129251-S0017</AccountId>
          <AccountFiName>ADVANTAGE CHECKING            </AccountFiName>
          <AccountType>checking</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>9868.66</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000129251-S0028</AccountId>
          <AccountFiName>TRADITIONAL IRA SHARE         </AccountFiName>
          <AccountType>investment</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>11895.88</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

          <Transaction>
            <TransactionId>84</TransactionId>
            <AccountId>0000129251-S0028</AccountId>
            <TransactionType>Debit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>-10.00</Amount>
            <Memo>EBAY</Memo>
          </Transaction>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000129251-L0001</AccountId>
          <AccountFiName>SIGNATURE LOC FIXED RATE      </AccountFiName>
          <AccountType>loan</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Outstanding</BalanceType>
              <BalanceAmount>0.00</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

      </Account>

  </User>
  <User>
    <Details>
      <PartnerCustomerId>322079353</PartnerCustomerId>
      <FirstName>KOBE</FirstName>
      <LastName>BRYANT                                    </LastName>
      <Email>kbryant@gmail.com</Email>
      <ZipCode>22030-6090</ZipCode>
    </Details>

      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000173112-S0000</AccountId>
          <AccountFiName>REGULAR SAVINGS               </AccountFiName>
          <AccountType>savings</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>15.00</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

          <Transaction>
            <TransactionId>66</TransactionId>
            <AccountId>0000173112-S0000</AccountId>
            <TransactionType>Credit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>10.00</Amount>
            <Memo>STEAMGAMES</Memo>
          </Transaction>
          <Transaction>
            <TransactionId>67</TransactionId>
            <AccountId>0000173112-S0000</AccountId>
            <TransactionType>Debit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>0.00</Amount>
            <Memo>TEST                                      </Memo>
          </Transaction>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000173112-S0012</AccountId>
          <AccountFiName>SECOND CHECKING               </AccountFiName>
          <AccountType>checking</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>40.00</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

          <Transaction>
            <TransactionId>61</TransactionId>
            <AccountId>0000173112-S0012</AccountId>
            <TransactionType>Debit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>-5.00</Amount>
            <Memo>NONBLANK</Memo>
          </Transaction>
          <Transaction>
            <TransactionId>62</TransactionId>
            <AccountId>0000173112-S0012</AccountId>
            <TransactionType>Debit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>-5.00</Amount>
            <Memo>NINTENDO</Memo>
          </Transaction>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000173112-S0017</AccountId>
          <AccountFiName>ADVANTAGE CHECKING            </AccountFiName>
          <AccountType>checking</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>0.00</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000173112-S0021</AccountId>
          <AccountFiName>TRADITIONAL IRA SHARE         </AccountFiName>
          <AccountType>investment</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>0.00</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000173112-S0029</AccountId>
          <AccountFiName>ROTH IRA SHARE                </AccountFiName>
          <AccountType>investment</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>90.00</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

          <Transaction>
            <TransactionId>63</TransactionId>
            <AccountId>0000173112-S0029</AccountId>
            <TransactionType>Credit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>10.00</Amount>
            <Memo>TRANSACTION MEMO NONBLANK</Memo>
          </Transaction>
          <Transaction>
            <TransactionId>64</TransactionId>
            <AccountId>0000173112-S0029</AccountId>
            <TransactionType>Debit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>0.00</Amount>
            <Memo>TEST                                      </Memo>
          </Transaction>
          <Transaction>
            <TransactionId>65</TransactionId>
            <AccountId>0000173112-S0029</AccountId>
            <TransactionType>Debit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>-10.00</Amount>
            <Memo>TRANSACTION MEMO NONBLANK</Memo>
          </Transaction>
          <Transaction>
            <TransactionId>74</TransactionId>
            <AccountId>0000173112-S0029</AccountId>
            <TransactionType>Credit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>100.00</Amount>
            <Memo>TRANSACTION MEMO NONBLANK</Memo>
          </Transaction>
          <Transaction>
            <TransactionId>75</TransactionId>
            <AccountId>0000173112-S0029</AccountId>
            <TransactionType>Debit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>0.00</Amount>
            <Memo>Check Received 100.00                     </Memo>
          </Transaction>
          <Transaction>
            <TransactionId>78</TransactionId>
            <AccountId>0000173112-S0029</AccountId>
            <TransactionType>Debit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>-10.00</Amount>
            <Memo>TRANSACTION MEMO NONBLANK</Memo>
          </Transaction>
          <Transaction>
            <TransactionId>79</TransactionId>
            <AccountId>0000173112-S0029</AccountId>
            <TransactionType>Debit</TransactionType>
            <PostedDate>2016-07-07</PostedDate>
            <OriginationDate>2016-07-07</OriginationDate>
            <Amount>0.00</Amount>
            <Memo>Check 00 0 Disbursed 10.00                </Memo>
          </Transaction>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000173112-S0122</AccountId>
          <AccountFiName>COVERDELL ESA SHARE           </AccountFiName>
          <AccountType></AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Current</BalanceType>
              <BalanceAmount>0.00</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000173112-L0092</AccountId>
          <AccountFiName>HOME EQUITY PRIME             </AccountFiName>
          <AccountType>loan</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Outstanding</BalanceType>
              <BalanceAmount>25.00</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

      </Account>
      <Account>
        <Details>
          <PartnerCustomerId>322079353</PartnerCustomerId>
          <AccountId>0000173112-L0095</AccountId>
          <AccountFiName>HOME EQUITY PRIME             </AccountFiName>
          <AccountType>loan</AccountType>
          <AccountBalances>
            <AccountBalance>
              <BalanceType>Outstanding</BalanceType>
              <BalanceAmount>25.00</BalanceAmount>
              <CurrencyCode>USD</CurrencyCode>
            </AccountBalance>
          </AccountBalances>
        </Details>

      </Account>
  </User>
</Users>

Reporting Errors

Error Response

<Errors>
  <Error>
    <Code>500</Code>
    <Description>
      Unable to find account 12345 for member 99999.
    </Description>
  </Error>
  ...
</Errors>

If an API request cannot be processed, please include any applicable errors by code and/or description in the body of the response.

General reused types

Account Types

AccountType Description
checking Checking Account
savings Savings Account
cards Credit Card Account
autos Auto Loan
home Mortgage
loan Other Loan type account not listed specifically
asset Other Asset type account not listed specifically
investment Investment Accounts (positions/transactions will not be created)

Action Types

ActionType
New
Update
Delete

Push Data Source

Geezeo provides robust transaction enrichment for partner and aggregated accounts. The first step in any implementation is connecting the platform to a data source for all partner accounts.

Geezeo provides a Push Data Source mechanism for integrations that require real-time data enrichment.

Geezeo’s Push Data Source allows partners to asynchronously submit transactions via a batch JSON interface.

Each request submitted to the Push Data Source should provide a callback URL where the results will be returned to. Once the Geezeo platform has completed processing the batch, the platform will call back the URL with the results.

All requests to and from the Push Data Source will use JWT tokens to validate authenticity as well as forced TLS with certificate validation.

Initial queuing requests will also respond with a unique token for that batch. That token will also be on the response. That token should be used to tracking and troubleshooting.

All data provided to this interface is considered an upsert and will replace the data in the Geezeo platform.

Callback URL

Requests should include a callback URL. Once the Geezeo platform has completed processing the submitted batch, the platform will call the callback URL with the payload in the POST body.

The request will come with a JWT token to ensure authenticity.

Push Batch of Data

Sample request

{
  "callback": "https://url.to.post.to/",
  "users": [
    {
      "partner_customer_id": "1234",
      "first_name": "Firstname",
      "last_name": "Lastname",
      "email": "flastname@geezeo.com",
      "zip_code": "06000",
      "accounts": [
          {
            "reference_id": "13579",
            "name": "Savings",
            "account_type": "savings",
            "account_balances": [
              {
                "balance_type": "current",
                "balance_amount": "2591.71"
              }
            ],
            "transactions": [
              {
                "balance": "-112.03",
                "memo": "DUNKINDONUTS*100094",
                "posted_at": "2009-03-19T11:40:50-04:00",
                "reference_id": "4567",
                "transaction_type": "debit"
              }
            ]
          }
      ]
    }
  ]
}

Sample response

{
  "batch_id": "4403f9f7-0b0b-484e-b73b-bf948ecd2b9f"
}

Sample callback

{
  "batch" : {
    "batch_id": "4403f9f7-0b0b-484e-b73b-bf948ecd2b9f",
    "status": "success",
    "totals": {
      "users": {
        "total": 1,
        "success": 1,
        "error": 0
      },
      "accounts" : {
        "total": 1,
        "success": 1,
        "error": 0
      },
      "transactions" : {
        "total": 1,
        "success": 1,
        "error": 0
      }
    }
  },
  "users": [
    {
      "user_id": "10000001",
      "partner_customer_id": "1234",
      "first_name": "Firstname",
      "last_name": "Lastname",
      "email": "flastname@geezeo.com",
      "zip_code": "06000",
      "accounts": [
          {
            "account_id": "20000001",
            "reference_id": "13579",
            "name": "Savings",
            "account_type": "savings",
            "account_balances": [
              {
                "balance_type": "current",
                "balance_amount": "2591.71"
              }
            ],
            "transactions": [
              {
                "transaction_id": "2009_03_19_4567_20000001",
                "balance": "-112.03",
                "memo": "DUNKINDONUTS*100094",
                "posted_at": "2009-03-19T11:40:50-04:00",
                "reference_id": "4567",
                "transaction_type": "Debit",
                "original_name": "DUNKINDONUTS*100094",
                "nickname": "Dunkin Donuts",
                "tags": [
                  {
                    "name": "Coffee",
                    "balance": 112.03
                  }
                ]
              }
            ]
          }
      ]
    }
  ]
}

Create or update one or more users, accounts, or transactions in bulk.

PUT /api/v2/batches

Status Codes

Status Description
200 OK returned when a batch was submitted successfully
400 Bad Request returned when no batch content is provided
401 Not Authorized returned when invalid credentials are provided

User Properties

Property Required Description
partner_customer_id Yes Identifier of the user, unique to the submitter
first_name Yes First name/given name of the user
last_name Yes Last name/family name of the user
email Yes Email address
zip_code No ZIP code
accounts No Array of accounts, as defined in Account Properties

User Result Properties

On callback, additional properties may be returned in a user.

Property Description
user_id Geezeo user identifier

Account Properties

Property Required Description
reference_id Yes Identifier of the account, unique to the submitter
name No Account name, as defined by the user
account_type Yes Account type; allowed values are below
account_balances Yes Array of account balances, as defined in Account Balance Properties
transactions No Array of transactions, as defined in Transaction Properties

Account Result Properties

On callback, additional properties may be returned in an account.

Property Description
account_id Geezeo account identifier

Account Balance Properties

Property Required Description
balance_type Yes Type of balance; allowed values are 'current', 'available'
balance_amount Yes Amount

Transaction Properties

Property Required Description
balance Yes Amount of the transaction, where credits are positive and debits are negative
check_number No If the transaction was a check, a check number
hide No If the transaction should be hidden from the user interface, set to true
memo No Transaction memo
nickname No The user-assigned transaction memo
posted_at Yes An ISO-8601 date (YYYY-MM-DD) or date-time (YYYY-MM-DDTHH:MM:SS-00:00) that the transaction was posted
reference_id Yes Unique identifier of the transaction within the account
transaction_type No Set to "credit" or "debit", and must match how "amount" is signed

Transaction Result Properties

On callback, additional properties may be returned in a transaction.

Property Description
tags List of tags that have been assigned to the transaction, with corresponding amounts that will total the amount of the transaction
transaction_id Geezeo transaction identifier
original_name The transaction memo, exactly as it was provided to the API

Account Types

Account Type
asset
autos
bill
cards
cd
certificates
checking
creditline
home
investment
loan
money_market
savings
student_loans

Get Batch Status

curl -X "GET" "http://partner.url/api/v2/batches/{batch_id}" --header 'Authorization: Bearer x'

GET /api/v2/batches/{batch_id}

Response payload

{
  "batch_id": "4403f9f7-0b0b-484e-b73b-bf948ecd2b9f",
  "status": "partial-success",
  "totals": {
    "users": {
      "total": 1,
      "success": 1,
      "error": 0
    },
    "accounts": {
      "total": 1,
      "success": 1,
      "error": 0
    },
    "transactions": {
      "total": 2,
      "success": 1,
      "error": 1
    }
  },
  "errors": [
    {
      "context": "transaction",
      "identifier": "4567",
      "message": "Missing posted_at"
    }
  ]
}

Retrieve the status of a submitted push batch.

Status Codes

Status Description
200 OK returned when a a batch was found and returned successfully
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when the requested batch was not found

Batch Data Properties

Property Description
batch_id Batch ID
status Status of processing; allowed values are 'new', 'processing', 'success', 'partial-success', or 'error'. A batch that is ingested, but with some data errors, will come back as 'partial-success'. A batch that is ingested without errors will come back as 'success'.
totals Object containing statuses of the three data types allowed in a push request; 'users', 'accounts', and 'transactions'
errors List of errors, if any

Totals Properties

Property Description
total Number of items received in the batch
success Number of items processed successfully
error Number of items processed with errors

Error Description Properties

Property Description
context The object type where the error was found; allowed values are 'user', 'account', or 'transaction'
identifier The provided identifier for that object, 'partner_customer_id' for user, 'reference_id' for 'account' or 'transaction'
message Description of the error

Get Completed Batch Content

curl -X "GET" "http://partner.url/api/v2/batches/{batch_id}/content" --header 'Authorization: Bearer x'

GET /api/v2/batches/{batch_id}/content

Response payload

{
  "batch" : {
    "batch_id": "4403f9f7-0b0b-484e-b73b-bf948ecd2b9f",
    "status": "success",
    "totals": {
      "users": {
        "total": 1,
        "success": 1,
        "error": 0
      },
      "accounts" : {
        "total": 1,
        "success": 1,
        "error": 0
      },
      "transactions" : {
        "total": 1,
        "success": 1,
        "error": 0
      }
    }
  },
  "users": [
    {
      "user_id": "10000001",
      "partner_customer_id": "1234",
      "first_name": "Firstname",
      "last_name": "Lastname",
      "email": "flastname@geezeo.com",
      "zip_code": "06000",
      "accounts": [
          {
            "account_id": "20000001",
            "reference_id": "13579",
            "name": "Savings",
            "account_type": "savings",
            "account_balances": [
              {
                "balance_type": "current",
                "balance_amount": "2591.71"
              }
            ],
            "transactions": [
              {
                "transaction_id": "2009_03_19_4567_20000001",
                "balance": "-112.03",
                "memo": "DUNKINDONUTS*100094",
                "posted_at": "2009-03-19T11:40:50-04:00",
                "reference_id": "4567",
                "transaction_type": "Debit",
                "original_name": "DUNKINDONUTS*100094",
                "nickname": "Dunkin Donuts",
                "tags": [
                  {
                    "name": "Coffee",
                    "balance": 112.03
                  }
                ]
              }
            ]
          }
      ]
    }
  ]
}

Retrieve the callback content of a submitted push batch.

Status Codes

Status Description
200 OK returned when a a batch was found and returned successfully
401 Not Authorized returned when invalid credentials are provided
404 Not Found returned when the requested batch was not found or the batch has not completed processing

Properties

Property Description
batch Batch data
users User data structure

Batch Data Properties

Property Description
batch_id Batch ID
status Status of processing; allowed values are 'new', 'processing', 'success', 'partial-success', or 'error'. A batch that is ingested, but with some data errors, will come back as 'partial-success'. A batch that is ingested without errors will come back as 'success'.
totals Object containing statuses of the three data types allowed in a push request; 'users', 'accounts', and 'transactions'
errors List of errors, if any

Totals Properties

Property Description
total Number of items received in the batch
success Number of items processed successfully
error Number of items processed with errors

Error Description Properties

Property Description
context The object type where the error was found; allowed values are 'user', 'account', or 'transaction'
identifier The provided identifier for that object, 'partner_customer_id' for user, 'reference_id' for 'account' or 'transaction'
message Description of the error

User Properties

Property Required Description
user_id Yes Geezeo user identifier
partner_customer_id Yes Identifier of the user, unique to the submitter
first_name Yes First name/given name of the user
last_name Yes Last name/family name of the user
email Yes Email address
zip_code No ZIP code
accounts No Array of accounts, as defined in Account Properties

Account Properties

Property Required Description
account_id Yes Geezeo account identifier
reference_id Yes Identifier of the account, unique to the submitter
name No Account name, as defined by the user
account_type Yes Account type; allowed values are above
account_balances Yes Array of account balances, as defined in Account Balance Properties
transactions No Array of transactions, as defined in Transaction Properties

Account Balance Properties

Property Required Description
balance_type Yes Type of balance; allowed values are 'current', 'available'
balance_amount Yes Amount

Transaction Properties

Property Required Description
transaction_id Yes Geezeo transaction identifier
balance Yes Amount of the transaction, where credits are positive and debits are negative
check_number No If the transaction was a check, a check number
hide No If the transaction should be hidden from the user interface, set to true
memo No Transaction memo
nickname No The user-assigned transaction memo
original_name Yes The transaction memo, exactly as it was provided to the API
posted_at Yes An ISO-8601 date (YYYY-MM-DD) or date-time (YYYY-MM-DDTHH:MM:SS-00:00) that the transaction was posted
reference_id Yes Unique identifier of the transaction within the account
tags No List of tags that have been assigned to the transaction, with corresponding amounts that will total the amount of the transaction
transaction_type No Set to "credit" or "debit", and must match how "amount" is signed

Platform SDKs

Geezeo is creating platform specific SDK's to accelerate integrating our platform features into OLBs, mobile, support, or any other use case that you can envision.

These SDKs will follow best practices for the specific platform, and should significantly lower the barrier of entry for any integration project.

JWT

The token

The Geezeo API supports JWT for authentication.

A JWT is broken up into three parts:

Decrypted JWT example


"Header:"
{
  "alg": "HS256",
  "typ": "JWT"
}
"Payload:"
{
  "sub": "123",
  "aud": "fi.mybankhq.com",
  "iat": 1467038374,
  "exp": 1467039374,
  "iss": "1203"
}
"Signature:"

  HMACSHA256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
  "1e44a00ceafb5b8b0da5"
  )

Encrypted JWT example

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjMiLCJhdWQiOiJmaS5teWJhbmtocS5jb20iLCJpYXQiOjE0NjcwMzgzNzQsImV4cCI6MTQ2NzAzOTM3NCwiaXNzIjoiMTIwMyJ9.FCu8RexBWr9qEOVbnJzjefhCg9oKU9yz02r30SYGVRw

1) Header

A JWT header contains two claims: alg and typ.

Claim Purpose Example
alg The hashtag algorithm that is being used for encryption HS256
typ A field used to let the receiving end know this is a JWT jwt

2) Payload

Geezeo will implement the following reserved and public claims:

Claim Purpose Example
iss Partner's SSO ID 1
sub Case-sensitive string that uniquely identifies the partner customer ID of the end user in the partner's system abc123
aud Single case-sensitive Fully Qualified Domain Name of the partner's Geezeo PFM fi.mybankhq.com
exp This claim sets the exact time, in seconds from epoch, from which this JWT is considered invalid. No more than 24 hours past the iat value. This value should be a number and not a strong. 1467038374
iat A number representing a specific time, in seconds from epoch, at which the JWT was issued. Number must be in the past and no more than 24 hours ago. This value should be a number and not a strong. 1467038374

3) Signature

The third and final part of a JWT is the signature. To create the signature you take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.

Implementation

The partner will generate a JWT via a Geezeo SDK (or via their own means) and either attach it as an Authorization Bearer, or pass that to the initialization of the Client SDK. All platform SDK’s have a JWT generation method added to them. Please work with your Geezeo implementation team to get the appropriate platform SDK.

Troubleshooting

During implementation testing you may run in to some issues displaying tiles. A common cause for this issue is an invalid JWT.

1) Grab the JWT On the page where a tile should be displaying get the JWT. It should be located in the authorization header or the partner can provide it. With any rendered tile you can look in your browser's developer tools to find API calls to the Geezeo platform. These calls will have an authorization header with the value of the JWT being used.

2) JWT Validation Once you have the JWT paste it over at the JWT Debugger. The token should break apart into human readable json. Check the data to make sure it is line with how Geezeo uses JWT. You can use this Epoch Converter to make sure the 'iat' and 'exp' values are both a number within our platform rules. From here take the API key provided for that partner and paste it into the lower right hand side of the Debugger page. If the token was created correctly it should validate.

3) JWT Test Go to our Codepen JWT Tester and navigate through the Spending Wheel example and paste in the JWT and uncomment the 'geezeo.SetAuth()' line. This page has a correctly implemented and barebones spending wheel. As long as your JWT is correct the spending wheel will render with the proper data.

.net SDK

The Geezeo .net SDK is available here

For access to Geezeo's github provide your github username to your Geezeo contact and we will give you access.

The .net SDK provides :

For more information, please contact your account representative and ask for an introduction to the .net SDK!

JWT

The Geezeo API supports JWT for authentication. Each SDK has a method to generate a JWT token. The JWT token should be passed into the .net SDK via the setAuth method.

Using JWT

To initialize the SDK using JWT pass apiKey, hostName, userId, partnerId, as well as "true" to tell the SDK to use JWT for all calls.

initialize the .NET SDK with JWT

var sdk = new SDK(apiKey, hostName, userId, partnerId,true);

You can also control the time to live (TTL) in seconds of JWT by passing in additional parameter as a string

var sdk = new SDK(apiKey, hostName, userId, partnerId,true,"3600");

Passing in the User Id and storing the API Key and Hostname in the App.config file as shown below.

var sdk = new SDK(userId,true);

App.config

<appSettings>
       <add key="apiKey" value="KEY GOES HERE" />
       <add key="hostName" value="HOST GOES HERE" />
   <add key="partnerId" value="PARTNER ID GOES HERE" />
   <add key="timeToLive" value="VALUE IN SECONDS GOES HERE" />
</appSettings>

Generating JWT

sdk.generateJWT(partnerId,partnerCustomerId,domain, ttl, secret)

Aggregation SDKs

Geezeo is building a series of aggregation SDKs to provide a simplified, future proof implementation of Geezeo aggregation.

Aggregation SDKs are meant to run on a partners platform, and provide a simplified interface to Geezeo aggregation.

The aggregation SDKs provide methods for searching for Financial Institutions, or Geezeo can publish a list of Financial Institutions nightly for consumption.

Python SDK

Installing the library

Install from pip

pip install geezeo

The Geezeo SDK is available via pip.

Using the library

These items will be provided during implementation

import geezeo

sdk = geezeo.SDK(api_key, user_id, url)

Raises an UnauthorizedError if api_key is incorrect.

Raises a DoesNotExistError if the user_id doesn’t correspond to an actual user.

Returns an SDK instance.

Python SDK for the Geezeo API.

The use of this package starts with an SDK instance, which is created with the authentication information required by Geezeo’s web API.

Argument Description
api_key Authentication key for the partner institution using this SDK. If api_key is invalid, the constructor will raise an UnauthorizedError.
user_id Shared identifier for the scoped user.
url URL for the partner institution’s web site.

Once you have an instance the SDK has methods to handle all of the operations of aggregation.


sdk.get_featured_institutions()

Returns a list of AuthPrompt objects.

Partners can maintain a list of featured institutions. This method will return that list in the specified order.

Contact support to change the list of featured institutions for a partner.

get_all_institutions


sdk.get_all_institutions(get_all_pages=false, page=1)

Returns a PagedResults object.

Partners can request a list institutions supported by the Geezeo aggregation platform.

Argument Description
get_all_pages The SDK will aggregate all pages into one. WARNING this call will take a LONG time.
page A specific page to retrieve.

search_institutions


sdk.search_institutions(search_string, scope=None, page=None)

Returns a PagedResults object.

Partners can search for an Institutions based on name, url, or both.

Argument Description
search_string The search term to search for.
scope An optional argument to limit the search to the name or url. Accepted values are ['name', 'url']
page Optional page number, since the results are paginated. Defaults to the first page.

get_institution


sdk.get_institution(id)

Returns an AuthPrompt object.

Partners can load the AuthPrompt for a specific institution.

Argument Description
id The id of the institution

authenticate


sdk.authenticate(submit_key, parameters)

Raises a MFARequiredError if MFA is required.

Returns an AggregatedInstitution object.

To execute a specific AuthPrompt request, submit it's submit_key with the list of parameters that were provided.

All parameters should now have a populated value field.

Argument Description
submit_key An AuthPrompt has a submit_key that is used to submit authentication requests.
parameters An AuthPrompt has an array of parameters that should be displayed to the user. This argument needs to be a dictionary with a key for the key attribute of each of those parameter objects.

change_authentication


sdk.change_authentication(submit_key, parameters)

Raises a DoesNotExistError if account is not found.

Raises a MFARequiredError if MFA is required.

Returns an AggregatedInstitution object.

To change a user's credentials a partner must first get an AuthPrompt and submit_key. Accounts expose fi.id. This id can be used to get an AuthPrompt from get_institution.

Argument Description
account_id The id of the account that will be updated.
parameters The login_parameters from an AuthPrompt

AuthPrompt

Property Description
id Identifier for this financial institution.
name Name of this financial institution.
url url of this financial institution.
login_parameters A list of AuthParameter objects for authentication.
submit_key The key for this auth prompt. This key should be used when submitting this AuthPrompt for authentication.
Operation Description
to_json Create a json representation.

AggregatedInstitution

Property Description
id Identifier for this financial institution.
name Name of this financial institution.
url url of this financial institution.
accounts An array of accounts for this institution.
Operation Description
to_json Create a json representation.

AuthParameter

Property Description
key String that identifies this parameter uniquely among the parameters for the parent prompt.
caption String challenge for the user, e.g. "What is your favorite color?".
type String description of the information to be provided. If this is “password”, the field should be masked.
max_length Maximum length that the answer for the parameter can have (int).
value The value parameter should be provided by the end user. It will default to None.
Operation Description
to_json Create a json representation.

PagedResults

Property Description
auth_prompts A list of auth_prompts that match the criteria.
current_page Current page of the results.
total_pages Total number of pages that match the criteria.

MFARequiredError

Property Description
AuthPrompt An additional AuthPrompt for the user to complete. There may be multiple in succession.

UnauthorizedError

DoesNotExistError

NetworkError

Java SDK

Installing the library

The Geezeo SDK is available via

Maven Central or Source code

Using the library

These items will be provided during implementation

import com.geezeo.sdk.Sdk

public class Main {
    public static void main(String[] args) {
        Sdk sdk = new Sdk(apiKey, userId, url);

        // ...
    }
}

Returns an SDK instance.

Java SDK for the Geezeo API.

The use of this package starts with an Sdk instance, which is created with the authentication information required by Geezeo’s web API.

The package also comes with a build.sbt file. If you have scala and sbt installed, typing sbt console in the project folder will load a REPL with access to the SDK.

Once you have an instance the SDK has methods to handle basic operations, and its Aggregation object can be used to access aggregation functionality.


generateJwt(apiKey, userId, url, partnerId, domain, secret)

generateJwt(apiKey, userId, url, partnerId, domain, secret, ttl)

GenerateJwt

The Geezeo API supports JWT for authentication. Each SDK has a method to generate a JWT token. The JWT token should be passed into the javascript SDK via the setAuth method.

There are two ways to generate JWT using the Java SDK, both of which are a public static function. Both methods are almost identical with the only difference being one uses the default ttl time (3600 seconds) while the other allows for a custom ttl.

Aggregation objects

An Aggregation object, like an Sdk object, is primarily a home for methods - specifically, those involving the third-party aggregation services. Aggregation objects are not instantiated directly, but retrieved from Sdk objects.

Aggregation.getFeaturedInstitutions


agg = sdk.getAggregation();
sdk.getFeaturedInstitutions();

Returns a Collection of AuthPrompt objects.

Partners can maintain a list of featured institutions. This method will return that list in the specified order.

Contact support to change the list of featured institutions for a partner.

Aggregation.searchInstitutions


agg = sdk.getAggregation();

// scope, if present, is an Aggregation.SearchScope value
// (either NAME or URL)

agg.searchInstitutions(searchString);
agg.searchInstitutions(searchString, scope);
agg.searchInstitutions(searchString, page);
agg.searchInstitutions(searchString, scope, page);

Returns a PagedResults object.

Partners can search for an Institutions based on name, url, or both.

Argument Description
search_string The search term to search for.
scope (Aggregation.SearchScope) An optional argument to limit the search to the name or url.
page Optional page number, since the results are paginated. Defaults to the first page.

Aggregation.getInstitution


agg.getInstitution(id)

Returns an AuthPrompt object.

Partners can load the AuthPrompt for a specific institution.

Argument Description
id The id of the institution

Aggregation.authenticate


sdk.authenticate(submitKey, parameters)
sdk.authenticate(authPrompt, parameters)

Raises a MfaException if MFA is required.

Returns an AuthenticatedInstitution object.

To execute a specific AuthPrompt request, submit its submitKey with the list of parameters that were provided.

All parameters should now have a populated value field.

Argument Description
submitKey or prompt An AuthPrompt has a submitKey that is used to submit authentication requests. Either this submit key, or the prompt itself, can be used as the first argument.
parameters An AuthPrompt has an array of parameters that should be displayed to the user. This argument needs to be a dictionary with a key for the key attribute of each of those parameter objects.

Aggregation.updateAuthentication


sdk.updateAuthentication(submitKey, parameters)
sdk.updateAuthentication(authPrompt, parameters)

Raises a DoesNotExistError if account is not found.

Raises a MfaException if MFA is required.

Returns an AuthenticatedInstitution object.

To change a user's credentials a partner must first get an AuthPrompt and submitKey. Accounts expose fi.id. This id can be used to get an AuthPrompt from getInstitution.

Argument Description
account_id The id of the account that will be updated.
parameters The login_parameters from an AuthPrompt

aggregation.dto.AuthPrompt

Method Description
getId Identifier for this financial institution.
getName Name of this financial institution.
getParameters A Collection of AuthParameter objects for authentication.
getSubmitKey The key for this auth prompt. This key should be used when submitting this AuthPrompt for authentication.
toJson Create a stringified JSON representation.
toJsonTree Create a GSON-compatible JSON AST from this object.

aggregation.dto.AuthenticatedInstitution

Operation Description
getId Identifier for this financial institution.
getName Name of this financial institution.
getAccounts A Collection of Accounts for this institution.
toJson Create a stringified JSON representation.
toJsonTree Create a GSON-compatible JSON AST from this object.

aggregation.dto.AuthParameter

Operation Description
getKey String that identifies this parameter uniquely among the parameters for the parent prompt.
getCaption String challenge for the user, e.g. "What is your favorite color?".
getType String description of the information to be provided. If this is “password”, the field should be masked.
getMaxLength Maximum length that the answer for the parameter can have (int).
toJson Create a stringified JSON representation.
toJsonTree Create a GSON-compatible JSON AST from this object.

dto.PagedResults

Operation Description
getCurrentPage Current page of the results (starting with 1).
getData A Collection of paginated objects.
getLastPage Total number of pages that match the criteria.
hasMore Boolean, true if there are more pages, false otherwise.
toJson Create a stringified JSON representation.
toJsonTree Create a GSON-compatible JSON AST from this object.

dto.Account

Operation Description
getAccountType Get a string describing the nature of this account.
getId Get a unique string identifier for this account.
getName Get the name of this account.
toJson Create a stringified JSON representation.
toJsonTree Create a GSON-compatible JSON AST from this object.

Exceptions

aggregation.exceptions.MfaException

Operation Description
getPrompt An additional AuthPrompt for the user to complete. There may be multiple in succession.
getMessage Get the user-readable message associated with this MFA request.
toJson Create a stringified JSON representation.
toJsonTree Create a GSON-compatible JSON AST from this object.

aggregation.exceptions.InvalidSubmitKeyException

The user has submitted a mangled string submit key that does not correspond to valid data.

exceptions.GeezeoException

Parent for all of the following exceptions. This is a very general umbrella class for when you just want to catch exceptions that occur while using the SDK.

exceptions.NetworkException

Somehting has gone wrong while attempting to communicate with the server. No response has been received. The server was not found, the connection timed out, etc.

exceptions.PendingAccountDeletionException

One or more exceptions occurred while attempting to delete pending accounts.

Operation Description
getErrors() A Collection of GeezeoExceptions thrown during pending account deletion.

exceptions.ApiException

The server has reported an error. Parent class for all of the following exceptions.

exceptions.ServerException

The server encountered an internal error. Triggered by HTTP 500.

exceptions.DoesNotExistException

A requested resource was not found. Triggered by HTTP 404.

exceptions.UnauthorizedException

The user is not authenticated at the appropriate level. Triggered by HTTP 401.

CORS

Geezeo uses CORS (Cross Origin Resource Sharing) to whitelist domains for an extra layer of security. You can read up more on the specifics of CORS here.

Here is a quick rundown of how CORS works:

Suppose your local development testing environment domain is http://domain.dev/. When your browser calls Geezeo's service with an HTTP OPTIONS verb asking for allowed hosts, and our platform will respond with a list of allowed hosts. If the host in your address bar is not in that list, your browser will manufacture a 4xx.

Geezeo maintains a list of CORS white label domains. Please provide a list of hostnames for your development and testing environments to your Geezeo contact and we will add them to our whitelist.