Confirm wallet ownership

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

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:

  • needMasking becomes false.
  • travelRuleInfo.status becomes awaitingOnChainTransfer if the names match, or counterpartyMismatchedData if 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 — if applicantId is unknown to you. A new applicant profile is created with the transaction linked to it. If you provide an externalUserId that already exists, the transaction is attached to the applicant with that ID, and the participant data is applied to it, including fullName.
📘

Note

For accounts without the awaitingOnChainTransfer status rollout, the status completed (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 applicantId is not provided, a new applicant profile will be created with the transaction linked to this applicant. The response will include the generated applicantId along with the corresponding applicant data.
  • If the applicant profile already exists, the txn.data.applicant.fullName field will be updated.
  • needMasking is false, and travelRuleInfo.status is awaitingOnChainTransfer if the names match, or counterpartyMismatchedData if 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 codeDescription
400Both applicantId and applicantParticipant are sent. Send only one of them.
400The transaction is not an incoming Travel Rule request.
400Neither applicantId nor applicantParticipant is sent. Returned if the applicant data is required for your account.
403The 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").
404The transaction is not found, or applicantId is not found.
409The request is already answered or has expired.
Path Params
string
required

Unique transaction identifier in the Sumsub system.

This ID is returned in the response to the transaction submission and a webhook (kytTxnId). Save it for future use in subsequent API calls. Alternatively, you can get this identifier by the following method.

Body Params
string

Unique identifier of the applicant in the Sumsub system. Specify if applicantId is known to you. When provided, the transaction will be linked to this applicant.

⚠️ Send only one of applicantId and applicantParticipant.

applicantParticipant
object

Data related to the transaction participant. Specify if applicantId is unknown to you. When provided, a new applicant profile will be created with the transaction linked to this applicant; or the applicant profile already specified in the transaction will be updated.

⚠️ Send only one of applicantId and applicantParticipant.

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here!