Enriching Transactions with Genie

Use the Genie Search API to enrich transactions

❗️

Beta feature

Genie is still in beta release and may be subject to breaking API changes. If you spot any issues or would like to request a feature, please get in touch at [email protected].

Applications that use Akahu's enduring access to users bank accounts can use our transactions API to get high quality enriched transactions that include merchant and category information. We've built the Genie API to expose Akahu's transaction enrichment engine for applications that instead source transactions either directly from the bank, or via a third-party service.

Genie is entirely separate from the core Akahu API and does not require an Akahu App ID Token or App Secret to access. If you're keen to get your hands on an API key to try it out, get in touch with us at [email protected].

📘

Merchant Database

Genie's merchant database is tailored specifically to New Zealand merchants. We have focussed our efforts on building the best possible dataset for New Zealand, which means that we offer only limited support for enrichment of overseas transactions.

If you require robust enrichment of both domestic and overseas transactions, we recommend using Genie in conjunction with additional services that offer support for the markets that you require (e.g. Look Who's Charging or Basiq in Australia).

Usage

Authentication

We will provide you with an API key beginning with genie_token_ to authenticate against the API. Call the API using this key by including it as a bearer token in the HTTP Authorization header:

Authorization: Bearer genie_token_abc123

Request Schema

The Genie search endpoint is https://api.genie.akahu.io/v1/search.

The endpoint accepts an HTTP POST request with request body containing a JSON serialized array of query objects. Each query object has the schema described in the table below (an example request can be found later on in this guide):

FieldTypeRequired?Description
idstring✖️A unique correlation id for the query to help you to find the corresponding result in the response data.
descriptionstringThe transaction description. This should be the full description as provided by the bank / transaction source.
_connectionstring✖️The Akahu connection ID corresponding to the bank from which the transaction description was sourced. See the connection list below for values. It is strongly recommended to include this parameter to ensure best results.
amount*number✖️Transaction amount (+ for credit, - for debit).
direction*string✖️"DEBIT" or "CREDIT". May improve results if the amount is unknown.

*For best results, it is recommended to include at least one of amount or direction.

Akahu Connection Ids

The below table includes the mapping of bank to Akahu connection id for all supported New Zealand banks.

BankConnection Id
ANZconn_cjgaawozb000001nyd111xixr
ASBconn_cjgaaqcna000001ldwof8tvj0
Westpacconn_cjgaaozdo000001mrnqmkl1m0
Kiwibankconn_cjgaac5at000001qi2yw8ftil
BNZconn_cjgaatd57000001pe1t1z0iy9
TSB*conn_cjgab6fis000001qsytf1semy
The Cooperative Bank*conn_cjgab1c8e000001pmyxrkhova
Heartland*conn_ck5rhsdbv0000ftx1bmdu9zas
Rabobank*conn_ckydkmy3r000009mde2sx2i4d

*While in beta, we are offering limited support for these banks. If you need support for one of these banks, get in touch and we'll work with you to ensure we can provide you with the best possible results.

Response Schema

The transaction enrichment results are returned as an array nested inside a wrapper object, following the standard Akahu "list of items" response format:

{
    "success": true,
    "items": [ <query result items> ]
}

Each query result item has the schema described in the table below (an example response can be found later on in this guide):

FieldTypeRequired?Description
idstring✖️The correlation ID for the query (if you provided one).
querystringThe original query description as provided.
resultsarrayArray of results for this query (empty if no results).
results[*].confidencenumberA value between 0 and 0.99 indicating the strength of the matched result (although currently the lowest returned confidence score is 0.5). Note: while in beta we are still tweaking the maths behind this value, but we intend to release guidelines for usage once it becomes stable.
results[*].categoryobjectThe merchant category classification for the query. This is present on all result items.
results[*].category._idstringUnique ID for the base NZFCC category.
results[*].category.namestringThe name of the base category.
results[*].category.groupsstringA map of category grouping name to category group for this transaction.
results[*].category.groups[*]._idstringThe category group ID.
results[*].category.groups[*].namestringThe category group name.
results[*].category.componentsarrayDeprecated. Will be removed on the 1st of March. An array of categories for the query result. Each item represents a category type of differing granularity. If you're unsure how to use this, look for the component of type: "nzfcc:base" which is our most granular category type.
results[*].category.components[*].namestringThe category name.
results[*].category.components[*].typestringThe category type e.g. nzfcc:base.
results[*].merchantobject✖️The merchant match for this result. Available on most results, but may be omitted in certain cases.
results[*].merchant._idstringUnique ID for the matched merchant.
results[*].merchant.namestringThe name of the matched merchant.
results[*].merchant.logostringA URL a .png image of the merchant logo. If no logo is available, a placeholder image is provided.

Example

Example Request

The snippet below shows an example request to the Genie search endpoint using curl. Simply insert your Genie API key in place of <YOUR API KEY> to test it out for yourself:

curl --request POST 'https://api.genie.akahu.io/v1/search' \
--header 'Authorization: Bearer <YOUR API KEY>' \
--header 'Content-Type: application/json' \
--data '[
    {
        "_id": "1",
        "description": "CJ PALMERSTON NTH - 203PALM NTH",
        "_connection": "conn_cjgaaqcna000001ldwof8tvj0",
        "amount": -4.9
    },
    {
        "_id": "2",
        "description": "CARD 2293 WHOLEMEAL TRAD CO LTDTAKAKA",
        "_connection": "conn_cjgaaqcna000001ldwof8tvj0",
        "amount": -25.1
    }
]'

Example Response

{
  "success": true,
  "items": [
    {
      "id": "1",
      "query": "CJ PALMERSTON NTH - 203PALM NTH",
      "results": [
        {
          "confidence": 0.99,
          "category": {
            "_id": "nzfcc_ckouvvywi004508mlacrd41wf",
            "name": "Fast food stores",
            "groups": {
              "personal_finance": {
                "_id": "group_clasr0ysw0011hk4m6hlk9fq0",
                "name": "Lifestyle",
              }
            },
          },
          "merchant": {
            "_id": "merchant_cjjwm2gy5004bguzydvu4dttf",
            "name": "Carl's Jr.",
            "logo": "https://static.akahu.io/outlets/merchant_cjjwm2gy5004bguzydvu4dttf_logo.png"
          }
        }
      ]
    },
    {
      "id": "2",
      "query": "CARD 2293 WHOLEMEAL TRAD CO LTDTAKAKA",
      "results": [
        {
          "confidence": 0.99,
          "category": {
            "_id": "nzfcc_ckouvvyw1004408mlhy158i7j",
            "name": "Cafes and restaurants",
            "groups": {
              "personal_finance": {
                "_id": "group_clasr0ysw0011hk4m6hlk9fq0",
                "name": "Lifestyle",
              }
            },
          },
          "merchant": {
            "_id": "merchant_cksxp1au3001g09mp3ilt01tz",
            "name": "The Wholemeal Cafe",
            "logo": "https://static.akahu.io/images/merchant_cksxp1au3001g09mp3ilt01tz_logo.jpeg"
          }
        }
      ]
    }
  ]
}