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):
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). |
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
ordirection
.
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 |
BNZ | conn_cjgaatd57000001pe1t1z0iy9 |
Heartland* | conn_ck5rhsdbv0000ftx1bmdu9zas |
Kiwibank | conn_cjgaac5at000001qi2yw8ftil |
Rabobank* | conn_ckydkmy3r000009mde2sx2i4d |
The Cooperative Bank* | conn_cjgab1c8e000001pmyxrkhova |
TSB* | conn_cjgab6fis000001qsytf1semy |
Westpac | conn_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):
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: We are still tweaking the maths behind this value, and 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 NZFCC category. |
results[*].category.name | string | ✅ | The name of the base category. |
results[*].category.groups | string | ✅ | A map of category grouping name to category group for this transaction. |
results[*].category.groups[*]._id | string | ✅ | The category group ID. |
results[*].category.groups[*].name | string | ✅ | The category group name. |
results[*].merchant | object | ✖️ | The merchant match for this result. Available on most results, but may be omitted in certain cases. |
results[*].merchant._id | string | ✖️ | If there is a merchant, the unique ID for that merchant. |
results[*].merchant.name | string | ✖️ | If there is a merchant, the name of that merchant. |
results[*].merchant.logo | string | ✖️ | 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.website | string | ✖️ | 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/"
}
}
]
}
]
}
Updated 3 months ago