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

CURL

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:

CURL

curl -X GET {baseUrl}/v1/businesssearchs?country={country}&vatNumber={vatNumber} \
	--header 'Authorization: Bearer {accessToken}'

Or alternatively, using the registrationNumber:

CURL

curl -X GET {baseUrl}/v1/businesssearchs?country={country}&registrationNumber={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:

CURL

curl -X GET {baseUrl}/v1/businessinformations?country={country}&vatNumber={vatNumber} \
	--header 'Authorization: Bearer {accessToken}'

Or alternatively, using the registrationNumber:

CURL

curl -X GET {baseUrl}/v1/businessinformations?country={country}&registrationNumber={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 to 2, 3, or 4)
• Self-employed individuals (i.e., individuals with a legalForm set to 1000)

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:

1. Specify for which part of the entity the user answers the questionnaire (entitySanctionsQuestionnaire).
2. Indicate whether they have activity outside the European Union (activityOutsideEu).
3. 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: 1 – Only the legal entity 2 – The legal entity and all its subsidiaries held at 100% 3 – The legal entity and all its subsidiaries held at 50% or more 4 – The legal entity and a list of subsidiaries The 0 value is also available, but prevents the user from being KYC validated if they have to fill the questionnaire.
activityOutsideEu	integer	Whether the entity and its business units, subsidiaries, and joint ventures have a commercial activity the European Union. Can be: 0 – False 1 – True. When set to this value, the next attributes become mandatory.
economicSanctions	integer	Whether the entity, its subsidiaries, entities, employees, directors, beneficial owners, or joint ventures are subject to Economic Sanctions. Can be: 0 – False 1 – True
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: 0 – False 1 – True
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: Any countries or territories subject to Comprehensive Sanctions, or Any person or entity which is the target of any Sanctions (“Sanctioned Targets”). Can be: 0 – False 1 – True

Example

Here is an example of a legal entity creation with the questionnaire:

CURL

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,
    "entitySanctionsQuestionnaire": 1,
    "activityOutsideEu": 1,
    "economicSanctions": 0,
    "residentCountriesSanctions": 0,
    "involvedSanctions": 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": 1,
            "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.

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 of 2, 3, or 4
• userTypeId of 1 with a legalForm set to 1000 (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.