Company Research — SpiderIQ

POST/api/v1/company-research/submit

Submit company research job

Submit a new company research job with Celery workflow orchestration.

## Input Types

locations: List of locations to search (triggers SpiderMaps discovery)
domains: List of domains to research directly (skips SpiderMaps)

## Pipeline Stages

SpiderMaps - Business discovery from Google Maps
SpiderSite - Website crawling for contacts
SpiderCompanyData - Company registry enrichment (US/UK/EU)
Social Enrichment - Instagram, Facebook, LinkedIn
SpiderVerify - Email verification

## SpiderCompanyData Configuration

    {
      "config": {
        "spidercompanydata": {
          "enabled": true,
          "countries_filter": ["US", "GB"],
          "include_officers": true,
          "include_financials": false
        }
      }
    }

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/company-research/submit' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "locations": [
    {
      "city": "string",
      "state": "string",
      "country": "string",
      "postal_code": "string",
      "address": "string"
    }
  ],
  "domains": [
    "string"
  ],
  "search_query": "string",
  "config": {
    "spidermaps": {
      "max_results": 100,
      "search_radius_km": 10.0,
      "include_place_details": true
    },
    "spidersite": {
      "enabled": true,
      "max_pages": 10,
      "crawl_strategy": "bestfirst",
      "target_pages": [
        "contact",
        "about",
        "team"
      ],
      "enable_spa": true,
      "spa_timeout": 30,
      "extract_team": false,
      "extract_company_info": true,
      "timeout": 30
    },
    "spidercompanydata": {
      "enabled": false,
      "countries_filter": {},
      "include_officers": false,
      "include_financials": false,
      "include_vat_validation": false,
      "match_threshold": 0.7,
      "timeout": 30
    },
    "social_enrichment": {
      "enabled": true,
      "instagram": true,
      "facebook": true,
      "linkedin": true,
      "timeout": 30
    },
    "spiderverify": {
      "enabled": true,
      "check_gravatar": false,
      "check_dnsbl": false,
      "smtp_timeout_secs": 45,
      "max_emails_per_company": 10
    },
    "domain_filter": {
      "filter_social_media": true,
      "filter_review_sites": true,
      "filter_directories": true,
      "custom_blacklist": [
        {}
      ]
    },
    "deduplication": true
  },
  "webhook_url": "string",
  "webhook_secret": "string",
  "priority": 5
}'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/company-research/submit",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"name": "string", "locations": [{"city": "string", "state": "string", "country": "string", "postal_code": "string", "address": "string"}], "domains": ["string"], "search_query": "string", "config": {"spidermaps": {"max_results": 100, "search_radius_km": 10.0, "include_place_details": true}, "spidersite": {"enabled": true, "max_pages": 10, "crawl_strategy": "bestfirst", "target_pages": ["contact", "about", "team"], "enable_spa": true, "spa_timeout": 30, "extract_team": false, "extract_company_info": true, "timeout": 30}, "spidercompanydata": {"enabled": false, "countries_filter": {}, "include_officers": false, "include_financials": false, "include_vat_validation": false, "match_threshold": 0.7, "timeout": 30}, "social_enrichment": {"enabled": true, "instagram": true, "facebook": true, "linkedin": true, "timeout": 30}, "spiderverify": {"enabled": true, "check_gravatar": false, "check_dnsbl": false, "smtp_timeout_secs": 45, "max_emails_per_company": 10}, "domain_filter": {"filter_social_media": true, "filter_review_sites": true, "filter_directories": true, "custom_blacklist": [{}]}, "deduplication": true}, "webhook_url": "string", "webhook_secret": "string", "priority": 5},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/company-research/submit", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"name": "string", "locations": [{"city": "string", "state": "string", "country": "string", "postal_code": "string", "address": "string"}], "domains": ["string"], "search_query": "string", "config": {"spidermaps": {"max_results": 100, "search_radius_km": 10.0, "include_place_details": true}, "spidersite": {"enabled": true, "max_pages": 10, "crawl_strategy": "bestfirst", "target_pages": ["contact", "about", "team"], "enable_spa": true, "spa_timeout": 30, "extract_team": false, "extract_company_info": true, "timeout": 30}, "spidercompanydata": {"enabled": false, "countries_filter": {}, "include_officers": false, "include_financials": false, "include_vat_validation": false, "match_threshold": 0.7, "timeout": 30}, "social_enrichment": {"enabled": true, "instagram": true, "facebook": true, "linkedin": true, "timeout": 30}, "spiderverify": {"enabled": true, "check_gravatar": false, "check_dnsbl": false, "smtp_timeout_secs": 45, "max_emails_per_company": 10}, "domain_filter": {"filter_social_media": true, "filter_review_sites": true, "filter_directories": true, "custom_blacklist": [{}]}, "deduplication": true}, "webhook_url": "string", "webhook_secret": "string", "priority": 5})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"name": "string", "locations": [{"city": "string", "state": "string", "country": "string", "postal_code": "string", "address": "string"}], "domains": ["string"], "search_query": "string", "config": {"spidermaps": {"max_results": 100, "search_radius_km": 10.0, "include_place_details": true}, "spidersite": {"enabled": true, "max_pages": 10, "crawl_strategy": "bestfirst", "target_pages": ["contact", "about", "team"], "enable_spa": true, "spa_timeout": 30, "extract_team": false, "extract_company_info": true, "timeout": 30}, "spidercompanydata": {"enabled": false, "countries_filter": {}, "include_officers": false, "include_financials": false, "include_vat_validation": false, "match_threshold": 0.7, "timeout": 30}, "social_enrichment": {"enabled": true, "instagram": true, "facebook": true, "linkedin": true, "timeout": 30}, "spiderverify": {"enabled": true, "check_gravatar": false, "check_dnsbl": false, "smtp_timeout_secs": 45, "max_emails_per_company": 10}, "domain_filter": {"filter_social_media": true, "filter_review_sites": true, "filter_directories": true, "custom_blacklist": [{}]}, "deduplication": true}, "webhook_url": "string", "webhook_secret": "string", "priority": 5}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/company-research/submit", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`201`	Successful Response
`422`	Validation Error

GET/api/v1/company-research/{research_id}/status

Get research job status

Get the current status and progress of a research job.

Parameters

Name	In	Type	Required	Description
`research_id`	path	string	true

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/company-research/{research_id}/status' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/company-research/{research_id}/status",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/company-research/{research_id}/status", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/company-research/{research_id}/status", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/company-research/{research_id}/results

Get research job results

Get the results of a completed research job.

Includes all discovered companies with:

Contact information (emails, phones)
Registry data (registration number, officers, financials)
Social media profiles (Instagram, Facebook, LinkedIn)
Company info extracted from website

Parameters

Name	In	Type	Required	Description
`research_id`	path	string	true
`include_registry_data`	query	boolean	false	Include SpiderCompanyData registry results

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/company-research/{research_id}/results' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/company-research/{research_id}/results",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/company-research/{research_id}/results", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/company-research/{research_id}/results", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/company-research/{research_id}/cancel

Cancel research job

Cancel a running or queued research job.

Parameters

Name	In	Type	Required	Description
`research_id`	path	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/company-research/{research_id}/cancel' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/company-research/{research_id}/cancel",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/company-research/{research_id}/cancel", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/company-research/{research_id}/cancel", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/company-research

List research jobs

List all research jobs for the current client.

Parameters

Name	In	Type	Required	Description
`status`	query	any	false	Filter by status: queued, processing, completed, failed, cancelled
`limit`	query	integer	false
`offset`	query	integer	false

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/company-research' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/company-research",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/company-research", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/company-research", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/company-research/{research_id}/pause

Pause research job

Pause a running research job.

The job will stop processing new companies but will complete any currently running tasks. Use /resume to continue.

Parameters

Name	In	Type	Required	Description
`research_id`	path	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/company-research/{research_id}/pause' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/company-research/{research_id}/pause",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/company-research/{research_id}/pause", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/company-research/{research_id}/pause", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/company-research/{research_id}/resume

Resume paused research job

Resume a paused research job and continue processing.

Parameters

Name	In	Type	Required	Description
`research_id`	path	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/company-research/{research_id}/resume' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/company-research/{research_id}/resume",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/company-research/{research_id}/resume", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/company-research/{research_id}/resume", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

PATCH/api/v1/company-research/{research_id}

Update research job configuration

Update configuration for a research job.

Allowed updates:

name: Job display name
config: Stage configurations (spidercompanydata, social_enrichment, etc.)
priority: Job priority (0-10)
auto_submit: Auto-submit settings

Parameters

Name	In	Type	Required	Description
`research_id`	path	string	true

Try it

Examples

cURL

curl -X PATCH 'https://spideriq.ai/api/v1/company-research/{research_id}' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "config": {
    "spidermaps": {
      "max_results": 100,
      "search_radius_km": 10.0,
      "include_place_details": true
    },
    "spidersite": {
      "enabled": true,
      "max_pages": 10,
      "crawl_strategy": "bestfirst",
      "target_pages": [
        "contact",
        "about",
        "team"
      ],
      "enable_spa": true,
      "spa_timeout": 30,
      "extract_team": false,
      "extract_company_info": true,
      "timeout": 30
    },
    "spidercompanydata": {
      "enabled": false,
      "countries_filter": {},
      "include_officers": false,
      "include_financials": false,
      "include_vat_validation": false,
      "match_threshold": 0.7,
      "timeout": 30
    },
    "social_enrichment": {
      "enabled": true,
      "instagram": true,
      "facebook": true,
      "linkedin": true,
      "timeout": 30
    },
    "spiderverify": {
      "enabled": true,
      "check_gravatar": false,
      "check_dnsbl": false,
      "smtp_timeout_secs": 45,
      "max_emails_per_company": 10
    },
    "domain_filter": {
      "filter_social_media": true,
      "filter_review_sites": true,
      "filter_directories": true,
      "custom_blacklist": [
        {}
      ]
    },
    "deduplication": true
  },
  "priority": 0,
  "webhook_url": "string",
  "webhook_secret": "string"
}'

Python

import httpx

resp = httpx.patch(
    "https://spideriq.ai/api/v1/company-research/{research_id}",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"name": "string", "config": {"spidermaps": {"max_results": 100, "search_radius_km": 10.0, "include_place_details": true}, "spidersite": {"enabled": true, "max_pages": 10, "crawl_strategy": "bestfirst", "target_pages": ["contact", "about", "team"], "enable_spa": true, "spa_timeout": 30, "extract_team": false, "extract_company_info": true, "timeout": 30}, "spidercompanydata": {"enabled": false, "countries_filter": {}, "include_officers": false, "include_financials": false, "include_vat_validation": false, "match_threshold": 0.7, "timeout": 30}, "social_enrichment": {"enabled": true, "instagram": true, "facebook": true, "linkedin": true, "timeout": 30}, "spiderverify": {"enabled": true, "check_gravatar": false, "check_dnsbl": false, "smtp_timeout_secs": 45, "max_emails_per_company": 10}, "domain_filter": {"filter_social_media": true, "filter_review_sites": true, "filter_directories": true, "custom_blacklist": [{}]}, "deduplication": true}, "priority": 0, "webhook_url": "string", "webhook_secret": "string"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/company-research/{research_id}", {
  method: "PATCH",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"name": "string", "config": {"spidermaps": {"max_results": 100, "search_radius_km": 10.0, "include_place_details": true}, "spidersite": {"enabled": true, "max_pages": 10, "crawl_strategy": "bestfirst", "target_pages": ["contact", "about", "team"], "enable_spa": true, "spa_timeout": 30, "extract_team": false, "extract_company_info": true, "timeout": 30}, "spidercompanydata": {"enabled": false, "countries_filter": {}, "include_officers": false, "include_financials": false, "include_vat_validation": false, "match_threshold": 0.7, "timeout": 30}, "social_enrichment": {"enabled": true, "instagram": true, "facebook": true, "linkedin": true, "timeout": 30}, "spiderverify": {"enabled": true, "check_gravatar": false, "check_dnsbl": false, "smtp_timeout_secs": 45, "max_emails_per_company": 10}, "domain_filter": {"filter_social_media": true, "filter_review_sites": true, "filter_directories": true, "custom_blacklist": [{}]}, "deduplication": true}, "priority": 0, "webhook_url": "string", "webhook_secret": "string"})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"name": "string", "config": {"spidermaps": {"max_results": 100, "search_radius_km": 10.0, "include_place_details": true}, "spidersite": {"enabled": true, "max_pages": 10, "crawl_strategy": "bestfirst", "target_pages": ["contact", "about", "team"], "enable_spa": true, "spa_timeout": 30, "extract_team": false, "extract_company_info": true, "timeout": 30}, "spidercompanydata": {"enabled": false, "countries_filter": {}, "include_officers": false, "include_financials": false, "include_vat_validation": false, "match_threshold": 0.7, "timeout": 30}, "social_enrichment": {"enabled": true, "instagram": true, "facebook": true, "linkedin": true, "timeout": 30}, "spiderverify": {"enabled": true, "check_gravatar": false, "check_dnsbl": false, "smtp_timeout_secs": 45, "max_emails_per_company": 10}, "domain_filter": {"filter_social_media": true, "filter_review_sites": true, "filter_directories": true, "custom_blacklist": [{}]}, "deduplication": true}, "priority": 0, "webhook_url": "string", "webhook_secret": "string"}`)
	req, _ := http.NewRequest("PATCH", "https://spideriq.ai/api/v1/company-research/{research_id}", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/company-research/{research_id}/wait

Wait for research job completion

Wait for research job to complete and return results.

This is a blocking endpoint that polls until:

Job completes (returns results)
Job fails (returns error)
Timeout reached (returns current status)

Parameters

Name	In	Type	Required	Description
`research_id`	path	string	true
`timeout`	query	integer	false	Timeout in seconds
`poll_interval`	query	integer	false	Poll interval in seconds

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/company-research/{research_id}/wait' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/company-research/{research_id}/wait",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/company-research/{research_id}/wait", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/company-research/{research_id}/wait", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error