Skip to main content

Enrichment Objects

The core functionality of Ntropy API is the enrichment of transactions. Each transaction is understood by our system and a structured response is returned containing all the extracted information. The API supports both enrichment synchronously up to 4000 transactions and asynchronously up to 24960 transactions in the same batch.

Input Transaction Object​

The enrichment process requires a list of transaction objects as input and outputs a list of enriched transaction objects (in the same order) containing additional structured information. The input transaction object contains the following fields:

attributetypesummary
descriptionstringDescription text of the transaction. Has a maximum length of 1024 characters.
entry_typeenumDirection of the flow of money from the perspective of the account holder. Possible values are incoming and outgoing.
amountfloatAmount of the transaction. Should always be a positive number. Use entry_type to represent the direction of the flow of money.
iso_currency_codestringCurrency of the transaction in ISO-4217 format. See supported options.
datedateDate when the transaction was made in ISO-8601 format, i.e. YYYY-MM-DD.
transaction_idstringUnique identifier of the transaction in your system.
countrystring(optional) - The country where the transaction was made in ISO-3166-2 format. See supported options.
account_holder_idstring(optional) - Unique identifier of the account holder in your system.
account_holder_typeenum(optional) - Type of the account holder. Possible values are consumer, business.
account_holder_namestring(optional) - Name of the account holder. Can significantly improve enrichment quality if provided.

In the transaction model, the amount attribute must always be positive, as the direction of the flow of money is represented only by the entry_type attribute. From the point of view of the account holder, if a transaction represents money leaving the account it should have an entry_type value of outgoing (debit), and if a transaction represents money entering an account it should have an entry_type value of incoming (credit).

caution

Multiple transactions submitted with the same transaction_id will be considered the same transaction, where the most recent will replace previous submissions.

While providing account holder information is optional, it is needed for labeling. If neither account_holder_id nor account_holder_type are provided, labeling will be disabled. The account_holder_name field is also optional but can significantly improve enrichment quality if provided. Check the Account Holder section for more information regarding this.

Enriched Output Transaction Object​

The enriched transactions that are returned by the API will contain the set of fields described below.

attributetypesummary
labelslist(string)Label from our live hierarchy, depending on the type of account holder (consumer, business).
label_groupstringHigher level category that groups together related labels
recurrenceenumIndicates whether a transaction is a one-time transfer, e.g. purchasing a mattress (one-off), regularly repeats with personalized pricing, e.g. utilities, mortgage (recurring), regularly repeats with fixed pricing (subscription).
recurrence_groupRecurrenceGroupIf a transaction is recurrent, this is a RecurrenceGroup object with fields described below, (null if transaction is not recurrent).
locationstringLocation of the transaction (if a location is present) as a formatted string.
location_structuredLocationStructuredLocation of the transaction (if a location is present) as a structured object.
logostring, url formatLogo of the merchant (if a merchant is present).
merchantstringNormalized merchant name (if a merchant is present).
merchant_idstringUnique merchant identifier (if a merchant is present).
personstringName of the person in the transaction text (if a person is present).
transaction_idstringUnique transaction identifier.
websitestringWebsite of the merchant (if a merchant is present).
mcclist(int)Predicted MCC codes, usually containing a single value. Can be multiple values if the merchant can operate with multiple MCCs (if a merchant is present).
intermediarieslist(object)List of objects containing the properties id, name, website and logo corresponding to all the intermediary merchants of the transaction (i.e., the payment processor)

Most of the output fields listed above can be enabled / disabled for your specific API key, and if disabled they won't be returned by the API. You can check your MSA for details. You can also reach out to Ntropy Support at support@ntropy.com for more information regarding returned fields.

Nullable fields​

In the enriched transaction some fields may be null if it was not possible (or does not make sense in the context of the request) to determine its value. For example: merchant, merchant_id, logo, website and mcc will be set to null if a merchant is not detected in a transaction. There are also fields that must be enabled for an account per request through any support communication channel.