Skip to main content

Labeling hierarchies

The labels returned by the API are different depending on the account_holder_type of the transaction. You can find the listing containing all the labels for each account_holder_type below:

Custom Hierarchies​

In addition to the default label hierarchies, Ntropy allows you to define and use custom hierarchies for your specific needs. This feature enables you to tailor the labels system to your unique use case.

Defining a Custom Hierarchy​

To define a custom hierarchy, you need to create a JSON structure that represents your desired label organization. The structure should contain two main categories: "incoming" and "outgoing", each containing an array of labels.

Here's an example of how to define a custom hierarchy:

{
  "incoming": [
    "salary",
    "investment income",
    "other income"
  ],
  "outgoing": [
    "rent",
    "utilities",
    "groceries",
    "entertainment"
  ]
}

Uploading a Custom Hierarchy​

Once you have defined your custom hierarchy, you can upload it using the Ntropy API. Here's how to do it:

  1. Ensure you have the necessary permissions to use custom hierarchies.
  2. Use the POST endpoint /v2/labels/hierarchy/custom/{account_holder_type} to upload your custom hierarchy.
  3. Include your custom hierarchy in the request body.

Here's an example using Python and the requests library:

import requests
import json

api_key = "your_api_key_here"
account_holder_type = "consumer"  # or "business"

custom_hierarchy = {
    "direct": {
        "incoming": ["salary", "investment income", "other income"],
        "outgoing": ["rent", "utilities", "groceries", "entertainment"]
    }
}

response = requests.post(
    f"https://api.ntropy.com/v2/labels/hierarchy/custom/{account_holder_type}",
    headers={"X-API-Key": api_key},
    json=custom_hierarchy
)

if response.status_code == 200:
    print("Custom hierarchy successfully uploaded.")
else:
    print(f"Error uploading custom hierarchy: {response.text}")

Using a Custom Hierarchy​

After uploading your custom hierarchy, Ntropy will automatically use it for labeling transactions associated with your API key. The custom labels will replace the default labels in the enrichment results.

Retrieving a Custom Hierarchy​

You can retrieve your current custom hierarchy using a GET request:

response = requests.get(
    f"https://api.ntropy.com/v2/labels/hierarchy/custom/{account_holder_type}",
    headers={"X-API-Key": api_key}
)

if response.status_code == 200:
    custom_hierarchy = response.json()
    print("Current custom hierarchy:", json.dumps(custom_hierarchy, indent=2))
else:
    print(f"Error retrieving custom hierarchy: {response.text}")

Deleting a Custom Hierarchy​

To remove a custom hierarchy and revert to the default labels, you can use a DELETE request:

response = requests.delete(
    f"https://api.ntropy.com/v2/labels/hierarchy/custom/{account_holder_type}",
    headers={"X-API-Key": api_key}
)

if response.status_code == 200:
    print("Custom hierarchy successfully deleted.")
else:
    print(f"Error deleting custom hierarchy: {response.text}")

Special Labels​

In cases where there is not enough information to accurately classify a transaction, the API will return a special label:

  • "not enough information": This label is used when the available transaction data is insufficient to determine a specific category.

This ensures that transactions are not incorrectly labeled when the data is ambiguous or incomplete.

By using custom hierarchies, you can ensure that the transaction labels align perfectly with your specific requirements while still leveraging Ntropy's powerful labeling capabilities.