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 investor types are defined by the person_type field: natural person (natural_person), legal entity (legal_person) and on behalf of and to the order of (nominee). The investor_sub_type field distinguishes sub-types such as investment fund (fund_class), which have their own rules throughout the registration 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.

This rule is exclusive to sandbox. In production, every analysis goes through the real compliance flow.

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

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

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 and, when the investor is created by the manager or by the consultant, email and phone
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). For a distributor, natural person email and phone are optional, 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 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 the address step must have country: "BRA", otherwise IVR000227. With resident: false, the country cannot be BRA, otherwise IVR000226.

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	-	No
`document_number`	string	CPF (`XXX.XXX.XXX-XX`) or CNPJ (`XX.XXX.XXX/XXXX-XX`). Not required for `nominee`	14 or 18	Yes*
`external_distribution_key`	string	External distribution key. Required only 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. Required for `natural_person` created by a manager or consultant	1 - 255	Conditional
`phone`	object	Phone object. Required for `natural_person` created by a manager or consultant	-	Conditional
`registry_user`	object	Registry User object	-	No
`external_id`	string	Investor identifier in your system	1 - 50	No

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`	On behalf of and to the order of (PCO)

nominee (PCO) registration

The on-behalf-of-and-to-the-order-of flow must be previously enabled and agreed upon for use in Production. Talk to your commercial contact before planning the integration of this case.

Investor Sub Type

Enumerator	Description
`default`	Regular investor, natural person or legal entity
`fund_class`	Investment fund. Has its own rules for related parties, documents and investor owners
`financial_institution`	Financial institution. Follows the same rules as `default`
`non_resident`	Rejected with `IVR000255`. Residence is declared through `resident` and `non_resident_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	`IVR000064`	`investor_sub_type` `fund_class` or `financial_institution` sent with `natural_person`
400	`IVR000222`	`resident: false` without `non_resident_type`
400	`IVR000255`	`investor_sub_type: non_resident`
400	`IVR000256` to `IVR000259`	The declared sub-type does not match the CNPJ (registered financial institution / class at CVM)
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​