Company Data Enrichment

Overview

SpiderCompanyData enriches your leads with official company information from free public government registries. No expensive third-party data providers needed.

Use cases:

Enrich B2B leads with company details
Verify company registration status
Validate EU VAT numbers for invoicing
Research company directors and officers

Supported Data Sources

Country	Source	Coverage	Data Available
US	SEC EDGAR	~10,000 public companies	Name, address, CIK, filings
UK	Companies House	~5 million companies	Name, address, directors, status, financials
EU	VIES	All EU member states	VAT validation, company name/address

Quick Start

1. Search for a Company

Find companies by name in a specific country:

cURL
Python

curl -X POST https://spideriq.ai/api/v1/jobs/spiderCompanyData/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>" \
  -d '{
    "payload": {
      "mode": "search",
      "name": "Tesco",
      "country": "GB",
      "limit": 5
    }
  }'

import requests
import time

API_URL = "https://spideriq.ai/api/v1"
HEADERS = {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json"
}

# Submit search job
response = requests.post(
    f"{API_URL}/jobs/spiderCompanyData/submit",
    headers=HEADERS,
    json={
        "payload": {
            "mode": "search",
            "name": "Tesco",
            "country": "GB",
            "limit": 5
        }
    }
)

job_id = response.json()["job_id"]
print(f"Job submitted: {job_id}")

# Poll for results
while True:
    status = requests.get(
        f"{API_URL}/jobs/{job_id}/status",
        headers=HEADERS
    ).json()

    if status["status"] == "completed":
        break
    elif status["status"] == "failed":
        raise Exception("Job failed")

    time.sleep(2)

# Get results
results = requests.get(
    f"{API_URL}/jobs/{job_id}/results",
    headers=HEADERS
).json()

# Parse search results
data = results.get("data", {})
for company in data.get("results", []):
    print(f"{company['name']} ({company['registration_number']}) - {company['status']}")

2. Look Up by Registration Number

If you know the company's registration number, lookup is faster and more accurate:

curl -X POST https://spideriq.ai/api/v1/jobs/spiderCompanyData/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_token>" \
  -d '{
    "payload": {
      "mode": "lookup",
      "country": "GB",
      "identifier": "00445790"
    }
  }'

3. Validate EU VAT Numbers

Validate VAT numbers for invoicing compliance:

curl -X POST https://spideriq.ai/api/v1/jobs/spiderCompanyData/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_token>" \
  -d '{
    "payload": {
      "mode": "vat",
      "vat_number": "DE123456789"
    }
  }'

Real response from EU VIES (SAP SE):

{
  "success": true,
  "query_time_ms": 2357,
  "data": {
    "valid": true,
    "vat_number": "DE129273398",
    "country_code": "DE",
    "company_name": "---",
    "company_address": "---",
    "request_date": "2026-02-14T21:07:42.167969"
  }
}

note

Germany returns "---" for company name/address due to privacy regulations. Other EU countries (Netherlands, France, Belgium) return full company details.

Response Data

Search Results (Real Example)

Real response from UK Companies House search for "Barclays":

{
  "success": true,
  "query": "Barclays",
  "country": "GB",
  "total_results": 3,
  "sources_queried": ["uk_companies_house"],
  "query_time_ms": 463,
  "results": [
    {
      "name": "BARCLAYS PLC",
      "source": "uk_companies_house",
      "source_id": "00048839",
      "country_code": "GB",
      "status": "active",
      "legal_form": "plc",
      "registration_number": "00048839",
      "incorporation_date": "1896-07-20",
      "address": {
        "line_1": "1 Churchill Place, London, E14 5HP",
        "city": null,
        "region": null,
        "postal_code": null,
        "country": "GB"
      },
      "metadata": {
        "cached": false,
        "retrieved_at": "2026-02-14T18:35:56.457471",
        "data_freshness": "real-time",
        "confidence_score": 1
      }
    },
    {
      "name": "BARCLAYS ALDERSGATE INVESTMENTS LIMITED",
      "source": "uk_companies_house",
      "source_id": "02223073",
      "country_code": "GB",
      "status": "active",
      "legal_form": "ltd",
      "registration_number": "02223073",
      "incorporation_date": "1988-02-19",
      "address": {
        "line_1": "1 Churchill Place, London, E14 5HP",
        "country": "GB"
      },
      "metadata": {
        "cached": false,
        "retrieved_at": "2026-02-14T18:35:56.457495",
        "data_freshness": "real-time",
        "confidence_score": 1
      }
    }
  ]
}

Lookup Result (Real Example)

Real response from UK Companies House lookup for company number "00048839" (Barclays PLC):

{
  "success": true,
  "country": "GB",
  "query_time_ms": 413,
  "data": {
    "name": "BARCLAYS PLC",
    "source": "uk_companies_house",
    "source_id": "00048839",
    "country_code": "GB",
    "status": "active",
    "legal_form": "plc",
    "registration_number": "00048839",
    "incorporation_date": "1896-07-20",
    "address": {
      "line_1": "1 Churchill Place",
      "line_2": null,
      "city": "London",
      "region": null,
      "postal_code": "E14 5HP",
      "country": "GB"
    },
    "industry": {
      "sic_codes": ["64191"],
      "nace_codes": [],
      "description": null
    },
    "officers": [],
    "financials": null,
    "vat_number": null,
    "tax_id": null,
    "lei": null,
    "dissolution_date": null,
    "metadata": {
      "cached": false,
      "retrieved_at": "2026-02-14T18:40:19.255108",
      "data_freshness": "real-time",
      "confidence_score": 1
    }
  }
}

tip

Lookup returns more detailed data than search - including parsed address fields (city, postal_code) and SIC industry codes.

Field Descriptions

Field	Description
`name`	Official registered company name
`source`	Data source (`uk_companies_house`, `us_sec_edgar`, `eu_vies`)
`source_id`	Registry-specific ID (CIK, company number)
`country_code`	ISO 3166-1 alpha-2 country code
`status`	`active`, `dissolved`, `liquidation`, etc.
`legal_form`	Legal entity type (plc, ltd, Inc, GmbH)
`registration_number`	Official registration number
`incorporation_date`	When the company was registered (YYYY-MM-DD)
`address`	Registered office address object
`industry.sic_codes`	Standard Industrial Classification codes (UK lookup only)
`officers`	Directors and officers (UK only, requires separate API call)
`metadata.cached`	Whether result came from cache
`metadata.data_freshness`	`real-time` or `cached`
`metadata.confidence_score`	Match confidence (0-1)

Integration Examples

Enrich Leads from SpiderMaps

Combine SpiderMaps business data with official company information:

import requests

API_URL = "https://spideriq.ai/api/v1"
HEADERS = {"Authorization": "Bearer <your_token>", "Content-Type": "application/json"}

# 1. Get businesses from SpiderMaps
maps_job = requests.post(
    f"{API_URL}/jobs/spiderMaps/submit",
    headers=HEADERS,
    json={"payload": {"search_query": "accountants in London", "limit": 10}}
).json()

# ... wait for completion ...

# 2. For each business, enrich with company data
for business in maps_results["data"]["businesses"]:
    company_job = requests.post(
        f"{API_URL}/jobs/spiderCompanyData/submit",
        headers=HEADERS,
        json={
            "payload": {
                "mode": "search",
                "name": business["name"],
                "country": "GB",
                "limit": 1
            }
        }
    ).json()

    # ... wait and get results ...

Validate VAT for EU Invoices

def validate_vat(vat_number: str) -> dict:
    """Validate EU VAT number before invoicing."""
    response = requests.post(
        f"{API_URL}/jobs/spiderCompanyData/submit",
        headers=HEADERS,
        json={"payload": {"mode": "vat", "vat_number": vat_number}}
    )

    job_id = response.json()["job_id"]

    # Poll for completion
    while True:
        status = requests.get(f"{API_URL}/jobs/{job_id}/status", headers=HEADERS).json()
        if status["status"] in ["completed", "failed"]:
            break
        time.sleep(1)

    results = requests.get(f"{API_URL}/jobs/{job_id}/results", headers=HEADERS).json()
    return results.get("data", {})

# Usage
vat_info = validate_vat("DE123456789")
if vat_info.get("valid"):
    print(f"Valid VAT for: {vat_info['company_name']}")
else:
    print("Invalid VAT number")

Best Practices

Caching

SpiderCompanyData caches results for 24 hours. For company data that rarely changes, you can cache even longer client-side:

import redis
import json
import hashlib

cache = redis.Redis()

def get_company_cached(name: str, country: str, cache_days: int = 7):
    cache_key = f"company:{hashlib.md5(f'{name}:{country}'.encode()).hexdigest()}"

    # Check cache
    cached = cache.get(cache_key)
    if cached:
        return json.loads(cached)

    # Fetch from API
    result = fetch_company_from_api(name, country)

    # Cache result
    cache.setex(cache_key, cache_days * 86400, json.dumps(result))
    return result

Error Handling

def safe_company_lookup(identifier: str, country: str) -> dict | None:
    """Look up company with error handling."""
    try:
        response = requests.post(
            f"{API_URL}/jobs/spiderCompanyData/submit",
            headers=HEADERS,
            json={
                "payload": {
                    "mode": "lookup",
                    "identifier": identifier,
                    "country": country
                }
            },
            timeout=30
        )
        response.raise_for_status()

        job_id = response.json()["job_id"]

        # Poll with timeout
        for _ in range(30):  # 30 attempts, 2s each = 60s max
            status = requests.get(f"{API_URL}/jobs/{job_id}/status", headers=HEADERS).json()

            if status["status"] == "completed":
                return requests.get(f"{API_URL}/jobs/{job_id}/results", headers=HEADERS).json()
            elif status["status"] == "failed":
                return None

            time.sleep(2)

        return None  # Timeout

    except requests.RequestException as e:
        print(f"API error: {e}")
        return None

VIES Service Reliability

The EU VIES service can be intermittent. Implement retry logic:

def validate_vat_with_retry(vat_number: str, max_retries: int = 3) -> dict | None:
    """Validate VAT with automatic retry on VIES failures."""
    for attempt in range(max_retries):
        result = validate_vat(vat_number)

        if result and result.get("valid") is not None:
            return result

        # Wait before retry (exponential backoff)
        time.sleep(2 ** attempt)

    return None

Rate Limits

Source	Limit	Notes
UK Companies House	600 req/5min	Free API key required
US SEC EDGAR	No strict limit	User-agent based
EU VIES	No limit	Service can be slow

Next Steps

Complete endpoint documentation

Find businesses to enrich

Verify contact emails

Chain multiple jobs together

Company Data Enrichment

Overview

Supported Data Sources

Quick Start

1. Search for a Company

2. Look Up by Registration Number

3. Validate EU VAT Numbers

Response Data

Search Results (Real Example)

Lookup Result (Real Example)

Field Descriptions

Integration Examples

Enrich Leads from SpiderMaps

Validate VAT for EU Invoices

Best Practices

Caching

Error Handling

VIES Service Reliability

Rate Limits

Next Steps

API Reference

SpiderMaps

Email Verification

Orchestrated Campaigns

Overview​

Supported Data Sources​

Quick Start​

1. Search for a Company​

2. Look Up by Registration Number​

3. Validate EU VAT Numbers​

Response Data​

Search Results (Real Example)​

Lookup Result (Real Example)​

Field Descriptions​

Integration Examples​

Enrich Leads from SpiderMaps​

Validate VAT for EU Invoices​

Best Practices​

Caching​

Error Handling​

VIES Service Reliability​

Rate Limits​

Next Steps​

API Reference

SpiderMaps

Email Verification

Orchestrated Campaigns

Overview

Supported Data Sources

Quick Start

1. Search for a Company

2. Look Up by Registration Number

3. Validate EU VAT Numbers

Response Data

Search Results (Real Example)

Lookup Result (Real Example)

Field Descriptions

Integration Examples

Enrich Leads from SpiderMaps

Validate VAT for EU Invoices

Best Practices

Caching

Error Handling

VIES Service Reliability

Rate Limits

Next Steps