Coresignal company, employee and job data

Coresignal is available through the shared REST, MCP and CLI catalog. The calling
agent chooses the dataset and queries, checks relevance and completeness, and
selects configurations. Scrappycoco does not score records or choose a comparison winner.

Inspect the live schemas and availability before execution:

scrappycoco catalog inspect company.search --json
scrappycoco catalog inspect employee.collect --json
scrappycoco catalog inspect jobs.preview --json

Company and employee datasets support base, clean, and multi_source.
Jobs support base and multi_source. base is the documented deterministic
default, not a quality judgment. IDs and native query fields are dataset-specific:
retain the same dataset when collecting search results.

Search options accept query_type: es_dsl (default), filter (base only), or
semantic (multi-source only). Semantic search is an explicitly selected
Coresignal endpoint; it does not move semantic judgment into Scrappycoco.
Preview supports es_dsl and base filter, not semantic search. The native
query body is passed unchanged. Inspect input_schema.properties.query for
base Elasticsearch examples and the x-native-query-guide search mapping link.
Search mappings differ from preview/collected output keys. Employee employer
fields are nested under experience; base company country is
headquarters_country_parsed; base job created ranges require
yyyy-MM-dd HH:mm:ss. Examples are advisory and do not restrict or rewrite
native queries. For other datasets/query types, follow the linked API overview.

Validate matching IDs with search before paid preview/collect when useful.
The integration currently meters ID search at zero credits; previews charge
per successful page, including empty pages. Zero matches do not prove that a
field is unsupported. Use the selected dataset's provider mapping to diagnose
queries, rather than repeating paid guesses.

Save this as request.json:

{
  "input": {"query": {"query": {"match_all": {}}}},
  "providers": ["coresignal_search"],
  "provider_options": {"coresignal_search": {"dataset": "base", "query_type": "es_dsl"}},
  "limit": 2
}

scrappycoco run company.search --file request.json --output company-ids.json --json

With --output, the CLI also saves the full response to
OUTPUT.REQUEST_ID.receipt.json and reports output.receipt_path. Keep it with
the request to inspect native errors and billing without executing again.
Retrieve an existing job if needed. Count distinct request IDs and sum only
finalized exact customer charges; missing receipts leave an incomplete total.

Use a task-specific native query instead of match_all for real work. Search
returns IDs, not complete company or employee profiles. Inspect native metadata,
then collect caller-selected IDs using the same dataset:

{
  "input": {"items": [{"id": 123}, {"id": 456}]},
  "providers": ["coresignal_collect"],
  "provider_options": {"coresignal_collect": {"dataset": "base"}}
}

For REST, add source and capability to the same request and send it to
POST /api/v1/scrapers/execute. For MCP use run_scraper with
scraper_id: company.collect and the same input/providers/provider_options.
When dataset or configuration choice is uncertain, use Discover with explicit
candidates and judge their separate evidence before finalizing exact options.

Pagination is caller-controlled. Pass search's returned cursor as input.after
with the same query and dataset. Preview uses input.page; native pagination
metadata reports next_page, total matches and its 1,000-record ceiling. A
preview is always partial. Complete returned pages and native records remain
available even if an upstream response exceeds the requested count. No result
is called complete merely because HTTP succeeded.

Bulk collection submits unique IDs once, preserves duplicate caller entries,
correlates by record ID (never position), downloads every returned file, and
reports missing/ambiguous results. It persists submission intent and job IDs.
Uncertain submissions are not replayed. Pending accepted jobs require
reconciliation; only persisted internal job state can resume downloads, so
clients cannot read other tenants' jobs by supplying a Coresignal request ID.

Configure CORESIGNAL_API_KEY on API and worker services. Optional
CORESIGNAL_TIMEOUT_S defaults to 60. Real-time employee lookup requires separate
account entitlement and CORESIGNAL_REALTIME_ENABLED=true; it is disabled by
default because the configured account returned HTTP 403, "You cannot consume
this service", during live validation. Migration 0046_coresignal_rates seeds the owner-confirmed $100 / 5,500 credits
($0.018181818181818182 per credit at ledger precision) for all paid capabilities,
effective only from migration activation. Owner-managed rates can replace it;
CORESIGNAL_CREDIT_COST_USD is an optional transport-level override. Apply the
migration before deploying API and workers.
Search IDs consume zero credits. Preview consumes 10 credits for base/clean or
20 for multi-source per successful page. Collection consumes 1 credit per job,
10 per base/clean company/employee, or 20 per multi-source company/employee.
Duplicate IDs submitted together are charged once. Successful malformed
responses retain usage evidence. Real-time employee requests consume 12 credits on success. Unknown rates stay
unresolved; shared account credit balances are not treated as per-request cost.

The real-time gate does not disable employee.search, employee.preview or
employee.collect; inspect each capability's own availability.

For sales evidence, the calling agent should collect relevant job status and
observation dates. application_active=0 or deleted=1 describes historical
recruitment, not current hiring; missing flags are unknown. Headline/history
conflicts remain unverified buyer roles. Recruitment and robotics spending are
signals to investigate, not proof of purchase intent or manual office processes.
These judgments remain in the calling client; the gateway preserves native data.

This integration covers data acquisition, not account management, persistent
employee webhook subscriptions, or a scheduler. Numeric IDs are the supported
cached collection input; use company website enrichment or real-time employee
URL lookup when those identifiers are available. Subscription entitlements and
provider freshness vary; configured availability does not prove live access.

Official references: API overview,
pagination,
preview,
bulk collection,
credits,
real-time employees.