Appearance

KYC Request ​

Prior to requesting a KYC Review for a user, make sure that:

  • All the necessary declarative data has been provided in the User object
  • All the necessary Documents have been uploaded and checked
  • The country of tax residency has been properly declared
Thumbs icon

Best practice – Submitting a KYB must be done for all users at once

The legal entity, its legal representative and shareholders are reviewed as a whole. You can submit the legal entity KYB request only once you have provided all the required documents for all the corresponding users.

The more you abide by the rules of verification, the more efficient Treezor teams will be in verifying your users, allowing for a much smoother experience.

Request a review of the user Legacy ​

Endpoint: /v1/users/{userId}/Kycreview

bash
curl -X PUT '{baseUrl}/v1/users/{userId}/Kycreview' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

It returns the User object, with its kycLevel set to 0 (NONE) and kycReview set to 1 (PENDING).

json
{
	"users": [
		{
			"userId": "1611975",
			"userTypeId": "1",
			"kycLevel": "0",		// NONE
			"kycReview": "1",		// PENDING
			"kycReviewComment": "",	// <--- No comment has been set by Treezor yet
			[...] // some attributes are hidden
		}
	]
}

Treezor also sends a user.kycrequest webhook. Once the user refused or validated, you receive a user.kycreview webhook.

Info icon

Information – Treezor's Compliance team verifies your company in Production

Verification usually takes about 24h, but may take up to 48h or more (working days only).

Request User verification New KYC Life Cycle ​

KYC object ​

The New KYC life cycle introduces a new KYC object gathering the user KYC-related information as part of the life cycle.

json
{
  "userId": 1,
  "clientId": 1234,
  "distributionCountry": "FR",
  "kycLevel": 1,
  "kycReview": 2,
  "kycReviewComment": "foo",
  "kycStatus": "VALIDATED",
  "kycReviewType": "ONBOARDING",
  "codeStatus": "110006",
  "informationStatus": "The user's identity has been successfully verified, and all compliance requirements are met.",
  "lastRequestDatetime": "2015-02-25T11:06:39Z",
  "lastReviewDatetime": "2015-02-25T15:06:39Z",
  "nextReviewDate": "2020-02-25"
}

Please note there can be only one KYC object per user; the object is updated as the user goes through their KYC journey.

Key attributes ​

Below the attributes of the new KYC object.

AttributeTypeDescription
userIdintegerThe unique identifier of the user.
clientIdintegerThe identifier of the Treezor environment.
distributionCountrystringThe user's country of distribution. See Distribution country.
kycLevel integerRetained for migration purposes only.
kycReview integerRetained for migration purposes only.
kycReviewCommentstringInternal comments from Treezor’s compliance team. Provides specific guidance if a request is "Incomplete".
kycStatusstringThe current verification stage. Replaces kycLevel and kycReview. See statuses.
kycReviewTypestringThe reason for the verification:
  • ONBOARDING – Initial verification.
  • PERIODIC – Routine compliance check.
  • ON_EVENT – Triggered by account changes (e.g., address change).
codeStatusstringA unique technical code indicating the specific reason for the current kycStatus. See statuses.
informationStatusstringA human-readable explanation of the codeStatus. See statuses.
lastRequestDatetimestringTimestamp of the user's most recent KYC request.
lastReviewDatetimestringTimestamp of the most recent manual or automatic review by Treezor.
nextReviewDatestringThe date of the next scheduled review. Note: kycStatus changes to REVIEW_NEEDED 3 months prior to this date.

Statuses (codeStatus) ​

statuscodeStatusinformationStatus
NONE110001No request has been submitted for this user yet.
PENDING110002The request for verification has been submitted and is currently awaiting review.
INCOMPLETE110003Some documents or information are missing; action is required for this user.
REFUSED110004Treezor refused to validate the user identity due to non-compliance, fraud suspicion, or ineligible documentation.
REVIEWNEEDED110005The user must be verified again (periodic review or review following an event).
VALIDATED110006The user's identity has been successfully verified, and all compliance requirements are met.
CANCELED110007The request was canceled after being refused for a certain amount of time.

Request a review ​

Request example ​

Endpoint: /v1/users/{userId}/Kycreview

bash
curl -X PUT '{baseUrl}/v1/users/{userId}/Kycreview' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

Treezor sends a kycreview.request webhook. Once the user refused or validated, you receive a kycreview.result webhook.

Retrieve the user's KYC information ​

Request example ​

Endpoint: /v1/users/{userId}/kyc

bash
curl -X PUT '{baseUrl}/v1/users/{userId}/kyc' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json'

Returns the KYC object of the user if successful.

json
{
  "userId": 1,
  "clientId": 1234,
  "distributionCountry": "FR",
  "kycLevel": 1,
  "kycReview": 2,
  "kycReviewComment": "foo",
  "kycStatus": "VALIDATED",
  "kycReviewType": "ONBOARDING",
  "codeStatus": "110006",
  "informationStatus": "The user's identity has been successfully verified, and all compliance requirements are met.",
  "lastRequestDatetime": "2015-02-25T11:06:39Z",
  "lastReviewDatetime": "2015-02-25T15:06:39Z",
  "nextReviewDate": "2020-02-25"
}

Endpoints ​

EndpointScope
/v1/users/{userId}/Kycreview
Initiate the user KYC review process		read_write
/v1/users/{userId}/kyc
Retrieve a user KYC information		read_only