Enriching Transactions with Genie

❗

️ 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, outlet, 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):

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

Akahu Connection Ids

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

^*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):

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",
            "components": [
              {
                "name": "Fast food restaurants",
                "type": "nzfcc:base"
              },
              {
                "name": "Cafes & restaurants",
                "type": "nzfcc:group"
              },
              {
                "name": "Lifestyle",
                "type": "nzfcc:pfm"
              }
            ]
          },
          "merchant": {
            "_id": "merchant_cjjwm2gy5004bguzydvu4dttf",
            "name": "Carl's Jr.",
            "logo": "https://static.akahu.io/outlets/merchant_cjjwm2gy5004bguzydvu4dttf_logo.png"
          },
          "outlet": {
            "_id": "outlet_ckpor47kq035ttkp2h17k1y8i",
            "name": "Carl's Jr."
          }
        }
      ]
    },
    {
      "id": "2",
      "query": "CARD 2293 WHOLEMEAL TRAD CO LTDTAKAKA",
      "results": [
        {
          "confidence": 0.99,
          "category": {
            "_id": "nzfcc_ckouvvyw1004408mlhy158i7j",
            "components": [
              {
                "name": "Cafes & restaurants",
                "type": "nzfcc:base"
              },
              {
                "name": "Cafes & restaurants",
                "type": "nzfcc:group"
              },
              {
                "name": "Lifestyle",
                "type": "nzfcc:pfm"
              }
            ]
          },
          "merchant": {
            "_id": "merchant_cksxp1au3001g09mp3ilt01tz",
            "name": "The Wholemeal Cafe",
            "logo": "https://static.akahu.io/images/merchant_cksxp1au3001g09mp3ilt01tz_logo.jpeg"
          },
          "outlet": {
            "_id": "outlet_cksxp1av6001i09mpci6s69m4",
            "name": "The Wholemeal Cafe",
            "location": {
              "accuracy": "establishment",
              "coordinates": {
                "lon": "174.77080320000005",
                "lat": "-36.8484346"
              }
            }
          }
        }
      ]
    }
  ]
}