For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Legacy DocsSign in
DocumentationChangelog
DocumentationChangelog
  • Get Started
    • Introduction
    • Get your API keys
    • Support
    • Privacy policy
    • Status
  • Transaction Enrichment
    • Overview
    • Entities Identification
    • Categorization
    • Recurrence
  • Bank Statements
    • Overview
    • Fast verification
  • Core resources
    • Batches
    • Entities
    • Account Holders
    • Webhooks
    • Personalization
    • Reporting wrong results
  • API Reference
    • Authentication
    • Errors
    • Request IDs
    • Pagination
    • Rate limits
LogoLogo
Legacy DocsSign in
On this page
  • Understanding recurrence
  • Recurrence groups
  • Example usage
Transaction Enrichment

Recurrence

Was this page helpful?
Previous

Bank Statements

Next
Built with

Understanding recurrence in financial transactions is crucial for categorizing and predicting future cash flows. The Recurrence API allows you to identify and categorize recurring patterns found in the transactions of an account holder, such as periodic payments or subscriptions. These patterns are classified into a recurrence type and a recurrence group that encodes detailed information about its periodicity, transaction counterparty and amount metrics.

Understanding recurrence

We employ a machine learning model to identify recurring transactions and group them together. This model is designed to detect patterns of recurring transactions while filtering out noisy data, such as frequent transactions that may have similar periodicity by chance rather than being truly recurring. The model is able to categorize transactions into a recurrence type and group noncontiguous transactions, so even if there is a gap in a pattern - say missing a month on a monthly subscription over a year, it is still recognized.

Recurrence groups

A recurrence group is a grouping of transactions with the same recurring pattern. Every transaction in a recurring pattern shares the same counterparty, but not necessarily amounts. This means that:

  • We might have transactions with different amounts in the same recurring group.
  • There could be multiple recurrence groups per counterparty/general category.
  • We could have non-recurrent transactions with a counterparty (e.g Amazon Web Services) even if there’s already transactions with the same counterparty belonging to a group.

Example usage

SDK
1from ntropy_sdk import SDK
2
3sdk = SDK("cd1H...Wmhl")
4for i in range(1,5):
5 sdk.transactions.create(
6 id=f"netflix-{i}",
7 description=f"Recurring Debit Purchase Card 1350 #{i} netflix.com Netflix.com CA",
8 amount=17.99,
9 currency="USD",
10 entry_type="outgoing",
11 date=f"2021-0{i}-01",
12 account_holder_id="35b927b6-6fda-40aa-93b8-95b47c2b2cad",
13 )
14
15 sdk.transactions.create(
16 id=f"netflix-{i}",
17 description=f"Payment #{i} from netflix.com Netflix.com CA",
18 amount=1000,
19 currency="USD",
20 entry_type="incoming",
21 date=f"2021-0{i}-01",
22 account_holder_id="35b927b6-6fda-40aa-93b8-95b47c2b2cad",
23 )
24
25recurring_groups = sdk.account_holders.recurring_groups(
26 "35b927b6-6fda-40aa-93b8-95b47c2b2cad"
27)
See the full raw output
1[
2 {
3 "id": "5a38529e-2df2-3e34-ac4d-98dcd294b781",
4 "start_date": "2024-01-20",
5 "end_date": "2024-04-20",
6 "total_amount": 4000.0,
7 "average_amount": 1000.0,
8 "periodicity_in_days": 31.0,
9 "periodicity": "monthly",
10 "counterparty": {
11 "id": "dc425051-df94-3509-9103-cf8c0f0bcf6a",
12 "name": "Netflix",
13 "website": "netflix.com",
14 "logo": "https://logos.ntropy.com/netflix.com",
15 "mccs": [],
16 "type": "organization"
17 },
18 "categories": {
19 "general": "entertainment - television - subscriptions",
20 },
21 "transaction_ids": [
22 "sub-4",
23 "sub-3",
24 "sub-2",
25 "sub-1"
26 ],
27 "entry_type": "outgoing"
28 },
29 {
30 "id": "7e529088-cc5b-3eed-8050-b98034bc5184",
31 "start_date": "2024-01-20",
32 "end_date": "2024-04-20",
33 "total_amount": 4000.0,
34 "average_amount": 1000.0,
35 "periodicity_in_days": 31.0,
36 "periodicity": "monthly",
37 "counterparty": {
38 "id": "dc425051-df94-3509-9103-cf8c0f0bcf6a",
39 "name": "Netflix",
40 "website": "netflix.com",
41 "logo": "https://logos.ntropy.com/netflix.com",
42 "mccs": [],
43 "type": "organization"
44 },
45 "categories": {
46 "general": "income - paycheck",
47 },
48 "transaction_ids": [
49 "sal-4",
50 "sal-3",
51 "sal-2",
52 "sal-1"
53 ],
54 "entry_type": "incoming"
55 }
56]