# Company Enrichment

Enriches company records with firmographics and website-verified data.

## Overview
The Company Enrichment API enriches company records with comprehensive firmographics data including company details, location information, industry classification, size range, and geographic coordinates.

## Request Body
- record_id: Unique identifier for this enrichment request (required)
- company_name: Company name (optional) - improves accuracy when provided
- domain: Company domain (optional) - improves accuracy when provided
- country: Country code or name (optional) - helps with geographic targeting
- external_ids: External system IDs (optional) - for integration with CRM systems
- effort: Enrichment effort level (optional, default: low)
- max_credits: Maximum credits to spend on this request (optional, defaults to your account limit)

## Request Constraints
- record_id is required
- company_name, domain are optional but improves accuracy when provided
- external_ids should be a dictionary of key-value pairs (e.g., {"sf_account_id": "001xx000..."})
- max_credits must be a positive integer if provided

## Response Fields
- success: Boolean indicating request success
- record_id: Echo of the input record ID
- company: Enriched company data object containing:
  - name: Company name
  - domain: Company domain
  - linkedin_url: LinkedIn company page URL
  - hq: Headquarters location (city, state, country, postal_code)
  - size_range: Employee size range (e.g., "500+")
  - industry: Industry classification
  - geo: Geographic coordinates and location details (lat, lon, county)
  - last_verified_at: ISO timestamp of last verification
- confidence: Confidence score (0.0-1.0) or null if disabled/not found
- credits_consumed: Number of credits used for this request
- credits_remaining: Credits remaining in your account after this request
- processing_time_ms: Time taken to process the request in milliseconds
- cached: Boolean indicating if this result was returned from cache

## Credit Usage
Company enrichment consumes credits based on the data sources queried:
- Cached Result: 0 credits (if same company queried recently)
- Company Lookup: 5 credits

Endpoint: POST /v1/enrich/company
Version: 1.4.1
Security: BearerAuth

## Request fields (application/json):

  - `record_id` (string, required)
    Unique identifier for this enrichment request

  - `company_name` (any)
    Company name

  - `domain` (any)
    Company domain

  - `country` (any)
    Country code or name

  - `external_ids` (any)
    External system IDs (e.g., Salesforce account ID)

  - `effort` (string)
    Enrichment effort type
    Enum: "low", "medium", "high"

  - `max_credits` (integer)
    Maximum credits to spend on this request

## Response 200 fields (application/json):

  - `success` (boolean, required)
    Boolean indicating request success

  - `record_id` (string, required)
    Unique identifier for this enrichment request

  - `company` (any)
    Enriched company data

  - `confidence` (any)
    Confidence score (0.0-1.0) or null if disabled/not found

  - `credits_consumed` (integer, required)
    Number of credits used for this request

  - `credits_remaining` (integer, required)
    Credits remaining in your account after this request

  - `processing_time_ms` (integer, required)
    Time taken to process the request in milliseconds

  - `cached` (boolean, required)
    Boolean indicating if this result was returned from cache

## Response 400 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 401 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 402 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 422 fields (application/json):

  - `detail` (array)

  - `detail.loc` (array, required)

  - `detail.msg` (string, required)

  - `detail.type` (string, required)

## Response 429 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors

## Response 500 fields (application/json):

  - `success` (boolean)
    Always false for error responses

  - `error` (string, required)
    Error message

  - `details` (any)
    Additional error details

  - `request_id` (any)
    Request ID for tracking

  - `credits_required` (any)
    Credits required for insufficient credit errors

  - `credits_remaining` (any)
    Credits remaining for insufficient credit errors

  - `retry_after` (any)
    Seconds to wait before retrying for rate limit errors