Skip to main content
API docs by Redocly

Ntropy Transaction API (2.0)

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

You can find the Open API Specification here.

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:
APIKeyHeader
Request Body schema: application/json
required
Array (<= 4000 items)
transaction_id
required
string (Transaction Id) non-empty

A unique identifier of the transaction

account_holder_id
string (Account Holder Id) non-empty

The unique ID of the account holder of the transaction

account_holder_type
string (AccountHolderType)
Enum: "consumer" "business" "unknown"

The type of an account holder, may be one of 'consumer', 'business' or 'unknown'. Only used when create_account_holder is true.

amount
required
number (Amount) >= 0

The amount of the transaction

entry_type
required
any (EntryType)
Enum: "incoming" "outgoing"

The direction of the transaction (incoming or outgoing)

date
required
string <date> (Date)

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

iso_currency_code
required
string (Iso Currency Code)

The currency of the transaction in ISO 4217 format

description
required
string (Description) [ 0 .. 1024 ] characters

The description string of the transaction

location
string (Location) [ 0 .. 1024 ] characters

Location where the transaction occurred in

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

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

mcc
integer (Mcc) [ 700 .. 9999 ]

The Merchant Category Code of the merchant according to ISO 18245

account_holder_name
string (Account Holder Name) [ 0 .. 1024 ] characters

The name of the account holder

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Enrich and add transactions to the ledger 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:
APIKeyHeader
Request Body schema: application/json
required
Array (<= 24960 items)
transaction_id
required
string (Transaction Id) non-empty

A unique identifier of the transaction

account_holder_id
string (Account Holder Id) non-empty

The unique ID of the account holder of the transaction

account_holder_type
string (AccountHolderType)
Enum: "consumer" "business" "unknown"

The type of an account holder, may be one of 'consumer', 'business' or 'unknown'. Only used when create_account_holder is true.

amount
required
number (Amount) >= 0

The amount of the transaction

entry_type
required
any (EntryType)
Enum: "incoming" "outgoing"

The direction of the transaction (incoming or outgoing)

date
required
string <date> (Date)

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

iso_currency_code
required
string (Iso Currency Code)

The currency of the transaction in ISO 4217 format

description
required
string (Description) [ 0 .. 1024 ] characters

The description string of the transaction

location
string (Location) [ 0 .. 1024 ] characters

Location where the transaction occurred in

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

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

mcc
integer (Mcc) [ 700 .. 9999 ]

The Merchant Category Code of the merchant according to ISO 18245

account_holder_name
string (Account Holder Name) [ 0 .. 1024 ] characters

The name of the account holder

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

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:
APIKeyHeader
path Parameters
id
required
string (Id) = 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
{
  • "id": "247ee045-3d04-4b3c-872b-a9160b810f33",
  • "progress": 88,
  • "status": "started",
  • "updated_at": "2019-11-30T18:32:28Z"
}

Account Holder

Ledger operations

Gets a list of the registered account holders

Authorizations:
APIKeyHeader
query Parameters
page
integer (Page)
Default: 0
per_page
integer (Per Page)
Default: 50
query
string (Query)
sort_by
string (Sort By)
Default: "created_at"
sort_order
string (Sort Order)
Default: "desc"
named_only
boolean (Named Only)
Default: false
with_confidence
boolean (With Confidence)
Default: false

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an account holder.

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

Authorizations:
APIKeyHeader
Request Body schema: application/json
required
type
required
string (ntropy_server__schemas__account_holder__AccountHolderType)
Enum: "consumer" "business" "unknown"

An enumeration.

name
string (Name)
industry
string (Industry)
website
string (Website)
object (AccountHolderCompany)
id
string (Id)

Responses

Request samples

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

Response 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 information of an account holder.

Authorizations:
APIKeyHeader
path Parameters
account_holder_id
required
string (Account Holder Id)

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

Replace an existing account holder.

Replace a existing account holder and start tracking its ledger. The account holder can be a consumer, business or unknown.

Authorizations:
APIKeyHeader
path Parameters
account_holder_id
required
string (Account Holder Id)
Request Body schema: application/json
required
type
required
string (ntropy_server__schemas__account_holder__AccountHolderType)
Enum: "consumer" "business" "unknown"

An enumeration.

name
string (Name)
industry
string (Industry)
website
string (Website)
object (AccountHolderCompany)

Responses

Request samples

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

Response samples

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

Delete an account holder.

Delete an account holder and all of its ledger. This operation is permanent.

Authorizations:
APIKeyHeader
path Parameters
account_holder_id
required
string (Account Holder Id)

Responses

Request samples 

curl -X "DELETE" \
  "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
{
  • "status": "success"
}

Renames an existing account-holder

Authorizations:
APIKeyHeader
path Parameters
account_holder_id
required
string (Account Holder Id)
Request Body schema: application/json
required
name
required
string (Name)

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
null

List transactions of an account holder.

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

Authorizations:
APIKeyHeader
path Parameters
account_holder_id
required
string (Account Holder Id)
query Parameters
page
integer (Page)
Default: 0

Page number

per_page
integer (Per Page) [ 1 .. 1000 ]
Default: 100

How many items per page

sort_by
string (Sort By)

Column to sort items by, allowed values are ['date']. When not specified the default order will be used.

sort_order
string (SortOrder)
Default: "desc"
Enum: "asc" "desc"

Sorting direction asc or desc

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
}

Correct any property for multiple transactions.

Provide a correction for any field of a set of previously enriched transactions by transaction_id.

Authorizations:
APIKeyHeader
path Parameters
account_holder_id
required
string (Account Holder Id)
Request Body schema: application/json
required
transaction_ids
required
Array of strings (Transaction Ids)
required
Array of objects (Corrections)

Responses

Request samples

Content type
application/json
{
  • "transaction_ids": [
    ],
  • "corrections": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

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:
APIKeyHeader
path Parameters
account_holder_id
required
string (Account Holder Id)
query Parameters
page
integer (Page)
Default: 0

Page number

per_page
integer (Per Page) [ 1 .. 1000 ]
Default: 100

How many items per page

sort_by
string (Sort By)

Column to sort items by, allowed values are ['date']. When not specified the default order will be used.

sort_order
string (SortOrder)
Default: "desc"
Enum: "asc" "desc"

Sorting direction asc or desc

Request Body schema: application/json
required
Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

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

Correct any transaction property.

Provide a correction for any field of a previously enriched transaction.

Authorizations:
APIKeyHeader
path Parameters
transaction_id
required
string (Transaction Id)
account_holder_id
required
string (Account Holder Id)
Request Body schema: application/json
required
logo
string (Logo)
website
string (Website)
location
string (Location)
location_structured
any (Location Structured)
merchant
string (Merchant)
labels
Array of strings (Labels)
recurrence
any (Recurrence)
person
string (Person)
transaction_type
any (Transaction Type)
intermediaries
Array of any (Intermediaries)
review_state
string (ReviewState)
Enum: "incomplete" "satisfied" "forced"

An enumeration.

Responses

Request samples

Content type
application/json
{
  • "logo": "string",
  • "website": "string",
  • "location": "string",
  • "location_structured": null,
  • "merchant": "string",
  • "labels": [
    ],
  • "recurrence": null,
  • "person": "string",
  • "transaction_type": null,
  • "intermediaries": [
    ],
  • "review_state": "incomplete"
}

Response samples

Content type
application/json
{
  • "transaction_id": "xbx8YP14g565Xketw3tFmn4yp49x3tbj9mD8DB4fM8DDY6x",
  • "logo": "https://logo.clearbit.com/aws.amazon.com",
  • "website": "starbucks.com",
  • "location": "10 Union Square East, New York, New York 10003, US",
  • "location_structured": {},
  • "merchant": "Starbucks",
  • "merchant_id": "d4bc3c80-ec1a-3da2-836e-2a4ca4758be5",
  • "labels": [
    ],
  • "recurrence": "recurring",
  • "recurrence_group": {
    },
  • "recurrence_group_id": "3b0c689b-e123-30a6-9f53-878f3ebf46aa",
  • "intermediaries": []
}

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:
APIKeyHeader
path Parameters
account_holder_id
required
string (Account Holder Id)

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:
APIKeyHeader
path Parameters
account_holder_id
required
string (Account Holder Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Bank statements

The bank statements API allows you to view and enrich transactions found in bank statements. Below is a table with the description of each of the statuses and steps that each bank statement goes through:

Status Description
QUEUED The document is queued for processing
PROCESSING OCR is in progress
PROCESSED The document was successfully processed
FAILED An error occurred during processing of any of the previous steps

A list of error codes for the FAILED status can be found below:

Code Description
301 Failed to parse document as bank statement.
301 Failed to enrich transactions in bank statement.
500 Unexpected error. Please contact support.

Check paginated processing status for bank statements

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

The status of the document to filter on

account_holder_id
string (Account Holder Id) 
The unique ID of the account holder to which the bank statement is associated
page
integer (Page) >= 0
Default: 0

The page number to retrieve

per_page
integer (Per Page) [ 1 .. 1000 )
Default: 20

The page size to retrieve

order_by
string (Order By)
Default: "desc"
Enum: "desc" "asc"

The sorting order by creation

query
string (Query)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Submit a bank statement PDF for OCR and enrichment

Creates a new dataset from a bank statement and queues it for enrichment. The maximum size of the statement must be less than 50.0 MB

Authorizations:
APIKeyHeader
query Parameters
account_holder_id
string (Account Holder Id)

ID for account holder. If no account holder with the given id exists, one will be created with account_type or "business" if not specified.

account_type
string (AccountHolderType)
Enum: "consumer" "business" "unknown"

Type of account holder to use when it is being created. Otherwise it'll override the type of the existing one for the transactions on this bank statement.

iso_currency_code
string (Iso Currency Code)

The currency of transactions in the bank statement in ISO 4217 format. Defaults to USD

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

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "size": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "account_holder_id": "string",
  • "account_type": "consumer",
  • "status": "queued",
  • "bank_accounts": [
    ],
  • "statements": [
    ],
  • "error_code": 0,
  • "error": "string",
  • "complete": true,
  • "batch_id": "string",
  • "file": {
    }
}

Check processing status for a bank statement

Authorizations:
APIKeyHeader
path Parameters
uuid
required
string (Uuid)

The unique ID of the bank statement

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "size": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "account_holder_id": "string",
  • "account_type": "consumer",
  • "status": "queued",
  • "bank_accounts": [
    ],
  • "statements": [
    ],
  • "error_code": 0,
  • "error": "string",
  • "complete": true,
  • "batch_id": "string",
  • "file": {
    }
}

Delete a bank statement

Deletes a bank statement and all its underlying transactions

Authorizations:
APIKeyHeader
path Parameters
uuid
required
string (Uuid)

Responses

Response samples

Content type
application/json
null

Change information of an existing bank statement

Authorizations:
APIKeyHeader
path Parameters
uuid
required
string (Uuid)
Request Body schema: application/json
required
name
required
string (Name)

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
null

Gets the enriched transactions for a bank statement

Authorizations:
APIKeyHeader
path Parameters
uuid
required
string (Uuid)
query Parameters
page
integer (Page)
Default: 0

Page number

per_page
integer (Per Page) [ 1 .. 1000 ]
Default: 100

How many items per page

sort_by
string (Sort By)

Column to sort items by, allowed values are ['date']. When not specified the default order will be used.

sort_order
string (SortOrder)
Default: "desc"
Enum: "asc" "desc"

Sorting direction asc or desc

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Extracts bank and account details for instant file verification and UI enhancements.

Statement Info endpoint is a low-latency response analysing the first page of a bank statement which returns key identification details such as the underlying bank institution and the account-holder. The can be used for UX improvements through instant verification of correct file upload, for UI improvements like returning bank names and logos, or for logging information about a file upon upload.

Authorizations:
APIKeyHeader
path Parameters
uuid
required
string (Uuid)

Responses

Response samples

Content type
application/json
{
  • "institution": "Well's Fargo",
  • "start_date": "2024-01-01",
  • "end_date": "2024-02-01",
  • "account_holder": {
    },
  • "accounts": [
    ]
}

Personalization

Custom rules for enrichment.

Get the current personalization ruleset.

Get the current personalization ruleset.

Authorizations:
APIKeyHeader

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set the personalization ruleset.

Set the personalization ruleset.

Authorizations:
APIKeyHeader
Request Body schema: application/json
required
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 starts_with (object) or ends_with (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (Expr)
then
Array of any (action)
else
Array of any (action)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
null

Append a rule.

Append a rule to the personalization ruleset.

Authorizations:
APIKeyHeader
Request Body schema: application/json
required
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 starts_with (object) or ends_with (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (Expr)
then
Array of any (action)
else
Array of any (action)

Responses

Request samples

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

Response samples

Content type
application/json
null

Delete a rule.

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

Authorizations:
APIKeyHeader
path Parameters
index
required
integer (Index)

Responses

Request samples 

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

Response samples

Content type
application/json
null

Modify an existing rule.

Modify an existing rule at the specified index on the ruleset.

Authorizations:
APIKeyHeader
path Parameters
index
required
integer (Index)
Request Body schema: application/json
required
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 starts_with (object) or ends_with (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (Expr)
then
Array of any (action)
else
Array of any (action)

Responses

Request samples

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

Response samples

Content type
application/json
null

Misc

Miscellaneous endpoint.

Get the list of possible MCC codes that can be assigned

Get the list of possible MCC codes that can be assigned. Derived from the ISO:18245:2003 standard (https://www.iso.org/standard/33365.html) with private and US-specific MCC codes removed.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the API health info

Get the API health info

Responses

Response samples

Content type
application/json
null

Labels

Get the hierarchy of Ntropy labels

Get the hierarchy of Ntropy labels

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

An enumeration.

Responses

Response samples

Content type
application/json
{ }

Get a custom label hierarchy

Get a custom label hierarchy

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

An enumeration.

Responses

Response samples

Content type
application/json
{
  • "incoming": [
    ],
  • "outgoing": [
    ]
}

Upload a custom label hierarchy

Upload a custom label hierarchy. Transactions that don't match a label will be labeled not enough information regardless of whether it is present in the hierarchy.

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

An enumeration.

Request Body schema: application/json
required
incoming
required
Array of strings (Incoming)
outgoing
required
Array of strings (Outgoing)

Responses

Request samples

Content type
application/json
{
  • "incoming": [
    ],
  • "outgoing": [
    ]
}

Response samples

Content type
application/json
null

Delete a custom label hierarchy

Delete a custom label hierarchy

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

An enumeration.

Responses

Response samples

Content type
application/json
null

Reporting

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:
APIKeyHeader
query Parameters
per_page
integer (Per Page) [ 1 .. 10000 ]
Default: 1000
page
integer (Page)
Default: 0
status
string (Status)
transaction_id
string (Transaction Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Report a wrongly classified transaction.

Report a wrongly classified transaction specifying expected enrichment values.

Authorizations:
APIKeyHeader
Request Body schema: application/json
required
transaction_id
required
string (Transaction Id)
notes
string (Notes)
webhook_url
string (Webhook Url)
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "transaction_id": "string",
  • "notes": "string",
  • "webhook_url": "string",
  • "property1": null,
  • "property2": null
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "open",
  • "transaction_id": "string",
  • "fields": {
    },
  • "notes": "string",
  • "webhook_url": "string"
}

Returns a report by id

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

Authorizations:
APIKeyHeader
path Parameters
id
required
string (Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Entities

Search for entities

Resolves a query into an entity by querying our entity resolution system. The parameters name and website are mutually exclusive. Calls to this endpoint using the name parameter are billed the same way transactions are.

Authorizations:
APIKeyHeader
query Parameters
name
string (Name)

The name of the entity to resolve

website
string (Website)

The website of the entity to resolve

location
string (Location)

A location string of the entity to resolve

Responses

Response samples

Content type
application/json
{
  • "website": "string",
  • "name": "string",
  • "logo": "string",
  • "id": "string",
  • "location": "string",
  • "location_structured": {
    },
  • "confidence": 0
}

Retrieve an entity by its ID

Retrieve more information about an entity by using its unique ID. These ID's may be obtained from the field id in entity search or from merchant_id in transaction enrichment

Authorizations:
APIKeyHeader
path Parameters
id
required
string (Id)

The unique ID of the entity

Responses

Response samples

Content type
application/json
{
  • "website": "string",
  • "name": "string",
  • "logo": "string",
  • "id": "string",
  • "location": "string",
  • "location_structured": {
    },
  • "confidence": 0
}