Personalization

If you want to customize the output of the Ntropy API you can do so by setting a ruleset through the personalization API. With a ruleset, you can conditionally add or remove labels and change some of the fields returned by the Ntropy API.

Ruleset

There are two types of rulesets: API key rulesets and account holder rulesets. API key rulesets are applied to all transactions submitted, while account holder rulesets only apply to transactions that match a specific account holder. The API key rulesets is applied first.

There is a size limit of 50,000 bytes for API key rulesets, and 10,000 bytes for account holder rulesets, which is enough for approximately 2000 basic rules per key and 400 basic rules per account holder.

Uploading rulesets

Rulesets can be uploaded via POST request to the /v2/rules/ and /v2/rules/account-holder/{account_holder_id} endpoints.

Sending a GET request will return the currently set ruleset.

Modifying a ruleset

You can append a rule to a ruleset via a POST request to the /v2/rules/append and /v2/rules/account-holder/{account_holder_id}/append endpoints.

To delete a rule, send a DELETE request to the /v2/rules/{index} and /v2/rules/account-holder/{account_holder_id}/{index} endpoints, where index is the zero based index of the rule you wish to delete.

To replace a rule, send a PATCH request to the /v2/rules/{index} and /v2/rules/account-holder/{account_holder_id}/{index} endpoints.

You can also of course reupload the entire ruleset.

Specification

A ruleset is a list of rules. Rulesets are type checked when uploaded.

Rules

There are 3 kinds of actions a rule can perform.

Set property

{"set": "property", "to": expression}

Properties that can be set are:

property	type
logo	string
website	string
merchant	string
merchant_id	string
location	string
person	string
mcc	string
transaction_type	string

Modify labels

You can add labels, remove labels, or replace all the labels.

{"set_labels": [expressions...]}
{"add_label": expression}
{"remove_label": expression}

Conditional

Execute some rules if a condition is satisfied.

{"if": expression, "then": [rules...]}
{"if": expression, "then": [rules...], "else": [rules...]}

Expressions

Expressions can have one of three types: number, boolean, or string. null is not an allowed value. All numbers are interpreted as floats.

Literals

0
true
"string"

Function calls

There are currently 5 functions.

{"is_substring": [expression, expression]}
{"to_lower": [expression]}
{"to_upper": [expression]}
{"has_label": expression}
{"get": "property"}

is_substring takes two strings and returns a boolean, indicating whether the 2nd argument is a substring of the 1st.

to_lower takes a string converts it to lowercase.

to_upper takes a string converts it to uppercase.

has_label takes a string and returns a boolean

get returns the value of a property. property can be one of the settable properties, or description. The valid properties are:

property	type
logo	string
website	string
description	string
merchant	string
merchant_id	string
location	string
person	string
mcc	string
transaction_type	string

Operators

These are technically also function calls.

Operators that take an arbitrary number of arguments are evaluated as ((arg1 <op> arg2) <op> arg3) <op> ....

{"!": expression} // logical not, accepts a boolean
{"&&": [expressions...]} // logical and, accepts a list of booleans
{"||": [expressions...]} // logical or,  accepts a list of booleans
{"==": [expressions...]} // equals, accepts a list of expressions of the same type
{"+": [expressions...]} // accepts a list of numbers
{"*": [expressions...]} // accepts a list of numbers
{"/": [expressions...]} // accepts a list of numbers
{"-": [expressions...]} // accepts a list of of numbers
{"//": [expressions...]} // integer division, accepts a list of numbers
{"<": [expression, expression]} // accepts two numbers
{"<=": [expression, expression]} // accepts two numbers
{">": [expression, expression]} // accepts two numbers
{">=": [expression, expression]} // accepts two numbers

Examples

This example checks if the website contains "ntropy" and replaces the logo if so, and adds a label otherwise.

cURL

$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X POST \
--data '[
    {
        "if": {
            "is_substring": [
                {"get": "website"},
                "ntropy"
            ]
        },
        "then": [
            {"set": "logo", "to": "http://example.com/favicon.ico"}
        ],
        "else": [
            {"add_label": "not ntropy :("}
        ]
    }
]' \
https://api.ntropy.com/v2/rules/

Python SDK

rules = [
    {
        "if": {
            "is_substring": [
                {"get": "website"},
                "ntropy"
            ]
        },
        "then": [
            {"set": "logo", "to": "http://example.com/favicon.ico"}
        ],
        "else": [
            {"add_label": "not ntropy :("}
        ]
    }
]

sdk.upload_rules(rules)

Here's another example to add the income label for interest payments.

cURL

$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X POST \
--data '[
    {
        "if": {
            "||": [
                {"has_label": "interest"},
                {"is_substring": [{"to_lower": {"get": "description"}}, "interest"]},
            ]
        },
        "then": [{"add_label": "income"}],
    }
]' \
https://api.ntropy.com/v2/rules/

Python SDK

rules = [
    {
        "if": {
            "||": [
                {"has_label": "interest"},
                {"is_substring": [{"to_lower": {"get": "description"}}, "interest"]},
            ]
        },
        "then": [{"add_label": "income"}],
    }
]

sdk.upload_rules(rules)