Introduction

Users typically refer to your customers, also known 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	The unique and valid email address of the user.
`specifiedUSPerson`	integer	Indicates if the user is a US Person.
`userTypeId`	integer	The type of user. See the list of user types.
`kycLevel`	integer	The current level of KYC validation. See the verification section for more information.
`kycReview`	integer	The current status of the KYC validation. See list of statuses in the verification section.
`kycComment`	string	The 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. Can be one of the following values: `PENDING` – User is being created. `VALIDATED` – User is active. `CANCELED` – User is deleted.
`employeeType`	integer	The kind of employment relation between the user and the company in the context of parent-children relations.
`controllingPersonType`	integer	The type of relation between the user and the legal entity in the context of parent-children relations.
`parentType`	string	The kind of relationship in the context of parent-children relations.
`parentUserId`	integer	The parent user to which the current user is linked, in the context of parent-children relations.
`title`	string	The title of the user (also used when sending physical cards). Can be one of the following: `M` – Stands for mister (Mr.) `MME` – Stands for missus (Mrs.) `MLLE` – Stands for miss `MX` – Gender-neutral title
`firstname`	string	The first name of the Physical User (also used when sending physical cards).
`lastname`	string	The last name of the Physical User (also used when sending physical cards).
`middleNames`	string	The middle names of the Physical 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 (also used when sending physical cards).
`city`	string	The user's address city (also used when sending physical cards).
`state`	string	The user's address state, if any (may also be used when sending physical cards).
`country`	string	The residence country of the user in the ISO 3166-1 alpha-2 format (also 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 date of birth of the Physical User in the `YYYY-MM-DD` format.
`occupationCategory`	string	Type of occupation of the physical user. See occupation category for the list of values.
`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). Conditions the language of the SMS sent for the X-Pay feature.
`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.

API – API Reference available

For a complete list of User attributes, including rules and character restrictions, check the Users section of the API Reference.

Types (`userTypeId`)

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

Reading – Special case of charity, clubs, and syndicates

More information is available on Treezor Support Center regarding charity, clubs, and syndicates.

User Status (`codeStatus`)

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

`codeStatus`	`userStatus`	Description
`110012`	PENDING	Internal checks in progress.
`110005`	CANCELED	User canceled by the end user.
`110006`	CANCELED	User canceled by an operator.
`110009`	VALIDATED	User is validated.

Using unique and valid email addresses

Email addresses must be unique, except for CANCELED users, which are not taken into account for email address checks.

During your Sandbox development phase, however, if you don't cancel users, we recommend that stakeholders (e.g., developers, QA testers) 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@example.com.

Please note that 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 on user's email. Only emails complying with this limit are used for the X-Pay provisioning OTP method.

Legal Forms (`legalForm`)

The legalForm indicates the legal category of the User.

It is required for the KYC Review of any user with a professional activity:

userTypeId of 2, 3, or 4
userTypeId of 1 with a legalForm set to 1000, 10001, 20001,30001, 40001, 50001, or 60001 (self-employed physical users)

You can use the /v1/businessinformations request if you have any doubt regarding the legalForm of your User. An example is available in the Finding the legal representatives section.

Reading – The list of French Legal Forms available on the Insee website

For the most up-to-date list, you can check out the Insee website.

Legal Forms values for Belgian users

Below is the list of legalForm values for users with a distributionCountry set to BE. These apply to users with a userTypeId of 2 except for the first one which is for self-employed users.

Value	Description
`40001`	Self-employed user
`40002`	AAM / OVV / PRVGaG – Association d'assurances mutuelles / Onderlinge verzekeringsvereniging / Versicherungsvereinigung auf Gegenseitigkeit
`40003`	SAM DPU / OVV PR / ÖrVgGe – Association d'assurances mutuelles de droit public / Onderlinge verzekeringsvereniging van publiek recht / Öffentlich-rechtliche Versicherungsvereinigung auf Gegenseitigkeit
`40004`	ACP / VME / MEV – Association des copropriétaires / Vereniging van mede-eigenaars / Miteigentümervereinigung
`40005`	AISBL / IVZW / IVoG – Association internationale sans but lucratif / Internationale vereniging zonder winstoogmerk / Internationale Vereinigung ohne Gewinnerzielungsabsicht
`40006`	ASBL / VZW / VoG – Association sans but lucratif / Vereniging zonder winstoogmerk / Vereinigung ohne Gewinnerzielungsabsicht
`40007`	ASBL DPU / VZW PR / ÖrVohGza – Association sans but lucratif de droit public / Vereniging zonder winstoogmerk van publiek recht / Öffentlich-rechtliche Vereinigung ohne Gewinnerzielungsabsicht
`40008`	FORME FS / VORM SO / RFmsZ – Autre forme à finalité sociale de droit public / Andere vorm met een sociaal oogmerk van publiek recht / Andere öffentlich-rechtliche Rechtsform mit sozialer Zielsetzung
`40009`	AFDP PJ / APRV RP / PRRFmRP – Autre forme de droit privé avec personnalité juridique / Andere privaatrechtelijke vorm met rechtspersoonlijkheid / Andere privatrechtliche Rechtsform mit Rechtspersönlichkeit
`40010`	AFL / AV / ARF – Autre forme juridique / Andere rechtsvorm / Andere Rechtsform
`40011`	CPAS / OCMW / ÖSHZ – Centre public d'action sociale / Openbaar centrum voor maatschappelijk welzijn / Öffentliches Sozialhilfezentrum
`40012`	ETSPUBLI / OI / ÖE – Etablissement public / Openbare instelling / Öffentliche Einrichtung
`40013`	FUP / SON / gnS – Fondation d'utilité publique / Stichting van openbaar nut / Gemeinnützige Stiftung
`40014`	FP / PS / PrSt – Fondation privée / Private stichting / Privatstiftung
`40015`	MUTU / ZIEK F / Kankenka – Mutualité / Ziekenfonds / Krankenkasse
`40016`	SRL / BV / GmbH – Société à responsabilité limitée / Besloten Vennootschap / Gesellschaft mit beschränkter Haftung
`40017`	SRL DPU / BV PR / ÖrGmbH – Société à responsabilité limitée de droit public / Besloten Vennootschap van publiek recht / Öffentlich-rechtliche Gesellschaft mit beschränkter Haftung
`40018`	S. Agr. / LV / LG – Société agricole / Landbouwvennootschap / Landwirtschaftliche Gesellschaft
`40019`	SA / NV / AG – Société anonyme / Naamloze vennootschap / Aktiengesellschaft
`40020`	SC SCS / BV GCV / ZRG EKG – Société civile (Société en commandite simple) / Burgerlijke vennootschap (Gewone commanditaire vennootschap) / Zivilrechtliche Gesellschaft (Einfache Kommanditgesellschaft)
`40021`	SC SNC / BV VOF / ZRG OHG – Société civile (Société en nom collectif) / Burgerlijke vennootschap (Vennootschap onder firma) / Zivilrechtliche Gesellschaft (Offene Handelsgesellschaft)
`40022`	SC / CV / Gen – Société coopérative / Coöperatieve vennootschap / Genossenschaft
`40023`	SC DPU / CV PR / ÖrGen – Société coopérative de droit public / Coöperatieve vennootschap van publiek recht / Öffentlich rechtliche Genossenschaft
`40024`	SDC / MS / GaR – Société de droit commun / Maatschap / Gesellschaft des allgemeinen Rechts
`40025`	SComm / CommV / KommG – Société en commandite / Commanditaire vennootschap / Kommanditgesellschaft
`40026`	SCommDPU / CommV PR / ÖrKommG – Société en commandite de droit public / Commanditaire vennootschap van publiek recht / Öffentlich-rechtliche Kommanditgesellschaft
`40027`	SCA / Comm.VA / KGaA – Société en commandite par actions / Commanditaire vennootschap op aandelen / Kommanditgesellschaft auf Aktien
`40028`	SCS / Comm.V / EKG – Société en commandite simple / Gewone commanditaire vennootschap / Einfache Kommanditgesellschaft
`40029`	SNC / V.O.F. / OHG – Société en nom collectif / Vennootschap onder firma / Offene Handelsgesellschaft
`40030`	SPRL / BVBA / PGmbH – Société privée à responsabilité limitée / Besloten vennootschap met beperkte aansprakelijkheid / Privatgesellschaft mit beschränkter Haftung
`40031`	UP / BV / BV – Union professionnelle / Beroepsvereniging / Berufsvereinigung

Legal Forms values for German users

Below is the list of legalForm values for users with a distributionCountry set to DE. These apply to users with a userTypeId of 2 except for the first one which is for self-employed users.

Value	Description
`20001`	Freiberufler – Selbstständiger
`20002`	GmbH – Gesellschaft mit beschränkter Haftung
`20003`	AG – Aktiengesellschaft Kapitalgesellschaft
`20004`	UG – Unternehmergesellschaft (haftungsbeschränkt)
`20005`	OHG – Offene Handelsgesellschaft Personengesellschaft
`20006`	KG – Kommanditgesellschaft Personengesellschaft
`20007`	GmbH & Co. KG – GmbH & Co. Kommanditgesellschaft Mischform
`20008`	e.K. – Eingetragener Kaufmann Einzelunternehmen
`20009`	eG – Eingetragene Genossenschaft Zusammenschluss
`20010`	PartG – Partnerschaftsgesellschaft Personengesellschaft
`20011`	KGaA – Kommanditgesellschaft auf Aktien Mischform
`20012`	Stiftung – Stiftung Vermögensgebundene Organisation
`20013`	e.V. – Eingetragener Verein Nichtwirtschaftlicher
`20014`	SCE – Europäische Genossenschaft Genossenschaft
`20015`	PartG mbB. – Partnergesellschaft mit beschränkter Berufshaftung
`20016`	jur. Person des öR – juristische Personen des öffentlichen Rechts
`20017`	WEG – Wohnungseigentümergesellschaft
`20018`	EU – Einzelunternehmer (Gewerbetreibender)
`20019`	GbR – Gesellschaft bürgerlichen Rechts
`20020`	SE – Europäische Aktiengesellschaft (Societas Euro.)
`20021`	GmbH u. Co. OHG – Gesellschaft mit beschränkter Haftung Kapitalgesellschaft mit beschränkter Haftung der Gesellschafter und Offene Handelsgesellschaft Personengesellschaft (beschränkte Haftung auf GmbH)
`20022`	gGmbH – Gemeinnützige Gesellschaft mit beschränkter Haftung
`20023`	AG u. Co. KG – Aktiengesellschaft (AG) Kommanditgesellschaft = AG übernimmt die Rolle des Komplementärs (persönlich haftend)
`20024`	AG u. Co. OHG – Personenhandelsgesellschaft mit einer AG als Komplementärin
`20025`	AöR – Anstalt des öffentlichen Rechts

Legal Forms values for Italian users

Below is the list of legalForm values for users with a distributionCountry set to IT. These apply to users with a userTypeId of 2 except for the first one which is for self-employed users.

Value	Description
`10001`	Ditta individuale
`10002`	S.S. – Società semplice
`10003`	S.N.C. – Società in nome collettivo
`10004`	S.A.S. – Società in accomandita semplice
`10005`	S.P.A. – Società per azioni
`10006`	S.A.P.A. – Società in accomandita per azioni
`10007`	S.R.L. – Società a responsabilità limitata
`10008`	S.R.L.S. – Società a responsabilità limitata semplificata
`10009`	COOP. – Società cooperativa
`10010`	E.P.E. – Ente Pubblico Economico
`10011`	Associazione

Legal Forms values for Luxembourg users

Below is the list of legalForm values for users with a distributionCountry set to LU. These apply to users with a userTypeId of 2 except for the first one which is for self-employed users.

Value	Description
`60001`	Entrepreneur individuel
`60002`	AA – Association agricole
`60003`	AAM – Association d'assurances mutuelles
`60004`	ASSEP – Association d'épargne pension
`60005`	AISBL – Association Internationale sans but lucratif
`60006`	ASBL – Association sans but lucratif
`60007`	AUT – Autres Formes juridiques
`60008`	EP – Etablissement public
`60009`	FON – Fondation
`60010`	FIAR – Fonds d'investissement alternatif réservé
`60011`	GIE – Groupement d'intérêt économique
`60012`	Mutuelles
`60013`	SP – Secteur public
`60014`	SARL – Société à responsabilité limitée
`60015`	SARLS – Société à responsabilité limitée simplifiée
`60016`	SA – Société anonyme
`60017`	SC – Société civile
`60018`	SCOP – Société coopérative
`60019`	CoopSA – Société coopérative organisée comme une SA
`60020`	SEPCAV – Société d’épargne-pension à capital variable
`60021`	SICAF – Société d'investissement à capital fixe
`60022`	SICAR – Société d'investissement à capital risque
`60023`	SICAV – Société d'investissement à capital variable
`60024`	SECA – Société en commandite par actions
`60025`	SECS – Société en commandite simple
`60026`	SECSP – Société en commandite spéciale
`60027`	SNC – Société en nom collectif
`60028`	SAS – Société par actions simplifiée

Legal Forms values for Netherlands users

Below is the list of legalForm values for users with a distributionCountry set to NL. These apply to users with a userTypeId of 2 except for the first one which is for self-employed users.

Value	Description
`50001`	Eenmanszaak
`50002`	B.V. – Besloten vennootschap met beperkte aansprakelijkheid
`50003`	C.V. – Commanditaire vennootschap
`50004`	Coöperatie
`50005`	Maatschap
`50006`	N.V. – Naamloze vennootschap
`50007`	Stichting
`50008`	V.o.f. – Vennootschap onder firma
`50009`	Vereniging

Legal Forms values for Spanish users

Below is the list of legalForm values for users with a distributionCountry set to ES. These apply to users with a userTypeId of 2 except for the first one which is for self-employed users.

Value	Description
`30001`	Autónomo – Empresario Individual
`30002`	SC – Sociedad civil
`30003`	S.C. – Sociedad colectiva
`30004`	S.Com. – Sociedad Comanditaria Simple
`30005`	S.Com.P.A. – Sociedad Comanditaria por acciones
`30006`	S.L. – Sociedad de responsabilidad limitada
`30007`	S.L.U. – Sociedad de responsabilidad limitada unipersonal
`30008`	S.A. – Sociedad Anónima
`30009`	S.A.U. – Sociedad Anónima Unipersonal
`30010`	S.L.N.E – Sociedad Limitada Nueva Empresa
`30011`	S.L.L. – Sociedad Limitada Laboral
`30012`	S.COOP. – Sociedad Cooperativa
`30013`	AIE – Agrupación de Interés económique
`30014`	SGR – Sociedad de garantía recíproca
`30015`	SAT – Sociedad agraria de transformación
`30016`	CB – Comunidad de Bienes
`30017`	Fundación
`30018`	Asociaciones y otras instituciones sin fines de lucro a servicio de los hogares
`30019`	Entidad de derecho público
`30020`	Patrimonio de inversión sin personalidad jurídica

Distribution country (`distributionCountry`)

The KYC requirements and regulations may depend on the country your end user is located. Therefore, if you operate in multiple countries, your Treezor configuration includes the list of countries in which you operate.

You must then associate the countries available in your configuration to your Users with the distributionCountry parameter. Doing so helps you tailor the onboarding process of your users, requesting the relevant declarative data and going through the appropriate verification solution.

Treezor currently supports the following distribution countries.

Country	`distributionCountry` value
Belgium	`BE`
France	`FR`
Germany	`DE`
Italy	`IT`
Luxembourg	`LU`
Spain	`ES`
The Netherlands	`NL`

User object

JSON

json

{
	"userId": 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": "FR",
	"secondaryAddress1": "string",
	"secondaryAddress2": "string",
	"secondaryAddress3": "string",
	"secondaryPostcode": "string",
	"secondaryCity": "string",
	"secondaryState": "string",
	"secondaryCountry": "string",
	"phone": "string",
	"mobile": "string",
	"nationality": "string",
	"nationalityOther": "string",
	"placeOfBirth": "string",
	"birthCountry": "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",
	"isFrozen": 0,
	"language": "string",
	"optInMailing": 0,
	"sepaCreditorIdentifier": "string",
	"position": "string",
	"activityOutsideEu": 0,
	"economicSanctions": 0,
	"residentCountriesSanctions": 0,
	"involvedSanctions": 0,
	"entitySanctionsQuestionnaire": 0,
	"sanctionsQuestionnaireDate": "string",
	"timezone": "string",
	"sourceOfFunds": "donation",
	"legalSectorType": "NAF",
	"isOnStockExchange": 0,
	"codeStatus": "string",
	"informationStatus": "string",
	"createdDate": "string",
	"modifiedDate": "string",
	"walletCount": 0,
	"payinCount": 0,
	"totalRows": 0,
	"occupationCategory": 1,
	"personalAssetsRange": 0,
	"monthlyIncomeRange": 1,
	"birthCityCode": null
}

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}/FreezeAssets` Freeze/Unfreeze a User	`admin`
`/v1/users/{userId}` Delete a User	`read_write`, `admin`
`/v1/taxResidences` Create a Tax Residence	`read_write`
`/v1/taxResidences` Search for Tax Residences	`read_only`
`/v1/taxResidences/{taxResidenceId}` Retrieve a Tax Residence based on its `id`	`read_only`
`/v1/taxResidences/{taxResidenceId}` Update a Tax Residence	`read_write`
`/v1/taxResidences/{taxResidenceId}` Delete a Tax Residence	`read_write`

Introduction ​

Key attributes ​

Types (userTypeId) ​

User Status (codeStatus) ​

Using unique and valid email addresses ​

Legal Forms (legalForm) ​

Distribution country (distributionCountry) ​

User object ​

Endpoints ​

Diagram ​