This guide walks you through creating custom categories and recategorizing transactions at the user-level. for information on creating integration-level personalizations, please see the integration category personalization guide.
Integration note
For simplicity, the examples in this guide shows you how to send requests to Spade directly. However, you will likely want to build user category personalization into client applications. Because client-side code is public and your API key is secret, you will need to proxy user category personalization requests through your backend to Spade’s servers. The merchant search guide demonstrates how to proxy requests through your backend to Spade’s API.
Fetch the default categories for your integration
The first thing you’ll likely want to do is fetch the default categories for your integration. This list contains all of the categories that Spade provides, plus any custom categories that you’ve added on an integration-wide level.Accounting and Bookkeeping
, for instance, sits underneath the Banking and Finance
category, which sits at the root level. For convenience, each serialized category includes a fullCategoryHierarchy
object, which contains the full hierarchy of the category.
Creating a custom user category
As with default categories and custom integration-wide categories, custom user categories are hierarchical. They can sit at the root level, under Spade’s categories, under custom integration-level categories, or under other custom user-level categories. For instance, here’s how you can create a custom user category that sits at the root level:Fetching custom user categories
In order to support curated user experiences, you’ll likely want to fetch custom user categories whenever you fetch the default categories for your integration. Here’s how you can fetch custom user categories:all_categories
to the frontend and display them as a tree, a searchable input, etc…

Recategorizing a specific transaction for a specific user
To recategorize a specific transaction, you’ll want to update that transaction record in your internal system. For instance:Recategorizing all future transactions for a specific counterparty
One of the most powerful features Spade provides is the ability for users to recategorize future transactions before they take place. This feature takes advantage of Spade’s ability to consistently match transactions to stable counterparty IDs using ground truth data. Here’s how a user can recategorize future transactions for a specific counterparty:
With this personalization in place, any future transactions that take place at
Lowe's
for this specific user will be enriched with the custom category, which will appear in the personalization
section of the enrichment as the counterparty’s industry
:
Deleting custom user-level categories
You can delete custom user-level categories all at once or individually. To delete all custom user-level categories, send aDELETE
request to the /users/:userId/categories
endpoint:
DELETE
request to the /users/:userId/categories/:id
endpoint with the category’s ID:
Deleting user-level counterparty category personalizations
You can delete user-level counterparty category personalizations all at once or individually. To delete all user-level counterparty category personalizations, send aDELETE
request to the /users/:userId/counterparty-category-personalizations
endpoint:
DELETE
request to the /users/:userId/counterparty-category-personalizations/:counterpartyId
endpoint with the counterpartyId
of the personalization you want to delete: