> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metal.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Data model
> Companies, deals, people, and how Metal's core resources relate.
Metal's data model centers on a few core resources that reference each other. Understanding how they relate makes the API easier to use.
## Core resources
An entity your firm tracks: an operating company, investor, advisor, or service provider.
An opportunity in your pipeline, usually tied to a target company.
A contact or executive, optionally linked to a company.
## Identifiers
Every resource has a Metal-assigned `id` (a 24-character hex string). You can also attach your own identifiers so you can reconcile records with external systems:
| Field | Purpose |
| ------------------- | ---------------------------------------------------------------------- |
| `id` | Metal's canonical identifier. |
| `externalId` | A single external identifier you control. |
| `externalReference` | A structured reference to a source system (for example, a CRM record). |
Companies, deals, and people can be fetched by external identifier as well as by Metal `id`. For example:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# By Metal id
curl https://api.metal.ai/v1/companies/665f1c2a9b1e4a0012a3b4c5 \
-H "x-metal-client-id: $METAL_CLIENT_ID" \
-H "x-metal-api-key: $METAL_API_KEY"
# By your external id
curl "https://api.metal.ai/v1/companies/externalId=crm-12345" \
-H "x-metal-client-id: $METAL_CLIENT_ID" \
-H "x-metal-api-key: $METAL_API_KEY"
```
## Companies
A company is the most central resource. The only required field on creation is `canonicalName`.
| Field | Type | Description |
| --------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `canonicalName` | string | The company's primary name. **Required.** |
| `alternativeNames` | string\[] | Other names the company is known by. |
| `website` | string | Primary website URL. |
| `description` | string | Long-form description. |
| `shortDescription` | string | One-line summary. |
| `sector` / `subsector` / `industry` | string | Classification labels. |
| `location` | object | Headquarters location. |
| `companyType` | string | `operating`, `investor`, `lender`, `investment_bank`, `advisor`, `sponsor`, or `service_provider`. |
| `tags` | string\[] | Tag references. |
| `assignees` | reference\[] | Users or teams responsible for the company. |
| `custom` | object | Org-defined custom fields. |
| `employeeCount` | number | Headcount. **Enriched.** |
| `ownershipStatus` | string | Private, public, or sponsor-owned. **Enriched.** |
| `lastValuation` / `lastAmountRaised` / `totalMoneyRaised` | number | Financial metrics. **Enriched.** See [Financial metrics](/concepts/financial-metrics). |
| `enrichment` | object | Discovered values and citations behind enriched fields. See [Reconciliation & ranking](/concepts/reconciliation). |
Fields marked **Enriched** are populated by Metal from your documents, data providers, and the web, then [reconciled](/concepts/reconciliation) into a single value. The `enrichment` object exposes the alternatives and their sources for each one.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"data": {
"id": "665f1c2a9b1e4a0012a3b4c5",
"canonicalName": "Acme Industrials",
"website": "https://acme.example",
"sector": "Industrials",
"companyType": "operating",
"createdAt": "2026-06-01T12:00:00Z",
"updatedAt": "2026-06-02T09:30:00Z"
}
}
```
## Deals
A deal represents an opportunity. It usually points at a target company via `companyId`.
| Field | Type | Description |
| --------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Deal name. |
| `companyId` | string | The target company's `id`. |
| `status` | string | Internal lifecycle status: `ACTIVE`, `CLOSED`, or `PASSED_DEAD`. |
| `stage` | string | Pipeline stage, for example `SOURCED`, `SCREENED`, `DUE_DILIGENCE`, `IC_MEETING`. |
| `owners` | reference\[] | Users or teams who own the deal. |
| `sector` / `industry` | string | Classification labels. |
| `size` | number | Deal size. |
| `acquisitionType` | string | Derived, read-only. `add_on` if the deal has a platform company, otherwise `platform`. Returned on every deal response; cannot be set via the API. |
Metal models deal status and stage with two layers: a fixed set of internal values (used for logic) and your firm's own custom labels (shown in the app). The API returns both the internal `status`/`stage` and the external labels where configured.
## People
A person is a contact, often linked to a company through the `company` field.
| Field | Type | Description |
| ------------------------ | ------ | ---------------------- |
| `firstName` / `lastName` | string | The person's name. |
| `email` | string | Primary email. |
| `currentTitle` | string | Current role. |
| `currentCompanyName` | string | Current employer name. |
| `company` | string | Linked company `id`. |
| `linkedinUrl` | string | LinkedIn profile URL. |
| `location` | object | Location. |
## Relationships
```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
graph LR
Person -->|works at| Company
Deal -->|targets| Company
Deal -->|owned by| User
Document -->|attached to| Company
Document -->|attached to| Deal
```
* A **deal** references a target **company** through `companyId`.
* A **person** references their **company** through `company`.
* **Documents** are attached to companies and deals and become searchable once ingested.
## Reading collections
List endpoints (`GET /v1/companies`, `GET /v1/deals`, `GET /v1/people`) return arrays under `data` and support [pagination](/guides/pagination). For relevance-ranked retrieval, use the [search endpoints](/guides/search) instead.