Skip to content

Share a Sumsub KYC token

Request

Share customer identity

Requires KYC sharing: KYC sharing must be enabled for your account. If it isn't, this endpoint returns 400 with code 4005 and the message "KYC sharing not enabled". Contact your Banxa integration manager to enable it.

Errors: these return 400 and save nothing, so you can fix the problem and retry.

CodeMessage
4005KYC sharing not enabled
4023The customer reference is already in use
4024The KYC sharing token is already in use
4025The customer is blocked and cannot be used
4026This customer has already completed KYC sharing and it cannot be repeated

Sending the same token again for the same customer returns 202 without processing it twice. After a share fails, you can send a new token. See KYC Token Sharing.

Security
HMACAuth
Bodyapplication/jsonrequired
identityReferencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$required

A unique customer identifier provided by the partner. This field is required and must be unique for each customer.

Important: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.

Format Requirements:

  • Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
  • Must be between 1 and 255 characters
  • Case-sensitive

Best Practices:

  • Use a consistent format across your system
  • Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
  • Do not include personally identifiable information (PII) in the reference
  • Store the mapping between your internal customer ID and this reference securely
Example:"c-13344"
emailstring, (email), <= 200 charactersrequired

The customer email

mobileNumberstring

Mobile phone number in international format (E.164).

Format: Include country code with + prefix

Examples:

  • "+61431000001" (Australia)
  • "+14155552671" (USA)
  • "+442071234567" (UK)

Requirements:

  • Must be a valid, active mobile number
  • Used for SMS verification if needed
  • Maximum 20 characters
Example:"61410001000"
taxIdTypestring(TaxIdType)

The category of tax or government identifier supplied in taxId. The correct value depends on the customer's country and the identifier type accepted for that country.

ValueDescription
identity_cardA government-issued identity card number used for identity or tax reporting in the customer's country.
tax_idA tax identification number issued by a tax authority, such as a TFN, TIN, ITIN, or equivalent.
national_numberA national, citizen, resident, or social insurance number used to identify an individual in their country.
ssnA Social Security Number, generally used for US individuals.
Enum:"identity_card""tax_id""national_number""ssn"
Example:"tax_id"
taxIdstring(TaxId)

Tax identification number.

Example:"123-11-123"
taxStatestring

Tax state or region if applicable.(associated with the taxId) Required format as two characters. Note; We do not accept any states where Banxa is not licensed.

Example:"IL"
providerobjectrequired

Share existing KYC verification from Sumsub

curl -i -X POST \
  https://docs.banxa.com/_mock/products/native-api/openapi/eapi/v0/identities/share/token \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "identityReference": "customer-12345",
    "email": "[email protected]",
    "mobileNumber": "+61431000001",
    "provider": {
      "vendor": "sumsub",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }
  }'

Responses

The identity sharing request has been accepted for processing, but the processing has not been finished yet.

Bodyapplication/json
identityReferencestring, [ 1 .. 255 ] characters(Identity Reference)^[A-Za-z0-9-]+$required

A unique customer identifier provided by the partner. This field is required and must be unique for each customer.

Important: You must consistently reuse the same identityReference for repeat interactions with the same customer, allowing Banxa to reliably recognize and associate their identity across multiple transactions.

Format Requirements:

  • Only ASCII letters (a-z, A-Z), digits (0-9), and hyphens (-) are allowed
  • Must be between 1 and 255 characters
  • Case-sensitive

Best Practices:

  • Use a consistent format across your system
  • Consider using a prefix to identify your organization (e.g., 'partner-customer-123')
  • Do not include personally identifiable information (PII) in the reference
  • Store the mapping between your internal customer ID and this reference securely
Example:"c-13344"
Response
{ "identityReference": "customer-12345" }