NAV Navbar
Code

Overview

Introduction

Welcome to Greenback! Let's get acquainted with the Greenback products.

Vision
Vision

Convert images and documents into structured transaction data.

Mailbox
Mailbox

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

Connect
Connect

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

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.

API Endpoint Prefix
Vision /v2/visions
Mailbox /v2/messages
Connect /v2/connects

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 aquired 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.

Environment Host
Sandbox https://sandbox-api.greenback.com
Production https://api.greenback.com

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. It's critical in your implementation to ignore unknown properties while processing our JSON to maintain compatibility with our API over time. Every 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.

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

Field Type Description
error object If the request failed then this represents the error. See the error object for more details.
pagination object If the response is from a bulk/list endpoint then this object will help you to paginate thru the results. See the pagination object for more details.
value object If the response is from an endpoint that returns a single value. The value varies by the endpoint.
values object[] If the response is from a bulk/list endpoint this is an array of those values. The object within the array varies by the endpoint.

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

Field Type Description
code integer The underlying Greenback error code.
message string A user-friendly message describing what went wrong.
category string The class of errors to simplify error handling. For example, unauthorized represents any authentication failure. Values may include: bad_request, unauthorized, not_found_or_bad_request, forbidden, not_found, not_found_or_forbidden, internal_error, temporary_error

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

Field Type Description
count long The count of records in the current result (page) of data.
total_count long (Optional) The total count of records for the current search/query of data.
next string (Optional) The cursor value to fetch the next result (page) of data. All list/batch endpoints support forward fetching of data. The value of this text should be passed thru as-is since future versions of this string may be obfuscated.
previous string (Optional) The cursor value to fetch the previous result (page) of data. Not all list/batch endpoints support reverse fetching of data. The value of this text should be passed thru as-is since future versions of this string may be obfuscated.
current string (Optional) The cursor value of the current result (page) of data. The value of this text should be passed thru as-is since future versions of this string may be obfuscated.

Common Types

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

The Attachment Object

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"
}
Field Type Description
rel_id string The unique identifier of the attachment relative to the other attachments. This is not a globally unique identifier.
name string (Optional) The name of the attachment.
media_type string (Optional) The standard media (MIME) type of the attachment such as application/pdf or image/png.
reference_id string (Optional) A custom field for referencing something else.
why enum (Optional) The reason an attachment exists. Values include: original, vat_invoice, and extra
size long (Optional) The size (in bytes) of the attachment.
md5 string (Optional) The MD5 hash of the attachment.

The Email Address Object

The Email Address Object

{
  "name": "Henry Ford",
  "address": "henry@example.com"
}
Field Type Description
name string The name of the email address.
address string The address (e.g. user@example.com)

The Line Item Object

Represents a line item on Greenback.

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
}
Field Type Description
grn string (Optional) A namespaced, unique identifier of the product/service purchased or sold. 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 namespace includes: vs, sku, var, gb, and asin. Please see item grn for more details.
alt_grns string[] (Optional) An array of alternative grn values.
name string (Optional) The name of the item.
description string (Optional) The description of the item (e.g. variations).
uri string (Optional) A URL of the product/service.
quantity double (Optional) The quantity purchased or sold.
unit_price double (Optional) The price per unit.
amount double (Optional) The total amount (e.g. quantity * unit_price).

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.

Type Description
vs A vendor specific code such as a product identifier.
sku A stock keeping unit defined by the seller. Many accounting programs track items primarily by SKU.
var A variation identifier defined by the seller. A variation usually includes the length, color, etc. of an item.
gb A Greenback defined value usually used for standard items on our platform such as Payment Processing Fees, Marketplace Facilitator Taxes, etc.
asin An Amazon product identifier

The Contact Object

Represents a party or entity that is a party to a transaction (e.g. the buyer or seller).

{
  "id" : "lBOp8mArOd",
  "name" : "Domino's Pizza",
  "domain" : "dominos.com"
}
Field Type Description
id string A unique identifier of the contact on Greenback.
name string The name of the contact.
domain string (Optional) The DNS domain of the contact if they are well-known such as amazon.com or ebay.com.

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.

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"
}
Field Type Description
name string (Optional) The name of the recipient.
line1 string (Optional) The first line of the address.
line2 string (Optional) The second line of the address.
city string (Optional) The city of the address.
region_code string (Optional) The region (e.g. state or province) of the address.
postal_code long (Optional) The postal code.
country_code string (Optional) The ISO-3166 country code of the address.
location geopoint (Optional) A geographic point consisting of a lat/long.
raw_address string (Optional) If a well-known address cannot be parsed, this represents the raw address text from the transaction source.

Vision

Vision example

With the Greenback Vision API you can quickly and easily build web or mobile applications that can convert images (PNG/JPG) or documents (PDF) into structured transaction data. To get started, simply upload an image or document to the Greenback Vision API endpoint.

Create Vision POST /v2/visions
Get Vision GET /v2/visions/{vision_id}
Get Vision Attachment GET /v2/visions/{vision_id}/attachments/{attachment_id}

The Vision Object

The Vision Object

{
  "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"
    } ],
    "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.

Field Type Description
id string The unique identifier of the Vision object.
name string The name of the vision object which is equal to the name of the file that was uploaded.
status enum The status of the vision request. Values include: pending, processing, success, and error.
created_at datetime ISO 8601 timestamp of when the vision object was created.
updated_at datetime ISO 8601 timestamp of when the vision object was last updated.
error object If the status is error then this will be present and is the error that occurred during processing. See the error object for more details.
attachments object[] An array of attachment objects for any images or documents that are part of the Vision object. See the attachment object for more details.
annotations object If the status is success then this includes all of the annotations extracted from the uploaded image or document. See the annotations object for more details.
transaction_matcher object If the status is success then this includes our suggested criteria for matching to a transaction in another system. See the transaction matcher object for more details.

The Transaction Matcher Object

Field Type Description
transacted_ats object[] An array of interval objects that include a start and end datetime for a range of dates that the transaction may have occurred at. The ranges are calculated using the extracted data, context, granularity, and other heuristics to help you find a matching transaction.
amounts object[] An array of monetary amount objects that represent possible transaction values such as the total or sub-total (e.g. authorized pre-tip amount). The amounts are calculated using the extracted data, context, and other heuristics to help you find a matching transaction.

The Annotations Object

Field Type Description
full_text object The full text annotation of the processed Vision image or document. See the full text annotation object for more details.
temporals array An array of temporal annotations of the processed Vision object. See the temporal annotation object for more details.
moneys array An array of money annotations of the processed Vision object. See the money annotation object for more details.
tenders array An array of tender (payment instrument) annotations of the processed Vision object. See the tender annotation object for more details.
emails array An array of email annotations of the processed Vision object. See the email annotation object for more details.
urls array An array of url annotations of the processed Vision object. See the url annotation object for more details.

The Full Text Annotation Object

Field Type Description
text string The full text of the image or document. The ordering of the text generally follows how a human would read the image or document, but may be re-ordered for optimized processing into structured data.

The Temporal Annotation Object

Field Type Description
text string The original, raw text of the recognized date or time within the image or document.
date localdate (Optional) The local date that was recognized.
time localtime (Optional) The local time that was recognized.
granularity enum The granularity of the date or time that was recognized. For example, if only a date was extracted the granularity would be to the day, whereas if a date and time such as "8:32 AM" were extracted then granularity would be to the minute. Values include: year, month, day, hour, minute, second, and millisecond.

The Money Annotation Object

Field Type Description
text string The original, raw text of the recognized money (monetary) amount within the image or document.
amount double The amount of money.
symbol string (Optional) The symbol of the money amount.
currency_code enum (Optional) The ISO 3-letter currency code of the money amount.

The Tender Annotation Object

Field Type Description
method enum (Optional) The method of tender (payment). Values include: visa, mastercard, amex, discover, and cash
ends_with string (Optional) The tail (e.g. last 4) of the tender.

The URL Annotation Object

Field Type Description
text string The original, raw text of the recognized URL within the image or document.
url string A normalized, well-formed version of the URL that mimics how a browser would interpret it.
domain string The top private domain of the URL host. For example, if the URL was either www.example.co.uk/survey or simply example.co.uk/survey then the domain value would be example.co.uk in either case.

The Email Annotation Object

Field Type Description
text string The original, raw text of the recognized email address within the image or document.
domain string The top private domain of the email address. For example, if the email address was either henry@em.example.co.uk or simply henry@example.co.uk then the domain value would be example.co.uk in either case.

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 multi-part 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
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}

Field Type Description
async boolean (Optional) Either synchronous or asynchronous processing mode. Defaults to false.

Request

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

Field Type Description
file file The image or document to upload. The name of the file and its file extension is how Greenback detects its mime-type.

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

Field Type Description
vision_id string The unique identifier of the Vision object.

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

Field Type Description
vision_id string The unique identifier of the Vision object.
attachment_id string The relative, unique identifier of attachment. This is the rel_id value in the attachment object.

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
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

Field Type Description
vision_id string The unique identifier of the Vision object.

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>

Annotated example

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
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

Field Type Description
vision_id string The unique identifier of the Vision object.

Request

Standard GET request will contain an empty body.

Response

The binary image or document.

Mailbox

Mailbox example

Convert RFC822 emails, including attachments and embedded links into structured transaction data. Leverage extra mailbox APIs to render an email as a PDF, or safe and embeddable HTML. To get started, simply upload the email to the Greenback Mailbox API endpoint.

Create Message POST /v2/messages
Get Message GET /v2/messages/{message_id}
Get Message Attachment GET /v2/messages/{message_id}/attachments/{attachment_id}
Get Message HTML GET /v2/messages/{message_id}/html
Get Message PDF GET /v2/messages/{message_id}/pdf

The Message Object

The Message Object

{
  "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" : [ {
      "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.

Field Type Description
id string The unique identifier of the Message object.
reference_id string An additional unique identifier of the Message object used internally by Greenback. Prefer id as your reference.
status enum The status of the message request. Values include: pending, processing, success, and error.
posted_at datetime ISO 8601 timestamp of the message (e.g. the Date header field).
created_at datetime ISO 8601 timestamp of when the message object was created on Greenback.
updated_at datetime ISO 8601 timestamp of when the message object was last updated on Greenback.
flags enum[] (Optional) Various flags about the message request. Values may include: converted and draft.
size long The size in bytes of the message object data.
subject string The subject of the message (e.g. the Subject header field).
snippet string A short (currently up to 200 characters) description of the contents of the message.
quoted object[] (Optional) If the email was forwarded then this array represents the unquoted (unforwarded) partial of the email. Each item in the array represents a hierarchical unquoting of the original email. The ordering will match outermost to innermost. The last index of this array will be the innermost forwarded email content. Any property of the Message object may be included here. However, the most common will be subject, from, to, and posted_at
from object (Optional) The sender of the email. See the email address object for more details.
to object[] (Optional) An array of email address objects for the to of the email. See the email address object for more details.
reply_to object[] (Optional) An array of email address objects for the reply-to of the email. See the email address object for more details.
cc object[] (Optional) An array of email address objects for the cc of the email. See the email address object for more details.
bcc object[] (Optional) An array of email address objects for the bcc of the email. See the email address object for more details.
transactions object[] An array of transaction objects for any recognized or extracted transactions in the Message object. See the transaction object 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.

The HTTP request consists of multi-part 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
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

Field Type Description

No query parameters.

Request

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

Field Type Description
file file The RFC822 email message to upload. The name of the file and its file extension is how Greenback detects its mime-type.

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

Field Type Description
message_id string The unique identifier of the Message object.

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

Field Type Description
message_id string The unique identifier of the Message object.
attachment_id string The relative, unique identifier of attachment. This is the rel_id value in the attachment object.

Request

Standard GET request will contain an empty body.

Response

The binary image or document.

Get Message HTML

Get an HTML (partial) document that is ready for embedding inside another HTML document. The HTML will be sanitized of javascript, inline css, and other potentially unsafe elements or attributes. The outermost element will usually be a div element. It will never be html or body. If the original email was text-only (no HTML part) then an HTML-ready version of that text will be returned here.

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
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

Field Type Description
message_id string The unique identifier of the Message object.

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.

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
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

Field Type Description
message_id string The unique identifier of the Message object.

Request

Standard GET request will contain an empty body.

Response

The PDF document of the rendered email message.

Connect

Mailbox example

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

Transaction

The Transaction Object

The Transaction Object

{
  "id" : "42d1YnO0oJ",
  "type" : "purchase",
  "currency_code" : "usd",
  "reference_id" : "5560f493-a1c7-430e-8f15-1ca88b5fc055",
  "transacted_at" : "2018-11-21T22:11:55.000Z",
  "created_at" : "2019-05-24T05:08:14.952Z",
  "updated_at" : "2019-05-24T05:08:14.956Z",
  "flags" : [ "converted" ],
  "attributes" : {
    "display_reference_id" : "104512",
    "ponum" : "123 Main"
  },
  "contact" : {
    "id" : "lBOp8mArOd",
    "name" : "Domino's Pizza",
    "domain" : "dominos.com"
  },
  "attachments": [
    {
      "rel_id": "sto_1dguhF",
      "media_type": "application/pdf",
      "why": "original",
      "size": 44985,
      "md5": "bc4ceede6e882d859861a58c05624eb9"
    }
  ],
  "store_address": {
    "line1" : "302 SOUTH WASHINGTON",
    "line2" : "SUITE 212",
    "city" : "Royal Oak",
    "region_code" : "mi",
    "postal_code" : "48067",
    "country_code" : "us",
    "raw_address": "302 SOUTH WASHINGTON \nROYAL OAK, MI 48067"
  },
  "items" : [ {
    "name" : "Your Domino's Order",
    "quantity" : 1.0,
    "unit_price" : 21.19,
    "amount" : 21.19
  } ],
  "travel" : { ... },
  "payments" : [ {
    "method" : "credit_card",
    "network" : "visa",
    "ends_with" : "1234"
  } ],
  "totals" : {
    "sub" : 21.19,
    "tax" : 1.24,
    "items" : [ {
      "type" : "tax",
      "name" : "Sales Tax",
      "amount" : 1.24
    } ],
    "grand" : 22.43
  }
}
Field Type Description
id string The unique identifier of the Transaction object.
type enum The type of the transaction. Values include: purchase, bill, reimbursement, sales_receipt, invoice, and refund.
currency_code enum ISO 4217 currency code of the transaction.
reference_id string A unique, stable reference identifier provided by the source of the transaction (e.g. an invoice number). In order to use this value as a unique identifier, please note that it will need to be scoped to the context of how its unique. For example, if the transaction is from Amazon, then this reference_id would be unique for amazon.com + reference_id. In some cases, the reference_id cannot be safely determined and so this value will be a stable identifier generated by Greenback. If this is the case, you will want to check if attributes.display_reference_id has a value that may help the user locate the transaction.
transacted_at datetime ISO 8601 timestamp of the transaction.
created_at datetime ISO 8601 timestamp of when the transaction object was created on Greenback.
updated_at datetime ISO 8601 timestamp of when the transaction object was last updated on Greenback.
flags enum[] (Optional) Various flags about the transaction. Values may include: converted, draft, archived, trashed, duplicate, and exported.
attributes object (Optional) A object of string keys and values of extra metadata about the transaction.
contact object (Optional) The counter party of the transaction. For example, if this is your purchase, then this will represent who you purchased from (the seller). See the contact object for more details.
attachments object[] (Optional) An array of attachment objects for any original, VAT receipts, or other documents attached to the transaction. See the attachment object for more details.
store_address object (Optional) The postal address of the store where the transaction took place. See the postal address object for more details.
billing_address object (Optional) The postal address of who was billed. See the postal address object for more details.
shipping_address object (Optional) The postal address of where it was shipped. See the postal address object for more details.
items object[] (Optional) An array of line items purchased or sold. See the line item object for more details.
travel object (Optional) If the transaction is related to travel (e.g. Lyft or Uber) then this represents what travel occurred. See the travel object for more details.
payments object[] (Optional) An array of funding instrument objects that represents the source/origin of funds for a transaction. See the funding instrument object for more details.
deposits object[] (Optional) An array of funding instrument objects that represents the target/destination of funds for a transaction. See the funding instrument object for more details.
totals object (Optional) The total amounts of the transaction. See the transaction totals object for more details.

The Funding Instrument Object

Represents a flow of cash/money in or out such as from a credit card or to a bank account. Can either be a payment or deposit.

{
  "method" : "credit_card",
  "network" : "visa",
  "ends_with" : "1234",
  "amount" : 12.24,
  "name" : "My Business Visa",
  "paid_at" : "2019-05-24T01:12:23.000Z"
}
Field Type Description
method enum The method used for funding such as a purchase on a credit_card. Values may include: credit_card, debit_card, paypal, reward, seller_acount, cash, and possibly others.
network enum (Optional) The network used based on the method such as visa.
ends_with string (Optional) The last part of an account number such as the last 4 of a credit card.
amount double (Optional) The amount of the payment or deposit.
name string (Optional) The name or description of the account to help the user identify which one was used.
paid_at datetime (Optional) ISO 8601 timestamp of the payment or deposit.

The Travel Object

Represents a type of travel occurred on the Greenback platform. Included as part of a transaction so that a map of the various legs of travel can be rendered along with the transaction itself.

Example travel object rendering

{
  "type": "car",
  "legs": [
    {
      "depart_at": "2019-04-25T12:13:05.000Z",
      "arrive_at": "2019-04-25T12:42:18.000Z",
      "depart_address": {
        "location": {
          "lat": 40.76506,
          "lon": -73.97508
        },
        "raw_address": "54 W 59 St, New York, NY 10019"
      },
      "arrive_address": {
        "location": {
          "lat": 40.76745,
          "lon": -73.86358
        },
        "raw_address": "Grand Central Pkwy, New York, NY"
      },
      "distance": 16737.178,
      "ticket_class": "Lyft"
    }
  ]
}

The Transaction Totals Object

A summary of the totals of a transaction. It consists of 3 parts: the sub total, non-sub totals, and the grand total. The sub-total is a sum of the line items. Non-sub totals are amounts such as tax, shipping, fees, discounts, etc. The grand is the sub-total and non-sub totals and is the final amount.

The Transaction Totals Object

{
  "sub" : 21.19,
  "tax" : 1.24,
  "items" : [ {
    "type" : "tax",
    "name" : "Sales Tax",
    "amount" : 1.24
  } ],
  "grand" : 22.43
}
Field Type Description
sub double The total line item amount of the transaction.
tax double The total tax amount of the transaction.
ship double The total shipping amount of the transaction.
fee double The total fee amount of the transaction.
tip double The total tip amount of the transaction.
discount double The total discount amount of the transaction.
other double The total other amount of the transaction.
grand double The grand total of the transaction which is sub plus all other non-sub totals.
items object[] An array of totals item objects that itemize what tax, shipping, fee, tip, discount, or other items are present.

Get Transaction Attachment

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

Send Request

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

HTTP Request

GET /v2/transactions/kg1DMpNKXA/attachments/rs_1tydV5YSlh9bOS8fVHt9k HTTP/1.1
Authorization: Bearer 1234567890
Accept: */*
If-None-Match: 123456789456879874556fdfdf

HTTP Response

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

<binary data here>

Endpoint

GET /v2/transactions/{transaction_id}/attachments/{attachment_id}

Field Type Description
transaction_id string The unique identifier of the Transaction object.
attachment_id string The relative, unique identifier of attachment. This is the rel_id value in the attachment object.

Request

Standard GET request will contain an empty body.

Response

The binary image or document.