| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Overview
Use this method to respond to an incoming Travel Rule request in one call: it confirms that the wallet address belongs to your VASP and identifies the user (the transaction participant, beneficiary or originator) whose data enriches the Travel Rule message.
If you do not respond to the request, the transaction stays in the onHold status and expires.
Use case
Use this method when your VASP receives an incoming Travel Rule request and has to respond to it. In a single call, you confirm that the wallet address belongs to your VASP and identify the user it belongs to, so the data exchange can proceed to the on-chain transfer. If you do not respond, the transaction stays in the onHold status and expires.
Required permissions
To use this method:
- Your app token must have the Manage TM transactions - Decisions permission.
- Travel Rule must be enabled for your account.
Both conditions are required — missing either one returns a 403 Forbidden. If Travel Rule is not enabled for your account, contact your CSM or Sumsub support.
How it works
The call confirms the address and identifies the user. After a successful call:
needMaskingbecomesfalse.travelRuleInfo.statusbecomesawaitingOnChainTransferif the names match, orcounterpartyMismatchedDataif the names do not match.
Identify the user with only one of the two body fields:
applicantId— if you already have an applicant profile for the user. The transaction is linked to this applicant.applicantParticipant— ifapplicantIdis unknown to you. A new applicant profile is created with the transaction linked to it. If you provide anexternalUserIdthat already exists, the transaction is attached to the applicant with that ID, and the participant data is applied to it, includingfullName.
NoteFor accounts without the
awaitingOnChainTransferstatus rollout, the statuscompleted(its legacy name) is returned instead.
Request examples
curl -X POST \
'https://api.sumsub.com/resources/kyt/txns/test_txn_id/ownership/confirmed' \
-H 'content-type: application/json' \
-H 'X-App-Token: <your-app-token>' \
-H 'X-App-Access-Sig: <your-signature>' \
-H 'X-App-Access-Ts: <unix-timestamp>' \
-d '{
"applicantId": "67a0ec0b9aa095000000000f"
}'curl -X POST \
'https://api.sumsub.com/resources/kyt/txns/test_txn_id/ownership/confirmed' \
-H 'content-type: application/json' \
-H 'X-App-Token: <your-app-token>' \
-H 'X-App-Access-Sig: <your-signature>' \
-H 'X-App-Access-Ts: <unix-timestamp>' \
-d '{
"applicantParticipant": {
"fullName": "John Doe",
"fullNameEn": "John Doe",
"externalUserId": "external_user_id",
"type": "individual"
}
}'Response explained
If the request is sent and processed correctly, you will get a JSON file that represents the structured transaction information. The presence of some fields depends on the transaction type and the matched rules.
Mind the following behavior depending on the request inputs:
- If
applicantIdis not provided, a new applicant profile will be created with the transaction linked to this applicant. The response will include the generatedapplicantIdalong with the corresponding applicant data. - If the applicant profile already exists, the
txn.data.applicant.fullNamefield will be updated. needMaskingisfalse, andtravelRuleInfo.statusisawaitingOnChainTransferif the names match, orcounterpartyMismatchedDataif they do not match.
Response examples
In case of success, you will get a response like in the following examples:
// The `applicantId` value changes.
{
"id": "67a22680c39d670000000000",
"applicantId": "66c61271ba899b0000088888",
"counterpartyApplicantId": "67a2267ec39d670000077777",
"scope": "events",
"externalUserId": "cool_external_user_id",
"clientId": "your_id",
"data": {
"txnId": "a31b7787-6add-415a-bce1-0000000000e7",
"txnDate": "2025-02-04 14:38:56+0000",
"applicant": {
"externalUserId": "cool_external_user_id",
"fullName": "John Doe",
"firstName": "John",
"lastName": "Doe",
"nameType": "birthName",
"dob": "1991-04-07",
"placeOfBirth": "Berlin, Germany",
"address": {
"subStreet": "100",
"street": "Chauseestr.",
"town": "Berlin",
"postCode": "10000",
"country": "DEU",
"formattedAddress": "Chauseestr., 100, Berlin, Germany, 10000"
},
"type": "individual",
"paymentMethod": {
"type": "",
"accountId": "bc1q080rkmk3kj86pxvf5nkxefdffclxkdjfb;hrvbzdkrf"
},
"idDoc": {
"number": "DE00000000",
"country": "DEU",
"idDocType": "PASSPORT",
"registrationAuthority": "BerlinMitte"
},
"residenceCountry": "DEU"
},
"counterparty": {
"externalUserId": "counterparty_external_user_id",
"fullName": "John Doe",
"firstName": "John",
"lastName": "Doe",
"nameType": "birthName",
"dob": "1992-05-08",
"placeOfBirth": "Paris, France",
"address": {
"subStreet": "1",
"street": "Rue de Rivoli",
"town": "Paris",
"postCode": "77777",
"country": "FRA",
"formattedAddress": "Rue de Rivoli, 100, Paris, France, 70000"
},
"type": "individual",
"paymentMethod": {
"type": "account",
"accountId": "1A1zP1eP5QGefi2DMPzdflkjnsldkfjhbkxjdfh"
},
"device": {
"ipInfo": {
"ip": "87.141.63.130",
"countryCode2": "DE",
"countryCode3": "DEU",
"city": "Berlin",
"zipCode": "13333",
"lat": 52.5583,
"lon": 13.3826,
"asn": 3320,
"asnOrg": "Deutsche Telekom AG",
"riskyAsn": false
},
"fingerprint": "irc3un0fc2p",
"userAgentInfo": {
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
"agentName": "Firefox",
"majorVersion": "42",
"fullVersion": "42.0",
"deviceClass": "Desktop",
"deviceName": "Macintosh"
}
},
"idDoc": {
"number": "FR42255555",
"country": "FRA",
"idDocType": "PASSPORT",
"registrationAuthority": "Ille-de-France 01"
},
"residenceCountry": "FRA"
},
"type": "travelRule",
"info": {
"type": "transfer",
"direction": "in",
"amount": 0.01,
"currencyCode": "BTC",
"currencyType": "crypto",
"amountInDefaultCurrency": 961.5384615384615,
"defaultCurrencyCode": "EUR"
}
},
"score": 0,
"review": {
"reviewId": "xkFcj",
"attemptId": "peqfY",
"attemptCnt": 3,
"elapsedSincePendingMs": 43317,
"elapsedSinceQueuedMs": 43317,
"createDate": "2025-02-04 14:38:56+0000",
"reviewResult": {
"reviewAnswer": "GREEN"
},
"reviewStatus": "completed",
"confirmed": false
},
"createdAt": "2025-02-04 14:38:56+0000",
"scoringResult": {
"score": 0,
"dryScore": 0,
"matchedRules": [
{
"id": "66be1caaf47b4f7a6fccf5fb",
"name": "TRI0-tra-rule-new-tr-data-exc-req-lVyy",
"revision": 1,
"title": "Travel Rule: New TR data exchange request",
"score": 0,
"dryRun": false,
"action": "score",
"stage": "pre",
"preScoringRunnerType": "travelRule"
}
],
"action": "score",
"ruleCnt": 4,
"dryRunRuleCnt": 0
},
"typedTags": [
{
"label": "Mirrored",
"type": "violation"
}
],
"travelRuleInfo": {
"protocolName": "sns",
"protocolAttempts": {
"sns": "completed"
},
"applicant": {
"externalUserId": "cool_external_user_idr_id",
"fullName": "Jack Posek",
"dob": "1991-04-07",
"address": {
"subStreet": "100",
"street": "Chauseestr.",
"town": "Berlin",
"postCode": "10000",
"country": "DEU",
"formattedAddress": "Chauseestr., 100, Berlin, Germany, 10000"
}
},
"counterparty": {
"externalUserId": "counterparty_external_user_id",
"fullName": "John Doe",
"address": {
"subStreet": "100",
"street": "Rue de Rivoli",
"town": "Paris",
"postCode": "77777",
"country": "FRA",
"formattedAddress": "Rue de Rivoli, 100, Paris, France, 70000"
}
},
"status": "awaitingOnChainTransfer",
"applicantVaspId": "668d5fb69c98ed00000gsfTr",
"counterpartyVaspId": "67977ac889a71d00000gsfTr"
},
"counterpartyKytTxnRef": {
"txnId": "67a2267ec39d670000000000"
},
"needMasking": false,
"mirrored": true,
"txnInactive": false
}// The `fullName` value changes to `New name`.
{
"id": "67a22682c39d67000000000d",
"applicantId": "67a2271fc39d67000000000a",
"counterpartyApplicantId": "67a2267ec39d67000000000c",
"scope": "events",
"externalUserId": "cool_external_user_id",
"clientId": "your_id",
"data": {
"txnId": "a0fa84f1-6c99-4ed9-9f1f-1b0000000txn",
"txnDate": "2025-02-04 14:38:58+0000",
"applicant": {
"externalUserId": "cool_external_user_id",
"fullName": "New name",
"nameType": "birthName",
"dob": "1991-04-07",
"placeOfBirth": "Berlin, Germany",
"address": {
"subStreet": "100",
"street": "Chauseestr.",
"town": "Berlin",
"postCode": "10000",
"country": "DEU",
"formattedAddress": "Chauseestr., 100, Berlin, Germany, 10000"
},
"type": "individual",
"paymentMethod": {
"type": "",
"accountId": "bc1q080rkmk3kj86dfgdgpxvf5nkxefdcghmcghmcghjmcfghzxdtfg"
},
"idDoc": {
"number": "DE42234089",
"country": "DEU",
"idDocType": "PASSPORT",
"registrationAuthority": "BerlinMitte"
},
"residenceCountry": "DEU"
},
"counterparty": {
"externalUserId": "counterparty_external_user_id",
"fullName": "John Doe",
"firstName": "John",
"lastName": "Doe",
"nameType": "birthName",
"dob": "1992-05-08",
"placeOfBirth": "Paris, France",
"address": {
"subStreet": "100",
"street": "Rue de Rivoli",
"town": "Paris",
"postCode": "77777",
"country": "FRA",
"formattedAddress": "Rue de Rivoli, 1, Paris, France, 77777"
},
"type": "individual",
"paymentMethod": {
"type": "account",
"accountId": "1A1zP1eP5QGefi2DMPTxfchjcgukcyftxz"
},
"device": {
"ipInfo": {
"ip": "87.141.63.130",
"countryCode2": "DE",
"countryCode3": "DEU",
"city": "Berlin",
"zipCode": "13333",
"lat": 52.5583,
"lon": 13.3826,
"asn": 3320,
"asnOrg": "Deutsche Telekom AG",
"riskyAsn": false
},
"fingerprint": "irc3un0fc2p",
"userAgentInfo": {
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
"agentName": "Firefox",
"majorVersion": "42",
"fullVersion": "42.0",
"deviceClass": "Desktop",
"deviceName": "Macintosh"
}
},
"idDoc": {
"number": "FR42200000",
"country": "FRA",
"idDocType": "PASSPORT",
"registrationAuthority": "Ille-de-France 01"
},
"residenceCountry": "FRA"
},
"type": "travelRule",
"info": {
"type": "transfer",
"direction": "in",
"amount": 0.01,
"currencyCode": "BTC",
"currencyType": "crypto",
"amountInDefaultCurrency": 961.5384615384615,
"defaultCurrencyCode": "EUR"
}
},
"score": 0,
"review": {
"reviewId": "NJqFu",
"attemptId": "IxBBH",
"attemptCnt": 4,
"elapsedSincePendingMs": 156674,
"createDate": "2025-02-04 14:38:58+0000",
"reviewResult": {
"reviewAnswer": "GREEN"
},
"reviewStatus": "completed",
"confirmed": false
},
"createdAt": "2025-02-04 14:38:58+0000",
"scoringResult": {
"score": 0,
"dryScore": 0,
"matchedRules": [
{
"id": "66be1caaf47b4f7a6fccf5fb",
"name": "TRI0-tra-rule-new-tr-data-exc-req-lVyy",
"revision": 1,
"title": "Travel Rule: New TR data exchange request",
"score": 0,
"dryRun": false,
"action": "score",
"stage": "pre",
"preScoringRunnerType": "travelRule"
}
],
"action": "score",
"ruleCnt": 4,
"dryRunRuleCnt": 0
},
"typedTags": [
{
"label": "Mirrored",
"type": "violation"
}
],
"travelRuleInfo": {
"protocolName": "sns",
"protocolAttempts": {
"sns": "completed"
},
"applicant": {
"externalUserId": "cool_external_user_id",
"fullName": "John Doe",
"dob": "1991-04-07",
"address": {
"subStreet": "100",
"street": "Chauseestr.",
"town": "Berlin",
"postCode": "10115",
"country": "DEU",
"formattedAddress": "Chauseestr., 100, Berlin, Germany, 10000"
}
},
"counterparty": {
"externalUserId": "counterparty_external_user_id",
"fullName": "John Doe",
"address": {
"subStreet": "1",
"street": "Rue de Rivoli",
"town": "Paris",
"postCode": "77777",
"country": "FRA",
"formattedAddress": "Rue de Rivoli, 100, Paris, France, 77777"
}
},
"status": "awaitingOnChainTransfer",
"applicantVaspId": "668d5fb69c98ed620cxfgnhxf",
"counterpartyVaspId": "67977ac889a71d4xgkmblxkfn"
},
"counterpartyKytTxnRef": {
"txnId": "67a22682c39d6760b0000000"
},
"needMasking": false,
"mirrored": true,
"txnInactive": false
}Possible errors
If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:
{
"description": "Ownership change is not allowed",
"code": 409,
"correlationId": "808ab395e1ef217e5c9fc6fad349ed19"
}The following table lists the possible errors.
| HTTP code | Description |
|---|---|
400 | Both applicantId and applicantParticipant are sent. Send only one of them. |
400 | The transaction is not an incoming Travel Rule request. |
400 | Neither applicantId nor applicantParticipant is sent. Returned if the applicant data is required for your account. |
403 | The app token does not have the Manage TM transactions - Decisions permission, or Travel Rule is not enabled for your account ("You don't have this feature enabled, please contact us"). |
404 | The transaction is not found, or applicantId is not found. |
409 | The request is already answered or has expired. |