Create investor

Introduction

This resource is used to provide us with the basic data to start the registration of an investor.

Creating an investor also triggers the opening of a first registration analysis linked to it. For this reason, at the end of this call two keys are returned: investor_key (identifies the investor) and investor_analysis_key (identifies the registration analysis in progress).

There are 3 main investor types, defined by the person_type field: natural person (natural_person), legal entity (legal_person) and PCO ('nominee'). For legal entities, the investor_sub_type field distinguishes sub-types such as investment fund (fund_class), which have their own rules throughout the registration flow.

Attention

For investors distributed on behalf of and to the order of others (PCO | nominee) there is no registration pipeline and therefore only the creation POST is needed to make them able to operate across the whole system.

Approval rule in sandbox

In sandbox, the analysis result depends on the first digit of the CPF/CNPJ: starting with 1 → automatic rejection; starting with 8 → manual analysis; all others are automatically approved.

Input / Output

As input, send the investor's basic data. The required fields vary according to person_type and investor_sub_type.

As output, the investor_key and the investor_analysis_key are returned. The investor_key identifies the investor; the investor_analysis_key identifies the registration analysis opened along with the creation. The same investor may have more than one registration analysis over time (renewals, updates).

Available on

Profile	Host
Distributor	`distributor-api`

Base URL for each host: Environments (Hosts).

Request

ENDPOINT

/investor_registry/v2/investor

METHOD

POST

STATUS

201

Request body

Case 01: Natural Person

Request Body
{
    "name": "João da Silva",
    "document_number": "969.698.790-03",
    "person_type": "natural_person",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}

Case 02: Legal Entity

Request Body
{
    "name": "Empresa XPTO Ltda",
    "document_number": "22.333.444/0001-81",
    "person_type": "legal_person",
    "investor_sub_type": "default",
    "registry_user": {
        "name": "José da Silva",
        "document_number": "969.698.790-03",
        "email": "jose.silva@example.com",
        "phone": {
            "international_dial_code": "55",
            "area_code": "11",
            "number": "987654321"
        }
    }
}

Case 03: Legal Entity — Investment Fund (fund_class)

Request Body
{
    "name": "Fundo XPTO Multimercado",
    "document_number": "22.333.444/0001-81",
    "person_type": "legal_person",
    "investor_sub_type": "fund_class"
}

Case 04: Nominee (PCO)

Request Body
{
    "name": "Nominee XPTO",
    "person_type": "nominee",
    "external_distribution_key": "ID-DISTRIBUICAO-001"
}

Required fields by person_type

The required fields change according to the person_type. The absence of any of them is rejected with IVR000009, whose message lists the full set required.

natural_person: name, document_number, person_type
legal_person: name, document_number, person_type
nominee: name, person_type, external_distribution_key

investor_sub_type is optional. If omitted, a natural person becomes default and, for a resident legal entity, the sub-type is identified by the CNPJ (financial_institution, fund_class or default). email and phone are optional for a distributor, but recommended: without email, no access user is created for the investor.

About the registry_user

The registry_user represents the user (natural person) responsible for filling in the investor's registration data. For a natural person, this user is usually the investor themselves and the field can be omitted. For a legal entity, it is the representative who will be responsible for filling it in.

When sent, the object requires name, document_number and email. If omitted for a natural person, the user is derived from the investor's own email — and, if the investor also has no email, no user is created.

investor_owner_type is not accepted from distributors

The investor_owner_type field is rejected with IVR000010 when the investor is created by a distributor integration with person_type natural_person or legal_person. Managed portfolio and fund links are established through the Create Investor Owner endpoint, within the registration analysis.

Non-resident investor

Residence is defined when the investor is created and is immutable after that. It is controlled by the resident field.

Request Body — non-resident natural person
{
    "name": "Maria Fernandes",
    "document_number": "969.698.790-03",
    "person_type": "natural_person",
    "investor_sub_type": "default",
    "resident": false,
    "non_resident_type": "third_party_representation",
    "investor_owners": [
        {
            "type": "non_resident_representative",
            "name": "Representante Legal Brasil Ltda",
            "document_number": "22.333.444/0001-81"
        }
    ]
}

Field	Type	Description	Required
`resident`	boolean	Defines the residence of the registration analysis. Default `true`	No
`non_resident_type`	string	`self_representation` or `third_party_representation`. Required when `resident: false` (`IVR000222`)	Conditional
`investor_owners`	array	Legal representative resident in Brazil, with `type: "non_resident_representative"`	No

Representation types

non_resident_type declares how the non-resident investor is represented in Brazil. This choice determines which entities you need to register and which documents will be required when the registration is sent for analysis.

Enumerator	Account type	Meaning
`third_party_representation`	4373 account	The non-resident investor (INR) operates through third parties: there is a custodian, responsible for safekeeping the assets, and a Brazilian legal representative, responsible for representing them in the country. In practice, they are usually the same entity.
`self_representation`	CNR account (self-custody / tax representation)	The investor is their own custodian and representative. There is no third-party custodian or representative.

What changes between the two:

	`third_party_representation`	`self_representation`
Custodian	Related party of type `asset_custodian`	Does not exist
Representative	Investor owner of type `non_resident_representative` — always resident, with CPF/CNPJ	Does not exist
Representation documents	`custody_contract` (on the custodian) and `representation_contract` (on the representative) — or a single `simplified_declaration` on the analysis	None

How the document requirement is checked

In third_party_representation, the custody_contract is only recognized when sent on an active related party of type asset_custodian, and the representation_contract is only recognized when sent on an active investor owner of type non_resident_representative. Sending both contracts as registration analysis documents does not satisfy the rule.

If the combination is not found at submit, the response is IVR000029.

Rules that apply to both types:

nif_number is required when sending the registration data (IVR000224);
a foreign related party without CPF/CNPJ needs a passport or foreign_id;
a natural person born in Brazil (natural_person.place_of_birth.country: "BRA") needs a final_departure_tax_return.

non_resident_type is immutable

The value is fixed when the investor is created. You can resend it in the registration data, but only with the same value — a mismatch, or sending it on a resident registration, results in IVR000225.

Residence and address must agree

With resident: true (default), the address sent in Step 3 must have country: "BRA", otherwise IVR000227. With resident: false, the country cannot be BRA, otherwise IVR000226.

postal_code and uf have no format validation, so foreign postal codes are accepted as they are. Use EX in uf for addresses abroad.

fund_class investors

For investment funds (investor_sub_type: "fund_class"), part of the registration data is filled in automatically from the CVM database when the registration is sent for analysis — including corporate name, incorporation date, net worth and links with the administrator, the manager and (when applicable) the exclusive investor. See the Create Investor Owner document for registering additional ownership relationships.

Body params

Field	Type	Description	Characters	Required
`name`	string	Name (or corporate name) of the investor	1 - 255	Yes
`person_type`	string	Person Type enumerator	-	Yes
`investor_sub_type`	string	Investor Sub Type enumerator. If omitted, it is inferred (see above)	-	No
`document_number`	string	CPF (`XXX.XXX.XXX-XX`) or CNPJ (`XX.XXX.XXX/XXXX-XX`)	14 or 18	Yes*
`external_distribution_key`	string	External distribution identifier (required for `nominee`)	1 - 100	Yes*
`resident`	boolean	Residence of the registration analysis. Default `true`. See Non-resident investor	-	No
`non_resident_type`	string	`self_representation` or `third_party_representation`. Required when `resident: false`	-	Conditional
`investor_owners`	array	Resident legal representative, for a non-resident investor	-	No
`email`	string	Investor e-mail	1 - 255	No
`phone`	object	Phone object	-	No
`registry_user`	object	Registry User object	-	No
`external_id`	string	Investor identifier in your system	1 - 50	No

* document_number must not be sent for person_type: nominee. external_distribution_key is required only for nominee.

Phone

Field	Type	Description	Characters	Required
`international_dial_code`	string	International code (e.g. `55`)	1 - 3	Yes
`area_code`	string	Area code (DDD)	2	Yes
`number`	string	Phone number	8 - 9	Yes

Registry User

Field	Type	Description	Characters	Required
`name`	string	Name of the registering user	1 - 255	Yes
`document_number`	string	User CPF (format `XXX.XXX.XXX-XX`)	14	Yes
`email`	string	User e-mail	1 - 255	Yes
`phone`	object	Phone object	-	No

Person Type

Enumerator	Description
`natural_person`	Natural person
`legal_person`	Legal entity
`nominee`	Nominee / PCO (no required document)

Investor Sub Type

Enumerator	Description
`default`	Regular investor, natural person or legal entity
`fund_class`	Investment fund — triggers automatic enrichment with CVM public data
`financial_institution`	Financial institution. Follows the same rules as `default`

The non_resident value is rejected with IVR000255: residence is declared through the resident and non_resident_type fields, not through the sub-type.

Response

Response Body
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}

Errors

Status	Code	When it happens
400	`IVR000004`	CPF/CNPJ with an invalid check digit, or CPF sent with `legal_person` (and vice versa)
400	`IVR000009`	A required field for the `person_type` is missing
400	`IVR000010`	`investor_owner_type` sent with `natural_person` or `legal_person`
400	`IVR000222`	`resident: false` without `non_resident_type`
400	`IVR000255`	`investor_sub_type: non_resident`
409	`IVR000007`	You have already registered an investor with this document

Authentication, permission and host errors: see API Errors.

Introduction​

Input / Output​

Request​

Request body​

Non-resident investor​

Representation types​

Body params​

Phone​

Registry User​

Person Type​

Investor Sub Type​

Response​

Errors​