Ntropy Transaction API

API Support: api@ntropy.com URL: https://ntropy.com/developers

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:

ApiKeyAuth

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

Payload
cURL
Python SDK

Content type

application/json

[{"transaction_id": "xbx8YP14g565Xketw3tFmn4yp49x3tbj9mD8DB4fM8DDY6x",
"account_holder_id": "35b927b6-6fda-40aa-93b8-95b47c2b2cad",
"account_holder_type": "business",
"amount": 12046.15,
"entry_type": "outgoing",
"date": "2019-12-01",
"iso_currency_code": "USD",
"country": "US",
"description": "AMAZON WEB SERVICES AWS.AMAZON.CO WA Ref5543286P25S Crd15"
}
]

Response samples

200
404

Content type

application/json

[{"transaction_id": "xbx8YP14g565Xketw3tFmn4yp49x3tbj9mD8DB4fM8DDY6x",
"logo": "https://logos.ntropy.com/aws.amazon.com",
"website": "aws.amazon.com",
"location": "wa",
"merchant": "Amazon Web Services",
"merchant_id": "2c0c799b-d003-30a6-9f53-878f3ebf46aa",
"labels": ["infrastructure",
"cloud operations"
],
"recurrence": "recurring",
"recurrence_group": {"id": "3b0c689b-e123-30a6-9f53-878f3ebf46aa",
"first_payment_date": "2020-02-02",
"latest_payment_date": "2022-02-02",
"total_amount": 130,
"average_amount": 65,
"periodicity_in_days": 31,
"other_party": "aws.amazon.com",
"periodicity": "monthly",
"transaction_ids": ["b708fbd8-be76-41c2-86d5-83f8ba05ed85",
"0e34b24d-646d-416e-8d51-fda5b6e10684"
]
},
"recurrence_group_id": "3b0c689b-e123-30a6-9f53-878f3ebf46aa",
"mcc": [4816
],
"person": null,
"transaction_type": "business"
}
]

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:

ApiKeyAuth

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

Payload
cURL
Python SDK

Content type

application/json

[{"transaction_id": "xbx8YP14g565Xketw3tFmn4yp49x3tbj9mD8DB4fM8DDY6x",
"account_holder_id": "35b927b6-6fda-40aa-93b8-95b47c2b2cad",
"account_holder_type": "business",
"amount": 12046.15,
"entry_type": "outgoing",
"date": "2019-12-01",
"iso_currency_code": "USD",
"country": "US",
"description": "AMAZON WEB SERVICES AWS.AMAZON.CO WA Ref5543286P25S Crd15"
}
]

Response samples

202
404

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:

ApiKeyAuth

path Parameters

id

required

string <uuid> 36 characters

Example: 247ee045-3d04-4b3c-872b-a9160b810f33

Batch id.

Responses

Request samples

cURL

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

200
404

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": [{"transaction_id": "xbx8YP14g565Xketw3tFmn4yp49x3tbj9mD8DB4fM8DDY6x",
"logo": "https://logos.ntropy.com/aws.amazon.com",
"website": "aws.amazon.com",
"location": "wa",
"merchant": "Amazon Web Services",
"merchant_id": "2c0c799b-d003-30a6-9f53-878f3ebf46aa",
"labels": ["infrastructure",
"cloud operations"
],
"recurrence": "recurring",
"recurrence_group": {"id": "3b0c689b-e123-30a6-9f53-878f3ebf46aa",
"first_payment_date": "2020-02-02",
"latest_payment_date": "2022-02-02",
"total_amount": 130,
"average_amount": 65,
"periodicity_in_days": 31,
"other_party": "aws.amazon.com",
"periodicity": "monthly",
"transaction_ids": ["b708fbd8-be76-41c2-86d5-83f8ba05ed85",
"0e34b24d-646d-416e-8d51-fda5b6e10684"
]
},
"recurrence_group_id": "3b0c689b-e123-30a6-9f53-878f3ebf46aa",
"mcc": [4816
],
"person": null
}
]
}

Account Holder

Ledger operations.

Retrieve the information of an account holder.

Retrieve the stored information for an account holder.

Authorizations:

ApiKeyAuth

path Parameters

account_holder_id

required

string

Example: 247ee045-3d04-4b3c-872b-a9160b810f33

Responses

Request samples

cURL
Python SDK

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

200
404

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:

ApiKeyAuth

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

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

200

Content type

application/json

{"transactions": [{"transaction_id": "string",
"account_holder_id": "string",
"amount": 0,
"entry_type": "incoming",
"date": "2019-08-24",
"iso_currency_code": "string",
"description": "string",
"country": "string",
"logo": "string",
"website": "string",
"location": "string",
"merchant": "string",
"merchant_id": "string",
"labels": ["string"
],
"recurrence": "recurring",
"recurrence_group_id": "string",
"person": "string",
"intermediaries": [{"name": "string",
"id": "string",
"website": "string",
"logo": "string"
}
]
}
],
"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:

ApiKeyAuth

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

Payload
cURL

Content type

application/json

["string"
]

Response samples

200

Content type

application/json

{"transactions": [{"transaction_id": "string",
"account_holder_id": "string",
"amount": 0,
"entry_type": "incoming",
"date": "2019-08-24",
"iso_currency_code": "string",
"description": "string",
"country": "string",
"logo": "string",
"website": "string",
"location": "string",
"merchant": "string",
"merchant_id": "string",
"labels": ["string"
],
"recurrence": "recurring",
"recurrence_group_id": "string",
"person": "string",
"intermediaries": [{"name": "string",
"id": "string",
"website": "string",
"logo": "string"
}
]
}
]
}

Query the transaction ledger of an account holder.

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

Authorizations:

ApiKeyAuth

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

Payload
cURL
Python SDK

Content type

application/json

{"metrics": ["overall_stats",
"stats_by_label",
"stats_by_merchant"
],
"start": "2022-01-01T00:00:00",
"end": "2022-02-01T00:00:00"
}

Response samples

200

Content type

application/json

{"overall_stats": {"outgoing": {"USD": {"sum": 100,
"count": 1,
"mean": 100,
"std": 0,
"min": 100,
"max": 100
}
},
"incoming": {"USD": {"sum": 100,
"count": 2,
"mean": 50,
"std": 0,
"min": 50,
"max": 50
},
"MXN": {"sum": 10,
"count": 1,
"mean": 10,
"std": 0,
"min": 10,
"max": 10
}
}
},
"stats_by_label": {"employee spend - food and drink - groceries": {"outgoing": {"USD": {"sum": 125,
"count": 10,
"mean": 12.5,
"std": 0,
"min": 12.5,
"max": 12.5
}
}
}
},
"stats_by_merchant": {"Amazon Web Services": {"outgoing": {"USD": {"sum": 100,
"count": 1,
"mean": 100,
"std": 0,
"min": 100,
"max": 100
}
}
},
"Apple": {"outgoing": {"USD": {"sum": 2499,
"count": 1,
"mean": 2499,
"std": 0,
"min": 2499,
"max": 2499
}
}
}
}
}

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:

ApiKeyAuth

path Parameters

account_holder_id

required

string

Example: 247ee045-3d04-4b3c-872b-a9160b810f33

Responses

Response samples

200

Content type

application/json

[{"total_amount": 0,
"source": "string",
"is_active": true,
"income_type": "salary",
"first_payment_date": "string",
"latest_payment_date": "string",
"duration": "string",
"latest_payment_description": "string",
"transaction_ids": ["string"
],
"pay_frequency": "weekly",
"next_expected_payment_date": "string",
"next_expected_payment_amount": 0
}
]

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:

ApiKeyAuth

path Parameters

account_holder_id

required

string

Example: 247ee045-3d04-4b3c-872b-a9160b810f33

Responses

Response samples

200

Content type

application/json

[{"periodicity": "weekly",
"latest_payment_amount": 0,
"total_amount": 0,
"merchant": "string",
"logo": "string",
"website": "string",
"labels": ["string"
],
"first_payment_date": "string",
"latest_payment_date": "string",
"transaction_ids": ["string"
],
"is_active": true,
"next_expected_payment_date": "string",
"latest_payment_description": "string",
"type": "bill",
"is_essential": true,
"iso_currency_code": "string"
}
]

Misc

Other.

Report a wrongly classified transaction.

Report a wrongly classified transaction specifying expected enrichment values.

Authorizations:

ApiKeyAuth

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

Payload
cURL
Python SDK

Content type

application/json

{"transaction_id": "xbx8YP14g565Xketw3tFmn4yp49x3tbj9mD8DB4fM8DDY6x",
"website": "www.expected.website",
"merchant": "Other Merchant"
}

Response samples

200

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:

ApiKeyAuth

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

200

Content type

application/json

{"pages": 0,
"reports": [{"status": "string",
"id": "string",
"created_at": "2019-08-24",
"transaction_id": "string",
"webhook_url": "string"
}
]
}

Returns a report by id

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

Authorizations:

ApiKeyAuth

path Parameters

id

required

string <uuid> 36 characters

Example: 247ee045-3d04-4b3c-872b-a9160b810f33

Report id.

Responses

Response samples

200

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

Authorizations:

ApiKeyAuth

None

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
Python SDK

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

Response samples

200
400

Content type

application/json

{"professional services": ["accounting",
"consulting",
"legal"
],
"infrastructure": ["cloud operations",
"manufacturing",
"servers",
"website"
],
"fees": ["merchant processing fees",
"payment processor fees",
"banking fees",
"subscription"
],
"employees": {"benefits": ["retirement funds",
"healthcare",
"dental"
],
"payroll": ["salary",
"fees",
"tax"
]
},
"insurance": [ ]
}

Check API health.

Get the API health info.

Responses

Request samples

cURL

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

Response samples

200

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:

ApiKeyAuth

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

200
422

Content type

application/json

[{"id": "string",
"uuid": "string",
"fname": "string",
"status": "string",
"created_at": "2019-08-24T14:15:22Z",
"transactions": [null
],
"error_code": 0,
"error": "string"
}
]

Submit a bank statement

Authorizations:

ApiKeyAuth

Request Body schema: multipart/form-data

file

required

string <binary> (File)

Responses

Response samples

200
422

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:

ApiKeyAuth

path Parameters

uuid

required

string (Uuid)

Responses

Response samples

200
422

Content type

application/json

{"id": "string",
"uuid": "string",
"fname": "string",
"status": "string",
"created_at": "2019-08-24T14:15:22Z",
"transactions": [null
],
"error_code": 0,
"error": "string"
}

Custom Models

Get all available custom labelling models.

Authorizations:

ApiKeyAuth

Responses

Request samples

cURL
Python SDK

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

Response samples

200

Content type

application/json

[{"name": "string",
"created_at": "2019-08-24",
"account_holder_type": "string"
}
]

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:

ApiKeyAuth

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

Payload
cURL

Content type

application/json

{"transactions": [{"account_holder_type": "business",
"amount": 123.45,
"entry_type": "incoming",
"iso_currency_code": "USD",
"description": "AMAZON WEB SERVICES AWS.AMAZON.CO WA Ref5543286P25S Crd15",
"country": "USA",
"mcc": 3456,
"label": ["infrastructure",
"cloud operations"
]
}
]
}

Response samples

200

Content type

application/json

{"name": "string",
"progress": 0,
"status": "string"
}

Get requested model status.

Get requested model status identified by name

Authorizations:

ApiKeyAuth

path Parameters

name

required

string

Example: my-model-name

Model name.

Responses

Request samples

cURL

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

Response samples

200

Content type

application/json

{"name": "string",
"progress": 0,
"status": "string"
}