Legal Entities
A Legal Entity is a company, a governmental or non-governmental organization, or an association. It is identified by a legal name, legal register number, etc.
The legal representatives and majority shareholders must have a parent-children hierarchical relation with the Legal Entity. They are themselves created as Physical Users.
Information – Specific case of self-employed persons
Freelancers and self-employed persons (known as auto-entrepreneur in France) should be created as Physical Users with a legalForm
set to 1000
.
Creation
Parameters
Below are the necessary parameters to create Legal Entities.
While some parameters might not be required by the API, they are necessary when it comes to the KYC validation of the user. They should be collected from the creation (or you may have to update the user information later on).
Attribute | Type | Description |
---|---|---|
userTypeId | integer | Must be 2 (business), 3 (non-governmental organization), or 4 (governmental organization) for legal entities. |
specifiedUSPerson | integer | Indicates if the user is a US Person. |
email | string | The email of the legal entity, which must be valid and can't exceed 200 characters. |
address{1-3} (required for KYC) | string | The legal entity's postal address. The max value for each address line is 150 characters. If you're issuing cards, see the Data Formats article for information on further limitations. |
postcode (required for KYC) | string | The legal entity's address postcode. |
city (required for KYC) | string | The legal entity's address city. |
country (required for KYC) | string | The legal entity's address country (format ISO 3166-1 alpha-2) |
phone (required for KYC) | string | The legal entity's phone number, in international E.164 format. |
legalName (required for KYC) | string | The name of the company. |
legalRegistrationNumber (required for KYC) | string | The registration number of the legal entity (e.g., SIREN/SIRET). |
legalForm (required for KYC) | string | The legal category of the legal entity. See the list of legal forms. |
legalTvaNumber | string | The VAT number of the legal entity. |
legalRegistrationDate (required for KYC) | string | The registration date of the company. Format: YYYY-MM-DD. |
legalShareCapital | integer | The share capital of the legal entity. |
legalAnnualTurnOver (required for KYC) | string | The annual turn over of the legal entity in k€, among the following ranges: 0-39 , 40-99 , 100-249 , 250-999 , 1000-2999 , 3000-9999 , 10000-99999 , and 100000-* |
legalNetIncomeRange (required for KYC) | string | The net income of the legal entity in k€, among the following ranges: 0-4 , 5-9 , 10-49 , 50-149 , 150-499 , and 500-* . |
legalNumberOfEmployeeRange (required for KYC) | string | The number of employees of the legal entity among the following ranges: 0 , 1-9 , 10-99 , 100-249 , and 250-* |
legalSectorType | string | Either NAF or NACE , qualifies the type of data in the legalSector field. |
legalSector (required for KYC) | string | The business sector of the legal entity. Either a 4-digit code if NACE or a 5-digit code followed by an uppercase letter if NAF, depending on the value of the legalSectorType . |
distributionCountry (required for KYC if) | string | The country in which the end user is using your services. This field is only required when you operate in multiple countries. |
Information – Refer to your KYC Form for declarative data
Declarative data to submit depends on the type of user, the country you're operating in, the regulations linked to your use case, etc. Treezor provides you with your KYC Form so you know what needs to be submitted.
Request example
bash
curl -X POST {baseUrl}/v1/users \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
Here is an example of {payload}
:
json
{
"userTypeId":2,
"specifiedUSPerson":0,
"email":"contact.company@example.com",
"address1":"56 Bluewoods lane",
"postcode":"75000",
"city":"Paris",
"country":"FR",
"phone":"+33102030405",
"legalName":"Treehouse Company",
"legalRegistrationNumber":"42877171100028",
"legalTvaNumber":"FR27807465059",
"legalRegistrationDate":"2007-10-24",
"legalShareCapital": 4236474,
"legalForm":"5510",
"legalAnnualTurnOver":"100-249",
"legalNetIncomeRange":"50-149",
"legalNumberOfEmployeeRange":"100-249",
"legalSectorType":"NAF",
"legalSector":"1234F"
}
Returns a User object:
json
{
"users": [
{
"userId": 100138128,
"userTypeId": 2,
"userStatus": "VALIDATED",
"userTag": "",
"parentUserId": 0,
"parentType": "",
"controllingPersonType": 0,
"employeeType": 0,
"specifiedUSPerson": 0,
"title": "",
"firstname": "",
"lastname": "",
"middleNames": "",
"birthday": "0000-00-00",
"email": "contact.company@example.com",
"address1": "56 Bluewoods lane",
"address2": "",
"postcode": "75000",
"city": "Paris",
"state": "",
"country": "FR",
"countryName": "France",
"phone": "+33102030405",
"mobile": "",
"nationality": "",
"nationalityOther": "",
"placeOfBirth": "",
"birthCountry": "",
"occupation": "",
"incomeRange": "",
"legalName": "Treehouse Company",
"legalNameEmbossed": "Treehouse Company",
"legalRegistrationNumber": "42877171100028",
"legalTvaNumber": "FR27807465XX",
"legalRegistrationDate": "2007-10-24",
"legalForm": "5510",
"legalShareCapital": 4236474,
"entityType": null,
"legalSector": "1234F",
"legalAnnualTurnOver": "100-249",
"legalNetIncomeRange": "50-149",
"legalNumberOfEmployeeRange": "100-249",
"effectiveBeneficiary": 0,
"kycLevel": 2,
"kycReview": 0,
"kycReviewComment": "",
"isFreezed": 0,
"isFrozen": null,
"language": "",
"optInMailing": null,
"sepaCreditorIdentifier": "",
"taxNumber": "",
"taxResidence": "",
"position": "",
"personalAssets": "",
"createdDate": "2024-02-15 09:10:05",
"modifiedDate": "0000-00-00 00:00:00",
"walletCount": 0,
"payinCount": 0,
"totalRows": "1",
"activityOutsideEu": 0,
"economicSanctions": 0,
"residentCountriesSanctions": 0,
"involvedSanctions": 0,
"entitySanctionsQuestionnaire": 0,
"address3": null,
"timezone": null,
"occupationType": "",
"isOnStockExchange": 0,
"secondaryAddress1": "",
"secondaryAddress2": "",
"secondaryAddress3": "",
"secondaryPostcode": "",
"secondaryCity": "",
"secondaryState": "",
"secondaryCountry": "",
"clientId": "929252",
"sanctionsQuestionnaireDate": null,
"codeStatus": "110009",
"informationStatus": "",
"legalSectorType": "NAF",
"sourceOfFunds": ""
}
]
}
Checking for veracity
When onboarding a Legal Entity, checking for the veracity of the provided information is key.
Treezor offers a dedicated endpoint to help you in checking these.
Query parameters
Here are the necessary parameters to pass in the queryString.
Attribute | Type | Description |
---|---|---|
country | string | The country of registration of the legal entity. |
vatNumber | string | The VAT number of the legal entity. Required if the registrationNumber is left empty. |
registrationNumber | string | The registration number (e.g., SIREN) of the legal entity. Required if the vatNumber is left empty. |
Request examples
Using the vatNumber
:
bash
curl -X GET {baseUrl}/v1/businesssearchs?country={country}&vatNumber={vatNumber} \
--header 'Authorization: Bearer {accessToken}'
Or alternatively, using the registrationNumber
:
bash
curl -X GET {baseUrl}/v1/businesssearchs?country={country}®istrationNumber={registrationNumber} \
--header 'Authorization: Bearer {accessToken}'
Returns the Business Search object that contains everything CreditSafe knows about this business. You can cross-check these with other reliable source of information (such as infogreffe.fr or societe.com).
json
{
"businesssearchs": [
{
"legalName": "Treehouse Company",
"phone": "",
"legalTvaNumber": "FR018798XXXXX",
"legalRegistrationNumber": "879804805XXXXX",
"status": "I",
"officeType": "1",
"safeNumber": "FR30XXXXXXX",
"activityType": "6312Z",
"externalId": "FR-X-87980480XXXXXXX",
"address1": "26 Willow Road",
"postcode": "75000",
"city": "PARIS",
"state": "ILE DE FRANCE",
"country": "FR",
"tradename": "Treehouse Company"
}
]
}
Information – This endpoint relies on CreditSafe
Despite CreditSafe's best efforts, some information may be inaccurate or up to 72 hours outdated.
Finding the legal representatives
Treezor offers an endpoint to quickly identify the business legal representatives and majority shareholders (assuming they hold more than 25% worth of shares).
Query parameters
Here are the necessary parameters to pass in the queryString.
Attribute | Type | Description |
---|---|---|
country | string | The country of registration of the legal entity. |
vatNumber | string | The VAT number of the legal entity. Required if the registrationNumber is left empty. |
registrationNumber | string | The registration number (e.g., SIREN) of the legal entity. Required if the vatNumber is left empty. |
Request examples
Using the vatNumber
:
bash
curl -X GET {baseUrl}/v1/businessinformations?country={country}&vatNumber={vatNumber} \
--header 'Authorization: Bearer {accessToken}'
Or alternatively, using the registrationNumber
:
bash
curl -X GET {baseUrl}/v1/businessinformations?country={country}®istrationNumber={registrationNumber} \
--header 'Authorization: Bearer {accessToken}'
Returns the Business Information object, with the users
attribute, which contains an array of representatives.
json
{
"businessinformations": [
{
"legalName": "Treehouse Company",
"legalRegistrationNumber": "807465059XXXX",
"legalRegistrationDate": "2014/10/29",
"legalForm": "5710",
"legalShareCapital": "",
"legalSector": "",
"legalAnnualTurnOver": "100-249",
"legalNetIncomeRange": "0-4",
"legalNumberOfEmployeeRange": "100-249",
"phone": "0102030405",
"email": "",
"address1": "33 Rosewood Lane",
"postcode": "75000",
"city": "PARIS",
"state": "Ile-de-France",
"country": "FR",
"status": "A",
"tradename": "Treehouse Company",
"users": [
{
"firstname": "",
"lastname": "",
"fullnames": "M Alex Oak",
"birthday": "1974-12-30T00:00:00Z",
"parentType": "Managing director",
"userTypeId": 2
},
{
"firstname": "",
"lastname": "",
"fullnames": "M Chris Willow",
"birthday": "1982-07-26T00:00:00Z",
"parentType": "President",
"userTypeId": 2
},
// More users can be returned
]
}
]
}
Information – Children relationship for legal representatives
The legal representatives and majority shareholders must be created as Physical Users and associated to the Business User.
Information – This endpoint relies on CreditSafe
Despite CreditSafe's best efforts, some information may be inaccurate or up to 72 hours outdated.
Sanctions and embargo
Some legal entities may be obligated to complete a due diligence questionnaire regarding sanctions and embargoes. Treezor provides a series of parameters for your end users to declare this information directly through the API.
The need to answer the questionnaire concerns:
- Legal entities (
userType
set to2
,3
, or4
) - Self-employed individuals (i.e., individuals with a
legalForm
set to1000
)
More information is available in the KYB - entityType and embargo survey article of the Support Center.
Filling out the questionnaire
To fill out the questionnaire through the API, collect the information while creating a user (/v1/users
) or requesting a user update (/v1/users/{userId}
).
Through the collected answers, the User must:
- Specify for which part of the entity the user answers the questionnaire (
entitySanctionsQuestionnaire
). - Indicate whether they have activity outside the European Union (
activityOutsideEu
). - If they operate outside the EU, answer the questions regarding economics, resident countries, and involved sanctions.
Parameters
Below are the parameters available for the sanctions and embargo questionnaire.
Attribute | Type | Description |
---|---|---|
entitySanctionsQuestionnaire | integer | Defines the scope to which the activityOutsideEu field applies:
|
activityOutsideEu | integer | Whether the entity and its business units, subsidiaries, and joint ventures have a commercial activity the European Union. Can be:
|
economicSanctions | integer | Whether the entity, its subsidiaries, entities, employees, directors, beneficial owners, or joint ventures are subject to Economic Sanctions. Can be:
|
residentCountriesSanctions | integer | Whether the entity, its subsidiaries, or joint ventures, located within or operating from any countries or territories are subject to Comprehensive Sanctions. Can be:
|
involvedSanctions | integer | Whether the entity, its subsidiaries, or joint ventures, are engaged in transactions, investments, business, or other dealings that directly or indirectly involve or benefit:
|
Example
Here is an example of a legal entity creation with the questionnaire:
bash
curl -X POST {baseUrl}/v1/users \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'
Here is an example of {payload}
:
json
{
"userTypeId":2,
"specifiedUSPerson":0,
"email":"contact.company@example.com",
"address1":"56 Bluewoods lane",
"postcode":"75000",
"city":"Paris",
"country":"FR",
"phone":"+33102030405",
"legalName":"Treehouse Company",
"legalRegistrationNumber":"42877171100028",
"legalTvaNumber":"FR27807465059",
"legalRegistrationDate":"2007-10-24",
"legalShareCapital": 4236474,
"legalNetIncomeRange":"50-149",
"legalNumberOfEmployeeRange":"100-249",
"legalSectorType":"NAF",
"legalForm": "5499",
"legalSector": "2051Z",
"legalAnnualTurnOver": "1000-2999",
"entityType": 4,
"activityOutsideEu": 1,
"economicSanctions": 0,
"residentCountriesSanctions": 0,
"involvedSanctions": 0,
"entitySanctionsQuestionnaire": 0
}
Returns a User object:
json
{
"users": [
{
"userId": 100138128,
"userTypeId": 2,
"userStatus": "VALIDATED",
"userTag": "",
"parentUserId": 0,
"parentType": "",
"controllingPersonType": 0,
"employeeType": 0,
"specifiedUSPerson": 0,
"title": "",
"firstname": "",
"lastname": "",
"middleNames": "",
"birthday": "0000-00-00",
"email": "contact.company@example.com",
"address1": "56 Bluewoods lane",
"address2": "",
"postcode": "75000",
"city": "Paris",
"state": "",
"country": "FR",
"countryName": "France",
"distributionCountry": null,
"phone": "+33102030405",
"mobile": "",
"nationality": "",
"nationalityOther": "",
"placeOfBirth": "",
"birthCountry": "",
"occupation": "",
"incomeRange": "",
"legalName": "Treehouse Company",
"legalNameEmbossed": "Treehouse Company",
"legalRegistrationNumber": "42877171100028",
"legalTvaNumber": "FR27807465XX",
"legalRegistrationDate": "2007-10-24",
"legalForm": "5499",
"legalShareCapital": 4236474,
"entityType": "4",
"legalSector": "2051Z",
"legalAnnualTurnOver": "1000-2999",
"legalNetIncomeRange": "50-149",
"legalNumberOfEmployeeRange": "100-249",
"effectiveBeneficiary": 0,
"kycLevel": 2,
"kycReview": 0,
"kycReviewComment": "",
"isFreezed": 0,
"isFrozen": null,
"language": "",
"optInMailing": null,
"sepaCreditorIdentifier": "",
"taxNumber": "",
"taxResidence": "",
"position": "",
"personalAssets": "",
"createdDate": "2024-02-15 09:10:05",
"modifiedDate": "0000-00-00 00:00:00",
"walletCount": 0,
"payinCount": 0,
"totalRows": "1",
"activityOutsideEu": 1,
"economicSanctions": 0,
"residentCountriesSanctions": 0,
"involvedSanctions": 0,
"entitySanctionsQuestionnaire": 0,
"address3": null,
"timezone": null,
"occupationType": "",
"isOnStockExchange": 0,
"secondaryAddress1": "",
"secondaryAddress2": "",
"secondaryAddress3": "",
"secondaryPostcode": "",
"secondaryCity": "",
"secondaryState": "",
"secondaryCountry": "",
"clientId": "929252",
"sanctionsQuestionnaireDate": null,
"codeStatus": "110009",
"informationStatus": "",
"legalSectorType": "NAF",
"sourceOfFunds": ""
}
]
}
Know Your Customer (KYC)
The legal representatives and majority shareholders of the business must have Physical Users created and associated to the Legal Entity. The Legal Entity can then undergo KYC review, this will trigger the review of all its children (representatives and shareholders) at the same time.
Information – The mandatory requirements regarding KYC review of businesses are constantly evolving
For the most up-to-date information, we recommend that you check the documents Treezor provided you with. Learn more about KYC review of Legal Entities in the Support Center.
Types (userTypeId
)
Below the userTypeId
values for legal entities.
Value | Description |
---|---|
2 | Business user |
3 | Non-governemental organization |
4 | Governemental organization |
Reading – Special case of charity, clubs, and syndicates
More information is available on Treezor Support Center regarding charity, clubs, and syndicates.
Entity Type (entityType
)
Below the entityType
values for legal entities.
Value | Description |
---|---|
1 | Reporting Financial Institution |
2 | Non-Reporting Financial Institution |
3 | Active Non-Financial Entity - Governmental entities, Int. organizations |
4 | Active Non-Financial Entity - Other |
5 | Passive Non-Financial Entity - Investment entity that is not Participating Jurisdiction FI |
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
of2
,3
, or4
userTypeId
of1
with alegalForm
set to1000
(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.