> ## 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. # Get a company by external reference > Retrieves a company by its external source reference. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/companies/externalReference={ref} openapi: 3.1.0 info: title: Metal API version: 1.0.0 description: >- REST API for Metal, the AI context layer for financial firms. Manage companies, deals, people, documents, activities, enrichments, scores, screenings, lists, workflows, and more. All endpoints are versioned under /v1, return JSON, and are scoped to the organization that owns your API key. contact: name: Metal Support email: support@metal.ai url: https://www.metal.ai servers: - url: https://api.metal.ai description: Production security: - MetalClientId: [] MetalApiKey: [] tags: - name: API keys description: Create, list, and revoke API keys. - name: Companies description: Manage and enrich companies. - name: Deals description: Track opportunities through your pipeline. - name: People description: Manage contacts and relationships. - name: Documents description: Search and retrieve ingested documents. - name: Activities description: Log and search meetings, calls, and other interactions. - name: Enrichments description: Read and write enriched property values on resources. - name: Scores description: Score companies and deals against scoring frameworks. - name: Screenings description: Run and manage AI-powered company screenings. - name: Lists description: Organize and enrich resources in bulk. - name: Tags description: Label companies, deals, and lists. - name: Industries description: Manage your organization's industry taxonomy. - name: Sectors description: Manage sectors within an industry. - name: Subsectors description: Manage subsectors within a sector. - name: Workflows description: Run and monitor AI workflows. - name: Data description: Query time-series metrics and observations. - name: Teams description: Manage deal teams and their members. - name: Workspaces description: Organize documents and data by workspace. paths: /v1/companies/externalReference={ref}: get: tags: - Companies summary: Get a company by external reference description: Retrieves a company by its external source reference. operationId: getCompanyByExternalReference parameters: - $ref: '#/components/parameters/ExternalReferencePath' responses: '200': $ref: '#/components/responses/CompanyResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: ExternalReferencePath: name: ref in: path required: true description: The external reference id. schema: type: string responses: CompanyResponse: description: A company. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Company' Unauthorized: description: Missing or invalid API key credentials. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid api key or clientId NotFound: description: The resource does not exist in your organization. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: not found schemas: Company: type: object description: >- A company record. Many attributes are populated by enrichment: Metal gathers candidate values from your documents, data providers, and the web, then ranks and reconciles them into the single value shown here. See the Enrichment and Reconciliation & ranking guides. The `enrichment` field exposes the discovered values and citations behind each reconciled attribute. properties: id: type: string example: 665f1c2a9b1e4a0012a3b4c5 canonicalName: type: string example: Acme Industrials alternativeNames: type: array items: type: string website: type: string example: https://acme.example description: type: string shortDescription: type: string sector: type: string example: Industrials subsector: type: string industry: type: string location: $ref: '#/components/schemas/Location' companyType: type: string enum: - operating - investor - lender - investment_bank - advisor - sponsor - service_provider example: operating origin: type: string enum: - user - crm - agent - screening externalId: type: string externalReference: $ref: '#/components/schemas/ExternalReference' tags: type: array items: type: string assignees: type: array items: $ref: '#/components/schemas/Reference' custom: type: object additionalProperties: true description: Organization-defined custom fields. employeeCount: type: integer description: Enriched. Approximate headcount, used as a size proxy. example: 450 ownershipStatus: type: string description: >- Enriched. Ownership status, e.g. "private", "public", or "sponsor-owned". example: private lastValuation: type: number description: Enriched. Most recent known valuation. lastRoundDate: type: string format: date description: Enriched. Date of the most recent funding round. lastAmountRaised: type: number description: Enriched. Amount raised in the most recent round. totalMoneyRaised: type: number description: Enriched. Total capital raised to date. lastFinancials: type: object additionalProperties: true description: Enriched. Most recent reported financials (such as revenue). enrichment: $ref: '#/components/schemas/EnrichmentProvenance' lastEnrichedAt: type: string format: date-time description: When enrichment last completed and wrote values. lastEnrichmentStartedAt: type: string format: date-time description: >- When the most recent enrichment run began. If newer than `lastEnrichedAt`, a run is in progress. createdAt: type: string format: date-time updatedAt: type: string format: date-time Error: type: object properties: error: type: string description: A human-readable error message. Location: type: object properties: city: type: string state: type: string country: type: string ExternalReference: type: object description: A structured reference to a record in an external source system. properties: source: type: string description: The external system, e.g. a CRM provider. id: type: string description: The record id in the external system. Reference: type: object description: A reference to another resource, such as a user or team. properties: id: type: string type: type: string description: The referenced resource type, e.g. "user" or "team". EnrichmentProvenance: type: object description: >- Maps an enriched field name to the list of values Metal discovered for it. The resolved (top-ranked or pinned) value is reflected on the field itself; this object exposes the alternatives and their citations. additionalProperties: type: array items: $ref: '#/components/schemas/DiscoveredValue' example: subsector: - value: Self-Funded Health Insurance / Third Party Administrator (TPA) source: CIM confidence: 100 pinned: true discoveredAt: '2026-02-14T10:00:00Z' - value: Third-Party Administrators (TPAs) source: Market Report confidence: 57 pinned: false discoveredAt: '2026-01-20T10:00:00Z' DiscoveredValue: type: object description: >- A single value Metal discovered for a field, with its provenance. Metal ranks and reconciles these into the value shown on the field. See the Reconciliation & ranking guide. properties: value: description: The discovered value. Type matches the underlying field. source: type: string description: >- Where the value came from, e.g. "CIM", "Market Report", "Web Search", "Third Party Data", or "User Updated". example: CIM confidence: type: number description: Confidence in the value, as a percentage (0–100). example: 100 pinned: type: boolean description: >- Whether this value is pinned as the displayed value, overriding ranking. example: true discoveredAt: type: string format: date-time description: When the value was discovered. securitySchemes: MetalClientId: type: apiKey in: header name: x-metal-client-id description: The Client ID of your API key. MetalApiKey: type: apiKey in: header name: x-metal-api-key description: The secret value of your API key. ````