Enrich

The Enrich resource enables you to retrieve details by passing in a search query containing a bank transaction description.

The service enriches transaction data with multiple attributes, returning a transaction classification and three metadata components. The transaction classification will first determine if the transaction is of type payment, transfer, cash-withdrawal, bank-fee etc. The engine then derives merchant information, purchase location and prescribes an industry standard categorisation for each payment transaction.

You can subscribe to one or all of the following three core datasets returned depending on your use case.

Data
`Merchant`	Details relating to the store or merchant such as business name, website and contact details
`Location`	Details relating to the location of the entity such as address and geocode location
`Category`	Industry standard categorisation with a 4 level hierarchy for banking transactions.
`Links`	Provides direct link to `self` - original query Provides links master and thumb merchant logos

The query will typically be the full textual description of a transaction record, however the partner calling the API may also optionally pass in more details to make the search more relevant (such as an MCC code).

Pre-requisties

• Prior to calling the enrich service, you will need to be authenticated via the Basiq API service.
• The service will only be accessible to partners that have been enabled.

Request

You can call the enrich endpoint by passing in the following query parameters:

📘
You will need to ensure that the search query is url encoded before calling the resource and must contain at least 3 characters.

Mandatory Arguments
qstring, required	This is the search string that is used to lookup the entity (merchant) information.`q=garfish%20MANLY%20NS&country=AU&institution=AU06703`

institution string, required	Identifies the institution from where the transaction was derived. This must be a Basiq recognisable institution ID.`enrich?METRO%20PETROLEUM%20FR%20FORE&country=AU&accountType=transaction&amount=-12.95&institution=AU04301`

country string, required	Specifies the country the search should be narrowed down to. Passing in a country value will limit the search to the specified country. The country must be in [ISO 3166 Alpha-2 format] (https://www.iso.org/obp/ui/#search)`q=garfish%20MANLY%20NS&country=AU&institution=AU06703`

Note: accountType and amount are mandatory arguments for transaction classification. If these arguments are not provided, the query will be treated as a payment transaction and categorised accordingly.

Optional Arguments
mccstring, optional	Merchant classification code as defined by Visa and Mastercard`q=garfish%20MANLY%20NS&country=AU&institution=AU06703&mcc=3299`

accountType string, optional	The Account type from which the transaction was derived.`METRO%20PETROLEUM%20FR%20FORE&country=AU&accountType=transaction&institution=AU04301**`Valid values: transaction credit-card savings mortgage loan foreign

amount string, optional	The dollar/cent amount relevant to the transaction.`q=garfish%20MANLY%20NS&country=AU&institution=AU06703&amount=-12.95`

GET /enrich

GET enrich?q=METRO%20PETROLEUM%20FR%20FORE&country=AU&accountType=transaction&amount=-12.95&institution=AU04301
HTTP/1.1
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

Response

The enrich endpoint will always return a 200 response to the user, along with a set of results for each of the datasets subscribed to: category, entity and location. If no results are found for the search query then an empty result set is returned. If parameter inputs are invalid an error is returned.

You can subscribe one or all of the following three datasets depending on your use case. The datasets are described below.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "type": "enrich",
    "direction": "debit",
    "class": "payment",
    "data": {
        "merchant": {
            "id": "15e83d60-7332-4cec-96ab-06cfc4e3d710",
            "businessName": "Metro Petroleum",
            "website": "http://www.metropetroleum.com.au/",
            "phoneNumber": {
                "local": "(03) 9471 0283",
                "international": "+61 3 9471 0283"
            }
        },
        "location": {
            "routeNo": "145",
            "route": "Spring St",
            "postalCode": "3073",
            "suburb": "Reservoir",
            "state": "VIC",
            "country": "Australia",
            "formattedAddress": "139/145 Spring St, Reservoir VIC 3073",
            "geometry": {
                "lat": "-37.7263016",
                "lng": "145.0009305"
            }
        },
        "category": {
            "anzsic": {
                "division": {
                    "code": "G",
                    "title": "Retail Trade"
                },
                "subdivision": {
                    "code": "40",
                    "title": "Fuel Retailing"
                },
                "group": {
                    "code": "400",
                    "title": "Fuel Retailing"
                },
                "class": {
                    "code": "4000",
                    "title": "Fuel Retailing"
                }
            }
        }
    },
    "links": {
        "self": "https://au-api.basiq.io/enrich?country=AU&institution=AU04301&q=METRO+PETROLEUM+FR+FORE",
        "logo-master": "https://enrich-enrichmerchantslogobucket-6or17iuhdvs9.s3-ap-southeast-2.amazonaws.com/metro_petroleum-master.png",
        "logo-thumb": "https://enrich-enrichmerchantslogobucket-6or17iuhdvs9.s3-ap-southeast-2.amazonaws.com/metro_petroleum-thumb.png"
    }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "type": "enrich",
    "direction": "debit",
    "class": "payment",
    "data": {
        "merchant": null,
        "location": null,
        "category": null
    },
    "links": {
        "self": "https://au-api.basiq.io/enrich?accountType=transaction&amount=-12.95&country=AU&institution=AU06703&q=sfdsdfsd",
        "logo-master": null,
        "logo-thumb": null
    }
}

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "type": "list",
    "correlationId": "923788f1-72de-11e9-9a9f-a7c155f44712",
    "data": [
        {
            "type": "error",
            "code": "parameter-not-valid",
            "title": "Parameter value is not valid",
            "detail": "accountType is not valid Basiq account type value",
            "source": {
                "parameter": "accountType"
            }
        }
    ]
}

Attributes

Enrich
`type`	Value is "enrich"

`direction`	Debit or Credit transaction

`class`	Describes the type of transaction: payment, transfer, cash-withdrawal, bank-fee, interest, refund etc.

Merchant
`id`	The merchant id.

`businessName`	The merchant business name.

`ABN`	The merchant business ABN.

`website`	The merchant website.

`phoneNumber`	Provides the `local` and `international` telephone numbers of the merchant.

Location
`routeNo`	The street number of the merchant location.

`route`	The street name of the merchant location.

`postalCode`	The post code of the merchant location.

`suburb`	The suburb of the merchant location.

`state`	The state of the merchant location.

`country`	The country of the merchant location.

`formattedAddress`	The full address for the merchant location

`geometry`	Contains the `lat` and `lng` coordinates of the merchant location.

Category
`class`	Details the `code` and `title` of the merchant ANZSIC class.

`group`	Details the `code` and `title` of the merchant ANZSIC group.

`subdivision`	Details the `code` and `title` of the merchant ANZSIC subdivision.

`division`	Details the `code` and `title` of the merchant ANZSIC division.

Links
`self`	Provides a reference link to the original query.

`logo-master`	Provides link to master logo. Logos are provided in a variety of formats: .svg, .png, .jpg, jpeg, gif. Where null no merchant logo is available.

`logo-thumb`	Provides link to thumb logo (where no thumb available master logo is returned for both). Logos are provided in a variety of formats: .svg, .png, .jpg, jpeg, gif. Where null no merchant logo is available.