Transaction Data API

Endpoints used to enrich banking transaction data with categories, merchant logos and the carbon footprint.

The Transaction Data API endpoints require authorization (via API key) as they are hosted by Genify in the cloud. Other endpoints are installed on our clients' cloud or premises.

Enrich Transaction Data

POST https://pfm.genify.ai/api/v1.0/txn-data/

Unified endpoint: this single endpoint can be used for all three features (categorization, merchant logo, carbon footprint), for convenience. This endpoint categorizes a banking transaction from its description and amount, and also returns the corresponding merchant logo and carbon footprint. Any one, two or all three features can be queried (See individual endpoint documentation for more details).

Query Parameters

Name	Type	Description
country*	string	Country where transaction was preformed. Need to insert the right format otherwise it will lead to an error, e.g., Egypt, EG or EGY.
date*	string	Date at which transaction occurred in the format: YYYY-MM-DD
latitude	number	Latitude of transaction merchant (mandatory if longitude is provided.)
longitude	number	Longitude of transaction merchant (mandatory if latitude is provided.)
amount*	string	Value of the transaction in USD by default. Negative ➖ amounts are expenses, positive ➕ amounts are incoming transactions.
description*	string	Description of the transaction, e.g., "Cafe Lucia Plaza Central XY123" (Note: if the char "&" is part of passed description in IDE, please use "%26" instead.)
mcc	number	Merchant category code (Use model_name = model_4 to use the mcc mapper as the primary categorizer)
currency	string	Options: [ Default:"USD", "EUR", "GBP", "AED", "SAR", "EGP", "AUD", "BRL", "CAD", "CHF", "CNY", "COP", "DKK", "HKD", "HUF", "INR", "JPY", "MXN", "MYR", "NOK", "OMR", "PHP", "PLN", "RON", "SEK", "SGD", "UAH", "ZAR"]

Headers

Name	Type	Description
account_id*	string	id used to identify current user provided in format of account_<id> eg: account_0 which exists for testing. (Note: the more the data collected for your user's id, the better results the models will provide you.)
category_name	string	If carbon_footprint is true, the category_name can be inserted to avoid running the categorizer and use the category you provide instead.
category_id	string	If carbon_footprint is true, the category_id can be inserted to avoid running the categorizer and use the category you provide instead
model_name	string	Name of the machine learning model to use. COMING SOON: separate endpoint to retrieve the list available. Defaults to model_2.
logo	boolean	If false or omitted, no logo is returned.
carbonfootprint	boolean	If false or omitted, omits carbon footprint value from response.
category	boolean	If false or omitted, omits category name and id values from response.
username*	string	Your username
authorization*	string	API key associated with your Genify account.
logo_format	String	Logo format you want returned. Options: [Default: raw, round, square]
website	boolean	flag specifies weither to get merchant website or not. value: 0(default) or 1.

200 success

{
	"Transaction UUID": "3dffdef7-29a2-42c3-91e5-75d10e3d69f1"
	"Merchant ID": "00005af3107a8964"
	"Carbon Footprint": 0.661,
	"Category ID": "2005",
	"Category Name": "Telephone and internet",
	"Clean Description": "Orange Egypt",
	"Country": "EGYPT",
	"Display Description": "Orange",
	"Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Orange.png",
	"Merchant Website": "www.orange.eg",
	"Subcategory Name": "Telephone and internet"
}

400 missing data

"Please make sure to send following missing data: ['country', 'amount', 'date : input date in iso format: YYYY-MM-DD.', 'description']"

401 invalid username

{
    "Message": "Invalid username"
}

404 no service selected

{
    "message": "please select a service to display"
}

500 error from our end

"something went wrong please try again"

403 user is not authorized

{
    "Message": "Forbidden"
}

Get Categorized Transaction

GET https://pfm.genify.ai/api/v1.0/txn-data/

The unified endpoint can be used to only categorize a banking transaction (from a credit card, a debit card or a bank account) from its description and amount. The transaction is categorized as one of ~80 categories in Genify's category tree.

Query Parameters

Name	Type	Description
longitude	number	Longitude of transaction merchant (mandatory if longitude is provided.)
latitude	number	Latitude of transaction merchant (mandatory if longitude is provided.)
date*	string	Date at which transaction occurred in the format: YYYY-MM-DD
country*	string	Country where the transaction was preformed. Need to insert the right format otherwise it will lead to an error, e.g., Egypt, EG or EGY.
description*	string	Description of the transaction, e.g., "Cafe Lucia Plaza Central XY123"
amount*	number	Value of the transaction in USD by default. Negative ➖ amounts are expenses, positive ➕ amounts are incoming transactions.

Headers

Name	Type	Description
account_id*	string	id used to identify current user provided in format of account_<id> eg: account_0 which exists for testing. (Note: the more the data collected for your user's id, the better results the models will provide you.)
category*	string	Flag used to activate categorizer.
model_name	string	Name of the machine learning model to use. COMING SOON: separate endpoint to retrieve the list available. Defaults to model_2.
username*	string	Your username.
authorization	string	API key associated with your Genify account.
website	boolean	flag specifies weither to get merchant website or not. value: 0(default) or 1.

200 Categorization successful.

{
    "Transaction UUID": "3dffdef7-29a2-42c3-91e5-75d10e3d69f1"
    "Merchant ID": "00005af3107a8964"
    "Carbon Footprint": null,
    "Category Confidence": null,
    "Category ID": "1003",
    "Category Name": "Coffeeshop",
    "Country": "EGYPT",
    "Logo": null,
    "Subcategory Name": "Coffee shop",
    "Clean Description": "Starbucks Plaza Central",
    "Display Description": "Starbucks"
}

400 In case of missing query parameters

"Please make sure to send following missing data: ['country', 'amount', 'date : input date in iso format: YYYY-MM-DD.', 'description']"

401 authorization is not passed in headers

{
	"Message": "Invalid username"
}

500

"Something went wrong, please try again"

Get Categorized Transaction ( based on client code )

GET https://pfm.genify.ai/api/v1.0/txn-data/

Query Parameters

Name	Type	Description
bank_code*	string	code of that client that will be used to fetch static categorization for the requested transaction.
country*	string	Country where the transaction was preformed. Need to insert the right format otherwise it will lead to an error, e.g., Egypt, EG or EGY.

Headers

Name	Type	Description
username*	string	client name.
authorization*	string	client api_key.
category*	boolean	Flag used to activate categorizer.
account_id*	string	id used to identify current user provided in format of account_<id> eg: account_0 which exists for testing. (Note: the more the data collected for your user's id, the better results the models will provide you.)

200: OK success

{

    "Transaction UUID": "3dffdef7-29a2-42c3-91e5-75d10e3d69f1"
    "Merchant ID": null
    "Carbon Footprint": null,
    "Category Confidence": 1,
    "Category ID": "CHD",
    "Category Name": "Banking Service",
    "Country": "egypt",
    "Logo": null,
    "Subcategory Name": null,
    "Clean Description": "CASH DEPOSIT",
    "Display Description": "CASH DEPOSIT"
}

400: Bad Request bank code is invalid

"Bank code doesn't exist"

401: Unauthorized

{
	"Message": "Invalid username"
}

403: Forbidden

{
	"Message": "Forbidden"
}

Get Merchant Logo

GET https://pfm.genify.ai/api/v1.0/txn-data/

The same endpoint can be used to only obtain the merchant logo corresponding to a transaction. The merchant logo is retrieved from Genify's proprietary database which grows incrementally if an unknown merchant is queried.

Query Parameters

Name	Type	Description
longitude	number	Longitude of transaction merchant (mandatory if longitude is provided.)
latitude	number	Latitude of transaction merchant (mandatory if longitude is provided.)
date*	string	Date at which transaction occurred in the format: YYYY-MM-DD
country*	string	Country where the transaction was preformed. Need to insert the right format otherwise it will lead to an error, e.g., Egypt, EG or EGY.
description*	string	Description of the transaction, e.g., "Cafe Lucia Plaza Central XY123" (Note: if the char "&" is part of passed description in IDE, please use "%26" instead.)
amount	string	Value of the transaction in USD by default. Negative ➖ amounts are expenses, positive ➕ amounts are incoming transactions.

Headers

Name	Type	Description
account_id*	string	id used to identify current user provided in format of account_<id> eg: account_0 which exists for testing. (Note: the more the data collected for your user's id, the better results the models will provide you.)
model_name	string	Name of the machine learning model to use. COMING SOON: separate endpoint to retrieve the list available. Defaults to model_2.
logo*	string	Flag used to activate logo grabber.
authorization*	string	API key associated with your Genify account.
username*	string	Your username.
logo_format	string	format of the output logo. Options: raw, square or round. Default: raw.
website	boolean	flag specifies weither to get merchant website or not. value: 0(default) or 1.

200 success

{
    "Transaction UUID": "3dffdef7-29a2-42c3-91e5-75d10e3d69f1"
    "Merchant ID": null
    "Carbon Footprint": null,
    "Category Confidence": null,
    "Category ID": "1003",
    "Category Name": "Coffeeshop",
    "Clean Description": "Starbucks",
    "Country": "EGYPT",
    "Display Description": "Starbucks",
    "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Starbucks%20round.png",
    "Merchant Website": "locations.starbucks.eg",
    "Subcategory Name": "Coffeeshop"
}

400 missing description field in params.

"Please make sure to send following missing data: ['country', 'amount', 'date : input date in iso format: YYYY-MM-DD.', 'description']"

401 authorization is not provided in headers.

{
	"Message": "Invalid username"
}

You can visit this link to view the image from the Base64 code.

Get Carbon Footprint

GET https://pfm.genify.ai/api/v1.0/txn-data/

The same endpoint can be used to only calculate the carbon footprint (carbon-equivalent weight in kg) corresponding to a transaction description, amount and category ID/name. The carbon footprint is computed using Genify's curated database of carbon footprint values. When no category is passed as input, the Genify transaction categorizer is used to infer the category.

Query Parameters

Name	Type	Description
longitude	number	Longitude of transaction merchant (mandatory if longitude is provided.)
latitude	number	Latitude of transaction merchant (mandatory if longitude is provided.)
date*	string	Date at which transaction occurred in the format: YYYY-MM-DD
country*	string	Country where the transaction was preformed. Need to insert the right format otherwise it will lead to an error, e.g., Egypt, EG or EGY.
amount*	number	Value of the transaction in USD by default. Negative ➖ amounts are expenses, positive ➕ amounts are incoming transactions.
description*	string	Description of the transaction, e.g., "Cafe Lucia Plaza Central XY123" (Note: if the char "&" is part of passed description in IDE, please use "%26" instead.)
currency	String	Options: [ Default:"USD", "EUR", "GBP", "AED", "SAR", "EGP", "AUD", "BRL", "CAD", "CHF", "CNY", "COP", "DKK", "HKD", "HUF", "INR", "JPY", "MXN", "MYR", "NOK", "OMR", "PHP", "PLN", "RON", "SEK", "SGD", "UAH", "ZAR"]

Headers

Name	Type	Description
account_id*	string	id used to identify current user provided in format of account_<id> eg: account_0 which exists for testing. (Note: the more the data collected for your user's id, the better results the models will provide you.)
category_id	string	If carbon_footprint is on, user can insert a category ID to avoid wait time of categorizer.
category_name	string	If carbon_footprint is on, user can insert a category name to avoid wait time of categorizer.
carbonfootprint*	boolean	Flag used to activate carbon footprint calculation.
username*	string	Your username.
authorization*	string	API key associated with your Genify account.

200

{

    "Transaction UUID": "3dffdef7-29a2-42c3-91e5-75d10e3d69f1"
    "Merchant ID": "00005af3107a8964"
    "Carbon Footprint": 6.3,
    "Category Confidence": null,
    "Category ID": "1003",
    "Category Name": "Coffeeshop",
    "Clean Description": "Starbucks",
    "Country": "EGYPT",
    "Display Description": "Starbucks",
    "Logo": null,
    "Merchant Website": "locations.starbucks.eg",
    "Subcategory Name": "Coffeeshop"
}

400 Missing fields

"Please make sure to send following missing data: ['country', 'amount', 'date : input date in iso format: YYYY-MM-DD.', 'description']"

401 No authorization in headers.

{
	"Message": "Invalid username"
}

500

"something went wrong,please try again"

Post Classification Error

POST https://pfm.genify.ai/api/v1.0/txn-data/report/error/

Request Body

Name	Type	Description
description*	string	the endpoint on which the user wants to report an error.
wrong_category*	string	genify's categorization to client's request.
suggested_category*	string	client's category suggestion to the request.

200: OK success message

{
    "message": "error report was received"
}

400: Bad Request validation error message when client enters a wrong category name in the wrong_category input param.

{
    "message": "category entered is not valid."
}

Batch Transactions

POST https://pfm.genify.ai/api/v1.0/txn-data/

This Endpoint will automatically operate as a batch endpoint whenever it gets a input as "raw body", "csv file", or "json file". The input ideally should contain list of transactions to be processed in batches.

Headers

Name	Type	Description
account_id*	string	id used to identify current user provided in format of account_<id> eg: account_0 which exists for testing. (Note: the more the data collected for your user's id, the better results the models will provide you.) This account_id will be overwritten in case of providing a specific account_id with each txn.
category_name	string	If carbon_footprint is true, the category_name can be inserted to avoid running the categorizer and use the category you provide instead.
category_id	string	If carbon_footprint is true, the category_id can be inserted to avoid running the categorizer and use the category you provide instead
model_name	string	Name of the machine learning model to use. COMING SOON: separate endpoint to retrieve the list available. Defaults to model_2.
logo	boolean	If false or omitted, omits logo from response. [removed value]
carbonfootprint	boolean	If false or omitted, omits carbon footprint value from response.
category	boolean	If false or omitted, omits category name and id values from response.
username*	string	Your username
authorization*	string	API key associated with your Genify account.
logo_format	string	format of the output logo. Options: raw, square or round. Default: raw.
enable_caching	boolean	flag that specifies whether to cache a merchant or not, in case It was not already cached. default: 0. value: 0 or 1.
extend_db	integer	flag that specifies whether to store a merchant in the database or not. default: 0. value: 0 or 1.
website	boolean	flag that specifies if you want to get merchant website or not. values: 0(default) or 1.

Request Body

Name	Type	Description
txns	JSON file	The other way of using batch endpoint, in JSON format, by attaching a JSON file as "Form-Data",
txns	csv file	The second way of using batch endpoint, in CSV format, by attaching a CSV file as "Form-Data",
txns	List	This is the first scenario of inputting transactions. We add in the raw body option (JSON Formatted), a list containing transactions in form of a JSON object each Transaction Parameters Required are: { "description", "amount", "country"} Optional: {"mcc", "bank-code", "account-id"}

200

{
    "batch_txn uuid": "22f48412-2fb5-11ee-9863-d281dc259316",
    "txns uuids": [
        "23560778-2fb5-11ee-931c-d281dc259316",
        "235608c2-2fb5-11ee-931c-d281dc259316",
        "23560944-2fb5-11ee-931c-d281dc259316",
        "235609a8-2fb5-11ee-931c-d281dc259316",
        "23560a02-2fb5-11ee-931c-d281dc259316",
        "23560a66-2fb5-11ee-931c-d281dc259316",
        "23560ac0-2fb5-11ee-931c-d281dc259316",
        "23560b24-2fb5-11ee-931c-d281dc259316",
        "23560b88-2fb5-11ee-931c-d281dc259316",
        "23560be2-2fb5-11ee-931c-d281dc259316"
    ]
}

400

"Please make sure to send following missing data: ['country', 'amount', 'date : input date in iso format: YYYY-MM-DD.', 'description']"

401

{
    "Message": "Invalid username"
}

404

{
    "message": "please select a service to display"
}

500

"something went wrong please try again"

403

{
    "Message": "Forbidden"
}

Batch Transactions Demo

• Demo Video with JSON body input

• CSV File input

  • Sample CSV

  • Demo Video

Retrieve Batch Transactions

POST https://pfm.genify.ai/api/v1.0/txn-data/retrieve-txn/batch/

In this Endpoint we will make use of the Txns UUIDs generated to retrieve all the Txns or Retrieve any number of txns by specifying their UUIDs

Headers

Name	Type	Description
username*	string	Your username
authorization*	string	API key associated with your Genify account.

Request Body

Name	Type	Description
txns_uuids	List	A list containing the txns uuid/s of transactions that we want to retrieve

200

{
    "successful_transactions": {
        "23560778-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8950"
            "Carbon Footprint": null,
            "Category ID": "1002",
            "Category Name": "Restaurant",
            "Clean Description": "Zomato Order",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Zomato",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Zomato.png",
            "Merchant Website": null,
            "Subcategory Name": "Indian restaurant"
        },
        "235608c2-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8951"
            "Carbon Footprint": null,
            "Category ID": "4003",
            "Category Name": "Electronics",
            "Clean Description": "Apple Itunes Store Aed",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Apple",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/logos/apple%20us.png",
            "Merchant Website": null,
            "Subcategory Name": "Electronics"
        },
        "23560944-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8952"
            "Carbon Footprint": null,
            "Category ID": "9005",
            "Category Name": "Software and apps",
            "Clean Description": "Itunes",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Itunes",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/google_logos/Itunes.png",
            "Merchant Website": null,
            "Subcategory Name": "Software and apps"
        },
        "235609a8-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8953"
            "Carbon Footprint": null,
            "Category ID": "1001",
            "Category Name": "Supermarket",
            "Clean Description": "Carrefour Market Alsee",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Carrefour Market",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Carrefour Market.png",
            "Merchant Website": null,
            "Subcategory Name": "Supermarket"
        },
        "23560a02-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8954"
            "Carbon Footprint": null,
            "Category ID": "1001",
            "Category Name": "Supermarket",
            "Clean Description": "Swiss Mart Supermarket",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Al Suwais Supermarket",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Al Suwais Supermarket.png",
            "Merchant Website": null,
            "Subcategory Name": "Supermarket"
        },
        "23560a66-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8955"
            "Carbon Footprint": null,
            "Category ID": "4005",
            "Category Name": "Other shopping",
            "Clean Description": "duty free dfs",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Beirut Duty Free Shops",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Beirut Duty-Free Shops.png",
            "Merchant Website": null,
            "Subcategory Name": "Duty free store"
        },
        "23560ac0-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8956"
            "Carbon Footprint": null,
            "Category ID": "6006",
            "Category Name": "Online activities and subscriptions",
            "Clean Description": "itunes  bill",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Itunes Bill",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/logos/itunes bill.png",
            "Merchant Website": null,
            "Subcategory Name": "Online activities and subscriptions"
        },
        "23560b24-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8957"
            "Carbon Footprint": null,
            "Category ID": "6006",
            "Category Name": "Online activities and subscriptions",
            "Clean Description": "itunes  bill",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Itunes Bill",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/logos/itunes bill.png",
            "Merchant Website": null,
            "Subcategory Name": "Online activities and subscriptions"
        },
        "23560b88-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8958"
            "Carbon Footprint": null,
            "Category ID": "5002",
            "Category Name": "Vehicle purchase, maintenance",
            "Clean Description": "Tensai Tuning Auto Wor",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Tensai",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Tensai.png",
            "Merchant Website": null,
            "Subcategory Name": "Auto tune up service"
        },
        "23560be2-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8959"
            "Carbon Footprint": null,
            "Category ID": "9002",
            "Category Name": "Online services",
            "Clean Description": "Google Services",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Google",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/google_logos/Google.png",
            "Merchant Website": null,
            "Subcategory Name": "Online services"
        },
        "23560c3c-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8960"
            "Carbon Footprint": null,
            "Category ID": "2005",
            "Category Name": "Telephone and internet",
            "Clean Description": "Etisalat Eshop Atg",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Etisalat",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Etisalat.png",
            "Merchant Website": null,
            "Subcategory Name": "Telephone and internet"
        },
        "23560c96-2fb5-11ee-931c-d281dc259316": {
            "Merchant ID": "00005af3107a8961"
            "Carbon Footprint": null,
            "Category ID": "2005",
            "Category Name": "Telephone and internet",
            "Clean Description": "Etisalat eshop",
            "Country": "UNITED ARAB EMIRATES",
            "Display Description": "Etisalat",
            "Logo": "https://pfm-logos.s3.eu-central-1.amazonaws.com/cached_logos/Etisalat.png",
            "Merchant Website": null,
            "Subcategory Name": "Telephone and internet"
        }
    }
}

400

"Please make sure to send following missing data: ['country', 'amount', 'date : input date in iso format: YYYY-MM-DD.', 'description']"

401

{
    "Message": "Invalid username"
}

404

{
    "message": "please select a service to display"
}

500

"something went wrong please try again"

403

{
    "Message": "Forbidden"
}

Batch Retrieval Demo

Batch Retrieval Demo Video