Skip to main content
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:
FieldPurpose
idMetal’s canonical identifier.
externalIdA single external identifier you control.
externalReferenceA 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.
FieldTypeDescription
canonicalNamestringThe company’s primary name. Required.
alternativeNamesstring[]Other names the company is known by.
websitestringPrimary website URL.
descriptionstringLong-form description.
shortDescriptionstringOne-line summary.
sector / subsector / industrystringClassification labels.
locationobjectHeadquarters location.
companyTypestringoperating, investor, lender, investment_bank, advisor, sponsor, or service_provider.
tagsstring[]Tag references.
assigneesreference[]Users or teams responsible for the company.
customobjectOrg-defined custom fields.
{
  "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.
FieldTypeDescription
namestringDeal name.
companyIdstringThe target company’s id.
statusstringInternal lifecycle status: ACTIVE, CLOSED, or PASSED_DEAD.
stagestringPipeline stage, for example SOURCED, SCREENED, DUE_DILIGENCE, IC_MEETING.
ownersreference[]Users or teams who own the deal.
sector / industrystringClassification labels.
sizenumberDeal size.
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.
FieldTypeDescription
firstName / lastNamestringThe person’s name.
emailstringPrimary email.
currentTitlestringCurrent role.
currentCompanyNamestringCurrent employer name.
companystringLinked company id.
linkedinUrlstringLinkedIn profile URL.
locationobjectLocation.

​
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.