# Entity

The `Entity` object represents a legal entity (company) or natural person returned from a registry search.

## Fields

### Core

| Field        | Type   | Description                                     |
| ------------ | ------ | ----------------------------------------------- |
| `_id`        | string | Unique entity identifier                        |
| `_entityURL` | string | URL of the entity's page in the source registry |

### Company Attributes

| Field                   | Type   | Description                                                    |
| ----------------------- | ------ | -------------------------------------------------------------- |
| `legalName`             | string | Official registered name of the company                        |
| `legalForm`             | string | Legal form (e.g., `GmbH`, `Ltd`, `S.A.`, `Inc.`)               |
| `companyStatus`         | string | Current status (e.g., `Active`, `Dissolved`, `In Liquidation`) |
| `companyURL`            | string | Company website URL                                            |
| `countryOfRegistration` | string | ISO country code where the company is registered               |
| `jurisdiction`          | string | Specific jurisdiction code (e.g., `US-DE` for Delaware)        |
| `registrationDate`      | string | Date of registration/incorporation                             |

### Person Attributes

When the entity represents a natural person (e.g., an officer or shareholder), these fields are populated instead:

| Field                | Type   | Description                  |
| -------------------- | ------ | ---------------------------- |
| `givenName`          | string | First name                   |
| `middleName`         | string | Middle name                  |
| `surname`            | string | Last name                    |
| `fullName`           | string | Full name as a single string |
| `dateOfBirth`        | string | Date of birth                |
| `nationality`        | string | Nationality                  |
| `countryOfResidence` | string | Country of residence         |
| `occupation`         | string | Occupation or profession     |

### Nested Objects

| Field             | Type                                                                       | Description                                   |
| ----------------- | -------------------------------------------------------------------------- | --------------------------------------------- |
| `addresses`       | [Address](broken://pages/0431ea28b5ce32adbcf00c2314ddcf503d2e3ff9)\[]      | Registered, headquarters, and other addresses |
| `activities`      | [Activity](broken://pages/8237aace816bc055ce07ec12c1780a15b091cc34)\[]     | Business activities and NACE/industry codes   |
| `capital`         | [Capital](broken://pages/31feae3008412d7a5d73560602a9dcb2595865c8)         | Share capital and structure                   |
| `financials`      | [Financials](broken://pages/0958e5b241ca38c94e1fb79c5fd05504d873cf32)      | Financial metrics (when requested)            |
| `identifiers`     | [Identifier](broken://pages/d78257fbf133f39ed2d6cb71dad86d2011f7bd6a)\[]   | Registration numbers and tax IDs              |
| `otherNames`      | OtherName\[]                                                               | Alternative, previous, or translated names    |
| `relationships`   | [Relationship](broken://pages/4f3be4e5a9cfa04a50192c257a4e539521280db1)\[] | Officers, shareholders, and beneficial owners |
| `sourceDocuments` | SourceDocument\[]                                                          | Proof documents retrieved from registries     |
| `counterparties`  | Entity\[]                                                                  | Related entities (nested Entity objects)      |

### OtherName Object

| Field      | Type   | Description                                                                      |
| ---------- | ------ | -------------------------------------------------------------------------------- |
| `name`     | string | The alternative name                                                             |
| `language` | string | Language code (e.g., `en`, `de`, `ja`)                                           |
| `nametype` | string | One of: `alias`, `native`, `previous`, `trading`, `translated`, `transliterated` |

### SourceDocument Object

| Field           | Type   | Description                                                                                    |
| --------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `_documentID`   | string | Document ID (use with the [Document Retrieval](/revolutio-api/document-retrieval.md) endpoint) |
| `_entityID`     | string | ID of the associated entity                                                                    |
| `dateRetrieved` | string | Date the document was retrieved                                                                |
| `name`          | string | Document name/title                                                                            |
| `source`        | string | Source registry name                                                                           |
| `url`           | string | Original URL of the document in the registry                                                   |

## Example

```json
{
  "_id": "550e8400-e29b-41d4-a716-446655440000",
  "_entityURL": "https://find-and-update.company-information.service.gov.uk/company/09215191",
  "legalName": "REVOLUT LTD",
  "legalForm": "Private Limited Company",
  "companyStatus": "Active",
  "countryOfRegistration": "GB",
  "jurisdiction": "GB",
  "registrationDate": "2014-07-01",
  "addresses": [
    {
      "_addressFormat": "raw",
      "_addressType": "Registered Address",
      "addressLine1": "7 Westferry Circus",
      "locality": "London",
      "postcode": "E14 4HD",
      "country": "GB"
    }
  ],
  "identifiers": [
    {
      "type": "Company number",
      "number": "09215191",
      "authority": "Companies House",
      "jurisdiction": "GB"
    }
  ],
  "activities": [
    {
      "activityCode": "64.19",
      "activityCodeType": "NACE",
      "activityDescription": "Other monetary intermediation",
      "mainActivity": true
    }
  ],
  "relationships": [
    {
      "natureOfRelationship": "Officer",
      "role": "Director"
    }
  ],
  "otherNames": [
    {
      "name": "Revolut",
      "nametype": "trading"
    }
  ],
  "sourceDocuments": [
    {
      "_documentID": "doc-abc-123",
      "_entityID": "550e8400-e29b-41d4-a716-446655440000",
      "dateRetrieved": "2025-01-15",
      "name": "Certificate of Incorporation",
      "source": "Companies House"
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://equinoxe-systems.gitbook.io/revolutio-api/data-models/entity.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.