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:
| attribute | type | summary |
|---|---|---|
| description | string | Description text of the transaction. Has a maximum length of 1024 characters. |
| entry_type | enum | Direction of the flow of money from the perspective of the account holder. Possible values are incoming and outgoing. |
| amount | float | Amount of the transaction. Should always be a positive number. Use entry_type to represent the direction of the flow of money. |
| iso_currency_code | string | Currency of the transaction in ISO-4217 format. See supported options. |
| date | date | Date when the transaction was made in ISO-8601 format, i.e. YYYY-MM-DD. |
| transaction_id | string | Unique identifier of the transaction in your system. |
| country | string | (optional) - The country where the transaction was made in ISO-3166-2 format. See supported options. |
| account_holder_id | string | (optional) - Unique identifier of the account holder in your system. |
| account_holder_type | enum | (optional) - Type of the account holder. Possible values are consumer, business. |
| account_holder_name | string | (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).
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.
| attribute | type | summary |
|---|---|---|
| labels | list(string) | Label from our live hierarchy, depending on the type of account holder (consumer, business). |
| label_group | string | Higher level category that groups together related labels |
| recurrence | enum | Indicates 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_group | RecurrenceGroup | If a transaction is recurrent, this is a RecurrenceGroup object with fields described below, (null if transaction is not recurrent). |
| location | string | Location of the transaction (if a location is present) as a formatted string. |
| location_structured | LocationStructured | Location of the transaction (if a location is present) as a structured object. |
| logo | string, url format | Logo of the merchant (if a merchant is present). |
| merchant | string | Normalized merchant name (if a merchant is present). |
| merchant_id | string | Unique merchant identifier (if a merchant is present). |
| person | string | Name of the person in the transaction text (if a person is present). |
| transaction_id | string | Unique transaction identifier. |
| website | string | Website of the merchant (if a merchant is present). |
| mcc | list(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). |
| intermediaries | list(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.