Skip to navigation

KYC Reliance using APIs

Submit KYC you have already completed on your platform, so users don't repeat it with Transak
View as Markdown

KYC Reliance using API lets you submit KYC your platform has already completed (via Sumsub, Onfido, or any provider), so end-users don’t repeat KYC for Transak. Transak validates the submission and relies on your KYC instead of re-running it, cutting friction and drop-off while meeting Transak’s compliance requirements.

EEA users: send the sourceOfIncome and additionalDetails objects in the Identity Details API, and do not send driving licences. Send the consent object only when Get Additional Requirements returns type: CONSENT for the user. See MiCA Changes for EEA Users.

Our Solution

Provider agnostic

Partners are not limited to a single KYC vendor. They can collect KYC data using providers like Sumsub, Onfido, and map that data via Transak’s KYC Reliance using API.

Aggregated payloads

All required data such as personal details, address, purpose of usage, and country-specific ID documents can be submitted together in a single API call, instead of multiple calls.

How to integrate?

1

Whitelist Your API Keys

Action
Follow the steps in the Need help in Integration section
Request API key whitelisting and ask to enable KYC Reliance using API for your API key
Share your public IP addresses with Transak for whitelisting to use our APIs in your backend
2

Submit user details (profile, address, purpose, and ID Document details)

Call the Identity Details API with a single combined payload.

This should include the following data:

Personal Details (required)

KeySub KeyTest data
personalDetailsfirstNameJane
lastNameDoe
dob1998-01-01
mobileNumber+33791112345
addressDetailsaddressLine1170 Rue du Faubourg Saint-Denis
countryCodeFR
postCode75010
stateParis
cityParis
addressLine2optional

PURPOSE OF USAGE (required)

keydescription
purposeList*"Buying/selling crypto for investments",
"Buying NFTs",
"Buying crypto to use a web3 protocol"

TIN Details (optional)

keydescription
documentType*[US_SSN]
documentNumber*Identification number

Use the same allowed purposeList values as existing API contract. Country-specific tax ID details are required only when applicable, for example US_SSN for the United States.

3

Submit identity documents

Call the Document Details API with this below fields:

KeyDescription
idType*Type of Document IDs (see Supported Document IDs section below)
idCountryCode*Country code where the document was issued
idNumber*Document identification number
frontImage*Front image of the document (base64, max 5MB)
backImageBack image of the document (base64, max 5MB) (optional)

idNumber field is Optional only for PROOF_OF_RESIDENCE document type. For all other document types, idNumber is required.

4

Submit biometrics (selfie and liveness)

Call the Biometrics Details API to submit the user’s biometric verification media.

Both values must be base64-encoded and sent as data URIs. See Supported formats for the accepted file types.

data:<mime-type>;base64,<base64_encoded_data>

Example: data:image/png;base64,<base64_encoded_data>

Either both or any other can be submitted for selfie and liveness to complete the KYC submission.

Supported Formats

Media typeAccepted formats
Selfie Image (document ID front/back, selfie)JPEG PNG WEBP
liveness VideoMP4

Supported Document IDs

idTypeAccepted documents
PASSPORTpassport
DRIVING_LICENSEDriving Licence
ID_CARDNational Identity Card
PROOF_OF_RESIDENCEBank Statement, Resident Permit, Utility Bill, Payslip
VISAvisa
UNKNOWNAny other value not listed above

Field Validation

Personal & Address Fields

FieldConstraint
firstName / lastName1–50 characters, counted after conversion (ß counts as ss). Latin letters, including accented letters (for example é, ø, ł, ß), which are converted to plain letters.
Cannot contain ^ ! # $ % * = < > ; { } " or a backslash; typographic double quotes “ ” count as ”. Letters from other scripts (Cyrillic, Greek, Arabic, Chinese and so on), symbols, ° and № are not accepted.
addressLine13–200 characters, with at least one letter. Latin letters, including accented letters, which are converted to plain letters, № becomes No, and º and ° become o. Letters from other scripts and symbols are not accepted.
addressLine2Optional Up to 200 characters. If sent, it must contain at least one letter (Apt 12 is accepted, 12 alone is not). Same character rules as addressLine1.
city2 to 50 characters, with at least one letter.
state2 to 100 characters, with at least one letter.
postCodeMust be a valid postal code for the given countryCode
dobISO 8601 date (YYYY-MM-DD). User must be ≥ 18 and < 150 years old
mobileNumberMust be a valid international phone number (E.164 format, e.g. +33791112345)

Transak keeps the name and address exactly as sent and uses the converted form for verification (for example Søren Ólafsdóttir is verified as Soren Olafsdottir). Invisible characters and extra spacing are removed, and typographic quotes and dashes are converted to their plain form before the value is checked.

Field patterns

FieldPattern
firstName, lastName^(?!\s+$)[NAME_CHARACTERS]{1,50}$
addressLine1^(?!\s+$)(?=.*[LETTERS])[ADDRESS_CHARACTERS]{3,200}$
addressLine2^(?=.*[LETTERS])[ADDRESS_CHARACTERS]{0,200}$|^\s*$
city^(?!\s+$)(?=.*[LETTERS])[ADDRESS_CHARACTERS]{2,50}$
state^(?!\s+$)(?=.*[LETTERS])[ADDRESS_CHARACTERS]{2,100}$

Tin Details

ValueApplicable countrydocumentNumber format
US_SSNUS9 digits (e.g. 123456789)

How to encode images and video as Base64

All document images, selfies, and liveness media should be sent as Base64-encoded strings.

  • The encoded value must be a single continuous string (no line breaks or spaces).
  • Ensure the full file is encoded — do not truncate the string.

Encode a file as Base64 (example snippets)

Node.js
const fs = require('fs');
// Supported image formats: JPEG, PNG, WEBP
// Supported video format: MP4
const filePath = './id-front.jpg';
const mimeType = 'image/jpeg'; // e.g. image/png, image/webp, video/mp4
const base64Data = fs.readFileSync(filePath, { encoding: 'base64' });
const encoded = `data:${mimeType};base64,${base64Data}`;
// Send `encoded` in the API request body

How does it work?

KYC Reliance Using API

Current Limitations

LimitationDetails
KYC Reliance APIs

The KYC Reliance API must be called only from the partner’s backend and subjected to the whitelisting of partner IP addresses. Direct API calls from the frontend apps are not supported.

FCA Flow (For UK Users) not supported

Partners can integrate the APIs to submit the FCA requirements. See the How to Submit FCA Requirements guide for step-by-step instructions.

API Overview

API Errors

Status CodeError CodeMessage
4011002Invalid or missing authentication token.
4011002authorization or x-access-token+x-user-identifier required
4011014Invalid or missing access-token.
4011002Invalid or expired token
4011010Invalid token
4011023User not found. Please onboard the user first.
4011002Auth reliance feature is not enabled for this partner
4011002API key is not active. Please complete the KYC to go live with us.
4011002IP not authorized
4039001IP not authorized
4011002Invalid access token
4031024Services are temporarily unavailable in your region. Please bear with us - we expect to be back soon.
4009001Invalid request payload JSON format
4139001Payload content length greater than maximum allowed: 1048576
4039999KYC reliance v2 is not allowed for partner
4009001personalDetails is required
4009001firstName is required in personalDetails
4009001lastName is required in personalDetails
4009001dob is required in personalDetails
4009001addressDetails is required
4009001countryCode is required in addressDetails
4009001postCode is required in addressDetails
4009001purposeList is required and must be a non-empty array
4009001documentType must be US_SSN or PAN_NUMBER
4009001documentNumber is required in tinDetails
4009001Invalid request payload input
4009999KYC is not required for this user
4009999firstName is required
4009999lastName is required
4009999mobileNumber is a required argument
4009999mobileNumber is required
4009999Invalid date
4009999Invalid date of birth
4003002You don’t meet our age requirements
4002021The phone number entered is invalid. Please check the selected country and entered digits.
4002020This phone number is already registered. It has been used by an account created with {masked email}. Login with this email to continue.
4009999addressLine1 is a required argument
4009999city is a required argument
4009999addressLine1 is required
4009999city is required
4009999postCode is required
4009999Address Line should be greater than 2 characters!
4009999Address Line should be less than 201 characters!
4009999Address Line 2 should be less than 201 characters!
4009999City should be greater than 1 characters!
4009999City should be less than 51 characters!
4009999State/Region should be greater than 1 characters!
4009999State/Region should be less than 101 characters!
4009999Your first name contains unsupported characters. Please enter it as shown on your ID.
4009999Your last name contains unsupported characters. Please enter it as shown on your ID.
4009999Your address line contains unsupported characters. Please enter it as shown on your ID.
4009999Your address line2 contains unsupported characters. Please enter it as shown on your ID.
4009999Your city name contains unsupported characters. Please enter it as shown on your ID.
4009999Your state name contains unsupported characters. Please enter it as shown on your ID.
4009999Following characters not allowed for name: ^,!,#,$,%,*,=,<,>,;,{,},“
4009999First Name should be less than 51 characters!
4009999Last Name should be less than 51 characters!
4009999’Address Line’ field should have at least 1 alphabet! Please check and enter a valid Address Line
4009999’Address Line 2’ field should have at least 1 alphabet! Please check and enter a valid Address Line 2
4009999’City’ field should have at least 1 alphabet! Please check and enter a valid City
4009999’State’ field should have at least 1 alphabet! Please check and enter a valid State
4003015Invalid postal codes, please enter your country postal code
4009999Please enter your postal code in English only! Remove accented characters, if any.
4009999Invalid country selection
4009999Unfortunately, we do not support your region. We are actively working on expanding our coverage!
4009999{state}, {country} residents can’t access crypto services due to regulatory changes. Please update your location if incorrect.
4009999{country} residents can’t access crypto services due to regulatory changes. Please update your location if incorrect.
4009999Transak service update: Currently unavailable for United Kingdom residents via this partner. Please place your order directly at https://global.transak.com. Contact https://support.transak.com for questions.
4009999We do not accept PO box as a valid form of address.
4009999Missing required reliance data: tinDetails
4002022Invalid SSN. Please enter a valid Social Security Number.
4002033This SSN is already registered. It has been used by an account created with {masked email}. Login with this email to continue.
4009999”purposeList[{index}]” must be one of [Buying/selling crypto for investments, Buying NFTs, Buying crypto to use a web3 protocol]
4009999”purposeList” must contain less than or equal to 10 items
4009999Invalid countryCode: “{value}“
4009001consentedAt is required
4009999Consent timestamps must be ISO 8601 with a timezone offset, e.g. 2026-09-01T10:15:00Z
4009001sourceOfFundsType is required in sourceOfIncome
4009999Invalid employment status
4009999Unable to submit KYC reliance data
5039999Service Unavailable
500VariesVaries
Status CodeError CodeMessage
4011002Invalid or missing authentication token.
4011002authorization or x-access-token+x-user-identifier required
4011014Invalid or missing access-token.
4011002Invalid or expired token
4011010Invalid token
4011023User not found. Please onboard the user first.
4011002Auth reliance feature is not enabled for this partner
4011002API key is not active. Please complete the KYC to go live with us.
4011002IP not authorized
4039001IP not authorized
4011002Invalid access token
4031024Services are temporarily unavailable in your region. Please bear with us - we expect to be back soon.
4009001Invalid request payload JSON format
4139001Payload content length greater than maximum allowed: 13983064
4009001documentProof is required
4009001idType must be one of PASSPORT, DRIVING_LICENSE, ID_CARD, VISA, PROOF_OF_RESIDENCE, UNKNOWN
4009001idCountryCode must be a 2-letter ISO uppercase country code
4009001idNumber is required in documentProof
4009001frontImage is required in documentProof
4009001frontImage must not exceed 6990508 characters in documentProof
4009001backImage must not exceed 6990508 characters in documentProof
4009001Invalid request payload input
4049999KYC request not found
4009999”documentProof.backImage” is not allowed to be empty
4009999”documentProof.idCountry” with value “{value}” fails to match the required pattern: /^[A-Z]{2,3}$/
4009999Invalid countryCode: “{value}“
4009999Invalid documentProof.frontImage: must be a non-empty base64 string
4009999Invalid documentProof.backImage: must be a non-empty base64 string
4009999Invalid documentProof.frontImage: base64 data is empty
4009999Invalid documentProof.backImage: base64 data is empty
4009999Invalid documentProof.frontImage: unsupported MIME type “{type}”. Allowed: image/jpeg, image/png, image/webp
4009999Invalid documentProof.backImage: unsupported MIME type “{type}”. Allowed: image/jpeg, image/png, image/webp
4009999Unable to submit KYC reliance data
5039999Service Unavailable
500VariesVaries
Status CodeError CodeMessage
4011002Invalid or missing authentication token.
4011002authorization or x-access-token+x-user-identifier required
4011014Invalid or missing access-token.
4011002Invalid or expired token
4011010Invalid token
4011023User not found. Please onboard the user first.
4011002Auth reliance feature is not enabled for this partner
4011002API key is not active. Please complete the KYC to go live with us.
4011002IP not authorized
4039001IP not authorized
4011002Invalid access token
4031024Services are temporarily unavailable in your region. Please bear with us - we expect to be back soon.
4009001Invalid request payload JSON format
4139001Payload content length greater than maximum allowed: 20973572
4009001at least one of selfie or liveness is required
4009001selfie must not be empty
4009001liveness must not be empty
4009001selfie must not exceed 6990508 characters
4009001liveness must not exceed 13981016 characters
4009001Invalid request payload input
4049999KYC request not found
4009999document-details to be called first
4009999Invalid selfie: must be a non-empty base64 string
4009999Invalid selfie: base64 data is empty
4009999Invalid selfie: unsupported MIME type “{type}”. Allowed: image/jpeg, image/png, image/webp
4009999Invalid liveness: must be a non-empty base64 string
4009999Invalid liveness: base64 data is empty
4009999Invalid liveness: unsupported MIME type “{type}”. Allowed: image/jpeg, image/png, image/webp
4009999Invalid liveness: decoded size {n} bytes exceeds 5MB limit
4009999tinDetails.type must be “SSN” for country USA, got “PAN”.
4009999tinDetails.countryCode must be “USA” for country USA, got “undefined”.
4009999Invalid date of birth
4001024Services are temporarily unavailable in your region. Please bear with us - we expect to be back soon.
4009999Incomplete KYC submission. Required details not received: {fields}
4009999Unable to submit KYC reliance data
5039999Service Unavailable
500VariesVaries