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 24960 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 (<= 24960 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.

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
}

Get transactions of an account holder by transaction id.

Fetch all the transactions matching given transaction ids in the transaction ledger of an account holder. Transactions returned will be in arbitrary order.

Authorizations:
path Parameters
account_holder_id
required
string
Example: 247ee045-3d04-4b3c-872b-a9160b810f33
Request Body schema: application/json
Array
string <= 5000 characters

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

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

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 (DateOrDateTime)
end
string (DateOrDateTime)
property name*
any

Responses

Request samples

Content type
application/json
{
  • "metrics": [
    ],
  • "start": "2022-01-01 00:00:00",
  • "end": "2022-02-01 00: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
webhook_url
string or null
property name*
any

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "status": "string",
  • "id": "string",
  • "created_at": "2019-08-24",
  • "transaction_id": "string",
  • "webhook_url": "string"
}

List all submited reports (paginated and filterable).

Given a page size and page number, lists a specific page of previously submitted reports, optionally filtered by status and transaction_id.

Authorizations:
query Parameters
per_page
integer [ 1 .. 10000 ]
Default: 1000

Number of results per page.

page
integer
Default: 0

What page to start from.

status
string

Report status to filter by.

transaction_id
string

Report transaction_id to filter by.

Responses

Response samples

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

Returns a report by id

Returns all the available information about a previously submitted report by it's identifier.

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

Report id.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "id": "string",
  • "created_at": "2019-08-24",
  • "transaction_id": "string",
  • "webhook_url": "string"
}

Get the hierarchy of Ntropy labels

Get the hierarchy of Ntropy labels

Authorizations:
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": [ ]
}

Get the current personalization ruleset.

Get the current personalization ruleset.

Authorizations:

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set the personalization ruleset.

Set the personalization ruleset.

Authorizations:
Request Body schema: application/json
Array
Any of
required
boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
Array of any (action) [ items ]
Array of any (action) [ items ]

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Delete a rule.

Delete the rule at the specified index from the personalization ruleset.

Authorizations:
path Parameters
index
required
integer

Responses

Request samples

curl -X "DELETE" \
  "https://api.ntropy.com/v2/rules/0" \
  -H "accept: */*" \
  -H "X-API-KEY: $NTROPY_API_KEY" \

Replace a rule.

Replace the rule at the specified index in the personalization ruleset.

Authorizations:
path Parameters
index
required
integer
Request Body schema: application/json
Any of
required
boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
Array of any (action) [ items ]
Array of any (action) [ items ]

Responses

Request samples

Content type
application/json
Example
{
  • "if": true,
  • "then": [
    ],
  • "else": [
    ]
}

Append a rule.

Append a rule to the personalization ruleset.

Authorizations:
Request Body schema: application/json
Any of
required
boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
Array of any (action) [ items ]
Array of any (action) [ items ]

Responses

Request samples

Content type
application/json
Example
{
  • "if": true,
  • "then": [
    ],
  • "else": [
    ]
}

Get an account holder's personalization ruleset.

Get an account holder's personalization ruleset.

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set an account holder's personalization ruleset.

Set an account holder's personalization ruleset.

Authorizations:
path Parameters
account_holder_id
required
string
Example: 247ee045-3d04-4b3c-872b-a9160b810f33
Request Body schema: application/json
Array
Any of
required
boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
Array of any (action) [ items ]
Array of any (action) [ items ]

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Append a rule.

Append a rule to an account holder's personalization ruleset.

Authorizations:
path Parameters
account_holder_id
required
string
Example: 247ee045-3d04-4b3c-872b-a9160b810f33
Request Body schema: application/json
Any of
required
boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
Array of any (action) [ items ]
Array of any (action) [ items ]

Responses

Request samples

Content type
application/json
Example
{
  • "if": true,
  • "then": [
    ],
  • "else": [
    ]
}

Delete a rule

Delete the rule at the specified index from an account holder's personalization ruleset.

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

Responses

Request samples

curl -X "DELETE" \
  "https://api.ntropy.com/v2/rules/0" \
  -H "accept: */*" \
  -H "X-API-KEY: $NTROPY_API_KEY" \

Replace a rule

Replace the rule at the specified index in an account holder's personalization ruleset.

Authorizations:
path Parameters
account_holder_id
required
string
Example: 247ee045-3d04-4b3c-872b-a9160b810f33
index
required
integer
Request Body schema: application/json
Any of
required
boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
Array of any (action) [ items ]
Array of any (action) [ items ]

Responses

Request samples

Content type
application/json
Example
{
  • "if": true,
  • "then": [
    ],
  • "else": [
    ]
}

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
}

Bank statements

Submit and view bank statements.

Retrieves paginated information of multiple bank statements

Authorizations:
query Parameters
status
string (DocumentStatus)
Enum: "queued" "processing" "processed" "failed"

An enumeration.

page
integer (Page) >= 0
Default: 0
page_size
integer (Page Size) [ 1 .. 1000 ]
Default: 20
order_by
string (Order By)
Default: "desc"
Enum: "desc" "asc"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Submit a bank statement

Authorizations:
Request Body schema: multipart/form-data
file
required
string <binary> (File)

Responses

Response samples

Content type
application/json
{
  • "doc_type": "payslip",
  • "id": "string",
  • "user_id": 0,
  • "filename": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Retrieve information of a bank statement

Authorizations:
path Parameters
uuid
required
string (Uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "uuid": "string",
  • "fname": "string",
  • "status": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "transactions": [
    ],
  • "error_code": 0,
  • "error": "string"
}

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"
}