# Firmographic Data API

*/Software/Firmographic_Data_API*

## Solution Overview

The Firmographic Data API accepts a corporate domain or company name and returns a standardized JSON payload detailing organizational structure, estimated revenue, employee headcount by department, and active technology stack. It resolves ambiguous inputs into deterministic company profiles, matching aliases and subsidiaries to their parent entities. The API outputs structured facts directly into lead routing engines without requiring a user interface or manual data entry.

Revenue operations engineers and builders of B2B sales agents consume this API to enrich inbound leads in real time. It eliminates the need to maintain custom web scrapers for corporate websites or pay for seat-based data platforms that trap information behind a graphical dashboard. By automating the data retrieval step, developers ensure their outbound agents have the exact organizational context required to draft highly relevant, account-specific communications.

Operating as a headless SaaS primitive, the API ingests and standardizes fragmented data from public business registries, SEC filings, and job board crawls at the bottom of the stack. Above it, autonomous sales agents and CRM webhooks query the endpoints to trigger programmatic workflows, such as routing high-headcount enterprise leads to senior account executives or qualifying target accounts based on specific software dependencies.

## Headless Saas Data Model

**Entities**:
- Name: CompanyProfile · Description: Represents a distinct corporate entity with consolidated firmographic facts
- Name: DomainAlias · Description: Maps alternative web domains to a canonical company profile
- Name: DepartmentMetric · Description: Quantifies employee headcount within a specific organizational department
- Name: TechnologyInstall · Description: Represents a software product actively used by the company
- Name: SourceCitation · Description: Tracks the origin of ingested firmographic data points
**Relations**:
- To: CompanyProfile · From: CompanyProfile · Label: has subsidiaries · Cardinality: one-to-many
- To: CompanyProfile · From: DomainAlias · Label: resolves to · Cardinality: one-to-many
- To: CompanyProfile · From: DepartmentMetric · Label: belongs to company · Cardinality: one-to-many
- To: CompanyProfile · From: TechnologyInstall · Label: installed at · Cardinality: one-to-many
- To: CompanyProfile · From: SourceCitation · Label: substantiates data for · Cardinality: one-to-many
**Primary Resource**: CompanyProfile

## Api Definition

**Protocols**:
- REST
- SDK
- MCP
- Webhooks
**Consumed By**:
- [Inbound Lead Router](/Agents/Inbound_Lead_Router)
- [Outbound SDR Agent](/Agents/Outbound_SDR_Agent)
- [Account Scoring Agent](/Agents/Account_Scoring_Agent)
**Integrations**:
- [EDGAR](/Products/EDGAR)
- [OpenCorporates](/Products/OpenCorporates)
- [BuiltWith](/Products/BuiltWith)
- [Common Crawl](/Products/Common_Crawl)
**Consumption Model**: An agent registers the MCP server to call the entity resolution endpoint for each new domain, retrieving a canonical company profile to contextualize its outreach.
**Workflow Wrappers**:
- Name: Resolve Company Entity · Wraps: Maps an ambiguous domain or alias to its canonical parent profile and corporate ID.
- Name: Enrich Lead Payload · Wraps: Aggregates revenue, department headcounts, and active technology installs into a single company profile.

## Api Function Cascade

**Ai Role**: As a stateless headless primitive, generative AI models execute inline without human intervention to extract attributes from raw crawl data and mathematically resolve fuzzy domains to strict canonical entities.
**Cascade**:
- Kind: Code · Note: Receives the target domain or alias via REST, SDK, or MCP. · Step: Ingest Query Payload · Verb: ingest · Realizes: Process Inbound API Request · Oversight: none
- Kind: Code · Note: Pulls structured entity and hierarchy data from EDGAR and OpenCorporates. · Step: Fetch Registry Records · Verb: fetch · Realizes: Retrieve Business Information · Oversight: none
- Kind: Code · Note: Retrieves active technology installs and crawl text from BuiltWith and Common Crawl. · Step: Scrape Web Signals · Verb: fetch · Realizes: Gather Web Data · Oversight: none
- Kind: Generative · Note: Parses unstructured crawl data to determine department headcounts and revenue bands. · Step: Extract Firmographic Attributes · Verb: extract · Realizes: Analyze Text Data · Oversight: none
- Kind: Generative · Note: Maps ambiguous aliases or regional domains to the master corporate parent. · Step: Resolve Canonical Entity · Verb: match · Realizes: Reconcile Master Data · Oversight: none
- Kind: Code · Step: Emit Enriched Profile · Verb: emit · Realizes: Transmit API Response · Oversight: none
**Optimizes**:
- [Entity Resolution Accuracy](/Metrics/Entity_Resolution_Accuracy)
- [Profile Completeness Rate](/Metrics/Profile_Completeness_Rate)
- [API Latency](/Metrics/API_Latency)
- [False Positive Match Rate](/Metrics/False_Positive_Match_Rate)

## Headless Saas Representative Offer

**Warranty**: Maintains a 99.9% API uptime SLA with guaranteed sub-500ms latency for entity resolution, issuing automated service credits for any billing cycle that breaches these thresholds.
**Price Band**: ~$0.01 to $0.05 per successful entity resolution or enriched profile, depending on the data fields requested and monthly call volume.
**Pricing Kind**: UsageMeter
**Deliverables**:
- Canonical company entity profiles
- Revenue and department headcount aggregates
- Active technology install footprints
- Corporate hierarchy and alias mappings
**Delivery Mode**: Self-serve API access is provisioned instantly upon registration, with usage metered automatically as endpoints or MCP server methods are called.
**Business Function**: ProvideService
**Agent Checkout Support**:
- agentic-commerce-protocol
- stored-credential

## Headless Saas Crud Surface

**Auth Model**: API Key
**Endpoints**:
- GET /company-profiles — list company profiles
- POST /company-profiles — create a new company profile
- GET /company-profiles/{id} — fetch a company profile
- PATCH /company-profiles/{id} — update a company profile
- GET /company-profiles/{id}/subsidiaries — list subsidiary company profiles
- GET /company-profiles/{companyProfileId}/domain-aliases — list domain aliases for a company
- POST /company-profiles/{companyProfileId}/domain-aliases — add a domain alias to a company
- GET /domain-aliases/{id} — fetch a specific domain alias
- PATCH /domain-aliases/{id} — update a domain alias
- GET /company-profiles/{companyProfileId}/department-metrics — list department headcount metrics for a company
- POST /company-profiles/{companyProfileId}/department-metrics — record a new department headcount metric
- GET /department-metrics/{id} — fetch a department metric
- PATCH /department-metrics/{id} — update a department metric
- GET /company-profiles/{companyProfileId}/technology-installs — list active software installs for a company
- POST /company-profiles/{companyProfileId}/technology-installs — record a newly detected technology install
- GET /technology-installs/{id} — fetch a technology install record
- PATCH /technology-installs/{id} — update a technology install record
- GET /company-profiles/{companyProfileId}/source-citations — list crawled source citations for a company
- POST /company-profiles/{companyProfileId}/source-citations — append a data source citation
- GET /source-citations/{id} — fetch a specific source citation
- PATCH /source-citations/{id} — update a source citation
**Multitenancy**: Row-level isolation
**Webhook Events**:
- company_profile.created
- company_profile.updated
- technology_install.detected
- domain_alias.activated

## Headless Saas Erd

```mermaid
erDiagram
CompanyProfile {
UUID id PK "tenant"
VARCHAR primaryDomain
VARCHAR legalName
DECIMAL estimatedRevenue
DECIMAL totalHeadcount
UUID parentProfileId FK
}
DomainAlias {
UUID id PK
UUID companyProfileId FK
VARCHAR alias
BOOLEAN isActive
}
DepartmentMetric {
UUID id PK
UUID companyProfileId FK
VARCHAR departmentName
DECIMAL headcount
}
TechnologyInstall {
UUID id PK
UUID companyProfileId FK
VARCHAR softwareName
TIMESTAMP detectedAt
}
SourceCitation {
UUID id PK
UUID companyProfileId FK
VARCHAR sourceType
VARCHAR sourceUrl
TIMESTAMP crawledAt
}
CompanyProfile ||--o{ CompanyProfile : "has subsidiaries"
DomainAlias ||--o{ CompanyProfile : "resolves to"
DepartmentMetric ||--o{ CompanyProfile : "belongs to company"
TechnologyInstall ||--o{ CompanyProfile : "installed at"
SourceCitation ||--o{ CompanyProfile : "substantiates data for"
```

## Neighborhood

### Composed into

- [Inbound Screening Agent](/Agents/Inbound_Screening_Agent) — composes · Agents
- [Nonexistent Cold Agent Xyz](/Agents/Nonexistent_Cold_Agent_Xyz) — composes · Agents

### Optimizes

- [API Latency](/Metrics/API_Latency) — optimizes · Metrics
- [Entity Resolution Accuracy](/Metrics/Entity_Resolution_Accuracy) — optimizes · Metrics
- [False Positive Match Rate](/Metrics/False_Positive_Match_Rate) — optimizes · Metrics
- [Profile Completeness Rate](/Metrics/Profile_Completeness_Rate) — optimizes · Metrics

### What it uses

- [Common Crawl](/Products/Common_Crawl) — uses · Products
- [EDGAR](/Products/EDGAR) — uses · Products
- [OpenCorporates](/Products/OpenCorporates) — uses · Products
- [BuiltWith](/Products/BuiltWith) — uses · Products

### Who consumes this

- [Account Scoring Agent](/Agents/Account_Scoring_Agent) — consumed by · Agents
- [Inbound Lead Router](/Agents/Inbound_Lead_Router) — consumed by · Agents
- [Outbound SDR Agent](/Agents/Outbound_SDR_Agent) — consumed by · Agents

### Similar Software

- [Firmographic Enrichment API](/Software/Firmographic_Enrichment_API) — similar · Software
- [Entity Structure Graph API](/Software/Entity_Structure_Graph_API) — similar · Software
- [Intent Signal Feed](/Software/Intent_Signal_Feed) — similar · Software
- [CRM Sync API](/Software/CRM_Sync_API) — similar · Software
- [Open Banking APIs](/Resources/Client_financial_data/Software/Open_Banking_APIs) — similar · Software
- [Bank Transaction API](/Software/Bank_Transaction_API) — similar · Software
- [Pipeline Gateway API](/Software/Pipeline_Gateway_API) — similar · Software
- [Sanctions Screening API](/Software/Sanctions_Screening_API) — similar · Software
- [Signal Match Engine](/Software/Signal_Match_Engine) — similar · Software
- [Entity Filing API](/Software/Entity_Filing_API) — similar · Software
- [Vendor Resolution Engine](/Software/Vendor_Resolution_Engine) — similar · Software

### Similar Startups

- [Clearbit](/Startups/Clearbit) — similar · Startups
- [Parserdomain](/Startups/Parserdomain) — similar · Startups
- [Registrylane](/Startups/Registrylane) — similar · Startups
- [Entitypod](/Startups/Entitypod) — similar · Startups

### Similar Agents

- [Real-Time Query API](/Agents/Real-Time_Query_API) — similar · Agents
- [Agnostic Ingestion API](/Agents/Agnostic_Ingestion_API) — similar · Agents
- [Unstructured Payroll API](/Agents/Unstructured_Payroll_API) — similar · Agents
- [Gateway Ingestion API](/Agents/Gateway_Ingestion_API) — similar · Agents
- [Pipeline Integration API](/Agents/Pipeline_Integration_API) — similar · Agents