Data model

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

Company

An entity your firm tracks: an operating company, investor, advisor, or service provider.

Deal

An opportunity in your pipeline, usually tied to a target company.

Person

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:

# 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.
`enrichment`	object	Discovered values and citations behind enriched fields. See Reconciliation & ranking.

Fields marked Enriched are populated by Metal from your documents, data providers, and the web, then reconciled into a single value. The enrichment object exposes the alternatives and their sources for each one.

{
  "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

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. For relevance-ranked retrieval, use the search endpoints instead.

Get started

Core concepts

MCP server

Core resources

Company

Deal

Person

Identifiers

Companies

Deals

People

Relationships

Reading collections

​Core resources

Company

Deal

Person

​Identifiers

​Companies

​Deals

​People

​Relationships

​Reading collections

Core resources

Identifiers

Companies

Deals

People

Relationships

Reading collections