Overview

Introduction

Welcome to Greenback! The Greenback Platform allows you to build modern web and mobile applications with high-def itemized financial data.

High-def itemized financial data includes all the details of a transaction that are missing on a typical credit card or bank feed. Rather than just an amount of money and a brief description, high-def itemized data includes the line items, vendor/supplier information, postal addresses, tax (sales, VAT, GST), payment instrument details, transaction type, invoice number, and more. In a nutshell, the fully detailed data that represents a GAAP-compliant financial transaction. Greenback provides a common data model and developer-friendly method to sync or extract data using various methods.

APIs

Let's get acquainted with the Greenback products.

Vision

Convert images and documents into structured transaction data.

Mailbox

Convert RFC822 emails, including attachments and embedded links into structured transaction data.

Connect

The complete transaction platform with support for rich connected accounts and Mailbox connectivity.

Account

Sync, view and manage connected and non-connected accounts.

Transaction

Search, view, and manage rich detailed transaction data.

Export

Export transactions to general ledgers.

You’ll find comprehensive information for integrating with the Greenback API endpoints and graphical UI plugin components. For assistance please contact our support group by email at support@greenback.com.

The Greenback API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Software Kits and Demos

The Greenback GitHub page will include any open source implementations and demos of the Greenback platform, data models, and APIs.

For example, here is a simple demo Android application of the Greenback Platform and our Vision API to extract receipt data from a photo taken by a mobile phone camera.

Get Access Token

Interested in our API? Contact our Business Development team via ping@greenback.com for more information.

Authentication

All requests to the Greenback API must include an access token (API key) in order to be authenticated. Any number of access tokens can be generated by Greenback that are associated with your overall organization and are unique to your account.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Once you have acquired your access token (API key) you simply add it to your request as an HTTP Authorization header with a Bearer scope. For example, if your access token was 123456789 then to send a request via curl.

Test Authentication

curl -v -H "Authorization: Bearer 123456789" https://api.greenback.com/v2/users/me

HTTP Request

GET /v2/users/me HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 123456789
User-Agent: curl/7.47.0
Accept: */*

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Hosts

Greenback supports two environments: Production and Sandbox. The two environments are entirely separate at Greenback and your access tokens (API keys) will only be valid in the environment they were issued in.

Versioning

Greenback versions every API endpoint. If major changes are released, and they break backwards compatibility, Greenback will ship new versioned API endpoints, while maintaining previous versions to allow for smooth migrations.

Within a released version (e.g. v2), Greenback may add new fields and enum values. It's critical in your implementation to ignore unknown properties while processing our JSON to maintain compatibility with our API over time. Most major JSON library across languages supports this concept. For example, in Java, the popular Jackson library will ignore unknown properties with a simple annotation at the top of your class file.

Many JSON processing libraries will NOT easily support unknown "enum" values. Please ensure your JSON library supports mapping unknown enum values or perhaps consider processing enums as strings.

Sample Java Class

@JsonIgnoreProperties(ignoreUnknown = true)
public class Response {

    private String error;

    public String getError() {
        return error;
    }

    public void setError(String error) {
        this.error = error;
    }

}

Responses

All Greenback endpoints that return JSON-encoded data use a common outer response object. We recommend you use the same strategy in your implementation and use a single base object or class to represent any Greenback response.

JSON Response

{
  "error" : { ... },
  "pagination" : { ... },
  "value" : { ... },
  "values" : [ ... ]
}

The Response Object

Errors

Greenback uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a vision request failed, etc.). Codes in the 5xx range indicate an error with Greenback's servers (these are rare).

In addition to the HTTP status code, the API returns a JSON-encoded response with a top-level error object with detailed information.

HTTP Response

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 114
Date: Fri, 19 Apr 2019 01:49:43 GMT

{
  "error" : {
    "code" : 10002,
    "message" : "Access token rejected",
    "category" : "unauthorized"
  }
}

The Error Object

See our reference Java implementation for more details.

Pagination

Many top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list transactions, list connects, etc. These list API methods share a common structure, where the first page of results will return a common pagination object that includes information about the entire result as well as an optional next field.

JSON Response

{
  "pagination" : {
    "count" : 100,
    "total_count" : 3116,
    "next" : "o-100,tc-3116"
  }
}

If the next field is present that means there is another page of data available. The next value will become the cursor field on your next request, and so on.

Some endpoints can paginate in both directions (forward and reverse). For these endpoints, the pagination object will contain next initially and also include previous and current fields as you fetch various pages. If these values are present, then the page can support both fetching data in either direction.

JSON Response

{
  "pagination" : {
    "count" : 100,
    "total_count" : 3116,
    "previous" : "o-100,tc-3116",
    "next" : "o-300,tc-3116",
    "current" : "o-200,tc-3116"
  }
}

The Pagination Object

See our reference Java implementation for more details.

Use Cases

The Greenback platform is a powerful pre-accounting system to help connect, sync, and manage financial transactions. There are a number of use cases in how businesses leverage our platform, here are just a few along with the various endpoints and steps they would entail.

Greenback for Business Custom Transactions

Greenback for Business user needs to integrate and post transactions from a source Greenback does not yet support, or perhaps from their own internal system. They want to leverage Greenback's other Software-as-a-Service features such as other integrations, reporting, exports, and automations such as Transforms.

1. Contact Greenback Sales and request a Personal Access Token. If your billing subscription allows API access then a Personal Access Token will allow you to utilize most aspects of our published API, such as manual transactions.

2. Create a shoebox account to store and organize the custom Transactions you need to create and update. If you are a Greenback for Business user, and you're logged into our web application, please visit Connect a Shoebox to create a Shoebox account.

3. Note the account_id of your new account in your browser URL such as "https://www.greenback.com/app/accounts/xyz123456" which means the account_id is xyz123456.

4. Use the Create Transaction endpoint, using the shoebox account_id to create custom Transactions.

5. Login to Greenback for Business and interact with your Transactions as though Greenback had synced them directly from one of its supported integrations. All features are available with these transactions such as Transforms, Advanced Mappings, Exports, etc.

Financial Institution Receipt or Invoice Extraction

Financial institutions (e.g. bank or credit card providers) can leverage Greenback to build a user-friendly interface to allow uploads of receipts, invoices, or bills in various document formats for extraction.

1. Use the Create Vision endpoint to upload photos or PDFs for processing. Greenback will process the photo, extract detailed financial transaction data, and return a response within seconds.

2. Use the Create Message endpoint to upload RFC822 mime messages (emails) for processing. Greenback will process the email and extract detailed financial transaction data and return a response within seconds.

3. Leverage the rich extracted information for receipt matching or other features within your own application.

Financial Institution Exports to Accounting

Financial institutions (e.g. bank or credit card providers) can leverage Greenback to build a user-friendly interface to directly reconcile and export financial data from a bank or credit card portal to an accounting system such as QuickBooks or Xero.

1. Exports are stateful operations, which means the transaction you want to export must exist on Greenback prior to starting the export process. Use the Create Account endpoint to directly create a shoebox account type. Due to enforcing uniqueness of transactions per-account, it is a best practice to create an account to mirror the account of data you are trying to export.

2. Create and update transactions on Greenback that represent the data you want to export. Use the Create Transaction and Update Transaction endpoints as needed.

3. Use the Get Transaction Export Intent endpoint to present your user with matches or the export form to help answer questions required to complete the export.

4. Use the Get Transaction Export to help present information about the state of what was exported.

Common Types

The Greenback API uses many of the same types across endpoints.

DateTime

Many API resources include a DateTime type as one or more fields. Greenback supports standard ISO date and time formatting of this type, typically in the UTC (Zulu) timezone such as "2021-04-06T01:02:03.456Z".

For example, in Java, the java.time.Instant type is an excellent choice to represent a Greenback DateTime.

Accounting Method Enum

Represents an accounting method in various objects within Greenback. See our reference Java implementation for more details.

The Processing Status Enum

Many API resources have a status field which represents the processing status of that resource. This is common across all endpoints. See our reference Java implementation for more details.

JSON Response

{
  "status" : "error",
  "error" : {
    "code" : 10000,
    "message" : "Access token rejected",
    "category" : "unauthorized"
  }
}

The Attachment Object

See our reference Java implementation for more details.

The Attachment Object

{
  "rel_id": "sto_jYOeO",
  "name": "Message.pdf",
  "media_type": "application/pdf",
  "reference_id": "msg_dbaa5f52-e0df-4a12-9c00-56811f4a939b_pdf",
  "why": "original",
  "size": 182464,
  "md5": "e882c89c98e502969722110a2adf0128"
}

The Email Address Object

See our reference Java implementation for more details.

The Email Address Object

{
  "name": "Henry Ford",
  "address": "henry@example.com"
}

The Line Item Object

Represents a line item on Greenback. See our reference Java implementation for more details.

The Line Item Object

{
  "grn": "it:asin:B0087RVIOU",
  "name": "Sugar In The Raw 200 Count",
  "uri": "https://www.amazon.com/gp/product/B0087RVIOU/ref=ppx_od_dt_b_asin_title_s00?ie=UTF8&psc=1",
  "quantity": 2,
  "unit_price": 16.47,
  "amount": 32.94
}

Item GRN

A Greenback Resource Number to identify what item was sold or purchased. The format follows a URN syntax of it:namespace:value. It will always start with it which indicates it is an item GRN. The namespace helps identify what kind value is present.

The Contact Object

Represents a party or entity that is a party to a transaction (e.g. the buyer or seller). See our reference Java implementation for more details.

{
  "id" : "lBOp8mArOd",
  "name" : "Domino's Pizza",
  "domain" : "dominos.com"
}

The Form Object

Represents a Form (user input needed) on Greenback. See our reference Java implementation for more details.

The Form Object

{
  "title": "Enter your 6th & Washington credentials",
  "fields": [
    {
      "type": "text",
      "name": "username",
      "label": "Username",
      "required": true
    },
    {
      "type": "password",
      "name": "password",
      "label": "Password",
      "required": true
    },
    {
      "type": "button",
      "name": "submit",
      "label": "Connect"
    }
  ]
}

The Form Field Object

Represents an input within a Form. See our reference Java implementation for more details.

The Form Select Option Object

Represents an option for a select field within a Form. See our reference Java implementation for more details.

The Postal Address Object

Represents a physical, geographic place on Greenback. Usually is a standard postal address, but can sometimes simply be a lat/long, or raw text describing the location. See our reference Java implementation for more details.

The Postal Address Object

{
  "name": "Greenback, Inc.",
  "line1": "307 W 6th St",
  "line2": "Suite 209",
  "city": "Royal Oak",
  "region_code": "MI",
  "postal_code": "48067",
  "country_code": "us"
}

Or

{
  "location": {
    "lat": 40.76745,
    "lon": -73.86358
  },
  "raw_address": "Grand Central Pkwy, New York, NY"
}

Vision

The Greenback Vision API uses advanced AI (artificial intelligence), natural language, and machine learning techniques, trained on its massive and proprietary transaction dataset, to simplify the extraction of structured transaction data from real world photos and documents.

With the Greenback Vision API you can quickly and easily build web or mobile applications that can convert images (PNG/JPG) or documents (Microsoft Word/HTML/PDF) that contain receipts, bills, invoices, statements, and other types into structured and annotated data. The API is designed to process documents in near real-time, generally averaging around 1-3 seconds for industry-leading accuracy and speed. Greenback will return the recognized text, bounding boxes, annotations, and structured data. To get started, simply upload an image or document to the Greenback Vision API endpoint.

Vision Examples (JPEG, PNG)

Vision Examples (PDF)

Vision Examples (Microsoft Word)

Vision Types

The Vision Object

The Vision Object

{
  "id" : "kg1DMpNKXA",
  "name" : "receipt.png",
  "status" : "success",
  "created_at" : "2019-04-02T14:25:49.299Z",
  "updated_at" : "2019-04-02T14:25:49.421Z",
  "attachments" : [ {
    "rel_id" : "rs_1tydV5YSlh9bOS8fVHt9k",
    "media_type" : "image/png",
    "size" : 29566,
    "md5" : "ff12c0a4a15f17049c09054f52f14be3"
  } ],
  "error" : { ... },
  "transaction_matcher" : {
    "transacted_ats" : [ {
      "start" : "2018-12-14T01:00:00.000Z",
      "end" : "2018-12-16T23:00:00.000Z"
    }, {
      "start" : "2019-01-14T01:00:00.000Z",
      "end" : "2019-01-16T23:00:00.000Z"
    } ],
    "amounts" : [ {
      "value" : 15.0
    } ]
  },
  "annotations" : {
    "full_text" : {
      "text" : "Greenback, Inc.  Receipt\nPaid to\nPaid by\nReceipt number\n2574-8279\nGreenback, Inc.\nHenry Ford\nInvoice number\n6C95218-0012\n307 W 6th St, Suite 208\nDate paid\nDecember 15, 2018\nRoyal Oak MI 48067\nPayment method: Visa – 7990\nUnited States\n+1 248-952-8217\nsupport@greenback.com\n$15.00 paid on December 15, 2018\nDescription\nQty\nUnit price\nAmount\nDEC 15, 2018 – JAN 15, 2019\nEarly Adopter Plan\n1\n$15.00\n$15.00\nSubtotal\n$15.00\nAmount paid\n$15.00\nQuestions? Contact Greenback, Inc. at support@greenback.com or call at +1 248-952-8217 or take a survey @ www.greenback.com/survey :-)\n2574-8279 – Page 1 of 1\n"
    },
    "temporals" : [ {
      "text" : "12/01/2018",
      "date" : "2018-12-01",
      "granularity" : "day"
    }, {
      "text" : "JAN 15, 2019",
      "date" : "2019-01-15",
      "granularity" : "day"
    } ],
    "moneys" : [ {
      "text" : "$15.00",
      "symbol" : "$",
      "amount" : 15.0,
      "currency_code" : "USD"
    } ],
    "tenders" : [ {
      "method" : "visa",
      "ends_with" : "7990"
    } ],
    "urls" : [ {
      "text" : "www.greenback.com/survey",
      "url" : "http://www.greenback.com/survey",
      "domain" : "greenback.com"
    } ],
    "emails" : [ {
      "text" : "support@greenback.com",
      "domain" : "greenback.com"
    } ]
  }
}

The vision object within the Greenback API. See our reference Java implementation for more details.

The Transaction Matcher Object

See our reference Java implementation for more details.

The Annotations Object

See our reference Java implementation for more details.

The Full Text Annotation Object

See our reference Java implementation for more details.

The Temporal Annotation Object

See our reference Java implementation for more details.

The Money Annotation Object

See our reference Java implementation for more details.

The Tender Annotation Object

See our reference Java implementation for more details.

The URL Annotation Object

See our reference Java implementation for more details.

The Email Annotation Object

See our reference Java implementation for more details.

Create Vision

Upload an image (JPEG/PNG) or document (PDF) to create a new vision request. Both synchronous and asynchronous processing of your request is supported.

In synchronous mode Greenback will accept your request, process it, and return a result in a single step. In asynchronous mode Greenback will accept your request and return a unique identifier. The unique identifier can be used with the Get Vision endpoint to poll for updated status.

The HTTP request consists of multipart form data with a file parameter named file.

Send Request (synchronous mode)

curl -v -X POST -H 'Authorization: Bearer 1234567890' -F 'file=@receipt.png' https://api.greenback.com/v2/visions

HTTP Request

POST /v2/visions HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Content-Length: 29604
Content-Type: multipart/form-data; boundary=b22c56d1-607a-4c13-abce-02c671633123

--b22c56d1-607a-4c13-abce-02c671633123
Content-Disposition: form-data; name="file"; filename="receipt.png"
Content-Type: application/octet-stream
Content-Length: 29566

<binary data>

--b22c56d1-607a-4c13-abce-02c671633123--

JSON Response (synchronous mode)

{
  "value" : {
    "id" : "kg1DMpNKXA",
    "name" : "receipt.png",
    "status" : "success",
    "created_at" : "2019-04-02T14:25:49.299Z",
    "updated_at" : "2019-04-02T14:25:49.421Z",
    "attachments" : [ {
      "rel_id" : "rs_1tydV5YSlh9bOS8fVHt9k",
      "media_type" : "image/png",
      "size" : 29566,
      "md5" : "ff12c0a4a15f17049c09054f52f14be3"
    } ],
    "transaction_matcher" : { ... },
    "annotations" : { ... }
  }
}

Or JSON Response (asynchronous mode)

{
  "value" : {
    "id" : "kg1DMpNKXA",
    "name" : "receipt.png",
    "status" : "processing",
    "created_at" : "2019-04-02T14:25:49.299Z",
    "updated_at" : "2019-04-02T14:25:49.421Z",
    "attachments" : [ {
      "rel_id" : "rs_1tydV5YSlh9bOS8fVHt9k",
      "media_type" : "image/png",
      "size" : 29566,
      "md5" : "ff12c0a4a15f17049c09054f52f14be3"
    } ]
  }
}

Endpoint

POST /v2/visions?async={async}

Request

Standard multipart form data with a multipart/form-data content type. The image or document will be uploaded as the file parameter.

Response

A JSON-encoded response is returned with either an error or a Vision object. See the vision object for more details.

Get Vision

Get a Vision object by its unique identifier.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/visions/kg1DMpNKXA

HTTP Request

GET /v2/visions/kg1DMpNKXA HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: application/json

JSON Response (synchronous mode)

{
  "value" : {
    "id" : "kg1DMpNKXA",
    "name" : "receipt.png",
    "status" : "success",
    "created_at" : "2019-04-02T14:25:49.299Z",
    "updated_at" : "2019-04-02T14:25:49.421Z",
    "attachments" : [ {
      "rel_id" : "rs_1tydV5YSlh9bOS8fVHt9k",
      "media_type" : "image/png",
      "size" : 29566,
      "md5" : "ff12c0a4a15f17049c09054f52f14be3"
    } ],
    "transaction_matcher" : { ... },
    "annotations" : { ... }
  }
}

Endpoint

GET /v2/visions/{vision_id}

Request

Standard GET request will contain an empty body.

Response

A JSON-encoded response is returned with either an error or a Vision object. See the vision object for more details.

Get Vision Attachment

Get the original document that was submitted as the Vision object. This attachment can be accessed by its relative unique identifier.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/visions/kg1DMpNKXA/attachments/rs_1tydV5YSlh9bOS8fVHt9k

HTTP Request

GET /v2/visions/kg1DMpNKXA/attachments/rs_1tydV5YSlh9bOS8fVHt9k HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: */*
If-None-Match: 123456789456879874556fdfdf

HTTP Response

200 OK
Date: Fri, 1 Apr 2019 18:39:11 GMT
Content-Type: image/png
ETag: "ff12c0a4a15f17049c09054f52f14be3"
Content-Length: 29566

<binary data here>

Endpoint

GET /v2/visions/{vision_id}/attachments/{attachment_id}

Request

Standard GET request will contain an empty body.

Response

The binary image or document.

Get Vision Rasterized Image

Get a rasterized image of the Vision object. If the original document was already a rasterized image (e.g. PNG or JPEG) then the response will usually return that image data. If the original document was not originally rasterized (e.g. a PDF) then the response will return a rasterized (rendered) version of that document. The width and height of the rasterized image will match the dimensions used for annotating and processing of the Vision request.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/visions/kg1DMpNKXA/rasterized

HTTP Request

GET /v2/visions/kg1DMpNKXA/rasterized HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: */*

HTTP Response

200 OK
Date: Fri, 1 Apr 2019 18:39:11 GMT
Content-Type: image/png
Content-Length: 29566

<binary data here>

Endpoint

GET /v2/visions/{vision_id}/rasterized

Request

Standard GET request will contain an empty body.

Response

The binary image or document.

Get Vision Annotated Image

Get an annotated image of the Vision object. The response will be an SVG (image/svg+xml) image with multiple layers representing the image-layer and annotation-layer layers as well as optionally the symbol-layer and text-layer if your application is permitted to request them.

You can embed this SVG into an HTML document and utilize standard CSS styling for customizing how it looks as well as listen for events (e.g. hovers). Since we expect this SVG to be possibly directly included as part of an HTML document, the id of all elements are prefixed with gbvl- for layers, gbva- for annotations, gbvs- for symbols, and gbvt- for texts.

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 702 1262" version="1.1">
  <defs>
    <style type="text/css"><![CDATA[#gbvl-annotation-layer .annotation {fill: #33ff00; fill-opacity: 0.2; stroke: #33ff00; stroke-opacity: 0.2; stroke-width: 2.0;}]]></style>
  </defs>
  <g id="gbvl-image-layer" data-layer="image">
    <image x="0" y="0" width="702" height="1262" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUh..."/>
  </g>
  <g id="gbvl-annotation-layer" data-layer="annotation">
    <rect id="gbva-0-0" class="annotation url" x="214" y="1171" width="237" height="31"/>
    <rect id="gbva-0-1" class="annotation phone" x="324" y="111" width="186" height="35"/>
    <rect id="gbva-0-2" class="annotation money" x="517" y="860" width="75" height="35"/>
    <rect id="gbva-0-3" class="annotation money" x="520" y="885" width="71" height="39"/>
    <rect id="gbva-0-4" class="annotation money" x="508" y="912" width="84" height="42"/>
    <rect id="gbva-0-9" class="annotation money" x="498" y="387" width="67" height="30"/>
    <rect id="gbva-0-10" class="annotation money" x="496" y="604" width="71" height="30"/>
    <rect id="gbva-0-23" class="annotation money" x="484" y="688" width="83" height="29"/>
    <rect id="gbva-0-24" class="annotation money" x="484" y="769" width="81" height="26"/>
    <rect id="gbva-0-25" class="annotation place" x="357" y="88" width="115" height="34"/>
    <rect id="gbva-0-26" class="annotation temporal" x="233" y="174" width="75" height="24"/>
    <rect id="gbva-0-27" class="annotation temporal" x="360" y="175" width="74" height="24"/>
    <rect id="gbva-0-28" class="annotation temporal" x="57" y="1048" width="252" height="34"/>
  </g>
</svg>

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/visions/kg1DMpNKXA/annotated

HTTP Request

GET /v2/visions/kg1DMpNKXA/annotated HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: */*

HTTP Response

200 OK
Date: Fri, 1 Apr 2019 18:39:11 GMT
Content-Type: image/svg+xml
Content-Length: 29566

<binary data here>

Endpoint

GET /v2/visions/{vision_id}/annotated

Request

Standard GET request will contain an empty body.

Response

The binary image or document.

Mailbox

The Greenback Mailbox API uses advanced AI (artificial intelligence), natural language, and machine learning techniques to simplify the extraction and display of structured data from real world emails and attachments.

With the Greenback Mailbox API, you can quickly convert original or forwarded RFC822 emails, including attachments and embedded URLs into structured transaction data. Greenback leverages its Vision and Connect technologies to power the core of its Mailbox API, then combines that with information extracted from both inside and outside the email to build the richest and most-complete representation of the data. The API is designed to process emails in near real-time, generally averaging around 2-6 seconds for industry-leading accuracy and speed. Additional Mailbox APIs help power compelling and secure display of original or forwarded email content inside your own product. To get started, simply upload the email to the Greenback Mailbox API endpoint.

Mailbox Examples (RFC822)

Quoted Emails (Forwards, Replies, etc.)

Greenback uses specialized and natural language processing to parse and recognize quoted email content such as when a user forwards or replies to an email. This support extends across even multiple forwards or replies. The quoted content and headers are useful to improve the accuracy of recognition and user-friendly display of email content. The Message object on the Greenback platform will include both the original and any quoted messages, along with their recognized properties. Some endpoints will optionally let you request either the unquoted or quoted versions when rendering HTML or PDFs.

By default, Greenback will prefer the innermost, quoted content when extracting structured transaction data, generating original PDFs, and more. This generally produces the most accurate results and beautiful user-friendly display.

Mailbox Types

The Message Object

The Message Object

{
  "id" : "xa7qYR61K8",
  "reference_id" : "4e562e56-6d49-448b-8b70-c3886479ed33",
  "status" : "success",
  "posted_at" : "2018-08-27T22:25:36.000Z",
  "created_at" : "2019-05-20T05:01:51.137Z",
  "updated_at" : "2019-05-20T05:01:55.184Z",
  "flags" : [ "converted" ],
  "size" : 60054,
  "subject" : "Fwd: Receipt from Mr. Broast Rosemont",
  "snippet" : "Receipt for $17.08 at Mr. Broast Rosemont on Aug 27 2018 at 5:25 PM. Square automatically sends receipts to the email address you used at any Square seller. Learn more Mr. Broast Rosemont How was your",
  "full_text" : "... text of email and any attachments ...",
  "quoted" : [ {
    "subject" : "Receipt from Mr. Broast Rosemont",
    "from" : {
      "name" : "Mr. Broast Rosemont via Square",
      "address" : "broast@reply2.squareup.com"
    },
    "to" : [ {
      "address" : "henry@example.com"
    } ],
    "posted_at" : "2018-12-10T13:20:00.000Z"
  } ],
  "from" : {
    "name" : "Henry Ford",
    "address" : "henry@example.com"
  },
  "to" : [ {
    "address" : "receipts@example.com"
  } ],
  "reply_to" : [ {
    "name" : "Henry Ford",
    "address" : "henry@example.com"
  } ],
  "attachments" : [ {
    "rel_id" : "rs_1tydV5YSlh9bOS8fVHt9k",
    "media_type" : "image/png",
    "size" : 29566,
    "md5" : "ff12c0a4a15f17049c09054f52f14be3"
  } ],
  "transactions" : [ {
    "id" : "RJwaz6aEAW",
    "type" : "purchase",
    "currency_code" : "usd",
    "reference_id" : "ar76blmRglPvfopGz1na08nuMF",
    "account_id" : "RYj10MDEao",
    "contact_id" : "rMOGneoBKW",
    "transacted_at" : "2018-08-28T00:25:00.000Z",
    "created_at" : "2019-05-20T05:01:55.177Z",
    "updated_at" : "2019-05-20T05:01:55.184Z",
    "flags" : [ "converted" ],
    "attributes" : {
      "message_reference_id" : "4e562e56-6d49-448b-8b70-c3886479ed33"
    },
    "attachments" : [ {
      "reference_id" : "msg_4e562e56-6d49-448b-8b70-c3886479ed33_pdf",
      "rel_id" : "sto_1nJ8Nj",
      "name" : "Message.pdf",
      "media_type" : "application/pdf",
      "why" : "original",
      "size" : 100990,
      "md5" : "78948a92f36ec5e73e2e69fb61eee979"
    } ],
    "store_address" : {
      "location" : {
        "lat" : 41.994,
        "lon" : -87.876
      },
      "raw_address" : "Mr. Broast Rosemont\n7104 N Manheim Rd\nRosemont, IL 60018"
    },
    "items" : [ {
      "name" : "3 PC Tender Meal",
      "description" : "Dipped in BBQ sauce",
      "quantity" : 1.0,
      "unit_price" : 5.0
    }, {
      "name" : "Beef Sandwich (Gyro Cheese Burger Meal)",
      "quantity" : 1.0,
      "unit_price" : 10.49
    } ],
    "payments" : [ {
      "method" : "credit_card",
      "network" : "visa",
      "ends_with" : "1234"
    } ],
    "totals" : {
      "sub" : 15.49,
      "tax" : 1.59,
      "items" : [ {
        "type" : "tax",
        "name" : "Sales Tax",
        "amount" : 1.59
      } ],
      "grand" : 17.08
    },
    "contact" : {
      "id" : "rMOGneoBKW",
      "name" : "Mr. Broast Rosemont",
      "account_id" : "RYj10MDEao"
    }
  } ]
}

The Message object within the Greenback API. See our reference Java implementation for more details.

The Quoted Message Object

The Quoted Message Object

{
  "posted_at" : "2018-08-27T22:25:36.000Z",
  "subject" : "Fwd: Receipt from Mr. Broast Rosemont",
  "from" : {
    "name" : "Henry Ford",
    "address" : "henry@example.com"
  },
  "to" : [ {
    "address" : "receipts@example.com"
  } ],
  "reply_to" : [ {
    "name" : "Henry Ford",
    "address" : "henry@example.com"
  } ]
}

The Quoted Message object within the Greenback API. See our reference Java implementation for more details.

Create Message

Upload a message (RFC822 compliant email) to create a new mailbox request. Asynchronous processing of your request is supported. Greenback will accept your request and return a unique identifier. The unique identifier can be used with the Get Message endpoint to poll for updated status.

Processing every email is a multistep process on the Greenback platform. The message object will receive updates as steps are completed. It is designed this way to enable you to display the message in your product before it is fully processed. Once the email is processed, you can then use its transactions array for extracted receipts, bills, invoices, and other structured data.

The HTTP request consists of multipart form data with a file parameter named file.

Send Request (synchronous mode)

curl -v -X POST -H 'Authorization: Bearer 1234567890' -F 'file=@email.msg' https://api.greenback.com/v2/messages

HTTP Request

POST /v2/messages HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Content-Length: 29604
Content-Type: multipart/form-data; boundary=b22c56d1-607a-4c13-abce-02c671633123

--b22c56d1-607a-4c13-abce-02c671633123
Content-Disposition: form-data; name="file"; filename="email.msg"
Content-Type: application/octet-stream
Content-Length: 29566

<binary data>

--b22c56d1-607a-4c13-abce-02c671633123--

JSON Response (synchronous mode)

{
  "value" : {
    "id" : "p3qg3VEqMe",
    "reference_id" : "6ce9e332-d4e2-4f35-8d71-6c8b64790e6a",
    "status" : "pending",
    "posted_at" : "2018-11-27T23:08:49.000Z",
    "created_at" : "2019-05-21T05:01:05.665Z",
    "updated_at" : "2019-05-21T05:01:05.667Z",
    "size" : 231654,
    "subject" : "[Personal] Your Tuesday evening trip with Uber"
  }
}

Endpoint

POST /v2/messages

No query parameters.

Request

Standard multipart form data with a multipart/form-data content type. The RFC822 email message will be uploaded as the file parameter.

Response

A JSON-encoded response is returned with either an error or a Message object. See the message object for more details.

Get Message

Get a Message object by its unique identifier. You will want to continue to poll for changes if the status is pending or processing since that means the processing of this message is not yet finalized.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/messages/kg1DMpNKXA

HTTP Request

GET /v2/messages/kg1DMpNKXA HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: application/json

JSON Response (synchronous mode)

{
  "value" : {
    "id" : "xa7qYR61K8",
    "reference_id" : "4e562e56-6d49-448b-8b70-c3886479ed33",
    "status" : "success",
    "posted_at" : "2018-08-27T22:25:36.000Z",
    "created_at" : "2019-05-20T05:01:51.137Z",
    "updated_at" : "2019-05-20T05:01:55.184Z",
    "flags" : [ "converted" ],
    "size" : 60054,
    "subject" : "Fwd: Receipt from Mr. Broast Rosemont",
    "snippet" : "Receipt for $17.08 at Mr. Broast Rosemont on Aug 27 2018 at 5:25 PM. Square automatically sends receipts to the email address you used at any Square seller. Learn more Mr. Broast Rosemont How was your",
    "quoted" : [ {
      "subject" : "Receipt from Mr. Broast Rosemont",
      "from" : {
        "name" : "Mr. Broast Rosemont via Square",
        "address" : "broast@reply2.squareup.com"
      },
      "to" : [ {
        "address" : "henry@example.com"
      } ],
      "posted_at" : "2018-12-10T13:20:00.000Z"
    } ],
    "from" : {
      "name" : "Henry Ford",
      "address" : "henry@example.com"
    },
    "to" : [ {
      "address" : "receipts@example.com"
    } ],
    "reply_to" : [ {
      "name" : "Henry Ford",
      "address" : "henry@example.com"
    } ],
    "attachments" : [ {
      "rel_id" : "rs_1tydV5YSlh9bOS8fVHt9k",
      "media_type" : "image/png",
      "size" : 29566,
      "md5" : "ff12c0a4a15f17049c09054f52f14be3"
    } ],
    "transactions" : [ { ... } ]
  }
}

Endpoint

GET /v2/messages/{message_id}

Request

Standard GET request will contain an empty body.

Response

A JSON-encoded response is returned with either an error or a message_id object. See the message object for more details.

Get Message Attachment

Get the attachment of a Message object by its relative unique identifier.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/messages/kg1DMpNKXA/attachments/rs_1tydV5YSlh9bOS8fVHt9k

HTTP Request

GET /v2/messages/kg1DMpNKXA/attachments/rs_1tydV5YSlh9bOS8fVHt9k HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: */*
If-None-Match: 123456789456879874556fdfdf

HTTP Response

200 OK
Date: Fri, 1 Apr 2019 18:39:11 GMT
Content-Type: image/png
ETag: "ff12c0a4a15f17049c09054f52f14be3"
Content-Length: 29566

<binary data here>

Endpoint

GET /v2/messages/{message_id}/attachments/{attachment_id}

Request

Standard GET request will contain an empty body.

Response

The binary image or document.

Get Message HTML

Get an HTML (partial or complete) document that is ready for embedding inside another HTML document or rendering on its own. The HTML will be sanitized of javascript, inline css, and other potentially unsafe elements or attributes. If embeddable, then the outermost element will be a div element, while non-embeddable will be a standard html element. If the original email was text-only (no HTML part) then an HTML-ready version of that text will be returned here.

If the email represents one or more quoted emails (e.g. a forward) and Greenback was able to recognize and extract that quoted content, then you can optionally request the innermost unquoted content is returned.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/messages/kg1DMpNKXA/html

HTTP Request

GET /v2/messages/kg1DMpNKXA/html HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: */*

HTTP Response

200 OK
Date: Fri, 1 Apr 2019 18:39:11 GMT
Content-Type: text/html; charset=uft-8
Content-Length: 29566

<html here>

Endpoint

GET /v2/messages/{message_id}/html?unquote={unquote}&embed={embed}

Request

Standard GET request will contain an empty body.

Response

The html (partial) document.

Get Message PDF

Get a PDF document of the rendered email message. The PDF will be similar to a user printing an email message and saving it as a PDF. The binary data returned by this method should be saved locally since every call to this method will render a fresh PDF.

If the email represents one or more quoted emails (e.g. a forward) and Greenback was able to recognize and extract that quoted content, then you can optionally request the innermost unquoted content is returned.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/messages/kg1DMpNKXA/pdf

HTTP Request

GET /v2/messages/kg1DMpNKXA/pdf HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: */*

HTTP Response

200 OK
Date: Fri, 1 Apr 2019 18:39:11 GMT
Content-Type: application/pdf
Content-Length: 29566

<binary data here>

Endpoint

GET /v2/messages/{message_id}/pdf?unquote={unquote}

Request

Standard GET request will contain an empty body.

Response

The PDF document of the rendered email message.

Connect

The Greenback Connect API will allow you to connect, authenticate and acquire transaction data directly from a growing list of supported integrations. The Connect API provides a unified method of connecting accounts using various authentication models including password-based web forms and oAuth redirect flows.

With the Connect API, you’ll be able to:

1. Connect accounts and using both password-based and oAuth-based authentication.
2. Handle additional Multi-factor authentication (2FA, Captcha, etc.) requests required from the account.
3. Reconnect accounts that experience authentication failures.
4. Sync transaction data from the account.

Connecting Accounts (Connect workflow)

The Connect API includes a Connect Intent object that indicates the current state of a connect request and what action your application will need to take next in order to finalize connecting the account.

The Connect API is designed this way for two reasons: (1) flexibility with how each upstream provider handles authentication, and (2) it promotes the use of switch statements to quickly handle all stages of the app implementation.

Greenback recommends handling the Connect Intent response from the various endpoints in a unified method in your app, with a switch statement to handle the action. You can view an example of how that may look in the code view (Java).

public Result handleConnect(ConnectIntent connectIntent) {
  switch (connectIntent.getAction()) {
    case OK: {
      // return an HTTP 200 OK response
    }
    case REDIRECT: {
      // use connectIntent.getRedirectUrl() to send a browser redirect back to user
    }
    case INPUT: {
      // use connectIntent.getInput() to render an HTML5 form for user to complete
    }
    case ISSUED: {
      // use connectIntent.getToken() to call Greenback 'Complete Connect' endpoint
      // to create a new Account, then you could either use the returned Account in that response
      // directly and display it to the user OR choose to use the returned Connect to recursively
      // call this method again to leverage the ERROR or COMPLETED handlers.
    }
    case PROFILE: {
      // multiple connected accounts were authorized by the user and one of them needs
      // to be selected by the user
      // use the connectIntent.getInput() to render an HTML5 form for user to complete
      // and then process the input form data and call the complete endpoint again
      // with the "parameters" field in the posted object
    }
    case CONFIRM: {
      // a potential issue was detected such as a duplicate account being connected, a different
      // account from what was being reconnected, and more.  The confirmation stage lets the user
      // confirm they want to proceed
      // use the connectIntent.getConfirm().getMessage() to help the user decide
      // the call the complete endpoint again with the "action" field in the posted object
    }
    case COMPLETED: {
      // use connectIntent.getAccountId() or connectIntent.getAccount() to know which Account was created
      // and display that to your app user
    }
    case ERROR: {
      // use connectIntent.getError() to render an error for user to see
    }
}

Typical Password Connect Flow

1. Display a list of available Connects to the user with the List Connects endpoint.

2. User selects a Connect. Display the Connect form to the user with the Begin Connect Intent endpoint. The Connect Intent object action will be returned to you with an action set to input.

3. User fills in form and submits it. Send the form data to the Authorize Connect Intent endpoint.

4. Greenback authorizes the connection and tokenizes the authentication data. Greenback returns a Connect Intent object with the action set to issued and an authorization token. Send the authorization token to the Complete Connect Intent endpoint. Greenback creates a new account, starts the first sync of that account, and returns the account in the response. If a potential issue is detected where the complete could connect a duplicate account or a reconnect would connect a different account from what was originally connected, then its possible you'll need to process the confirm action.

5. Poll the account periodically (e.g. every 2 seconds) to monitor the sync status and progress using the Get Account endpoint. Please note that you'll want to include the syncs value for the expand query parameter while getting the account, so that the syncs are included in the response.

6. Some Connects require some sort of 2-factor authentication for the user to answer. Typically, this only happens on the initial sync of an account. While polling the account for sync status, you'll want to check the input field of the Sync object for whether a value is present. If a value is present, the user must supply answers, otherwise the sync will timeout after 3-5 minutes of inactivity.

7. Once the account is synced, query the account for transactions with the List Transactions endpoint

Typical oAuth Connect Flow

1. Same as with password flow.

2. Same as with password flow.

3. Same as with password flow. Please note that most oAuth-based connects simply have empty forms that do not require any initial data to start. Your app will want to supply a complete_url value along with the parameters field, so that Greenback knows where to redirect back to once the oauth process has completed.

4. Greenback prepares for authorization and returns a redirect action back to your app along with a redirect_url value. You must allow the user to visit this url in a browser so that they can authorize the connection directly with the upstream provider.

5. User authorizes the connection. Upstream provider will then redirect back to Greenback. Greenback authorizes the connection and tokenizes the authentication data. Greenback then redirects the user back to your complete_url. Greenback will include a token parameter to your application endpoint.

6. Send the authorization token to the Complete Connect Intent endpoint. Greenback creates a new account, starts the first sync of that account, and returns the account in the response.

7. Same as with password flow steps 5 onward.

Reconnecting Accounts (Reconnect workflow)

If an account experiences an authentication failure, the user will need to be prompted to re-connect the account. Greenback offers an optimized flow for re-connecting an account. For example, if the account used the password flow for connecting, the username will be pre-populated on the INPUT stage form. Your app will want to call the Reconnect Account Intent endpoint.

Syncing Transactions from an Account

Once an account is connected and established, syncs need to be initiated for new data to be fetched from the source. By default, Greenback will begin the first, initial sync for each new Account in most cases. Syncs can also be triggered, on demand, by using the Create Account Sync endpoint.

Greenback is designed to potentially sync massive amounts of data that can take anywhere from seconds to hours to complete for a particular account. Only one sync can be pending on an Account at a time.

Syncs are also how authentication of an account is verified, 2-factor challenges are discovered, or other errors are uncovered that may need the user to help remedy. We suggest polling an Account on a frequent basis (every 2 to 3 seconds) when a sync is in-progress, so that these are relayed to your user in a timely fashion.

Testing Your Connect Workflow

Greenback includes a test e-commerce site https://www.6thandwashington.com as part of its platform to help test the connect flow, account syncing, and fetching of transactional data. To get started, visit https://www.6thandwashington.com/register and register for a free test account. Once registered, you can generate test purchases and generate the same kind of test data that Greenback can fetch from live integrations. Thus, by setting up the accounts you need, you can test invalid passwords or generate new transactions to validate your sync progress.

Most new applications are only permitted to connect to 6th & Washington during development. You can connect 6th & Washington by using any of the following connect labels in your application:

Connect Types

Connect Expands

The Connect Object

The Connect Object

{
  "id": "Zz532dXNWJ",
  "type": "merchant",
  "tags": [
    "expenses"
  ],
  "name": "Amazon.com",
  "label": "amazon",
  "state": "active",
  "logo_url": "https:\/\/www.greenback.com\/assets\/f\/logos\/amazon.com.svg",
  "contact_id": "lBOpD38eOd",
  "card" : {
    "description" : "Sync your personal or business expenses from Amazon.com.",
    "help_url" : "http://example.com/more-help"
  }
}

The Connect object within the Greenback API. See our reference Java implementation for more details.

The Connect Type Enum

See our reference Java implementation for more details.

The Connect Intent Object

The Connect Intent Object

{
  "token" : "7172jsjajC01-0ajayqmmss",
  "action" : "input",
  "connect_id" : "Zz532dXNWJ",
  "created_at" : "2021-04-06T05:35:24.368Z",
  "input" : {
    "title" : "Enter your Amazon.com credentials",
    "fields" : [ {
      "type" : "email",
      "name" : "username",
      "label" : "Email",
      "required" : true
    }, {
      "type" : "password",
      "name" : "password",
      "label" : "Password",
      "required" : true
    }, {
      "type" : "button",
      "name" : "submit",
      "label" : "Connect"
    } ]
  }
}

The Connect Intent object within the Greenback API. See our reference Java implementation for more details.

The Connect Intent Action Enum

See our reference Java implementation for more details.

The Connect Intent Confirm Object

The Connect Intent Confirm object within the Greenback API. See our reference Java implementation for more details.

The Connect Intent Complete Action Enum

See our reference Java implementation for more details.

List Connects

List all connects available on the Greenback platform. A subset of information is returned for each connect compared to the Get Connect endpoint which also allows you to request a card expansion which includes more information about a connect.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/connects

HTTP Request

GET /v2/connects HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: application/json

JSON Response (synchronous mode)

{
  "pagination": {
    "count": 38,
    "total_count": 38
  },
  "values": [
    {
      "id": "vVxwolN1xz",
      "type": "merchant",
      "tags": [
        "sales"
      ],
      "name": "Amazon Seller (North America)",
      "label": "amazon-seller-na",
      "state": "active",
      "logo_url": "https:\/\/www.greenback.com\/assets\/f\/logos\/sellercentral.amazon.com.svg"
    },
    {
      "id": "Zz532dXNWJ",
      "type": "merchant",
      "tags": [
        "expenses"
      ],
      "name": "Amazon.com",
      "label": "amazon",
      "state": "active",
      "logo_url": "https:\/\/www.greenback.com\/assets\/f\/logos\/amazon.com.svg",
      "contact_id": "lBOpD38eOd"
    },
    {
      "id": "KbWrVeQgWM",
      "type": "merchant",
      "tags": [
        "expenses"
      ],
      "name": "Best Buy",
      "label": "bestbuy",
      "state": "active",
      "logo_url": "https:\/\/www.greenback.com\/assets\/f\/logos\/bestbuy.com.svg",
      "contact_id": "me5NQmwPgn"
    },
    {
      "id": "lRxy6Kkw0k",
      "type": "merchant",
      "tags": [
        "sales",
        "expenses"
      ],
      "name": "eBay",
      "label": "ebay",
      "state": "active",
      "logo_url": "https:\/\/www.greenback.com\/assets\/f\/logos\/ebay.com.svg",
      "contact_id": "epOyv0eYgZ"
    },
    {
      "id": "1g0QKb9J5Z",
      "type": "merchant",
      "tags": [
        "sales",
        "expenses"
      ],
      "name": "Etsy",
      "label": "etsy",
      "state": "active",
      "logo_url": "https:\/\/www.greenback.com\/assets\/f\/logos\/etsy.com.svg",
      "contact_id": "VAOlQk0Dg9"
    },
    {
      "id": "3L0gJjVzxe",
      "type": "mailbox",
      "tags": [
        "email"
      ],
      "name": "Gmail",
      "label": "gmail",
      "state": "dev",
      "logo_url": "https:\/\/www.greenback.com\/assets\/f\/logos\/gmail.google.com.svg"
    },
    {
      "id": "3r063dJoWq",
      "type": "merchant",
      "tags": [
        "expenses"
      ],
      "name": "Home Depot",
      "label": "home-depot",
      "state": "active",
      "logo_url": "https:\/\/www.greenback.com\/assets\/f\/logos\/homedepot.com.svg",
      "contact_id": "aVKdRwLmg1"
    },
    {
      "id": "Gm0PMZ64Wj",
      "type": "merchant",
      "tags": [
        "sales"
      ],
      "name": "Shopify",
      "label": "shopify",
      "state": "active",
      "logo_url": "https:\/\/www.greenback.com\/assets\/f\/logos\/shopify.com.svg",
      "contact_id": "0NKjDZe8g4"
    },
    ... many more
  ]
}

Endpoint

GET /v2/connects?expands={expands}&limit={limit}&cursor={cursor}&labels={labels}&states={states}&types={types}&min_created_at={min_created_at}&max_created_at={max_created_at}&min_updated_at={min_updated_at}&max_updated_at={max_updated_at}

Request

Standard GET request will contain an empty body.

Response

A JSON-encoded response is returned with a paginated list of Connect objects. See pagination and the connect object for more details.

Get Connect

Get a connect object.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/connects/amazon

HTTP Request

GET /v2/connects/amazon HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: application/json

JSON Response (synchronous mode)

{
  "value" : {
    "id" : "Zz532dXNWJ",
    "type" : "merchant",
    "tags" : [ "expenses" ],
    "name" : "Amazon.com",
    "label" : "amazon",
    "state" : "active",
    "logo_url" : "https://www.greenback.com/assets/f/logos/amazon.com.svg",
    "contact_id" : "lBOpD38eOd",
    "created_at" : "2021-04-02T23:34:06.000Z",
    "updated_at" : "2021-04-02T23:34:06.000Z",
    "auth_strategy" : "default",
    "card" : {
      "description" : "Sync your personal or business expenses from Amazon.com.",
      "help_url" : "http://example.com/more-help"
    }
  }
}

Endpoint

GET /v2/connects/{connect_label}?expands={expands}

Request

Standard GET request will contain an empty body.

Response

A JSON-encoded response is returned with either an error or a Connect object. See the connect object for more details.

Begin Connect Intent

Begin connecting a new account. This method creates a new Connect Intent that will provide a token to be used throughout the connection process.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/connects/amazon/begin

HTTP Request

GET /v2/connects/amazon/begin HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: application/json

JSON Response (synchronous mode)

{
  "value" : {
    "token" : "S4Zq0IIFQbIVGAUBu7rnjPP3QMKyN6Zq",
    "connect_id" : "Zz532dXNWJ",
    "created_at" : "2021-04-06T05:31:36.866Z",
    "action" : "input",
    "input" : {
      "title" : "Enter your Amazon.com credentials",
      "fields" : [ {
        "type" : "email",
        "name" : "username",
        "label" : "Email",
        "required" : true
      }, {
        "type" : "password",
        "name" : "password",
        "label" : "Password",
        "required" : true
      }, {
        "type" : "button",
        "name" : "submit",
        "label" : "Connect"
      } ]
    },
    "connect" : {
      "id" : "Zz532dXNWJ",
      "type" : "merchant",
      "tags" : [ "expenses" ],
      "name" : "Amazon.com",
      "label" : "amazon",
      "state" : "active",
      "logo_url" : "https://www.greenback.com/assets/f/logos/amazon.com.svg",
      "contact_id" : "lBOpD38eOd",
      "created_at" : "2021-04-02T23:34:06.000Z",
      "updated_at" : "2021-04-02T23:34:06.000Z",
      "auth_strategy" : "default"
    }
  }
}

Endpoint

GET /v2/connects/{connect_label}/begin

Request

Standard GET request will contain an empty body.

Response

A JSON-encoded response is returned with either an error or a Connect Intent object. See the connect intent object for more details.

Reconnect Account Intent

Reconnect an existing account. This method creates a new Connect Intent that will provide a token to be used throughout the reconnection process.

Send Request

curl -v -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/accounts/Azyajzy1s/reconnect

HTTP Request

GET /v2/accounts/Azyajzy1s/reconnect HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Accept: application/json

JSON Response (synchronous mode)

{
  "value" : {
    "token" : "S4Zq0IIFQbIVGAUBu7rnjPP3QMKyN6Zq",
    "connect_id" : "Zz532dXNWJ",
    "account_id" : "Azyajzy1s",
    "created_at" : "2021-04-06T05:31:36.866Z",
    "action" : "input",
    "input" : {
      "title" : "Enter your Amazon.com credentials",
      "fields" : [ {
        "type" : "email",
        "name" : "username",
        "label" : "Email",
        "value" : "henry@example.com",
        "required" : true
      }, {
        "type" : "password",
        "name" : "password",
        "label" : "Password",
        "required" : true
      }, {
        "type" : "button",
        "name" : "submit",
        "label" : "Connect"
      } ]
    },
    "connect" : {
      "id" : "Zz532dXNWJ",
      "type" : "merchant",
      "tags" : [ "expenses" ],
      "name" : "Amazon.com",
      "label" : "amazon",
      "state" : "active",
      "logo_url" : "https://www.greenback.com/assets/f/logos/amazon.com.svg",
      "contact_id" : "lBOpD38eOd",
      "created_at" : "2021-04-02T23:34:06.000Z",
      "updated_at" : "2021-04-02T23:34:06.000Z",
      "auth_strategy" : "default"
    }
  }
}

Endpoint

GET /v2/accounts/{account_id}/reconnect

Request

Standard GET request will contain an empty body.

Response

A JSON-encoded response is returned with either an error or a Connect Intent object. See the connect intent object for more details.

Authorize Connect Intent

Authorize a connection by submitting form data and getting back the next step.

Send Request

curl -v -X POST -H 'Authorization: Bearer 1234567890' -H "Content-Type: application/json" -d '{ "parameters" : { "username": "henryford", "password": "test" } }' https://api.greenback.com/v2/connect_intents/S4Zq0IIFQbIVGAUBu7rnjPP3QMKyN6Zq

HTTP Request

POST /v2/connect_intents/lLkVlCrTENMcosgaSx44_R5-cb2ibUjS HTTP/1.1
Authorization: Bearer 1234567890
Content-Length: 62
Content-Type: application/json

{
  "parameters" : {
    "username": "henryford",
    "password": "test"
  }
}

JSON Response

{
  "value" : {
    "token" : "lLkVlCrTENMcosgaSx44_R5-cb2ibUjS",
    "connect_id" : "jyWa9nJpW1",
    "created_at" : "2021-04-06T14:48:58.266Z",
    "updated_at" : "2021-04-06T14:48:58.632Z",
    "action" : "issued",
    "connect" : {
      "id" : "jyWa9nJpW1",
      "type" : "merchant",
      "tags" : [ "expenses" ],
      "name" : "6th & Washington",
      "label" : "saw",
      "state" : "dev",
      "logo_url" : "https://www.greenback.com/assets/f/logos/6thandwashington.com.svg",
      "contact_id" : "rMOGqlnV5W",
      "created_at" : "2021-04-02T23:34:06.000Z",
      "updated_at" : "2021-04-02T23:34:06.000Z",
      "auth_strategy" : "default"
    }
  }
}

Endpoint

POST /v2/connect_intents/{token}

Request

A JSON-encoded request as the HTML request body.

Response

A JSON-encoded response is returned with the updated Connect Intent object. Depending on what type of connect process is used, it is possible for the intent returned to be another input (e.g. a required field is missing and the form needs to be resubmitted), a redirect is required, or the connect was issued and a token is available. See the connect intent object for more details.

Complete Connect Intent

Completes a connection by consuming the issued authorization token, creating a new account, and optionally starting the first sync. The authorization token can be consumed just once and can only be assigned to a single account.

Send Request

curl -v -X POST -H 'Authorization: Bearer 1234567890' https://api.greenback.com/v2/connect_intents/X2Kd5wlAD-dSXV8vRGa7ffZglw1U-g89/complete

HTTP Request

POST /v2/connect_intents/X2Kd5wlAD-dSXV8vRGa7ffZglw1U-g89/complete HTTP/1.1
Host: api.greenback.com
Authorization: Bearer 1234567890
Content-Length: 0
Content-Type: application/json

JSON Response

{
  "value" : {
    "token" : "X2Kd5wlAD-dSXV8vRGa7ffZglw1U-g89",
    "connect_id" : "jyWa9nJpW1",
    "account_id" : "5abB3ldPaP",
    "created_at" : "2021-04-06T14:55:20.028Z",
    "updated_at" : "2021-04-06T14:55:20.514Z",
    "completed_at" : "2021-04-06T14:55:20.514Z",
    "action" : "completed",
    "account" : {
      "id" : "5abB3ldPaP",
      "name" : "henryford",
      "user_id" : "3ByO7xK7Xq",
      "connect_id" : "jyWa9nJpW1",
      "type" : "merchant",
      "default_name" : "henryford",
      "reference_id" : "henryford",
      "connection_state" : "pending",
      "state" : "active",
      "consecutive_errors" : 0,
      "created_at" : "2021-04-06T14:55:20.512Z",
      "updated_at" : "2021-04-06T14:55:20.512Z"
    },
    "connect" : {
      "id" : "jyWa9nJpW1",
      "type" : "merchant",
      "tags" : [ "expenses" ],
      "name" : "6th & Washington",
      "label" : "saw",
      "state" : "dev",
      "logo_url" : "https://www.greenback.com/assets/f/logos/6thandwashington.com.svg",
      "contact_id" : "rMOGqlnV5W",
      "created_at" : "2021-04-02T23:34:06.000Z",
      "updated_at" : "2021-04-02T23:34:06.000Z",
      "auth_strategy" : "default"
    }
  }
}

Profile Action

Greenback will detect possible multiple accounts that can be connected during the completion process. Some connections support authenticating multiple accounts in a single authorization. For example, Xero accounting connections will authenticate the user and then allow you to access any accounting files that they are a member of. After a connect intent is issued by Xero, if multiple accounting files are detected, Greenback may need to prompt the user to select which one they want to connect. This results in a profile action, where the input field of the connect intent object will contain a form that needs to be completed.

JSON Response

{
  "value" : {
    "token" : "omJXh7Oks131jds_IdQt4jzNMCZwK8gy",
    "connect_id" : "jY5lJ3zV0O",
    "created_at" : "2021-04-06T16:09:45.560Z",
    "updated_at" : "2021-04-06T16:09:45.775Z",
    "action" : "profile",
    "input" : {
      "title" : "Which Xero account would you like to connect?",
      "fields" : [ {
        "type" : "select",
        "name" : "profile",
        "label" : "Account",
        "required" : true,
        "options" : [ {
          "value" : "",
          "text" : "Select an account"
        }, {
          "value" : "a49f3ce8-3764-439f-98ac-d6ed33c7eab6",
          "text" : "Henry Consulting LLC"
        }, {
          "value" : "6c18f354-9b97-4136-9ec8-38036a710ea9",
          "text" : "Kangaroo Ltd"
        }, {
          "value" : "dfad74ac-8d43-4afe-92f9-b4c13d913e22",
          "text" : "Widget, Inc."
        } ]
      } ]
    },
    "connect" : {
      "id" : "jY5lJ3zV0O",
      "type" : "accounting",
      "tags" : [ "accounting" ],
      "name" : "Xero",
      "label" : "xero",
      "state" : "active",
      "logo_url" : "https://www.greenback.com/assets/f/logos/xero.com.svg",
      "contact_id" : "8EOMqXJYOy",
      "created_at" : "2021-04-02T23:34:13.000Z",
      "updated_at" : "2021-04-02T23:34:13.000Z",
      "auth_strategy" : "default"
    }
  }
}

Confirm Action

Greenback will detect possible unsafe scenarios during the completion process. For example, a user may try to connect the same account twice, in which case Greenback will need confirmation that it is okay to proceed with completing the account. If your call to the Complete Connect endpoint results in a stage of CONFIRM you will need to relay the confirmation message to your user and then call the Complete Connect endpoint again with a query parameter of action which represents which action you'd like Greenback to take on your behalf.

Please note that you can preemptively provide the action to take to avoid this intermediate stage of completing an account.

JSON Response

{
  "value" : {
    "token" : "X2Kd5wlAD-dSXV8vRGa7ffZglw1U-g89",
    "connect_id" : "jyWa9nJpW1",
    "created_at" : "2021-04-06T14:55:20.028Z",
    "updated_at" : "2021-04-06T14:55:20.514Z",
    "completed_at" : "2021-04-06T14:55:20.514Z",
    "action" : "confirm",
    "confirm" : {
      "code" : 10121,
      "message" : "You are attempting to connect a new 6th & Washington account 'hford', but you already have an existing account with the same identity. Do you want to proceed with re-connecting your existing account 'hford'?"
    },
    "connect" : {
      "id" : "jyWa9nJpW1",
      "type" : "merchant",
      "tags" : [ "expenses" ],
      "name" : "6th & Washington",
      "label" : "saw",
      "state" : "dev",
      "logo_url" : "https://www.greenback.com/assets/f/logos/6thandwashington.com.svg",
      "contact_id" : "rMOGqlnV5W",
      "created_at" : "2021-04-02T23:34:06.000Z",
      "updated_at" : "2021-04-02T23:34:06.000Z",
      "auth_strategy" : "default"
    }
  }
}

Endpoint

POST /v2/connect_intents/{token}/complete

Request

Response

A JSON-encoded response is returned with the updated Connect Intent object, its authorization, and the newly connected account or a confirmation message. See the connect intent object and the account object for more details.

Account

The Account API is for managing connected accounts, triggering syncs, and fetching sync status.

Account Types

Account Expands

The Account Object

The Account Object

{
  "id": "exBKAywEad",
  "default_name": "henryford",
  "user_id": "kNgX7qmBzR",
  "connect_id": "jyWa9nJpW1",
  "type": "merchant",
  "connection_state": "pending",
  "state": "active",
  "consecutive_errors": 0,
  "created_at": "2020-01-27T19:49:40.381Z",
  "updated_at": "2020-01-27T19:49:40.524Z",
  "connect" : { ... },
  "syncs" : {
      "last" : {
        "id" : "gbDWlA6yG0",
        "triggered_by" : "web",
        "type" : "default",
        "reference_id" : "280efcf4-413e-11ea-a539-b97fd65bc3a9",
        "message" : "OK",
        "progress" : 1.0,
        "created_at" : "2020-01-27T19:49:40.519Z",
        "updated_at" : "2020-01-27T20:37:37.278Z"
      }
    }
}

See our reference Java implementation for more details.