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:
|
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:
|
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:
|
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 autoentrepreneurs (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 |