Introduction

Users are usually your customers, also referred to as end users. They can be:

• Physical Users, representing an actual human being.
• Legal Entities, representing a company, association, etc.
• Anonymous, which are users with close to no declarative data, intended for specific and limited use cases.

Users can also have hierarchical parent-children relations between them.

Key attributes

Below are some of the most important User attributes.

Attribute	Type	Description
email	string	Unique and valid email address.
specifiedUSPerson	integer	Indicates if the user is a US Person.
userTypeId	integer	The type of user. See list of types.
kycLevel	integer	The current level of KYC validation. See list of levels.
kycReview	integer	The current status of the KYC validation. See list of statuses.
kycComment	string	A comment set by Treezor upon KYC review. It concatenates information for each KYC Review update, with the date, the kycReview and kycLevel values, and the comment from Treezor.
userStatus	string	The user status as set by Treezor. Can be one of the following values: PENDING – User has just been created. VALIDATED – User is validated. CANCELED – User is deleted.
entityType	integer	See list of types
employeeType	integer	Used in the context of parent-children relations
controllingPersonType	integer	Used in the context of parent-children relations
parentType	string	Used in the context of parent-children relations
parentUserId	integer	Used in the context of parent-children relations
title	string	The title of the user, used when sending physical cards. Can be one of the following: M – Stands for mister (Mr.) MME – Stands for misses (Mrs.) MLLE – Stands for miss
firstname	string	The first name of the user, used when sending physical cards.
lastname	string	The last name of the user, used when sending physical cards.
middleNames	string	The middle names of the user, if any.
address{1-3}	string	Postal address of the user, also used when sending physical cards. See limitations regarding address fields length
postcode	string	Postcode of the user, used when sending physical cards.
city	string	The user's address city, used when sending physical cards.
state	string	The user's address state, if any. May be used when sending physical cards.
country	string	The residence country of the user in the ISO 3166-1 alpha-2 format. Used when sending physical cards.
position	string	Only for NGOs, indicating their geographic activity coverage.
legal{Name/Form/...}	string	Used to describe Legal Entities
birthday	string	The birthday of the user in the YYYY-MM-DD format.
occupationType	string	The professional status of the user, used for Physical Users, which can be: self_employed, public_sector_employees, private_sector_employees, retired_people_and_students, without_any_professional_activity
timezone	string	The local timezone of the user in tz database format Area/Location (e.g., America/New_York, Europe/Paris)
language	string	The preferred language of the user (ISO 639-1).
isOnStockExchange	integer	The Legal Entity presence on Stock Exchange: 0 – No (Physical Users must use this value) 1 – Yes
distributionCountry	string	The country in which the end user is using your services. This field is only required when you operate in multiple countries. Otherwise, it either defaults to your country or is set to null. Please contact Treezor to configure this feature. Format: ISO 3166-1 alpha-2 format.

Best practice – For self-employed users (userTypeId=1 and legalForm=1000):

• Their professional address should be set in the primary address fields
• Their personal address should be set in the secondary address fields. Should one of the secondary address fields be set, all others must be set too before submitting a KYC Review.

API – Swagger documentation available

For a complete list of User attributes, check the Users section of the Swagger.

Types (userTypeId)

userTypeId	User types
1	Physical User and Anonymous User
2	Business User
3	Non-governmental organization
4	Governmental organization

User Status (codeStatus)

Most user codeStatus values are deprecated, here are the ones you may encounter.

	codeStatus	userStatus	Description
	110005	CANCELED	User canceled by an operator.
	110006	CANCELED	User canceled by the end user.
	110009	VALIDATED	User is validated.

Using unique and valid email addresses

During your Sandbox development phase, we recommend that stakeholders (Developers, QA testers, etc.) use their own email address with a random +tag suffixed to it.

For example, if your email address is firstname.lastname@example.com, you can use:

• firstname.lastname+test1@example.com
• firstname.lastname+test2@example.com
• firstname.lastname+testn@example.com

All of which are unique and valid addresses that automatically redirect emails to firstname.lastname@domain.tld.

Please note the use of disposable email addresses or services is strongly discouraged and can be rejected by the Treezor API.

Note – 50-character limit for X-Pay provisioning OTP method

If you're using the X-Pay feature, consider enforcing a < 50-character limit to user's email. Only emails complying with this limit are used for the X-Pay provisioning OTP method.

Structure

JSON

{
	"userId": 0,
	"userTypeId": 0,
	"userStatus": "PENDING",
	"userTag": "string",
	"parentUserId": 0,
	"parentType": "shareholder",
	"controllingPersonType": 0,
	"employeeType": 0,
	"specifiedUSPerson": 0,
	"title": "M",
	"firstname": "string",
	"lastname": "string",
	"middleNames": "string",
	"birthday": "string",
	"email": "string",
	"address1": "string",
	"address2": "string",
	"address3": "string",
	"postcode": "string",
	"city": "string",
	"state": "string",
	"country": "string",
	"countryName": "string",
	"distributionCountry": "string",
	"phone": "string",
	"mobile": "string",
	"nationality": "string",
	"nationalityOther": "string",
	"placeOfBirth": "string",
	"birthCountry": "string",
	"occupation": "string",
	"incomeRange": "string",
	"legalName": "string",
	"legalNameEmbossed": "string",
	"legalRegistrationNumber": "string",
	"legalTvaNumber": "string",
	"legalRegistrationDate": "string",
	"legalForm": "string",
	"legalShareCapital": 0,
	"legalSector": "string",
	"legalAnnualTurnOver": "string",
	"legalNetIncomeRange": "string",
	"legalNumberOfEmployeeRange": "string",
	"effectiveBeneficiary": 0,
	"kycLevel": 0,
	"kycReview": 0,
	"kycReviewComment": "string",
	"isFreezed": 0,
	"isFrozen": 0,
	"language": "string",
	"optInMailing": 0,
	"sepaCreditorIdentifier": "string",
	"taxNumber": "string",
	"taxResidence": "string",
	"position": "string",
	"personalAssets": "string",
	"activityOutsideEu": 0,
	"economicSanctions": 0,
	"residentCountriesSanctions": 0,
	"involvedSanctions": 0,
	"sanctionsQuestionnaireDate": "string",
	"timezone": "string",
	"createdDate": "string",
	"modifiedDate": "string",
	"walletCount": 0,
	"payinCount": 0,
	"totalRows": 0
}

Endpoints

Endpoint	Scope
/v1/users Create a User	legal, admin
/v1/users Search for Users	read_only
/v1/users/{userId} Retrieve a User based on its id	read_only
/v1/users/{userId} Update a User	read_write
/v1/users/{userId} Delete a User	read_write, admin
/v1/users/{userId}/FreezeAssets Freeze/Unfreeze a User	admin

Diagram