Legal Entity Account Opening

Account opening occurs in two mandatory steps. First, a POST request sends preliminary data to reserve the account. Then, a webhook of type account_request.status_change with status pending_additional_data is triggered. In the second step, a PATCH request finalizes the opening, officializing the account with the complementary information.

Request

ENDPOINT

/account_request/checking

METHOD

POST

Path Params

Field	Type	Description	Characters
`account_request_key`	uuidv4	Unique identification key for account reservation request.	36

Free Movement Account Opening

Request Body

{
    "account_owner": {
        "phone": {
            "country_code": "55",
            "area_code": "11",
            "number": "999999999"
        },
        "email": "email@teste.com.br",
        "person_type": "legal",
        "name": "Empresa de Teste",
        "address": {
            "street": "Rua Abrahão Calux",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Vila Teste",
            "number": "116",
            "postal_code": "04286100",
            "complement": "Complemento"
        },
        "trading_name": "Nome fantasia",
        "company_document_number": "99999999000130",
        "cnae_code": "4721102",
        "foundation_date": "1980-07-11",
        "company_statute": "99999999-01c9-4cf5-a0fa-1d2a96f4b34d",
        "company_representatives": [
            {
                "name": "Nome do Socio",
                "individual_document_number": "99999999999",
                "document_identification_number": "999999999",
                "birth_date": "1989-09-01",
                "mother_name": "Maria da Silva",
                "email": "teste@gmail.com",
                "is_pep": false,
                "person_type": "natural",
                "nationality": "brasileiro(a)",
                "marital_status": "single",
                "document_identification": "88888-0ddf-4932-874f-9231794963da",
                "phone": {
                    "country_code": "055",
                    "area_code": "19",
                    "number": "999999999"
                },
                "address": {
                    "street": "Rua dos Limões",
                    "neighborhood": "Vila Moinho Velho",
                    "city": "São Paulo",
                    "state": "SP",
                    "postal_code": "04286100",
                    "number": "116",
                    "complement": "complemento"
                }
            }
        ],
        "company_type": "ltda"
    },
    "signed_contract": {
        "document_key": "57cda530-d469-4427-a9d4-2523a510dee1",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "2024-05-10T14:15:03.114895Z",
                    "ip_address": "192168161",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
                    "facial_recognition_key": "c367a540-2e7e-4373-a167-61bc43c30dc1"
                },
                "signer": {
                    "name": "Nome do assinante",
                    "email": "teste@gmail.com.br",
                    "phone": {
                        "country_code": "55",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "additional_documents": [
        "61f2a65e-0ddf-4932-874f-9231794963da"
    ]
}

Request Body Params

Field	Type	Description	Characters
account_owner *	object	Account owner object	Object account_owner
allowed_user *	object	User linked to the account.	Object allowed_user
account_manager	object	Data of the integrating partner who will handle account transactions via API.	Object account_manager
`signed_contract` *	object	Object containing contract signature information.	Object signed_contract

Object account_owner

Field	Type	Description	Characters
address *	object	Account holder address object	Object address
cnae_code *	string	National Classification of Economic Activities	9
company_document_number *	string	CNPJ	14
company_statute *	string	DOCUMENT_KEY of the company statute PDF (sent previously).	36
company_type	enum	Company type	Enumerators company_type
company_representatives *	list	List of company legal representatives	Object company_representatives
email *	string	Company institutional email.	254
foundation_date *	string	Company establishment date (format "YYYY-MM-DD").	10
name *	string	Legal name.	100
person_type *	enum	Identifier that the sent object is a legal entity. Must ALWAYS contain the value "legal" for Legal Entity Object.	Enumerators person_type
phone *	object	Account holder phone.	Object phone
trading_name *	string	Trade name.	200

Object company_representatives

Field	Type	Description	Characters
name *	string	Company representative name	100
address *	object	Company representative address object	Object address
email *	string	Company representative email	254
birth_date *	string	Company representative birth date (format "YYYY-MM-DD")	10
individual_document_number *	string	Company representative CPF (numbers only).	11
document_identification	string	DOCUMENT_KEY of the person's photo identification document PDF (ID or driver's license) (sent previously)	36
document_identification_number	string	Person's photo identification document number (ID or driver's license)	16
document_identification_type	enum	Person's photo identification document type (ID or driver's license)	Enumerators document_identification_type
is_pep *	boolean	Declaration if the person is PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).	-
marital_status	enum	Company representative marital status	Enumerators marital status
mother_name *	string	Company representative mother's name	100
nationality	string	Company representative nationality	50
person_type *	enum	Identifier that the sent object is a natural person	Enumerators person_type
phone *	object	Object with company representative phone data	Object phone

Object address

This object, present in both the Natural Person and Legal Entity objects, is a simple object to represent an address.

Field	Description	Example	Characters
street *	string	Street address	500
state *	enum	State address (with two uppercase characters)	2
city *	string	City address	255
neighborhood *	string	Neighborhood address	500
number *	string	Street number	10
postal_code *	string	ZIP code address (http://www.buscacep.correios.com.br/sistemas/buscacep/) (numbers only)	8
complement	string	Address complement (free text)	500

Object signed_contract

Field	Type	Description	Characters
document_key *	uuidv4	Unique identification key for Account Opening Agreement or Escrow Account Contract document. (The DOCUMENT_KEY is returned in the Document upload endpoint response)	36
signatures *	list	Signature data of the sent document. Each list item corresponds to a document signer.	Object signatures

Object signatures

Field	Type	Description	Characters
authenticity *	object	Set of data evidencing the electronic signature performed by the signer.	Object authenticity
signer *	object	Object containing data of one of the document signers.	Object signer
authentication_type *	enumerator	Signature type. Will always be "opt-in"	"opt-in"

Object authenticity

Field	Type	Description	Characters
timestamp *	string	Date and time of document signature moment.	27
facial_recognition_key	uuidv4	Unique identification key for the account holder's selfie photo. (The DOCUMENT_KEY is returned in the Document upload endpoint response)	36
lang	string	Longitude coordinate of signer's geolocation captured at signature moment.	-
lat	string	Latitude coordinate of signer's geolocation captured at signature moment.	-
ip_address	string	Signer's device IP address.	-
session_id	string	Signer's session ID at signature moment.	-

Object signer

Field	Type	Description	Characters
name *	string	Signer name.	-
email *	string	Signer email.	-
phone *	object	Object with signer phone data	Object phone
document_number *	string	Signer CPF.	11

Object phone

Field	Description	Example	Max Characters
`country_code` *	string	Phone country code (https://ddi.guiamais.com.br/)	3
`area_code` *	string	Phone area code (https://ddd.guiamais.com.br/)	2
`number` *	string	Phone number (numbers only)	10

Enumerators person_type

Enum	Description
natural	Natural person
legal	Legal entity

Enumerators document_identification_type

Enum	Description
rg	ID - General Registry
cnh	Driver's License

Enumerators company_type

Enum	Description
ltda	Limited Liability Company
sa	Corporation
micro_enterprise	Micro Enterprise
freelancer	Freelancer
sa_opened	Public Corporation
sa_closed	Private Corporation
se_ltda	Limited Business Partnership
se_cn	General Partnership
se_cs	Limited Partnership
se_ca	Partnership Limited by Shares
scp	Joint Venture
ei	Individual Entrepreneur
ese	Foreign Company Establishment in Brazil
eeab	Argentine-Brazilian Binational Company Establishment in Brazil
ssp	Pure Simple Partnership
ss_ltda	Limited Simple Partnership
ss_cn	General Simple Partnership
ss_cs	Simple Limited Partnership
eireli_ne	Individual Limited Liability Company (Business Nature)
eireli_ns	Individual Limited Liability Company (Simple Nature)
eireli	Individual Liability Company
mei	Individual Micro Entrepreneur
me	Micro Enterprise
cop	Cooperative
private_association	Private Association

Enumerators marital_status

Enum	Description
single	Single
married	Married
widower	Widowed
divorced	Divorced
separated	Separated

Response

STATUS

201

Response Body

{
    "account_info": {
        "account_branch": "0001",
        "account_digit": "0",
        "account_number": "1693580"
    },
    "account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
    "account_request_status": "pending_kyc_analysis"
}

Warning

The account_request_key field must be stored and will be used for account opening confirmation.

Response Body Params

Field	Type	Description	Characters
`account_info` *	object	Object containing Account Holder information	Object account_info
`account_request_key` *	string	Creation request identification key	-
`account_request_status` *	string	KYC Status	-

Object account_info

Field	Type	Description	Characters
`account_branch` *	string	Branch Number	4
`account_digit` *	string	Email	11
`account_number` *	string	Account Holder Full Name	50

STATUS

4xx

Response Body: Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}

HTTP Code `status`	QI Code `code`	Title `title`	Description (eng) `description`	Description(ptbr) `translation`
400	QIT000001	Bad Request	Schema Error	Schema Error
404	QIT000404	Not Found	Resource could not be found	Resource not found

Request​

Path Params​

Free Movement Account Opening​

Request Body Params​

Object account_owner​

Object company_representatives​

Object address​

Object signed_contract​

Object signatures​

Object authenticity​

Object signer​

Object phone​

Enumerators person_type​

Enumerators document_identification_type​

Enumerators company_type​

Enumerators marital_status​

Response​

Response Body Params​

Object account_info​