Enriching Transactions with Genie

Use the Genie Search API to enrich transactions

Applications that use Akahu for bank account connectivity 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 raw transaction data themselves.

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 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
BNZconn_cjgaatd57000001pe1t1z0iy9
Heartland*conn_ck5rhsdbv0000ftx1bmdu9zas
Kiwibankconn_cjgaac5at000001qi2yw8ftil
Rabobank*conn_ckydkmy3r000009mde2sx2i4d
The Cooperative Bank*conn_cjgab1c8e000001pmyxrkhova
TSB*conn_cjgab6fis000001qsytf1semy
Westpacconn_cjgaaozdo000001mrnqmkl1m0

*We currently offer limited support for these banks. If your transaction data is sourced from 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: We are still tweaking the maths behind this value, and 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[*].merchantobject✖️The merchant match for this result. Available on most results, but may be omitted in certain cases.
results[*].merchant._idstring✖️If there is a merchant, the unique ID for that merchant.
results[*].merchant.namestring✖️If there is a merchant, the name of that merchant.
results[*].merchant.logostring✖️If there is a merchant, a URL of a .png image of the merchant logo. If no logo is available, a placeholder image is provided.
results[*].merchant.websitestring✖️If there is a merchant, a URL of the merchant's website. If no website is available, the value will be undefined.

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",
            "website": "https://www.carlsjr.co.nz/"
          }
        }
      ]
    },
    {
      "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",
            "website": "https://wholemealcafe.co.nz/"
          }
        }
      ]
    }
  ]
}