# Firmographic Enrichment API

*/Software/Firmographic_Enrichment_API*

## Solution Overview

The Firmographic Enrichment API ingests raw company names, messy URLs, or partial email domains and returns a standardized JSON payload of corporate data. It resolves entity ambiguity, standardizes industry classification codes like NAICS and SIC, and appends verified attributes including employee headcount, estimated revenue brackets, and active technology stacks. The output allows downstream systems to categorize inbound leads instantly based on verified data rather than user-submitted form fields.

Revenue Operations engineers and CRM administrators integrate this API to eliminate manual lead research and routing bottlenecks. When a prospect submits a bare email address, the API prevents marketing teams from forcing users through long qualification forms. It ensures the CRM captures the precise firmographic details required to route a lead to the correct enterprise, mid-market, or regional sales desk.

Operating as a headless SaaS primitive, the API consumes raw public web scraping data, state business registries, and localized job board postings to build its underlying entity graph. Above it, outbound sales agents, automated CRM workflows, and dynamic lead-scoring algorithms consume its endpoints, relying on its sub-200 millisecond response time to execute real-time routing decisions and flag ambiguous entity matches for human CRM administrators.

## Headless Saas Data Model

**Entities**:
- Name: EnrichedCompany · Description: The standardized corporate entity profile resolved from an ambiguous raw input
- Name: Workspace · Description: Tenant organization configuring API keys and consuming the enriched firmographic records
- Name: CompanyDomain · Description: Web domains and messy URLs successfully associated with the enriched company
- Name: IndustryCode · Description: Standardized NAICS or SIC classifications applied to the corporate entity
- Name: DetectedTechnology · Description: Active technology stack tools identified for the company via external scrapers
**Relations**:
- To: EnrichedCompany · From: Workspace · Label: owns enriched records · Cardinality: one-to-many
- To: CompanyDomain · From: EnrichedCompany · Label: operates web domains · Cardinality: one-to-many
- To: IndustryCode · From: EnrichedCompany · Label: is classified by · Cardinality: one-to-many
- To: DetectedTechnology · From: EnrichedCompany · Label: utilizes tech stack · Cardinality: one-to-many
**Tenant Anchor**: Workspace
**Primary Resource**: EnrichedCompany

## Api Definition

**Protocols**:
- REST
- SDK
- MCP
**Consumed By**:
- [Outbound Sales Agent](/Agents/Outbound_Sales_Agent)
- [Lead Routing Agent](/Agents/Lead_Routing_Agent)
- [Lead Scoring Agent](/Agents/Lead_Scoring_Agent)
**Integrations**:
- [Salesforce](/Products/Salesforce)
- [HubSpot](/Products/HubSpot)
- [EDGAR](/Products/EDGAR)
- [Common Crawl](/Products/Common_Crawl)
**Consumption Model**: A Lead Routing Agent triggers the SDK's entity resolution method when a prospect submits a bare email address, injecting the returned industry and headcount data directly into the CRM.
**Workflow Wrappers**:
- Name: Resolve Entity Record · Wraps: queries the underlying graph to match a partial input and hydrates all firmographic entities
- Name: Batch Process Domains · Wraps: accepts an array of messy URLs, performs async resolution, and returns standardized profiles

## Api Function Cascade

**Ai Role**: This primitive operates as stateless, fully automated software where deterministic graph lookups and generative data extraction run straight-through without human oversight to return structured firmographics to consuming agents.
**Cascade**:
- Kind: Code · Note: Accepts bare email or domain via REST/SDK. · Step: Receive API Request · Verb: ingest · Realizes: Process API Requests · Oversight: none
- Kind: Code · Note: Cleans and parses the messy URL or email domain. · Step: Normalize Domain Structure · Verb: standardize · Realizes: Standardize Data Formats · Oversight: none
- Kind: Code · Note: Deterministic lookup against EDGAR and structured datasets. · Step: Query Firmographic Graph · Verb: search · Realizes: Retrieve Information From Databases · Oversight: none
- Kind: Generative · Note: One-shot extraction of industry context from Common Crawl text. · Step: Extract Unstructured Attributes · Verb: extract · Realizes: Extract Unstructured Data · Oversight: none
- Kind: Code · Note: Assembles standardized profile with headcount and industry. · Step: Hydrate Entity Record · Verb: aggregate · Realizes: Compile Data Into Profiles · Oversight: none
- Kind: Code · Note: Returns JSON payload to the calling agent or CRM. · Step: Transmit Resolved Payload · Verb: transmit · Realizes: Transmit Data · Oversight: none
**Optimizes**:
- [Entity Match Rate](/Metrics/Entity_Match_Rate)
- [Data Completeness Score](/Metrics/Data_Completeness_Score)
- [Resolution Latency](/Metrics/Resolution_Latency)

## Headless Saas Representative Offer

**Warranty**: Backed by a 99.9% API uptime SLA with prorated usage credits applied automatically for service degradation or endpoint failure.
**Price Band**: ~$0.01 to $0.05 per successful entity resolution, depending on monthly query volume
**Pricing Kind**: UsageMeter
**Deliverables**:
- REST API endpoint access for real-time entity resolution
- Asynchronous batch processing queue for bulk domain enrichment
- Pre-built SDKs and MCP tool definitions for agent integration
- Standardized firmographic profile payloads including industry and headcount data
**Delivery Mode**: Self-serve provisioning where developers or autonomous agents instantly generate an API key and begin querying the entity graph immediately.
**Business Function**: ProvideService
**Agent Checkout Support**:
- agentic-commerce-protocol
- stored-credential

## Headless Saas Crud Surface

**Auth Model**: API Key
**Endpoints**:
- GET /enriched-companies — list enriched companies
- GET /enriched-companies/{id} — fetch a specific enriched company
- POST /enriched-companies — submit a raw query for firmographic enrichment
- PATCH /enriched-companies/{id} — update an enriched company profile
- POST /enriched-companies/{id}/resolve — trigger synchronous resolution of raw input
- GET /workspaces — list workspaces
- GET /workspaces/{id} — fetch workspace details
- POST /workspaces — create a new workspace
- PATCH /workspaces/{id} — update workspace configuration
- GET /enriched-companies/{enrichedCompanyId}/company-domains — list web domains associated with the company
- GET /enriched-companies/{enrichedCompanyId}/company-domains/{id} — fetch a specific company domain
- POST /enriched-companies/{enrichedCompanyId}/company-domains — add a new web domain
- PATCH /enriched-companies/{enrichedCompanyId}/company-domains/{id} — update a company domain record
- GET /enriched-companies/{enrichedCompanyId}/industry-codes — list assigned industry classifications
- GET /enriched-companies/{enrichedCompanyId}/industry-codes/{id} — fetch a specific industry code
- POST /enriched-companies/{enrichedCompanyId}/industry-codes — assign a new industry code
- PATCH /enriched-companies/{enrichedCompanyId}/industry-codes/{id} — update an industry code record
- GET /enriched-companies/{enrichedCompanyId}/detected-technologies — list technology stack tools
- GET /enriched-companies/{enrichedCompanyId}/detected-technologies/{id} — fetch a specific detected technology
- POST /enriched-companies/{enrichedCompanyId}/detected-technologies — record a new technology in the stack
- PATCH /enriched-companies/{enrichedCompanyId}/detected-technologies/{id} — update a detected technology
**Multitenancy**: Row-level isolation
**Webhook Events**:
- enriched_company.resolved
- enriched_company.enrichment_failed
- detected_technology.verified

## Headless Saas Erd

```mermaid
erDiagram
  Workspace ||--o{ EnrichedCompany : "owns enriched records"
  EnrichedCompany ||--o{ CompanyDomain : "operates web domains"
  EnrichedCompany ||--o{ IndustryCode : "is classified by"
  EnrichedCompany ||--o{ DetectedTechnology : "utilizes tech stack"
  Workspace {
    UUID id PK "tenant key"
    VARCHAR organizationName
    VARCHAR apiToken
    VARCHAR status
  }
  EnrichedCompany {
    UUID id PK
    UUID workspaceId FK
    VARCHAR rawInputQuery
    VARCHAR standardizedLegalName
    DECIMAL headcount
    DECIMAL annualRevenue
    VARCHAR matchConfidence
  }
  CompanyDomain {
    UUID id PK
    UUID enrichedCompanyId FK
    VARCHAR domainUrl
    BOOLEAN isPrimary
  }
  IndustryCode {
    UUID id PK
    UUID enrichedCompanyId FK
    VARCHAR classificationSystem
    VARCHAR codeValue
    VARCHAR industryDescription
  }
  DetectedTechnology {
    UUID id PK
    UUID enrichedCompanyId FK
    VARCHAR softwareName
    VARCHAR category
    TIMESTAMP lastVerifiedAt
  }
```

## Neighborhood

### Composed into

- [Pipeline Triage Agent](/Agents/Pipeline_Triage_Agent) — composes · Agents
- [Clearbit](/Startups/Clearbit) — composes · Startups
- [Intent Signal Worker](/Agents/Intent_Signal_Worker) — composes · Agents
- [Sales Development Representative](/Agents/Sales_Development_Representative) — composes · Agents

### Optimizes

- [Entity Match Rate](/Metrics/Entity_Match_Rate) — optimizes · Metrics
- [Resolution Latency](/Metrics/Resolution_Latency) — optimizes · Metrics
- [Data Completeness Score](/Metrics/Data_Completeness_Score) — optimizes · Metrics

### What it uses

- [Common Crawl](/Products/Common_Crawl) — uses · Products
- [EDGAR](/Products/EDGAR) — uses · Products
- [HubSpot](/Software/HubSpot) — uses · Software
- [Salesforce](/Software/Salesforce) — uses · Software

### Who consumes this

- [Lead Routing Agent](/Agents/Lead_Routing_Agent) — consumed by · Agents
- [Lead Scoring Agent](/Agents/Lead_Scoring_Agent) — consumed by · Agents
- [Outbound Sales Agent](/Agents/Outbound_Sales_Agent) — consumed by · Agents

### Similar Software

- [Firmographic Data API](/Software/Firmographic_Data_API) — similar · Software
- [Pipeline Gateway API](/Software/Pipeline_Gateway_API) — similar · Software
- [CRM Sync API](/Software/CRM_Sync_API) — similar · Software
- [Signal Match Engine](/Software/Signal_Match_Engine) — similar · Software
- [Entity Structure Graph API](/Software/Entity_Structure_Graph_API) — similar · Software
- [Ingestion Routing Engine](/Software/Ingestion_Routing_Engine) — similar · Software
- [Bank Transaction API](/Software/Bank_Transaction_API) — similar · Software
- [Sanctions Screening API](/Software/Sanctions_Screening_API) — similar · Software
- [Vendor Resolution Engine](/Software/Vendor_Resolution_Engine) — similar · Software
- [Identity Verification APIs](/Metrics/KYC_Cycle_Time/Software/Identity_Verification_APIs) — similar · Software
- [Entity Filing API](/Software/Entity_Filing_API) — similar · Software

### Similar Startups

- [Parserdomain](/Startups/Parserdomain) — similar · Startups
- [Leadibe](/Startups/Leadibe) — similar · Startups
- [Standardizedomain](/Startups/Standardizedomain) — similar · Startups
- [Codemap](/CompanyTypes/Regional_Accounting_&_Tax_Practice/Problems/Map_Trial_Balance_Accounts/Startups/Codemap) — similar · Startups
- [Vagress](/Problems/Degraded_Initial_SLA_Attainment/Startups/Vagress) — similar · Startups

### Similar Agents

- [Real-Time Query API](/Agents/Real-Time_Query_API) — similar · Agents
- [Gateway Ingestion API](/Agents/Gateway_Ingestion_API) — similar · Agents