Transaction Categorization
Transaction categorization is a feature where we classify your Transactions into useful categories (Restaurants, gas stations, income, etc.) using our categorizer AI engine. This allows you to quickly summarize, group and extract valuable insights from your items' transactions right out of the box.
For example, you could understand how much a user spent last month in eating, how much in services, and so on, and with this show them a summary of their expenses (like in our Creating a use case from scratch guide), or you can use it to create any kind of solutions, from client profiling to income analysis.
Using categorization
We return the result of our categorization in the category
field of a transaction:
{
"id": "6ec156fe-e8ac-4d9a-a4b3-7770529ab01c",
"description": "TED Example",
"amount": 1500,
"date": "2021-04-12T00:00:00.000Z",
// Categoy's name is provided
"category": "Transfer - TED",
"categoryId": "05080000",
...
}
The category will be a string if there was a category found, or null
if we could not interpret any known category.
Trial/Premium feature
Categorization is enabled by default during trial period. After that, it is an opt-in premium feature.
If you do not have the transaction categorization feature enabled,
category
will benull
for all transactions.
How categories are organized
You can view all possible categories in our GET /categories endpoint. We can find the transaction's category in this list with its categoryId
:
[
{
"id": "05080000",
"description": "Transfer - TED",
"descriptionTranslated": "Transferência - TED",
"parentId": "05000000",
"parentDescription": "Transfers"
},
...
]
We can see its translation to portuguese in the descriptionTranslated
field.
You might notice that it has a parentDescription Transfers
. This means that it is under a more general category called Transfers:
[
...
{
"id": "05000000",
"description": "Transfers"
},
...
]
Categories are organized in a tree. This allows you to use more general categories or more specific ones, depending on your particular needs. The Category Tree is detailed at the bottom of this guide.
Category accuracy
As much as we constantly train our categorizer model, categorization is never perfect. In case you encounter a wrong category in a transaction, you can correct it by using our Transaction Update endpoint, or from Demo by clicking on its Categoria field.
After you submit a category correction, you will get the corrected category
field on the transaction, and also feed back the correct annotation into our model, further improving the quality of categorization.
Categorization API (Categorization as a service)
If you need to categorize your own batch of transactions outside of Pluggy, we offer our categorizer engine as an API for you to use.
Want to try it out? Follow these steps:
- First, authenticate in Pluggy API to obtain an API key
- With the API key in your
X-API-Key
header, do a POST tohttps://enrichment-api.pluggy.ai/categorize
with a body like this: { "clientUserId": "[email protected]", "transactions": [{ "id": "12345", "date": "2022-05-01T00:00:00.000Z", "description": "Mc Donalds", "amount": 100 }] }
- You will receive a response that looks like this:
{ "results": [ { "id": "12345", "date": "2022-05-01T00:00:00.000Z", "description": "Mc Donalds", "amount": 100, "category": "Eating out", "merchant": { "name": "mc donalds", "businessName": "ARCOS DOURADOS COMERCIO DE ALIMENTOS LTDA", "cnpj": "42.591.651/0001-43" } } ] }
Categorization API reference
Endpoint: : POST /categorize
Body:
clientUserId
identifier for the user (ie. email or cpf)transactions
list of transactions to be categorized.
List of:description
stringid
string (uuid or number stringified)amount
number (ie. 100.30)date
date in ISO formatpaymentData
object referencing the related transfer details.
Limitations:
- The
transactions
list can contain up to 100 elements to be categorized per request. If you need to categorize more than 100 transactions, split them into multiple requests.
Response:
status
: 200 for successRequest latency
: between 0.5s to 2s depending on the payload.
Category Tree
Level 1 | Level 2 | Level 3 |
---|---|---|
Income | - Salary - Retirement - Entrepreneurial activities - Government aid - Non-recurring income | - - - - - |
Loans and financing | - Late payment and overdraft costs - Interests charged ----------------------------------- - - Financing - ----------------------------------- Loans | - - ----------- Financing ------------ - Real estate financing - Vehicle financing - Student loan ----------------------------------- - |
Investments | Automatic investment Fixed income Mutual funds Variable income Margin Proceeds interests and dividends Pension | - - - - - - - |
Same person transfer | - Same person transfer - Cash - Same person transfer - PIX - Same person transfer - TED | - - - |
Transfers | - Transfer - Bank slip - Transfer - Cash - Transfer - Check - Transfer - DOC - Transfer - Foreign exchange - Transfer - Internal - Transfer - PIX - Transfer - TED ---------------------------------- - - - Third party transfers - - ---------------------------------- - Credit card payment | - - - - - - - - ------- Third party transfer ------- - Bank slip - Debt card - DOC - PIX - TED ---------------------------------- - |
Legal obligations | - Blocked balances - Alimony | - - |
Services | -Telecommunications - Education - Wellness and fitness - Tickets | ------ Telecommunications -------- - Internet - Mobile - TV ----------- Education ------------- - Online Courses - University - School - Kindergarten ------ Wellness and fitness -------- - Gyms and fitness centers - Sports practice - Wellness ------------ Tickets -------------- - Stadiums and arenas - Landmarks and museums - Cinema, theater and concerts |
Shopping | - Online shopping - Electronics - Pet supplies and vet - Clothing - Kids and toys - Bookstore - Sports goods - Office supplies - Cashback | - - - - - - - - - |
Digital services | - Gaming - Video streaming - Music streaming | - - - |
Groceries | - | - |
Food and drinks | - Eating out - Food delivery | - - |
Travel | - Airport and airlines - Accomodation - Mileage programs - Bus tickets | - - - - |
Donations | - | - |
Gambling | - Lottery - Online bet | - - |
Taxes | - Income taxes - Taxes on investments - Tax on financial operations | - - - |
Bank fees | - Account fees - Wire transfer fees and ATM fees - Credit card fees | - - - |
Housing | - Rent ---------------------------------- - - Utilities - ---------------------------------- - Houseware - Urban land and building tax | - ------------ Utilities --------------- - Water - Electricity - Gas ---------------------------------- - - |
Healthcare | - Dentist - Pharmacy - Optometry - Hospital clinics and labs | - - - - |
Transportation | - Taxi and ride-hailing - Public transportation - Car rental - Bycicle ---------------------------------- - - - Automotive - - - ---------------------------------- | - - - - ---------- Automotive ------------- - Gas stations - Parking - Tolls and in vehicle payment - Vehicle ownership taxes and fees - Vehicle maintenance - Traffic tickets ---------------------------------- |
Insurance | - Life insurance - Home insurance - Health insurance - Vehicle insurance | - - - - |
Leisure | - | - |
Updated about 2 months ago