Instant integration with Ntropy API

View our quickstart guide for Postman collection and start testing right now.

from ntropy_sdk import SDK, Transaction

sdk = SDK("YOUR-API-KEY")

transaction = Transaction(
   amount=12042.6,
   description="AMAZON WEB SERVICES AWS.AMAZON.CO WA Ref5543286P25S: Crd15",
   entry_type="outgoing",
   account_holder_id="1",
   account_holder_type="business",
   iso_currency_code="USD",
   country="US",
)

batch = sdk.enrich_batch([transaction])
enriched_list = batch.wait_with_progress()
print("BATCH: ", enriched_list.transactions[0].labels)

enriched = sdk.enrich(transaction)
print("REALTIME: ", enriched.labels)

Quick Start Guide

The Ntropy API provides functionality to enrich financial transactions adding structured merchant information and labels. To take a glimpse of what you get from the API, try it out with this simple UI at try.ntropy.network. You will be presented with a simple form which you can use to make requests to the Ntropy API.

Try now

The input fields of the form are the following:

  • Account holder type: this field specifies whether the owner of the account from which the transaction was made is a consumer or a business entity.
  • Entry type: the direction of the flow of money from the perspective of the account holder, i.e. incoming or outgoing.
  • Description: the description text of the transaction.
  • Amount: the amount of the transaction.
  • Currency: the currency of the transaction.

After filling in the form or using the pre-filled values, press the Submit button and you will get the result below. As you may see, what you get back is:

  • The normalized name of the merchant the transaction was made to
  • The logo, website and address of the merchant
  • The labels assigned to the transaction

The Ntropy API has a simple interface with which you may supply transactions one at a time or in batches (of up to 100k transactions in each). You may explore the API in detail using the Swagger UI or Postman collection.

Authentication

In order to authenticate with the Ntropy API you need to have an API key and supply it in the X-API-KEY header of your HTTP requests.

Request API Key

Calling the Ntropy API directly

The Ntropy API is a regular HTTP API which may be called using any programming language. This section will walk you through the API using cURL. To begin, let’s first define some variables that will be used multiple times throughout this tutorial:

$ export NTROPY_API_URL=https://api.ntropy.network
$ export NTROPY_API_KEY=<REPLACE-THIS-WITH-YOUR-API-KEY>

Enriching a single transaction

Let’s start by enriching a single transaction using the /v2/enrich endpoint of Ntropy API. The input to this endpoint must be a Transaction JSON object, with the following fields:

  • description - the description text of the transaction
  • entry_type - the direction of the flow of money from the perspective of the account holder, i.e incoming or outgoing
  • amount - the amount of the transaction
  • iso_currency_code - the currency of the transaction in ISO-4217 format
  • date - the date when the transaction was made in ISO-8601 format, i.e. YYYY-MM-DD
  • transaction_id - a unique identifier of the transaction in your system
  • country (optional) - the country where the transaction was made in ISO-3166-2 format
  • account_holder - an object containing information about the holder of the account from which the transaction was made. The AccountHolder object must have the following fields:
    • id - unique identifier of the account holder in your system
    • type - the type of the account holder entity, i.e. consumer or business
    • details (optional) - object containing details about the account holder company (when type is business) with the following fields:
      • country_of_headquarters - country where the account holder company is incorporated
      • founded - year the account holder company was founded
      • industry - industry of the account holder company
      • number_of_employees - the number of employees the account holder company has

So let’s build the Transaction object and make a request to the Ntropy API with cURL like this:

$ curl \
-H "X-API-KEY: $NTROPY_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
--data '{
  "description": "AMAZON WEB SERVICES AWS.AMAZON.CO WA Ref5543286P25S Crd15",
  "entry_type": "outgoing",
  "amount": 12042.37,
  "iso_currency_code": "USD",
  "date": "2021-11-01",
  "transaction_id": "D8DB4fM8DDY6Yxbx8YP14g565Xketw3tFmn",
  "country": "US",
  "account_holder": {
    "id": "business-2",
    "type": "business"
  }
}' \
$NTROPY_API_URL/v2/enrich

You will get back the enriched transaction information as a JSON object, e.g.:

{
  "contact": {
    "email": null,
    "phone": null
  },
  "labels": [
    "infrastructure",
    "cloud operations"
  ],
  "location": {
    "address": "710 S Girls School Rd (bt Mt Herman Av & W McCarty St) Indianapolis, IN 46231 United States",
    "city": "Indianapolis",
    "country": "United States",
    "lat": 39.75652171278593,
    "lon": -86.29150852338404,
    "postal_code": "46231"
  },
  "logo": "https://www.bing.com/th?id=AMMS_234d7638413b734c1560bf8e7f642960&w=110&h=110&c=7&rs=1&qlt=95&cdv=1&pid=16.1",
  "merchant": "Amazon",
  "person": null,
  "transaction_id": "D8DB4fM8DDY6Yxbx8YP14g565Xketw3tFmn",
  "website": "amazon.com"
}

The fields of the response you will get are as follows:

  • person - the name of the person in the transaction text (if a person is present)
  • merchant - the normalized name of the merchant (if a merchant is present)
  • contact - an object containing the email and phone of the merchant in respective fields
  • website - the website address of the merchant
  • logo - a URL to the logo of the merchant
  • location - an object describing the location of the merchant with the following fields:
    • address - the address of the merchant
    • postal_code - the postal code of the merchant
    • city - the city where the merchant is located
    • country - the country where the merchant is located
    • lat - the geographic latitude of the merchant’s location
    • lon - the geographic longitude of the merchant’s location

In addition to the merchant information, you also get back a list of labels in the labels field which describe the transaction. You may find the full list of possible labels organized in a hierarchy by querying the /v2/labels/hierarchy/consumer and /v2/labels/hierarchy/business endpoints, which will return the labels hierarchies for consumer and business account holders respectively. For example:

$ curl $NTROPY_API_URL/v2/labels/hierarchy/business
{
  ...
  "infrastructure": [
    "cloud operations",
    "manufacturing",
    "servers",
    "website"
  ],
  "insurance": [],
  "investment": [
    "bonds and shares debt",
    "bonds and shares debt repayment",
    "distributions",
    "dividends",
    "equity",
    "share repurchase",
    "redemption"
  ],
  "personnel": {
    "contractors": [],
    "crowd outsourcing": [],
    "employees": {
      "benefits": [
        "dental",
        "healthcare",
        "retirement funds"
      ],
      "payroll": [
        "fees",
        "salary",
        "tax"
      ]
    },
    "recruiting": [],
    "training and education": []
  },
  ...
}

If you are only interested in the merchant information, you may disable labeling by passing in the labeling=false query parameter, which will return the response faster than with labeling enabled, e.g.:

$ curl \
-H "X-API-KEY: $NTROPY_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
--data '{
  ...
}' \
$NTROPY_API_URL/v2/enrich?labeling=false

By default, labeling is enabled. You may further speed up the response time at the expense of accuracy by passing in the latency_optimized=true query parameter. By default, this parameter is false.

Enriching transactions in batches

In addition to the /v2/enrich endpoint, the Ntropy API provides you with the /v2/enrich/batch endpoint, where you may submit a list of transactions as an input and get enriched transactions in a single batch. For the sake of brevity, we will only submit 2 transactions in this example, but in real-world cases you may submit up to 100k transactions in one batch. Let’s try:

$ curl \
-H "X-API-KEY: $NTROPY_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
--data '[
{
    "description": "AMAZON WEB SERVICES AWS.AMAZON.CO WA Ref5543286P25S Crd15",
    "entry_type": "outgoing",
    "amount": 12042.37,
    "iso_currency_code": "USD",
    "date": "2021-11-01",
    "transaction_id": "4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g565Xketw3tFmn",
    "country": "US",
    "account_holder": {
      "id": "business-2",
      "type": "business"
    }
  },
  {
    "description": "PAYGOV 8452036",
    "entry_type": "outgoing",
    "amount": 567.89,
    "iso_currency_code": "USD",
    "date": "2021-11-02",
    "transaction_id": "tw3tFmn4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g565Xke",
    "country": "US",
    "account_holder": {
      "id": "business-1",
      "type": "business"
    }
  }
]' \
$NTROPY_API_URL/v2/enrich/batch

You will get back a JSON object as a response containing an identifier for the batch you just submitted, along with the status of the batch:

{
  "id": "39a316c6-eb48-4dc4-a094-025243221ddc",
  "status": "started",
  "updated_at": "2021-10-28T08:32:55.340976+00:00"
}

The id field is to be used with the /v2/enrich/batch/{id} endpoint to request the enriched batch results. Let’s try it:

$ curl \
-H "X-API-KEY: $NTROPY_API_KEY" \
$NTROPY_API_URL/v2/enrich/batch/39a316c6-eb48-4dc4-a094-025243221ddc

If the processing is still in progress, you will get back a response similar to the previous request, with the progress field showing the number of transactions from the batch that have finished processing. When the batch enrichment is complete, the status field will be set to finished and the object in the response will contain an additional results field, which will hold the list of enriched transactions, e.g.:

{
  "id": "39a316c6-eb48-4dc4-a094-025243221ddc",
  "progress": 2,
  "results": [
    {
      "contact": {
        "email": null,
        "phone": null
      },
      "labels": [
        "infrastructure",
        "cloud operations"
      ],
      "location": {
        "address": "710 S Girls School Rd (bt Mt Herman Av & W McCarty St) Indianapolis, IN 46231 United States",
        "city": "Indianapolis",
        "country": "United States",
        "lat": 39.75652171278593,
        "lon": -86.29150852338404,
        "postal_code": "46231"
      },
      "logo": "https://www.bing.com/th?id=AMMS_234d7638413b734c1560bf8e7f642960&w=110&h=110&c=7&rs=1&qlt=95&cdv=1&pid=16.1",
      "merchant": "Amazon",
      "person": null,
      "transaction_id": "4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g565Xketw3tFmn",
      "website": "amazon.com"
    },
    {
      "contact": {
        "email": null,
        "phone": null
      },
      "labels": [
        "government",
        "tax",
        "tax payment"
      ],
      "location": {
        "address": null,
        "city": null,
        "country": null,
        "lat": null,
        "lon": null,
        "postal_code": null
      },
      "logo": "https://icons.duckduckgo.com/ip3/pay.gov.ico",
      "merchant": "Pay.gov",
      "person": null,
      "transaction_id": "565Xketw3tFmn4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g",
      "website": "pay.gov"
    }
  ],
  "status": "finished",
  "total": 2,
  "updated_at": "2021-10-28T08:55:25.294044+00:00"
}

Just like the single transaction enrichment endpoint, the batch endpoint also supports the labeling=false query parameter to disable labeling for all transactions in the batch.

Reporting a wrongly enriched transaction

If you find out that a transaction has been labelled wrongly or a wrong merchant has been identified, you may submit that transaction for our review by using the /v2/report endpoint using its respective transaction_id field. e.g:

$ curl \
-H "X-API-KEY: $NTROPY_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
--data '{
    "transaction_id": "ybx8YP14g565Xketw3t9x3tbj9mD8DB4fM8DDY6Y"
}' \
$NTROPY_API_URL/v2/report

Using the Ntropy SDK with Python

Instead of calling the Ntropy API directly you can also make use of the Ntropy Python SDK which is available publicly in PyPI. The Ntropy SDK is a handy Python wrapper around the Ntropy API which provides additional functionality like running benchmarks.

To find more information on how to use the Ntropy SDK have a look at the GitHub repository which includes guides and examples.

Ntropy SDK on GitHub

Using the Ntropy API Postman collections

To get started with our API using Postman, you can use our public Postman collection here.

  • Click Run in Postman, then run in either your browser or the Postman desktop app (if you've installed this).
  • Select a relevant workspace and click to import the collection. You should now be in the Authorization tab of Ntropy Transaction API.
  • Replace the {{apiKey}} text with your API key, then click Save on the action bar above.
  • You should now be ready to use the API.
Testing your transactions in Postman

The simplest way to test out your own transactions:

  • Click Ntropy Transaction API in the left column
  • Click v2
  • Click enrich
  • Click Enrich a transaction.
  • Click Body in the top bar.
  • The Body page allows you to match the payload sent to the server to the fields you would like to test (some sample fields have already been filled in).
  • When you have finished editing, click Send at the top right.
  • The response should appear in the bottom half of the page.
View Postman collection

API Key

You need an API key to access the Ntropy Transaction API. To get one, please contact us.

Get API Key

OpenAPI 3.x compatible

Use the link below to download our OpenAPI 3.x compatible API definition.

API Definition
Swagger icon

Swagger UI

We also provide Swagger UI for performing interactive queries.

Swagger UI

Ready to get started?

Ntropy can turn your raw transactions into rich data with enhanced merchant information and custom labels.

Request API Key