Free Movement Account Draft - Legal Entity

The Draft Checking Legal Person flow allows creating an account opening request in two steps:

1. POST: Creates a draft (rough) with maximum flexibility - accepts from minimal data to complete data
2. PATCH: Submits the draft for processing, validating completeness of all mandatory fields

Important: This flow is being prepared for integration with Monte Bravo. The field division between POST and PATCH will be adjusted after alignment with Monte Bravo on which data will be available at each moment of the process.

Create Legal Entity Account Draft

Request

ENDPOINT

/v2/account_request/draft_checking_legal_person

METHOD

POST

Description

This endpoint creates a draft for Legal Entity account opening. The POST accepts from minimal data to complete data, offering maximum flexibility.

Flexibility Strategy

• Minimal data: CNPJ + Name + Person type
• Partial data: Add fields as available
• Complete data: Send everything at once (less common)

Example 1: MINIMAL Payload (only required)

Request Body

{
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal"
  }
}

{
  "request_control_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal"
  }
}

Behavior: If the same request_control_key is used again, returns error 409 (Conflict) instead of creating a new draft.

Example 2: COMPLETE Payload (all data at once)

Request Body

{
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal",
    "email": "empresa@exemplo.com.br",
    "phone": {
      "country_code": "055",
      "area_code": "11",
      "number": "999999999"
    },
    "trading_name": "Empresa Exemplo",
    "company_type": "LTDA",
    "foundation_date": "2010-01-15",
    "cnae_code": "6209-1/00",
    "company_statute": "92c93e9e-b249-46b7-8c2e-95d4955a3c39",
    "monthly_revenue": 150000.00,
    "address": {
      "street": "Av. Brigadeiro Faria Lima",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Jardim Paulistano",
      "number": "2391",
      "postal_code": "01452905",
      "complement": "Conjunto 102"
    },
    "company_representatives": [
      {
        "name": "João Carlos da Silva",
        "email": "joao.silva@exemplo.com.br",
        "birth_date": "1985-03-20",
        "individual_document_number": "12345678901",
        "is_pep": false,
        "mother_name": "Maria da Silva",
        "nationality": "brasileira",
        "person_type": "natural",
        "phone": {
          "country_code": "055",
          "area_code": "11",
          "number": "988888888"
        },
        "address": {
          "street": "Rua das Flores",
          "state": "SP",
          "city": "São Paulo",
          "neighborhood": "Jardins",
          "number": "123",
          "postal_code": "01310100",
          "complement": "Apto 45"
        },
        "representative_relationship": "ceo",
        "gender": "male",
        "marital_status": "married",
        "documents": {
          "cnh": {
            "ocr_key": "7a73be1a-0b66-4c0a-932a-1d1d02efdc4c"
          }
        }
      }
    ]
  }
}

Response

STATUS

201

Response Body

{
  "account_request_key": "abc123-def456-...",
  "account_request_status": "draft",
  "account_info": {
    "account_number": "1638634",
    "account_digit": "3",
    "account_branch": "0001"
  }
}

Attention

The account_request_key field must be stored and will be used to submit the draft via PATCH.

Request Body Params

Field	Type	Description	Characters
request_control_key	string	UUID to ensure idempotency (36 characters)	36
reserved_account_key	string	UUID of previously reserved account (36 characters)	36
account_owner *	object	Account holder information (Legal Entity)	Object account_owner

Object account_owner (POST)

Field	Type	Description	Characters
company_document_number *	string	Company CNPJ (14 digits, numbers only)	14
name *	string	Company legal name	100
person_type *	enum	Person type (always "legal")	Enums person_type
email	string	Company email (valid email format)	254
phone	object	Company phone	Object phone
trading_name	string	Trade name	200
company_type	enum	Company type	Enums company_type
foundation_date	string	Foundation date (format: YYYY-MM-DD)	10
cnae_code	string	CNAE activity code	9
company_statute	string	Company statute UUID (UUID format)	36
monthly_revenue	number	Monthly revenue	-
address	object	Complete company address	Object address
company_representatives	array	List of legal representatives (minimum 1 item if sent)	Object company_representatives

Required Fields in POST

Only 3 fields are required in POST:

• company_document_number
• name
• person_type

All other fields are optional and can be sent according to availability.

Representative Validation

If company_representatives is sent in POST, it must have at least 1 item (minItems: 1). Each representative must have all required fields (see PATCH section). The documents field within each representative is optional in POST.

---

Submit Legal Entity Account Draft

Request

ENDPOINT

/v2/account_request/{account_request_key}/draft_checking_legal_person

METHOD

PATCH

Description

This endpoint submits the draft for processing. The PATCH validates completeness - all required fields must be present in the PATCH payload.

⚠️ IMPORTANT: The PATCH completely overwrites the account_owner data with the sent payload. This means that:

• You must send ALL required fields in the PATCH payload, even if they were already sent in POST
• Data sent only in POST will be lost if not resent in PATCH
• The behavior is complete replacement, not merge/partial update
• The documents field within each company_representative is required and must contain at least one valid document type (RG, CNH, RNE, CRNM, Passport or Digital CIN)

After successful submission, the status changes from draft to pending_bacen_validation and starts Bacen Protege+ validation.

Request Body

Request Body

{
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal",
    "email": "empresa@exemplo.com.br",
    "phone": {
      "country_code": "055",
      "area_code": "11",
      "number": "999999999"
    },
    "trading_name": "Empresa Exemplo",
    "company_type": "LTDA",
    "foundation_date": "2010-01-15",
    "cnae_code": "6209-1/00",
    "company_statute": "92c93e9e-b249-46b7-8c2e-95d4955a3c39",
    "monthly_revenue": 150000.00,
    "address": {
      "street": "Av. Brigadeiro Faria Lima",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Jardim Paulistano",
      "number": "2391",
      "postal_code": "01452905",
      "complement": "Conjunto 102"
    },
    "company_representatives": [
      {
        "name": "João Carlos da Silva",
        "email": "joao.silva@exemplo.com.br",
        "birth_date": "1985-03-20",
        "individual_document_number": "12345678901",
        "is_pep": false,
        "mother_name": "Maria da Silva",
        "nationality": "brasileira",
        "person_type": "natural",
        "phone": {
          "country_code": "055",
          "area_code": "11",
          "number": "988888888"
        },
        "address": {
          "street": "Rua das Flores",
          "state": "SP",
          "city": "São Paulo",
          "neighborhood": "Jardins",
          "number": "123",
          "postal_code": "01310100",
          "complement": "Apto 45"
        },
        "representative_relationship": "ceo",
        "gender": "male",
        "marital_status": "married",
        "documents": {
          "rg": {
            "ocr_front_key": "0aa8a4ca-5873-49bd-851c-1f2c71a1cc28",
            "ocr_back_key": "29f6e346-7fae-4dcb-9ea1-2a3e4ef593ea"
          },
          "cnh": {
            "ocr_key": "7479c8e4-2a5d-4b4d-b2eb-4b841ec9390d"
          }
        },
        "face": "68da08f1-6cf4-4dce-a297-7b2f09311784"
      }
    ]
  },
  "additional_documents": [
    "61f2a65e-0ddf-4932-874f-9231794963da"
  ]
}

Response

STATUS

200

Response Body

{
  "account_request_key": "abc123-def456-...",
  "account_request_status": "pending_bacen_validation",
  "account_info": {
    "account_number": "1638634",
    "account_digit": "3",
    "account_branch": "0001"
  }
}

Bacen Protege+ Flow

After successful submission, the status changes to pending_bacen_validation. The system performs a preliminary validation with Bacen Protege+ before proceeding with KYC analysis. After Bacen approval, the status will be automatically updated to pending_kyc_analysis.

Request Body Params

Field	Type	Description	Characters
additional_documents	array	List of additional document UUIDs (array of UUIDs)	-
account_owner *	object	Complete account holder information (Legal Entity)	Object account_owner (PATCH)

Object account_owner (PATCH)

Field	Type	Description	Characters
company_document_number *	string	CNPJ (14 digits, numbers only, pattern: ^[0-9]{14}$)	14
name *	string	Legal name	100
person_type *	enum	Always "legal"	Enums person_type
email *	string	Company email (valid email format)	254
phone *	object	Company phone	Object phone
trading_name *	string	Trade name	200
company_type *	enum	Company type	Enums company_type
foundation_date *	string	Foundation date (format: YYYY-MM-DD)	10
cnae_code *	string	CNAE activity code	9
company_statute *	string	Company statute UUID (UUID format)	36
monthly_revenue *	number	Monthly revenue	-
address *	object	Complete company address	Object address
company_representatives *	array	List of legal representatives (minimum 1 item required)	Object company_representatives

Required Fields in PATCH

ALL fields marked with * are required in PATCH. The JSON schema validates the completeness of all fields before processing the submission.

Object phone

Field	Type	Description	Characters
country_code *	string	Country code (1-3 digits, pattern: ^[0-9]{1,3}$)	1-3
area_code *	string	Area code (1-3 digits, pattern: ^[0-9]{1,3}$)	1-3
number *	string	Phone number (1-10 digits, pattern: ^[0-9]{1,10}$)	1-10
type	enum	Phone type (optional: "residential", "commercial", "mobile", "fax")	-

Object address

Field	Type	Description	Characters
street *	string	Street/Address	1-500
neighborhood *	string	Neighborhood	0-100
number *	string	Number	1-10
postal_code *	string	ZIP code (8 digits, numbers only, pattern: ^\d{8}$)	8
city *	string	City	1-100
state *	enum	State (2 uppercase characters)	Enums state
complement	string	Complement (optional, maximum 500 characters)	0-500

Object company_representatives

Field	Type	Description	Characters
name *	string	Full name	100
address *	object	Complete address (same structure as company address)	Object address
email *	string	Email (valid email format)	5-200
birth_date *	string	Birth date (format: YYYY-MM-DD, pattern: `\d4-((0[1-9])	(1[0-2]))-((0[1-9])
individual_document_number *	string	CPF (11 digits, numbers only, pattern: ^[0-9]{11}$)	11
is_pep *	boolean	If is Politically Exposed Person	-
mother_name *	string	Mother's name	100
nationality *	string	Nationality	50
person_type *	enum	Always "natural"	Enums person_type
phone *	object	Phone (same structure as company phone)	Object phone
documents *	object	Anti-fraud documents (required in PATCH)	Object documents
face	string	Facial photo UUID (36 characters)	36
document_identification	string	Identification document UUID (UUID format)	36
document_identification_number	string	Identification document number	16
marital_status	enum	Marital status	Enums marital_status
gender	enum	Gender	Enums gender
representative_relationship	enum	Relationship with company	Enums representative_relationship

Object documents

Field	Type	Description	Characters
rg	object	OCR keys for front and back of RG upload	Object rg
cnh	object	OCR key for CNH upload	Object cnh
cnh_digital	object	OCR key for digital CNH upload	Object cnh_digital
national_registry_of_foreigners	object	OCR keys for front and back of RNE upload	Object national_registry_of_foreigners
national_migration_registry	object	OCR keys for front and back of CRNM upload	Object national_migration_registry
passport	object	OCR key for passport upload	Object passport
cin_digital	object	OCR key for digital National Identity Card upload	Object cin_digital

Object rg

Field	Type	Description	Characters
ocr_front_key *	uuidv4	OCR key for front image upload of RG	36
ocr_back_key *	uuidv4	OCR key for back image upload of RG	36

OR

Field	Type	Description	Characters
ocr_key *	uuidv4	OCR key for RG image upload	36

Object cnh

Field	Type	Description	Characters
ocr_front_key *	uuidv4	OCR key for front image upload of CNH	36
ocr_back_key *	uuidv4	OCR key for back image upload of CNH	36

OR

Field	Type	Description	Characters
ocr_key *	uuidv4	OCR key for CNH image upload	36

Object cnh_digital

Field	Type	Description	Characters
ocr_key *	uuidv4	OCR key for digital CNH image upload	36

Object national_registry_of_foreigners

Field	Type	Description	Characters
ocr_front_key *	uuidv4	OCR key for front image upload of RNE	36
ocr_back_key *	uuidv4	OCR key for back image upload of RNE	36

OR

Field	Type	Description	Characters
ocr_key *	uuidv4	OCR key for RNE image upload	36

Object national_migration_registry

Field	Type	Description	Characters
ocr_front_key *	uuidv4	OCR key for front image upload of CRNM	36
ocr_back_key *	uuidv4	OCR key for back image upload of CRNM	36

OR

Field	Type	Description	Characters
ocr_key *	uuidv4	OCR key for CRNM image upload	36

Object passport

Field	Type	Description	Characters
ocr_key *	uuidv4	OCR key for passport image upload	36

Object cin_digital

Field	Type	Description	Characters
ocr_key *	uuidv4	OCR key for digital National Identity Card image upload	36

Information

The OCR keys (ocr_key or ocr_front_key and ocr_back_key) from document image uploads are provided as response from the image upload in anti-fraud. The face_recognition_key is returned in the facial recognition response.

Response Body Params

Field	Type	Description	Characters
account_request_key *	string	Account creation request identification key	-
account_request_status *	string	Request status (changes to pending_bacen_validation after submission)	-
account_info *	object	Object containing account information	Object account_info

Object account_info

Field	Type	Description	Characters
account_branch *	string	Branch number	4
account_digit *	string	Account check digit	1
account_number *	string	Account number	-

Error Response

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	Erro de Schema
400	-	Bad Request	Invalid request body	Corpo da requisição inválido
404	QIT000404	Not Found	Resource could not be found	Recurso não encontrado
409	-	Conflict	Duplicate request_control_key	Chave de controle duplicada

---

Differences between POST and PATCH

Aspect	POST (Create Draft)	PATCH (Submit Draft)
Objective	Create draft with flexibility	Validate completeness and submit to Bacen
Required Fields	Only CNPJ + Name + Type	ALL fields + 1 complete representative with documents
documents	Optional per representative	Required per representative (object with OCR documents)
Representatives	Optional	Required (minimum 1)
Validation	Minimal (only 3 fields)	Complete (all required fields)
Initial Status	N/A	draft (must be in this status)
Final Status	draft	pending_bacen_validation
Bacen Validation	No	Yes
KYC Analysis	No	Yes (after Bacen)
Idempotency	Yes (via request_control_key)	No

---

Usage Scenarios

Scenario 1: Client initially has only basic data

POST → {CNPJ, name, type}  [status: draft]
...client collects more data...
PATCH → {all fields + documents per representative} [status: pending_bacen_validation]

Scenario 2: Client has all data at once

POST → {all fields}  [status: draft]
PATCH → {all fields} [status: pending_bacen_validation]

Scenario 3: Client sends partial data gradually

POST → {CNPJ, name, type, email}  [status: draft]
...client collects more data...
PATCH → {all fields including representatives with documents} [status: pending_bacen_validation]

---

Enums

Enums person_type

Enum	Description
natural	Natural person
legal	Legal entity

Enums company_type

Enum	Description
ltda	Limited
sa	Corporation
micro_enterprise	Micro Enterprise
freelancer	Freelancer
sa_opened	Open Capital Corporation
sa_closed	Closed Capital Corporation
se_ltda	Limited Business Company
se_cn	General Partnership Business Company
se_cs	Limited Partnership Business Company
se_ca	Partnership Limited by Shares Business Company
scp	Partnership in Participation
ei	Individual Entrepreneur
ese	Establishment in Brazil of Foreign Company
eeab	Establishment in Brazil of Argentine-Brazilian Binational Company
ssp	Pure Simple Partnership
ss_ltda	Limited Simple Partnership
ss_cn	General Partnership Simple Partnership
ss_cs	Limited Partnership Simple 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

Enums state

Enum	Description
AC	Acre
AL	Alagoas
AM	Amazonas
AP	Amapá
BA	Bahia
CE	Ceará
DF	Distrito Federal
ES	Espírito Santo
GO	Goiás
MA	Maranhão
MG	Minas Gerais
MS	Mato Grosso do Sul
MT	Mato Grosso
PA	Pará
PB	Paraíba
PE	Pernambuco
PI	Piauí
PR	Paraná
RJ	Rio de Janeiro
RN	Rio Grande do Norte
RO	Rondônia
RR	Roraima
RS	Rio Grande do Sul
SC	Santa Catarina
SE	Sergipe
SP	São Paulo
TO	Tocantins
EX	Exterior

Enums marital_status

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

Enums gender

Enum	Description
male	Male
female	Female

Enums representative_relationship

Enum	Description
ceo	CEO / Chief Executive Officer
analyst	Analyst
partner	Partner
director	Director
attorney	Attorney
signer	Signer

---

Complete Flow

1. POST /v2/account_request/draft_checking_legal_person

   • Creates draft with available data
   • Status: draft
   • Returns: account_request_key

2. (Optional) Collect additional data

3. PATCH /v2/account_request/{account_request_key}/draft_checking_legal_person

   • Validates completeness of all fields
   • Sends to Bacen Protege+
   • Status: pending_bacen_validation

4. Bacen Protege+ validates (asynchronous)

   • Status: pending_kyc_analysis (if approved)

5. KYC analyzes legal entity

   • Status: approved (if everything is OK)

6. Account created and ready for use

---