Find specific transactions

Overview

This method allows you to search for and retrieve specific transactions using flexible filters and query parameters.

It supports a wide range of use cases, including preventing transaction duplication — a particularly useful feature for Travel Rule compliance. Before submitting a new inbound transaction for Travel Rule processing, you can query the system to check whether the mirrored transaction already exists (e.g., if the originating VASP is also a Sumsub client using the Travel Rule solution).

Supported filters

You can add filters directly in the PATH segment of the request. When combined with query parameters, they help in pagination, sorting, and selective field searching. See the request examples for clarity.

The table below includes and explains the filters that are currently supported.

Filter pathAllowed values
data.typeTransaction type:finance, travelRule.
data.info.directionTransaction direction:in, out
data.applicant.paymentMethod.accountIdCrypto wallet address or bank card number.
data.info.paymentTxnIdCrypto transaction hash.

📘

Note

The method is evolving and will support additional filters over time.

Request examples

To construct a valid request, mind the following:

  • Separate each filter using a semicolon (;).
  • Each filter must follow the key=value format.

Below are a couple of request examples to clarify how to correctly apply filters in the URL path.

// Checks whether a Travel Rule inbound transaction with a specific crypto hash and sender wallet already exists.

curl -X GET \
     'https://api.sumsub.com/resources/kyt/txns/query/-;data.type=travelRule;data.applicant.paymentMethod.accountId=bc1q080rkmk3kj86pxvf5nkxecdrw6nrx3zzy9xl7q;data.info.direction=in;data.info.paymentTxnId=000000000000000000013f2851d71e6ea8dfcc9151654ca4cbbbfd759122589f?order=-createdAt' \
     -H 'accept: application/json'
// Searches transactions of the finance type, limit results to 2.

curl -X GET \
     'https://api.sumsub.com/resources/kyt/txns/query/-;data.type=finance?limit=2' \
     -H 'accept: application/json'

Response explained

The response is a JSON file that represents the list of transactions found in accordance with the filters and parameters specified in the request.

FieldTypeDescription
itemsArray of objectsEach object corresponds to a specific transaction.

You can see the structured transaction information on the following page.
totalItemsIntegerTotal number of existing transactions matching the criteria specified in the request.

Response examples

If the request is successfully sent and processed, you will get a response like the one below.

{
    "list": {
        "items": [
            {
                "id": "67fe5cbd3d428fcef242df51",
                "applicantId": "67f64c4f634cfa68ed8035d6",
                "externalUserId": "ipt75sgftybloqwcmi51x",
                "clientId": "cool_id",
                "data": {
                    "txnId": "b44563gwi7m7s613kfj9wk",
                    "txnDate": "2025-04-15 13:18:53+0000",
                    "applicant": {
                        "externalUserId": "ipt75sgftybloqwcmi51x",
                        "type": "individual",
                        "paymentMethod": {
                            "type": "crypto",
                            "accountId": ""
                        },
                        "device": {
                            "ipInfo": {
                                "ip": "87.141.63.130",
                                "countryCode2": "DE",
                                "countryCode3": "DEU",
                                "city": "Berlin",
                                "lat": 52.5583,
                                "lon": 13.3826,
                                "asn": 3320,
                                "asnOrg": "Deutsche Telekom AG",
                                "riskyAsn": true
                            },
                            "fingerprint": "cdtevzq0v1o"
                        }
                    },
                    "counterparty": {
                        "externalUserId": "q6o6p38q79o7pdr81vhkbq",
                        "fullName": "Jack Posek",
                        "type": "individual",
                        "paymentMethod": {
                            "type": "crypto"
                        }
                    },
                    "type": "finance",
                    "info": {
                        "paymentTxnId": "84bf83c10dfddc9d1f0ea6a1a131c638488fb161e819dae25fd8128c671d2d5a",
                        "type": "On-chain transfer",
                        "direction": "in",
                        "amount": 2.0,
                        "currencyCode": "BTC",
                        "currencyType": "crypto",
                        "amountInDefaultCurrency": 151515.15151515152,
                        "defaultCurrencyCode": "EUR",
                        "paymentDetails": "Birthday Present"
                    },
                    "sourceKey": "DemoCryptoTxn",
                    "props": {
                        "customProperty": "Custom value that can be used in rules",
                        "dailyOutLimit": "10000"
                    }
                },
                "score": 0,
                "review": {
                    "reviewId": "jWmbC",
                    "attemptId": "mofgi",
                    "attemptCnt": 2,
                    "elapsedSincePendingMs": 1826,
                    "createDate": "2025-04-15 13:18:53+0000",
                    "reviewStatus": "onHold",
                    "confirmed": false
                },
                "createdAt": "2025-04-15 13:18:53+0000",
                "scoringResult": {
                    "score": 0,
                    "dryScore": 0,
                    "matchedRules": [
                        {
                            "id": "67fd1b2eea9e83c6c702cbec",
                            "name": "cry-mon-cry-scr-fai-nuIN",
                            "revision": 1,
                            "title": "Crypto Monitoring (Crystal): Screening failed",
                            "score": 0,
                            "dryRun": false,
                            "action": "onHold"
                        }
                    ],
                    "failedRules": [
                        {
                            "id": "67fd1b2eea9e83c6c702cbe9",
                            "name": "cry-mon-cry-new-scr-MNnN",
                            "revision": 1,
                            "title": "Crypto Monitoring (Crystal): New screening",
                            "dryRun": false,
                            "action": "score",
                            "error": "Applicant and counterparty wallets are empty. 'applicantPaymentMethodFingerprint' must not be null for the inbound transactions",
                            "stage": "pre",
                            "preScoringRunnerType": "cryptoTxn"
                        }
                    ],
                    "action": "onHold",
                    "ruleCnt": 10,
                    "dryRunRuleCnt": 0
                },
                "txnInactive": false
            },
            {
                "id": "67fe5d043d428fcef242df65",
                "applicantId": "67fd1f02b9779f2ac49f742f",
                "externalUserId": "93qy7ja4kwb1ypnwqokqmk",
                "clientId": "cool_id",
                "data": {
                    "txnId": "i6mf69id0prl2qbuzb4hzn",
                    "txnDate": "2025-04-15 13:20:04+0000",
                    "applicant": {
                        "externalUserId": "93qy7ja4kwb1ypnwqokqmk",
                        "type": "individual",
                        "paymentMethod": {
                            "type": "crypto",
                            "accountId": ""
                        },
                        "device": {
                            "ipInfo": {
                                "ip": "87.141.63.130",
                                "countryCode2": "DE",
                                "countryCode3": "DEU",
                                "city": "Berlin",
                                "lat": 52.5583,
                                "lon": 13.3826,
                                "asn": 3320,
                                "asnOrg": "Deutsche Telekom AG",
                                "riskyAsn": true
                            },
                            "fingerprint": "a81pno7qmt"
                        }
                    },
                    "counterparty": {
                        "externalUserId": "j57zpzq0hkny4r5qsqy3v",
                        "fullName": "Jack Posek",
                        "type": "individual",
                        "paymentMethod": {
                            "type": "crypto"
                        }
                    },
                    "type": "finance",
                    "info": {
                        "paymentTxnId": "84bf83c10dfddc9d1f0ea6a1a131c638488fb161e819dae25fd8128c671d2d5a",
                        "type": "On-chain transfer",
                        "direction": "in",
                        "amount": 2.0,
                        "currencyCode": "BTC",
                        "currencyType": "crypto",
                        "amountInDefaultCurrency": 151515.15151515152,
                        "defaultCurrencyCode": "EUR",
                        "paymentDetails": "Birthday Present"
                    },
                    "sourceKey": "DemoCryptoTxn",
                    "props": {
                        "customProperty": "Custom value that can be used in rules",
                        "dailyOutLimit": "10000"
                    }
                },
                "score": 0,
                "review": {
                    "reviewId": "tnnlD",
                    "attemptId": "xfijh",
                    "attemptCnt": 2,
                    "elapsedSincePendingMs": 808,
                    "createDate": "2025-04-15 13:20:04+0000",
                    "reviewStatus": "onHold",
                    "confirmed": false
                },
                "createdAt": "2025-04-15 13:20:04+0000",
                "scoringResult": {
                    "score": 0,
                    "dryScore": 0,
                    "matchedRules": [
                        {
                            "id": "67fd1b2eea9e83c6c702cbec",
                            "name": "cry-mon-cry-scr-fai-nuIN",
                            "revision": 1,
                            "title": "Crypto Monitoring (Crystal): Screening failed",
                            "score": 0,
                            "dryRun": false,
                            "action": "onHold"
                        }
                    ],
                    "failedRules": [
                        {
                            "id": "67fd1b2eea9e83c6c702cbe9",
                            "name": "cry-mon-cry-new-scr-MNnN",
                            "revision": 1,
                            "title": "Crypto Monitoring (Crystal): New screening",
                            "dryRun": false,
                            "action": "score",
                            "error": "Applicant and counterparty wallets are empty. 'applicantPaymentMethodFingerprint' must not be null for the inbound transactions",
                            "stage": "pre",
                            "preScoringRunnerType": "cryptoTxn"
                        }
                    ],
                    "action": "onHold",
                    "ruleCnt": 10,
                    "dryRunRuleCnt": 0
                },
                "txnInactive": false
            }
        ],
        "totalItems": 2
    }
}

If the request fails (e.g., incorrect data or filters provided), you will receive an HTTP response containing an error code along with a message explaining the error. For example:

{
    "code": 400,
    "correlationId": "00000000000000000000000000000000",
    "errorCode": 0,
    "description": "Invalid parameters provided",
    "type": "com.sumsub.commons.restler.exceptions.RestDslException"
}

If no transactions matching the specified criteria are found, the response will contain an empty items array.

{
  "list": {
    "items": [],
    "totalItems": 0
  }
}
Language
Credentials
Header
Click Try It! to start a request and see the response here!