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, 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):
Field | Type | Required? | Description |
---|---|---|---|
id | string | ✖️ | A unique correlation id for the query to help you to find the corresponding result in the response data. |
description | string | ✅ | The transaction description. This should be the full description as provided by the bank / transaction source. |
_connection | string | ✖️ | 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). |
type * | 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
ortype
.
Akahu Connection Ids
The below table includes the mapping of bank to Akahu connection id for all supported New Zealand banks.
Bank | Connection Id |
---|---|
ANZ | conn_cjgaawozb000001nyd111xixr |
ASB | conn_cjgaaqcna000001ldwof8tvj0 |
Westpac | conn_cjgaaozdo000001mrnqmkl1m0 |
Kiwibank | conn_cjgaac5at000001qi2yw8ftil |
BNZ | conn_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):
Field | Type | Required? | Description |
---|---|---|---|
id | string | ✖️ | The correlation ID for the query (if you provided one). |
query | string | ✅ | The original query description as provided. |
results | array | ✅ | Array of results for this query (empty if no results). |
results[*].confidence | number | ✅ | A 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[*].category | object | ✅ | The merchant category classification for the query. This is present on all result items. |
results[*].category._id | string | ✅ | Unique ID for the base category. |
results[*].category.components | array | ✅ | 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[*].name | string | ✅ | The category name. |
results[*].category.components[*].type | string | ✅ | The category type e.g. nzfcc:base . |
results[*].merchant | object | ✖️ | The merchant match for this result. Available on most results, but may be omitted in certain cases. |
results[*].merchant._id | string | ✅ | Unique ID for the matched merchant. |
results[*].merchant.name | string | ✅ | The name of the matched merchant. |
results[*].merchant.logo | string | ✅ | A URL a .png image of the merchant logo. If no logo is available, a placeholder image is provided. |
results[*].outlet | object | ✖️ | The outlet match for this result. Available on most results, but may be omitted in certain cases. Note: While in beta, the schema and data of this object are unstable and likely to change. It is not recommended to rely on outlet data at this point. |
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"
}
}
}
}
]
}
]
}
Updated 10 days ago