Create Related Party

Introduction

This resource is used to identify the ultimate beneficial owners (natural persons) and controllers related to the legal entity investor, such as partners, directors, administrators, etc., or attorneys-in-fact of a natural person.

Attention

This endpoint must be called multiple times, once for each related party
For a legal entity as a related party, the related_party_type must be parent_company (except in fund_class)
The quantity, legal representative and minimum equity interest requirements vary according to the investor type — see Requirements by investor type below
To correct or deactivate an already created related party, use Update Related Party and Update Related Party Status. Parties with the inactive status are no longer considered in any of the validations when the registration is sent for analysis

Requirements by investor type

The validations below are applied when the registration is sent for analysis (submit), not when the related party is created. Each rule is evaluated in sequence, so one rejection may hide the next pending issue.

Investor	Related parties	Legal representative	Summed equity interest
Natural person (`natural_person`)	Optional — send only if there is an attorney-in-fact	Not required	Not validated
Legal entity (`legal_person` / `default`, `financial_institution`)	At least one active, otherwise `IVR000134`	At least one with `legal_representative: true`, otherwise `IVR000136`	≥ 80% and never above 100%, otherwise `IVR000166` / `IVR000169`
Fund (`fund_class`) non-exclusive	None — the step can be skipped	Not required	Not validated
Fund (`fund_class`) exclusive	At least one, necessarily of type `exclusive_investor`, otherwise `IVR000134`	Forbidden — `exclusive_investor` cannot be a legal representative (`IVR000165`)	Exactly 100%, otherwise `IVR000170`

Investment funds

In a fund, representation is done through the investor owners (administrator and manager) — there is no need to send legal representatives as related parties. The only related_party_type accepted in fund_class is exclusive_investor; any other value is rejected with IVR000172.

The exclusive character of the fund (exclusive_fund_class) is automatically derived from the CVM class when the investor is created. If the CNPJ is not in the CVM database, the field remains undefined and the submit is rejected with IVR000068 — use the CNPJ of a fund actually registered at CVM.

About Ultimate Beneficial Owners

The Ultimate Beneficial Owner is the natural person who ultimately exercises a position of control or significant influence in the company, especially those who hold 15% or more of direct or indirect interest, hold a management position or represent the company for legal purposes.

Provide the data of the natural persons who hold 15% or more of direct or indirect equity interest and of the administrators. If none of the partners/shareholders individually holds an interest equal to or greater than 15%, we ask you to send the information of the 3 controllers who hold the largest interest percentages.

Reconciling the 15% rule with the 80% minimum. The two rules coexist: the 15% rule defines who needs to be qualified, the 80% rule defines how much of the corporate chain needs to be declared. A legal entity partner (parent_company) also counts toward the sum — with widely held capital, declaring the controlling holding company is usually the way to reach the minimum. We recommend sending at least 85% in total, so as not to depend on rounding.

The attorney-in-fact (attorney), although holding no interest, exercises a position of control and is therefore considered an ultimate beneficial owner. Send them with participation_percentage: 0.

When a natural person ultimate beneficial owner cannot be fully qualified, the registration of the controlling company may suffice — however, clarifications may be requested through feedbacks.

Input / Output:

As input, the related party data must be sent.

As output, an external_related_party_key and the details of the created related party are delivered.

Available on

Profile	Host	Required permission
Manager	`manager-api`	Write
Consultant	`consultant-api`	Granted by the integration team

Base URL for each host: Environments (Hosts).

Request

ENDPOINT

/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party

METHOD

POST

STATUS

201

Request body

Example: Natural Person Partner

Request Body
{
    "name": "João Silva",
    "document_number": "969.698.790-03",
    "person_type": "natural_person",
    "related_party_type": "partner",
    "resident": true,
    "legal_representative": true,
    "direct_beneficiary": true,
    "address": {
        "postal_code": "01000-000",
        "street": "Rua das Flores",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "uf": "SP",
        "country": "BRA",
        "complement": "Apto 101"
    },
    "participation_percentage": 0.5,
    "monthly_income": 50000.00,
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}

Example: Controlling Company (Legal Entity)

Request Body
{
    "name": "Empresa Controladora Ltda",
    "document_number": "66.777.888/0001-81",
    "person_type": "legal_person",
    "related_party_type": "parent_company",
    "resident": true,
    "legal_representative": false,
    "direct_beneficiary": true,
    "address": {
        "postal_code": "02000-000",
        "street": "Avenida Principal",
        "number": "456",
        "neighborhood": "Jardim",
        "city": "São Paulo",
        "uf": "SP",
        "country": "BRA"
    },
    "participation_percentage": 0.8,
    "email": "contato@controladora.com.br",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "123456789"
    }
}

Body params

Field	Type	Description	Characters	Required
`name`	string	Related party name	1 - 255	Yes
`person_type`	string	Person Type enumerator	-	Yes
`related_party_type`	string	Related Party Type enumerator	-	Yes
`resident`	boolean	Defines whether they are resident in Brazil	-	Yes
`legal_representative`	boolean	Defines whether they are a legal representative	-	Yes
`direct_beneficiary`	boolean	Defines whether they are an ultimate beneficial owner	-	Yes
`participation_percentage`	number	Interest percentage, as a fraction from 0 to 1 (e.g. `0.5` = 50%)	-	Yes
`document_number`	string	CPF or CNPJ. Required when `resident: true`	1 - 18	Conditional
`address`	object	Address object. Required when `person_type` is `legal_person` or when `direct_beneficiary: true`	-	Conditional
`monthly_income`	number	Monthly income. Required when `person_type` is `natural_person` and `direct_beneficiary: true`	-	Conditional
`nationality`	string	Nationality, 3-letter uppercase ISO code (e.g. `BRA`). Default `BRA` for a natural person. Not accepted for `legal_person`	3	No
`email`	string	E-mail	1 - 100	No
`phone`	object	Phone object	-	No
`expiration_date`	string	Expiration date (format: YYYY-MM-DD)	10	No

Conditional fields

address and monthly_income are rejected with IVR000068 when the condition above is met and the field is not sent — even though they are optional in other cases. Since the API validates one field at a time, send both in the first attempt for parties with direct_beneficiary: true.

nationality sent for a legal_person related party is rejected with IVR000238.

Enumerator	Description
`natural_person`	Natural person
`legal_person`	Legal entity

Enumerator	Description
`president`	President
`partner`	Partner
`administrator`	Administrator
`director`	Director
`manager`	Manager
`attorney`	Attorney-in-fact
`parent_company`	Controlling company (legal entity only)
`asset_custodian`	Asset custodian
`exclusive_investor`	Exclusive investor

Address

Field	Type	Description	Characters	Required
`postal_code`	string	Postal code. For an address in Brazil, CEP in the `XXXXX-XXX` format. For an address abroad, send the local postal code in the country's format	1 - 20	Yes
`street`	string	Street	1 - 255	No
`number`	string	Number	1 - 10	No
`neighborhood`	string	Neighborhood	1 - 255	No
`city`	string	City	1 - 255	No
`uf`	string	Federative unit (e.g. `SP`). For an address abroad, use `EX`	1 - 20	No
`country`	string	Country, 3-letter ISO code (e.g. `BRA`)	3	No
`complement`	string	Complement	1 - 255	No

Address abroad

postal_code and uf have no format validation — they accept any country's standard. The consistency required is between resident and country: a related party with resident: true needs country: "BRA" (otherwise IVR000227), and one with resident: false cannot have country: "BRA" (otherwise IVR000226).

Phone

Field	Type	Description	Characters	Required
`international_dial_code`	string	International code	1 - 3	Yes
`area_code`	string	Area code	2	Yes
`number`	string	Phone number	8 - 9	Yes

Response

Response Body
{
    "related_party_key": "UUID",
    "external_related_party_key": "UUID",
    "name": "João Silva",
    "document_number": "969.698.790-03",
    "person_type": "natural_person",
    "related_party_type": "partner",
    "status": "active",
    "resident": true,
    "legal_representative": true,
    "direct_beneficiary": true,
    "address": {
        "postal_code": "01000-000",
        "street": "Rua das Flores",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "uf": "SP",
        "country": "BRA",
        "complement": "Apto 101"
    },
    "participation_percentage": 0.5,
    "monthly_income": 50000.00,
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}

Errors

Status	Code	When it happens
400	`IVR000096`	The analysis is no longer in `pending_registry_data`
400	`IVR000004`	CPF/CNPJ with an invalid check digit
400	`IVR000068`	A required field for the party's `person_type` is missing
400	`IVR000169`	The summed equity interest would exceed 100%
409	`IVR000130`	There is already a related party with the same document in this analysis
400	`QIT000011`	Through the manager (`manager-api`): the investor is not a fund class linked to it

Authentication, permission and host errors: see API Errors.

Introduction​

Requirements by investor type​

Input / Output:​

Request​

Request body​

Body params​

Person Type (Related Party)​

Related Party Type​

Address​

Phone​

Response​

Errors​