Skip to main content

Account Holders

When using the Ntropy API, you can provide information about the account holder of a certain transaction. In this way, when you add a transaction using the API or SDK, it will also be added to that account holder's ledger.

An account holder represents an entity (business, consumer) that can be uniquely identified and holds the account associated with the transaction:

  • In an outgoing (debit) transaction, the account holder is the sender and the merchant is the receiver.
  • In an incoming (credit) transaction, the account holder is the receiver and the merchant is the sender.

Account holders provide important context for understanding transactions and allow additional operations such as:

  • Identifying recurrence between transactions of the same account.
  • Extracting metrics for an account over time.
  • Retrieving all enriched transactions for an account holder
  • Calculating additional insights for an account holder such as income information over a period of time, indentifying the account holder's subscriptions, and so on.

Using account holder information​

There are four possible options to provide account holder information in a transaction:

  1. Provide only the account_holder_id
    • this associates transaction with an already existing account holder identified by the provided account_holder_id
  2. Provide both the account_holder_id and account_holder_type
    • this associates transaction with the provided account_holder_id
    • if no account holder with the provided account_holder_id exists, then a new one is automatically created
  3. Provide only account_holder_type
    • transaction is not associated with any account holder
  4. Provide no account_holder_type and no account_holder_id
    • transaction is not associated with any account holder and is not labelled

By providing both properties, you can always ensure that a transaction will be associated with the correct account holder regardless whether the holder exists or not.

Optional account holder fields​

In addition to the account_holder_id and account_holder_type, you can provide the following optional fields to improve enrichment quality:

  • name: The name of the account holder
  • industry: The industry in which the account holder operates
  • website: The website of the account holder

While these fields are optional, providing them can significantly enhance the accuracy and depth of the enrichment process.

Accessing account holder history​

At any point, after adding transactions to an account holder by providing the account_holder_id during enrichment you can retrieve the history of that account holder's transactions through the API or SDK:

$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X GET \
https://api.ntropy.com/v2/account-holder/MY-ACCOUNT-HOLDER/transactions?page=0&per_page=100

Note that the endpoint is paginated, however the SDK will execute the necessary requests to retrieve all the available page for an account holder. You can also use the internal method sdk._get_account_holder_transactions_page to retrieve a specific page using the SDK.

The API endpoint returns both input and output propeties of each transaction in the history of the requested account holder. In the SDK you can access this information through the property parent_tx of each EnrichedTransaction.