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 path | Allowed values |
|---|---|
data.type | Transaction type:finance, travelRule. |
data.info.direction | Transaction direction:in, out |
data.applicant.paymentMethod.accountId | Crypto wallet address or bank card number. |
data.info.paymentTxnId | Crypto 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=valueformat.
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.
| Field | Type | Description |
|---|---|---|
items | Array of objects | Each object corresponds to a specific transaction. You can see the structured transaction information on the following page. |
totalItems | Integer | Total 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
}
}