DOCUMENTATION: GENIFY MACHINE-LEARNING MODELS API


Introduction

Welcome onboard! Our REST API enables your company to programmatically use our machine-learning powered model.


Authorization

A token is required to use the API. In the examples below, we will use this demo token:

uooqTdoyXHV9iC8hor7WtcQQPbHFRSc1fI8ifiwcj7

Please contact us in order to obtain a token.


Getting Started

The examples below show how to classify a banking transaction using its description and amount:


Python

import requests 

# A user is granted a token, such as: 
token = "uooqTdoyXHV9iC8hor7WtcQQPbHFRSc1fI8ifiwcj7"

# This token is used to determine the ML models a user has access to
headers = {'Authorization': 'Bearer ' + token} 

url = "http://www.genify.ai/api/v1.0/classifier?description=starbucks&amount=45" 
response = requests.get (url, headers=headers) 
print (response.text) 

# Example of a forbidden access (HTTP error 403) 
url = "http://www.genify.ai/api/v1.0/recosys" 
response = requests.get (url, headers=headers) 
print (response)


Selecting the machine-learning model to run using the model id

Any of our machine learning model can be run via our API using a model id instead of the model name. Below is an example (using the same token and headers):


Python

url = "http://www.genify.ai/api/v1.0/generic?model_id=1&description=starbucks&amount=45" 
response = requests.get (url, headers=headers) 
print (response.text) 

url = "http://www.genify.ai/api/v1.0/generic?model_id=2" 
response = requests.get (url, headers=headers) 
print (response) 

url = "http://www.genify.ai/api/v1.0/classifier/?description=starbucks&amount=31" 
response = requests.get(url, headers=headers) 
print(response.json())

Optionaly, a date and time can be provided:


Python

import requests 
url = "http://www.genify.ai/api/v1.0/classifier/?description=starbucks&amount=31&date=12Jun201903:45pm" 
response = requests.get(url, headers=headers) 
print(response.json())


Inputs of the transaction classifier API

The transaction classifier accepts the following parameters

InputDescriptionMandatoryType/format
Description
Nomenclature associated with the transaction (e.g. 'Starbucks Brooklyn')YesString
Amount
Value of the transaction in the relevant currencyYesDecimal
DateTime
Date and time of occurence of transactionNo"DDMonYYYYHH:MMam/pm"


Responses


Following the steps listed above, the expected JSON response should be:

{
   "category_description": "Coffeeshop",
   "category_id": 1003
}

where

category_description
is the label assigned to the transaction by Genify's model and
category_id
the id of the label in the below category hierarchy.


Genify's hierarchy of transaction categories can be found in the below dendrogram.



Dendrogram of transactions categories

The child categories are displayed on the outer ring, and the parent categories on the inner ring. The API currently only returns child categories.



Errors

In case, for example, the description or amount isn't provided in the transaction classifier API call, the API returns an error message with HTTP status code 400:

url = "http://www.genify.ai/api/v1.0/classifier/?description=starbucks"
response = requests.get(url, headers=headers)
print(response.status_code) # prints 400