> ## Documentation Index
> Fetch the complete documentation index at: https://docs.judit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity Schema (Registration Data)

> Structure of the Entity object returned by registration data queries by CPF (individual) or CNPJ (legal entity). Includes contacts, addresses, partners and links.

> 🤖 Registration data queries return a common base object called `entity`. Depending on whether the query was made by CPF or CNPJ, the `entity_type` property will return `"person"` or `"company"`, respectively. Some fields, such as `parents` (parentage) or `share_capital`, are exclusive to their respective entity type.

## Base structure (common to CPF and CNPJ)

Whenever you query a valid document, the Judit API returns the `entity` block containing the following universal properties:

### Main identification

| Property | Type | Description |
| :- | :- | :- |
| `entity_id` | string | Unique internal identifier for the entity in Judit's system. |
| `entity_type` | string | Entity type: `"person"` (natural person) or `"company"` (legal entity). |
| `main_document` | string | Primary document (CPF or CNPJ). *Returned as digits only.* |
| `name` | string | Full civil name of the person or official corporate name of the company. |
| `aka_names` | array | List of alternative names (nicknames, maiden names, or trade names). |
| `nationality` | string | Nationality of the person or country of registration of the company. |
| `revenue_service_active` | boolean | Indicates whether the document is active and in good standing with the Brazilian Federal Revenue (Receita Federal). |
| `created_at` / `updated_at` | string | ISO 8601 dates of record creation and last update in the system. |
| `tags` | object | Additional metadata or crawler control data (e.g., extraction date from Receita Federal). |

***

### Contact and location arrays

All entities (persons or companies) have standardized arrays for contacts and addresses.

#### Addresses (`addresses`)

List of residential or commercial addresses linked to the document.

| Property | Type | Description |
| :- | :- | :- |
| `street` | string | Main street name (Rua, Avenida, etc.). |
| `number` | string | Building number. |
| `complement` | string | Address complement (apartment, block, suite, floor). |
| `neighborhood` | string | Neighborhood. |
| `city` | string | City. |
| `state` | string | Brazilian state abbreviation (e.g., `"SP"`, `"RJ"`). |
| `country` | string | Country. |
| `zip_code` | string | Postal code (CEP). *Returned as digits only.* |
| `ibge_code` | number | Official IBGE municipality code. |

#### Contacts (`contacts`)

List of communication channels extracted from the data sources.

| Property | Type | Description |
| :- | :- | :- |
| `contact_type` | string | Contact category (e.g., `"phone"`, `"email"`). |
| `description` | string | The contact value itself (phone number or email address). |

#### Other documents (`documents`)

List of secondary identification documents (such as RG, CNH, or state registration — IE).

| Property | Type | Description |
| :- | :- | :- |
| `document_type` | string | Type of secondary document (e.g., `"RG"`, `"IE"`). |
| `document` | string | Document number without formatting. |

***

## 👤 Exclusive properties: Natural person (`person`)

If the query is for a **CPF** (`entity_type: "person"`), the object may contain the following additional properties and arrays:

| Property | Type | Description |
| :- | :- | :- |
| `birth_date` | string | Date of birth. ISO 8601 format. |
| `gender` | string | Registered gender (e.g., `"M"`, `"F"`). |
| `parents` | array | Parentage array. Each item contains `name` (full name) and `kinship` (degree of kinship, e.g., `"mother"`, `"father"`). |
| `partners` | array | List of identified spouses or domestic partners. |
| `associated_people` | array | List of other natural persons with identifiable relationships (business ties, shared residence). |

***

## 🏢 Exclusive properties: Company (`company`)

If the query is for a **CNPJ** (`entity_type: "company"`), the object may contain the following corporate and operational fields:

### Operational data

| Property | Type | Description |
| :- | :- | :- |
| `social_name` | string | Trade name (company's market-facing name). |
| `birth_date` | string | Official date of incorporation registered with Receita Federal. |
| `size` | string | Official company size classification (e.g., `"ME"`, `"EPP"`, `"DEMAIS"`). |
| `head_office` | boolean | Indicates whether this CNPJ is the head office (`true`) or a branch (`false`). |
| `special_status` | string | Special tax status (e.g., judicial reorganization, composition with creditors). |
| `share_capital` | number | Declared share capital value, numeric. |
| `parents` | array | List of companies acting as parent, controlling, or holding entities (economic group). |

### Corporate and economic structure

#### Legal nature (`legal_nature`)

| Property | Type | Description |
| :- | :- | :- |
| `code` | string | Official numeric code of the legal nature (e.g., `"206-2"`). |
| `name` | string | Full description (e.g., `"Sociedade Empresária Limitada"`). |
| `active` | boolean | Indicates whether this is the currently active classification. |

#### Shareholders and administrators — QSA (`partners`)

| Property | Type | Description |
| :- | :- | :- |
| `name` | string | Name of the partner or administrator. |
| `main_document` | string | CPF or CNPJ of the corporate participant. |
| `position` | string | Qualification / role held (e.g., `"SÓCIO-ADMINISTRADOR"`, `"DIRETOR"`). |
| `entity_type` | string | Type of the partner entity (`"person"` or `"company"`). |

#### Economic activities — CNAE (`branch_activities`)

| Property | Type | Description |
| :- | :- | :- |
| `code` | string | CNAE code of the activity. |
| `name` | string | Full title or description of the activity. |
| `main_activity` | boolean | Indicates whether this is the primary CNAE (`true`) or a secondary CNAE (`false`). |

***

## Example payload (Natural person)

<CodeGroup>
  ```json Response (CPF) theme={null}
  {
      "has_lawsuits": false,
      "request_id": "00000000-0000-0000-0000-000000000001",
      "response_data": [
          {
              "entity_id": "",
              "entity_type": "person",
              "main_document": "99999999999",
              "name": "JOÃO TESTE",
              "addresses": [
                  {
                      "street": "RUA RAMOS DE CARVALHO",
                      "number": "999",
                      "complement": "",
                      "neighborhood": "CENTRO",
                      "city": "RIO DE JANEIRO",
                      "state": "RJ",
                      "country": "Brasil",
                      "zip_code": "99999999",
                      "ibge_code": 9999999
                  }
              ],
              "aka_names": [],
              "contacts": [
                  {
                      "description": "21999999999",
                      "contact_type": "phone"
                  }
              ],
              "documents": [],
              "parents": [
                  {
                      "name": "MARIA TESTE",
                      "kinship": "mother"
                  }
              ],
              "partners": [],
              "associated_people": [],
              "tags": {
                  "revenue_update_date": "2022-05-30T00:00:00.000Z"
              },
              "created_at": "2024-10-12T13:28:59.051Z",
              "updated_at": "2024-10-12T13:28:59.051Z",
              "nationality": "BRASILEIRA",
              "birth_date": "1981-08-07T00:00:00.000Z",
              "gender": "male",
              "revenue_service_active": true
          }
      ]
  }
  ```
</CodeGroup>

***

## Next steps

Now that you understand the registration data dictionary, see how to query this information:

* 👉 **[Registration data queries](/en/registration-data/registration-data):** See the documentation for the request route to fetch and enrich CPFs and CNPJs in real time.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.