Skip to main content

Ntropy Transaction API

The world's most powerful, multi-geo, multi-lingual transaction categorization API.

Authentication

ApiKeyAuth

Security Scheme Type API Key
Header parameter name: X-API-KEY

Enrichment

Transaction enrichment.

Enrich and add transactions to the ledger of account holders synchronously.

Add transactions to the ledgers of account holders and get back enriched version of the transactions in the response. Accepts batch sizes up to 4k transactions. A single transaction should take ~100ms. A batch of 4000 transactions should take ~40s.

Authorizations:
query Parameters
model_name
string

If provided, the transaction enrichment will use the referenced custom model for labelling

Request Body schema: application/json
Array (<= 4000 items)
transaction_id
required
string non-empty

A unique identifier of the transaction

account_holder_id
string or null non-empty

The unique ID of the account holder of the transaction

account_holder_type
string or null
Enum: "consumer" "business" "freelance" "unknown"

The type of an account holder, may be one of 'consumer', 'business', 'freelance' or 'unknown'.

amount
required
number >= 0

The amount of the transaction

entry_type
required
string
Enum: "incoming" "outgoing"

The direction of the transaction (incoming or outgoing)

date
required
string or null <date>

The date that the transaction was posted. Uses ISO 8601 format (YYYY-MM-DD)

iso_currency_code
required
string <currency>

The currency of the transaction in ISO 4217 format

description
required
string [ 0 .. 1024 ] characters

The description string of the transaction

country
string[A-Z]{2}(-[A-Z0-9]{1,3})?

The country where the transaction was made in ISO 3166-2 format

mcc
number [ 700 .. 9999 ]

The Merchant Category Code of the merchant according to ISO 18245

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Enrich and add transactions to the ledgers of account holders asynchronously.

Add a batch of transactions to the ledgers of account holders. Return the batch id that has been assigned to this batch. A batch of 100k transactions should take 5-10mins.

Authorizations:
query Parameters
model_name
string

If provided, the transaction enrichment will use the referenced custom model for labelling

Request Body schema: application/json
Array (<= 100000 items)
transaction_id
required
string non-empty

A unique identifier of the transaction

account_holder_id
string or null non-empty

The unique ID of the account holder of the transaction

account_holder_type
string or null
Enum: "consumer" "business" "freelance" "unknown"

The type of an account holder, may be one of 'consumer', 'business', 'freelance' or 'unknown'.

amount
required
number >= 0

The amount of the transaction

entry_type
required
string
Enum: "incoming" "outgoing"

The direction of the transaction (incoming or outgoing)

date
required
string or null <date>

The date that the transaction was posted. Uses ISO 8601 format (YYYY-MM-DD)

iso_currency_code
required
string <currency>

The currency of the transaction in ISO 4217 format

description
required
string [ 0 .. 1024 ] characters

The description string of the transaction

country
string[A-Z]{2}(-[A-Z0-9]{1,3})?

The country where the transaction was made in ISO 3166-2 format

mcc
number [ 700 .. 9999 ]

The Merchant Category Code of the merchant according to ISO 18245

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "status": "started",
  • "updated_at": "2019-11-30 18:32:28+00:00",
  • "progress": 88,
  • "id": "247ee045-3d04-4b3c-872b-a9160b810f33"
}

Fetch the result of a batch transaction enrichment.

Get a result of batch transaction enrichments. The id field should be as returned by /v2/transactions/async.

Authorizations:
path Parameters
id
required
string <uuid> 36 characters
Example: 247ee045-3d04-4b3c-872b-a9160b810f33

Batch id.

Responses

Request samples

curl -X "GET" \
  "https://api.ntropy.com/v2/transactions/async/{batch_id}" \
  -H "accept: application/json" \
  -H "X-API-KEY: $NTROPY_API_KEY"

Response samples

Content type
application/json
{
  • "status": "finished",
  • "updated_at": "2019-11-30 18:32:28+00:00",
  • "progress": 88,
  • "id": "247ee045-3d04-4b3c-872b-a9160b810f33",
  • "results": [
    ]
}

Account Holder

Ledger operations.

Create an account holder.

Create an account holder and start tracking its ledger. The account holder can be a consumer, business, freelancer or unknown.

Authorizations:
Request Body schema: application/json
id
required
string non-empty
type
required
string (AccountHolderType)
Enum: "consumer" "business" "freelance" "unknown"

The type of an account holder, may be one of 'consumer', 'business', 'freelance' or 'unknown'

name
string or null
industry
string or null
website
string or null
property name*
any

Responses

Request samples

Content type
application/json
{
  • "id": "67890",
  • "type": "business",
  • "name": "Ntropy Network Inc.",
  • "industry": "fintech",
  • "website": "ntropy.com"
}

Retrieve the information of an account holder.

Retrieve the stored information for an account holder.

Authorizations:
path Parameters
account_holder_id
required
string
Example: 247ee045-3d04-4b3c-872b-a9160b810f33

Responses

Request samples

curl -X "GET" \
  "https://api.ntropy.com/v2/account-holder/{account_holder_id}" \
  -H "accept: application/json" \
  -H "X-API-KEY: $NTROPY_API_KEY"

Response samples

Content type
application/json
{
  • "id": "67890",
  • "type": "business",
  • "name": "Ntropy Network Inc.",
  • "industry": "fintech",
  • "website": "ntropy.com"
}

List transactions of an account holder.

Fetch all the transactions in the transaction ledger of an account holder.

Authorizations:
path Parameters
account_holder_id
required
string
Example: 247ee045-3d04-4b3c-872b-a9160b810f33
query Parameters
page
integer
Default: 0

What page to start from.

per_page
integer [ 1 .. 10000 ]
Default: 1000

Number of results per page.

Responses

Request samples

curl -X "GET" \
  "https://api.ntropy.com/v2/account-holder/{account_holder_id}/transactions?page=0&per_page=1000" \
  -H "accept: application/json" \
  -H "X-API-KEY: $NTROPY_API_KEY"

Response samples

Content type
application/json
{
  • "transactions": [
    ],
  • "pages": 0
}

Query the transaction ledger of an account holder.

Submit a query to the transaction ledger of an account holder.

Authorizations:
path Parameters
account_holder_id
required
string
Example: 247ee045-3d04-4b3c-872b-a9160b810f33
Request Body schema: application/json
metrics
Array of strings (AccountHolderMetricName)
Items Enum: "overall_stats" "stats_by_label" "stats_by_merchant"
start
string <date-time>
end
string <date-time>
property name*
any

Responses

Request samples

Content type
application/json
{
  • "metrics": [
    ],
  • "start": "2022-01-01T00:00:00",
  • "end": "2022-02-01T00:00:00"
}

Response samples

Content type
application/json
{
  • "overall_stats": {
    },
  • "stats_by_label": {
    },
  • "stats_by_merchant": {
    }
}

Categorize an account holder's histories income by their frequency and type

Given the history of transactions of an account holder, determines income sources based on grouping transactions by income groups accounting for their amounts, frequency, source and other properties. The information returned is a summary of all income groups for this account holder.

Authorizations:
path Parameters
account_holder_id
required
string
Example: 247ee045-3d04-4b3c-872b-a9160b810f33

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Identify existing recurring payments for an account holder's transaction history.

Given the history of transactions of an account holder, determines existing recurring payments and related properties such as the type (subscription or bill), amount, periodicity, etc...

Authorizations:
path Parameters
account_holder_id
required
string
Example: 247ee045-3d04-4b3c-872b-a9160b810f33

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Misc

Other.

Report a wrongly classified transaction.

Report a wrongly classified transaction specifying expected enrichment values.

Authorizations:
Request Body schema: application/json
transaction_id
required
string
logo
string or null
website
string or null
location
string or null
merchant
string or null
merchant_id
string or null
labels
Array of strings or null
person
string or null
recurrence
string or null
recurrence_group_id
string or null
mcc
Array of integers or null
notes
string or null
property name*
any

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "xbx8YP14g565Xketw3tFmn4yp49x3tbj9mD8DB4fM8DDY6x",
  • "website": "www.expected.website",
  • "merchant": "Other Merchant"
}

Get the hierarchy of Ntropy labels

Get the hierarchy of Ntropy labels

path Parameters
account_holder_type
required
string (AccountHolderType)
Enum: "consumer" "business" "freelance" "unknown"

The type of the transaction account holder (consumer, business, or freelance)

Responses

Request samples

curl -X "GET" \
  "https://api.ntropy.com/v2/labels/hierarchy/consumer" \
  -H "accept: application/json"

Response samples

Content type
application/json
{
  • "professional services": [
    ],
  • "infrastructure": [
    ],
  • "fees": [
    ],
  • "employees": {
    },
  • "insurance": [ ]
}

Check API health.

Get the API health info.

Responses

Request samples

curl -X "GET" \
  "https://api.ntropy.com/health" \
  -H "accept: */*"

Response samples

Content type
application/json
{
  • "status": "ok",
  • "updated_at": 1655476329.8150651
}

Custom Models

Get all available custom labelling models.

Authorizations:

Responses

Request samples

curl -X "GET" \
  "https://api.ntropy.com/v2/models" \
  -H "accept: application/json" \
  -H "X-API-KEY: $NTROPY_API_KEY"

Response samples

Content type
application/json
[
  • {
    }
]

Train a custom labelling model with unique name.

Using a set of pre-labeled transactions, trains a custom labelling model that is tuned in the provided dataset and associated with an unique name. To use the trained model for labeling, use the model_name parameter of the /transactions/sync or /transactions/async API call parameter of the /transactions/sync or /transactions/async API call.

Authorizations:
path Parameters
name
required
string
Example: my-model-name

Model name.

Request Body schema: application/json
required
Array of objects (LabelledTransaction) [ 1 .. 50000 ] items [ items ]
property name*
any

Responses

Request samples

Content type
application/json
{
  • "transactions": [
    ]
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "progress": 0,
  • "status": "string"
}

Get requested model status.

Get requested model status identified by name

Authorizations:
path Parameters
name
required
string
Example: my-model-name

Model name.

Responses

Request samples

curl -X "GET" \
  "https://api.ntropy.com/v2/models/{name}" \
  -H "accept: application/json" \
  -H "X-API-KEY: $NTROPY_API_KEY"

Response samples

Content type
application/json
{
  • "name": "string",
  • "progress": 0,
  • "status": "string"
}