Submit SpiderCompanyData Job

POST/api/v1/jobs/spiderCompanyData/submit

Overview

SpiderCompanyData enriches company information from free public government registries. It supports searching by company name, looking up by registration number, and validating EU VAT numbers.

Supported Sources:

US SEC EDGAR - US publicly traded companies (~10,000)
UK Companies House - All UK registered companies (~5 million)
EU VIES - VAT validation for all EU member states

Request Body

payloadobjectrequired

Company lookup parameters

payload.modestringdefault: search

Operation mode: search, lookup, or vat

payload.namestring

Company name to search for. Required for search mode.

payload.countrystring

ISO country code (e.g., US, GB). Required for search and lookup modes.

payload.identifierstring

Registry ID (e.g., CIK number, company number). Required for lookup mode.

payload.vat_numberstring

EU VAT number with country prefix (e.g., DE123456789). Required for vat mode.

payload.limitintegerdefault: 10

Maximum number of results to return (1-100)

payload.testbooleandefault: false

Route job to test queue for development

priorityintegerdefault: 5

Job priority (0-10, higher = processed first)

Search by Company Name

Find companies by name in a specific country:

cURL
Python
JavaScript

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": "Apple",
      "country": "US",
      "limit": 10
    }
  }'

import requests

headers = {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json"
}

data = {
    "payload": {
        "mode": "search",
        "name": "Apple",
        "country": "US",
        "limit": 10
    }
}

response = requests.post(
    "https://spideriq.ai/api/v1/jobs/spiderCompanyData/submit",
    headers=headers,
    json=data
)

print(response.json())

const response = await fetch(
  'https://spideriq.ai/api/v1/jobs/spiderCompanyData/submit',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <your_token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      payload: {
        mode: 'search',
        name: 'Apple',
        country: 'US',
        limit: 10
      }
    })
  }
);

const data = await response.json();
console.log(data);

Lookup by Registration Number

Look up a specific company by its registry ID:

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": "lookup",
      "country": "GB",
      "identifier": "00445790"
    }
  }'

import requests

headers = {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json"
}

data = {
    "payload": {
        "mode": "lookup",
        "country": "GB",
        "identifier": "00445790"  # Tesco PLC
    }
}

response = requests.post(
    "https://spideriq.ai/api/v1/jobs/spiderCompanyData/submit",
    headers=headers,
    json=data
)

print(response.json())

VAT Number Validation

Validate an EU VAT number:

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": "vat",
      "vat_number": "DE123456789"
    }
  }'

import requests

headers = {
    "Authorization": "Bearer <your_token>",
    "Content-Type": "application/json"
}

data = {
    "payload": {
        "mode": "vat",
        "vat_number": "DE123456789"
    }
}

response = requests.post(
    "https://spideriq.ai/api/v1/jobs/spiderCompanyData/submit",
    headers=headers,
    json=data
)

print(response.json())

Response

Job Submitted Successfully

{
  "job_id": "55c68385-cade-45da-92c8-708c8c833d1d",
  "type": "spiderCompanyData",
  "status": "queued",
  "created_at": "2026-02-14T18:35:55.432143",
  "from_cache": false,
  "message": "Job submitted to TEST queue (local workers only)"
}

Completed Job Result (Search)

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"
      },
      "industry": null,
      "officers": [],
      "financials": null,
      "vat_number": null,
      "tax_id": null,
      "lei": null,
      "dissolution_date": null,
      "metadata": {
        "cached": false,
        "retrieved_at": "2026-02-14T18:35:56.457471",
        "data_freshness": "real-time",
        "confidence_score": 1,
        "cache_expires_at": null
      }
    },
    {
      "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
      }
    }
  ],
  "metadata": {
    "fuzziq_stats": {
      "processed": false
    }
  }
}

Completed Job Result (Lookup)

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,
      "cache_expires_at": null
    }
  },
  "metadata": {
    "fuzziq_stats": {
      "processed": false
    }
  }
}

tip

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

Completed Job Result (VAT Validation)

Real response from EU VIES for German VAT number "DE129273398" (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"
  },
  "metadata": {
    "fuzziq_stats": {
      "processed": false
    }
  }
}

note

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

Company Data Fields

Field	Description
`name`	Official company name
`source`	Data source (e.g., `uk_companies_house`, `us_sec_edgar`)
`source_id`	Registry-specific identifier
`country_code`	ISO 3166-1 alpha-2 country code
`status`	Company status (`active`, `dissolved`, `liquidation`)
`legal_form`	Legal entity type (plc, ltd, Inc, GmbH, etc.)
`registration_number`	Official registration number
`incorporation_date`	Date company was registered
`address`	Registered office address
`officers`	Directors and officers (UK only)

Supported Countries

Country	Source	Identifier Type
`US`	SEC EDGAR	CIK number
`GB`	Companies House	Company number (8 digits)
`EU` (all)	VIES	VAT number with country prefix

note

US SEC EDGAR only includes publicly traded companies. For private US companies, use other data sources.

Rate Limits

Cache TTL: 24 hours (repeated lookups use cache)
UK Companies House: 600 requests per 5 minutes
US SEC EDGAR: User-agent based, no strict limit
EU VIES: No rate limit (service can be intermittent)

Best Practices

tip

Use lookup mode when you have the ID. It's faster and more accurate than searching by name.

tip

Cache results client-side. Company registry data doesn't change frequently. The worker caches for 24h, but you can cache longer.

warning

VIES service availability. The EU VIES service can be intermittent. If validation fails, retry after a few seconds.

Overview​

Request Body​

Search by Company Name​

Lookup by Registration Number​

VAT Number Validation​

Response​

Job Submitted Successfully​

Completed Job Result (Search)​

Completed Job Result (Lookup)​

Completed Job Result (VAT Validation)​

Company Data Fields​

Supported Countries​

Rate Limits​

Best Practices​