Reporting wrong results

The Ntropy API allows the user to report incorrect values from the enrichment process and react to any corrections that are enacted by the system using webhooks. Values reported through this endpoint are also part of the feedback loop that continuously improves our models and results.

A report can take between one hour and (less commonly) a few weeks, depending on the complexity of the issue.

The report entity

When a transaction is reported, a report entity is created to track the correction process of that particular wrong transaction. You can use the report entity to check back on the status of the existing reports. The report has the following attributes (excluding the information that was reported as incorrect):

attribute	type	summary
id	string, uuid format	unique identifier in UUID format of the report
status	enum	current status of the report (from open, resolved, pending, invalid)
created_at	string, datetime format ISO 8601	timestamp at which the report was submitted
transaction_id	string	transaction_id of the reported transaction
webhook_url	string	URL for a provided webhook which will be called with information of status changes in the report

Reporting a wrongly enriched transaction

You can report any attribute of a transaction that has been incorrectly enriched, by submiting that transaction for review through the /v2/report endpoint or the sdk.report_transaction method. The report must at least include the transaction_id. It should also contain any fields that are incorrect and their expected (correct) value:

cURL

$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X POST \
--data '{
    "transaction_id": "4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g565Xketw3tFmn",
    "merchant": "Expected Merchant",
    "website": "expected.website",
    "notes": "some additional notes about that correction..."
}' \
https://api.ntropy.com/v2/report

Python SDK

from ntropy_sdk import SDK, Transaction

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

tx = Transaction(
    description = "SQ* STARBUCKS UNION SQUARE",
    entry_type = "outgoing",
    amount = 42.17,
    iso_currency_code = "USD",
    date = "2023-01-01",
    transaction_id = "4yp49x3tbj9mD8DB4fM8DDY6Yxbx8YP14g565Xketw3tFmn",
    country = "US",
    account_holder_id = "id-1",
    account_holder_type = "consumer"
)
enriched_tx = sdk.add_transactions([tx])[0]

report = enriched_tx.report(
  merchant="Other Merchant",
  website="expected.com",
  notes="some additional notes about that correction..."
)

# or
report = sdk.report_transaction(tx.transaction_id, merchant="Other merchant", website="expected.com")

A report has one mandatory field, the transaction_id. You should also send the fields that should be corrected with their expected value. If you have any additional comments to add to the report, you should send them in the notes field.

If a report action is successful, the response object contains a report entity associated with this particular request. The id of the report can be used to consult its status by using the /v2/report/{id} endpoint:

cURL

$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X GET \
https://api.ntropy.com/v2/report/<report-id>

Python SDK

from ntropy_sdk import SDK, Transaction, EnrichedTransaction

sdk = SDK("YOUR-API-KEY")
report = sdk.get_report(<report-id>)

You can also list all the submitted reports through the paginated GET endpoint /v2/report

cURL

$ curl \
-H "X-API-KEY: <YOUR-API-KEY>" \
-H "Content-Type: application/json" \
-X GET \
https://api.ntropy.com/v2/report?page=1&per_page=20

Python SDK

from ntropy_sdk import SDK, Transaction, EnrichedTransaction

sdk = SDK("YOUR-API-KEY")
report = sdk.list_reports(page=1, per_page=20)

# list_reports can also filter reports by status
report = sdk.list_reports(status="open")

# or for specific transaction_ids
report = sdk.list_reports(transaction_id="<specific_transaction_id>")

Status

A transaction report can only be in one of four statuses: open, resolved, invalid or pending. The meaning of each status is as follows:

• open - report was recently created and hasn't been looked into
• resolved - report has been addressed
• pending - report has been looked into but the solution will take some time to rollout. The report will be moved to resolved when that happens
• invalid - report has been looked into and it contains an invalid structure or mis-reported issue. The reason provided by the webhook should provide further information

Getting notified using webhooks

While you can poll the API periodically to check on the status of your previously submitted reports, we also support providing a webhook URL that is called when the status of your report changes. We only support secure webhook URLs (that have https configured) with a valid domain name (IPs aren't supported).

If you provide the webhook_url property in the POST request body of the /v2/report endpoint (or the webhook_url argument of the corresponding sdk method), this URL is associated with the report.

When the report status changes you will receive a POST request on this URL. The body of this request contains the attributes id, status (respectively the report id and the new report status for which the webhook was called) and data. The content of the data attribute varies with the status of the request.

• In case the status attribute is resolved, data is an object containing the re-enriched transaction that was previously reported with the corrected information, so that you can update the transaction without manually re-enriching.
• In case the status attribute is pending or invalid, data is a string containing the reason for the report changing status.

The content of the webhook call contains the following fields:

attribute	type	summary
id	string, uuid format	unique identifier in UUID format of the report
transaction_id	string, uuid format	unique identifier of the reported transaction
status	enum	new status of the report
data	dict	dictionary containing either the re-enriched transaction fields, or the reason for the change in status