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).

The person_type field defines whether the investor is a natural person (natural_person) or a legal entity (legal_person). Within legal entity, the investor_sub_type field distinguishes a regular company (default) from an investment fund class (fund_class), which follows its own rules throughout the entire flow.

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.

Investor access user

By default, the creation also creates the investor's access user on the platform (query param create_investor_user, default true). If the investor will not fill in their own registration, send ?create_investor_user=false.

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	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

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: Investment Fund Class (fund_class)

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

Required fields

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, email and phone
legal_person: name, document_number, person_type. For fund_class, do not send registry_user — representation is done by the investor owners (administrator and manager)

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 if it is a registered financial institution, fund_class if it is a class registered at CVM and default in all other cases. If you provide the sub-type, it must match the CNPJ (see Errors).

Fund classes: who can register

Through the manager (manager-api), the creation of a fund_class investor is only accepted if the manager's CNPJ appears at the CVM as manager or administrator of the class; otherwise, IVR000260. The administrator and the manager of the class must also be registered as investors at QI Tech. See Introduction for the details.

Only classes in operation

Only classes that are operational at CVM can be registered. Pre-operational, closed, canceled or merged classes are rejected in the analysis. If the CNPJ is not in the CVM database, the submit is rejected with IVR000068.

What CVM fills in for you

For fund_class, part of the registration data is filled in automatically from the CVM public database when the registration is sent for analysis — including corporate name, incorporation date, net worth and the links with the administrator, the manager and (when applicable) the exclusive investor.

As a consequence, address, net worth, suitability, signer groups and investor documents are not sent for this sub-type. See Which steps apply to each type.

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.

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
`document_number`	string	CPF (`XXX.XXX.XXX-XX`) or CNPJ (`XX.XXX.XXX/XXXX-XX`). For `fund_class`, the CNPJ of the class registered at CVM	14 or 18	Yes*
`investor_sub_type`	string	Investor Sub Type enumerator. If omitted, it is inferred (see above)	-	No
`email`	string	Investor e-mail. Required for `natural_person`	1 - 255	Conditional
`phone`	object	Phone object. Required for `natural_person`	-	Conditional
`registry_user`	object	Registry User object	-	No
`resident`	boolean	Whether the investor is resident in Brazil. Default `true`	-	No
`non_resident_type`	string	`self_representation` or `third_party_representation`. Required when `resident: false`	-	Conditional

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

Investor Sub Type

Enumerator	Description
`default`	Regular investor, natural person or legal entity
`financial_institution`	Financial institution (`legal_person` only)
`fund_class`	Investment fund class (`legal_person` only) — triggers automatic enrichment with CVM public data and follows its own rules for steps, related parties and investor owners

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",
    "resident": true
}

The response also includes the distributor object and, for a non-resident investor, non_resident_type.

Investor that already exists

If another agent has already registered an investor with the same document, no new investor is created: it becomes linked to you and the response includes only the investor_key.

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 — for example, `email` or `phone` for a natural person
400	`IVR000222`	`resident: false` without `non_resident_type`
400	`IVR000064`	`investor_sub_type` `fund_class` or `financial_institution` sent with `natural_person`
400	`IVR000255`	`investor_sub_type: non_resident`. Use `resident: false` and `non_resident_type`
400	`IVR000256` / `IVR000257`	The declared sub-type does not match the CNPJ: `financial_institution` without a registered institution, or `fund_class` without a class at CVM
400	`IVR000258` / `IVR000259`	`default` sub-type declared for a CNPJ that is a registered financial institution or a class at CVM
403	`IVR000260`	Manager trying to register a fund class of which it is neither the manager nor the administrator
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​

Body params​

Phone​

Registry User​

Person Type​

Investor Sub Type​

Response​

Errors​