ai.spideriq/leads

Cancel a pending or queued job.

Capture a landing page — screenshots, HTML bundle, and AI-extracted marketing content. Useful for competitive analysis, ad tracking, and archiving landing pages. This is a convenience wrapper for submit_job with type=spiderLanding.

Check the status of a PAT access request. Returns 'pending', 'active', 'denied', 'expired', or 'revoked' (matches the backend PATRequestStatus enum). Once status==='active', the token is saved to ~/.spideriq/credentials.json automatically. Multi-brand approvals save one entry per workspace under client_id, with the first aliased as 'default' so existing tools (upload_local_file, etc.) keep working without --workspace.

Research multiple companies in batch (max 50). Same pipeline as single but processes all companies in parallel. Returns job_id to poll.

Research a single company through the full intelligence pipeline: Perplexity discovery → website crawl → company registry → email verification → people/LinkedIn. Returns job_id to poll for results.

Resume a stopped or paused campaign.

Create a new multi-location scraping campaign. Campaigns orchestrate Google Maps searches across multiple locations with optional website scraping and email verification. The backend automatically selects the appropriate WindMill workflow: - Maps + Site + Verify: Full pipeline (default) - Maps + Site: Skip email verification - Maps only: Quick business search without site scraping Provide a search query, country code, and optionally a workflow config to control which steps run. SMARTLEAD EXPORT (push leads to an outreach campaign automatically): set workflow.smartlead = { enabled: true, connection_id, remote_campaign_id }. When enabled, the campaign's VERIFIED leads are pushed into that SmartLead campaign automatically when the run finishes (no separate push step). You MUST discover the two ids first: call list_outreach_connections (→ connection_id) then list_outreach_campaigns(connection_id) (→ remote_campaign_id). Those two tools live in the SpiderMail slice / kitchen-sink @spideriq/mcp. field_map is optional (backend defaults already map location + VayaPin pin_name). Only leads with a verified email are exported; set only_with_vayapin_seo:true to restrict to businesses that got a VayaPin SEO pin. SCOPING US ZIP CAMPAIGNS ("state = country"): the US is too large to scrape whole. To run a US ZIP campaign, scope it to ONE STATE: set filter = { mode: "regions", admin_regions: ["Texas"], include_postcodes: true }. Discover valid state names with list_regions(country_code="US") (or list_countries, which lists the 50 states as country-equivalent units). One state runs every ZIP in it as its own Maps search — list_regions returns each state's postcode_count so you can size it first. Scoping a postcode (ZIP) run to all of the US — or omitting the state — is rejected by the API (422, >10K location cap). Pick exactly one state per campaign.

Stitch AI-generated video scenes into a final video with transitions and music. Supports portrait (9:16) and landscape (16:9), fade transitions, background music, and SpiderMedia upload. This is a convenience wrapper for submit_job with type=spiderVideo.

Delete a campaign and all of its data. Irreversible. The campaign must be STOPPED first — this fails with a 409 if it still has active jobs. Call stop_campaign, wait for in-flight jobs to settle, then delete.

Get information about the SpiderIQ API and your connection.

Check if you are authenticated and get current user info.

Get detailed status and progress of a campaign. Returns: - Campaign configuration (query, country, workflow settings) - Progress: completed/failed/pending locations and percentage - Total businesses found - Which WindMill workflow is being used

Look up company data from public registries (US SEC EDGAR, UK Companies House, EU VIES VAT). Modes: - search: Search by company name (e.g., "Apple Inc" in US) - lookup: Look up by registry ID (e.g., CIK "0000320193" in US) - vat: Validate EU VAT number (e.g., "GB123456789") This is a convenience wrapper for submit_job with type=spiderCompanyData.

Get event stream status — service health, active subscriptions, and whether your client is currently connected.

Get the results of a completed job.

Get the current status of a job.

Get statistics about job queues (pending jobs, consumers, etc.).

Check if the SpiderIQ API is healthy and responsive.

Batch fetch up to 100 resources by their idap:// refs. Accepts an array of ref strings (e.g., "idap://businesses/uuid1", "idap://emails/uuid2"). Returns results keyed by ref, plus errors for missing/invalid refs. Efficient for board views or CRM sync — one call instead of N individual fetches.

🔴 DESTRUCTIVE — delete a business + cascade across per-tenant tables. IRREVERSIBLE. Hard-deletes the business row in norm_cli_<client>.businesses AND cascades to linked tables (pins, business_contacts, business_registry, company_registry, contacts, phones, domains, linkedin_profiles). Transactional — all-or-nothing. Audit row written to public.idap_deletions_audit in the same transaction. WHEN TO USE: - Surfacing a duplicate via idap_resolve_resource + manual review, then cleaning up the duplicate. - Tenant cleanup of stale/incorrect business records. - Cascading removal of contact/email/phone associations for a business. RECOMMENDED FLOW: 1. Resolve target with idap_resolve_resource (e.g. {resource_type: 'businesses', domain: 'example.com'}) → get the canonical business_id (UUID). 2. (Optional) idap_find_duplicates (D.1) to confirm this isn't unique-data destruction. 3. Call idap_delete_business with the resolved UUID + a short audit reason. ⚠️ DOES NOT TOUCH cs.vayapin.com. VayaPin pin pages are permanent per VayaPin §10. Response includes vayapin_pins_remain_external (boolean) + vayapin_pin_data_set_ids_orphaned (array). Tell the user about any remaining external URLs. ⚠️ DOES NOT CASCADE THE 'emails' TABLE. emails is a tenant-wide canonical store (UNIQUE on the email column) shared across businesses via business_contacts (M:N). Only the link row is removed; the email's verification metadata stays. Other businesses still reference the same email. WHAT AUTO-CASCADES (Postgres ON DELETE CASCADE): booking_flows, services — surfaced in response.auto_cascaded {table: count}. WHAT BLOCKS THE DELETE (returns 409 Conflict, never partial): bookings rows referencing this business or its contacts via ON DELETE NO ACTION FK. Response.detail.blocking_booking_ids lists up to 50 blocking IDs. Caller must re-point or delete those bookings before retrying. AUTH: Tenant-owner only — caller's client_id IS the tenant scope. No super-admin override in V1. Second DELETE on t…

Fetch a single resource from the client's normalized data store. Returns the resource data with active flags and optional related resources. Use field projection (`fields`) to reduce token usage. Use `include` to fetch related data in one call (e.g., a business + its emails and phones). Resource types: businesses, domains, contacts, emails, phones, company_registry, linkedin_profiles, media. Example ref format: idap://businesses/550e8400-e29b-41d4-a716-446655440000

Find duplicate resources sharing a common external key. Used in dedupe workflows before calling the (future) delete endpoint. Returns clusters where two or more resources share the same value for a whitelisted key. Each cluster has `count >= 2` (single-occurrence values are filtered out server-side). Whitelisted `key` values per `resource_type` (Wave D.1, 2026-05-24): - businesses → google_place_id, domain, phone_e164 (direct columns on businesses) vat, registration_number, lei, tax_id (joined via company_registry.business_id) Other resource types are not yet supported (returns 400 with the list of currently-supported types). Response shape: ``` { "resource_type": "businesses", "key": "google_place_id", "clusters": [ { "key_value": "ChIJ...", "count": 3, "resource_ids": ["uuid", "uuid", "uuid"] }, ... ], "total_clusters": N } ``` Default `limit` = 100; max = 500. Clusters are ordered by count DESC, then key_value ASC. Use this BEFORE the (forthcoming) DELETE endpoint to confirm which duplicates to remove.

List resources from the client's normalized data with filtering and cursor-based pagination. Supports incremental sync via `since` parameter — only returns resources modified after that timestamp. Use `flags` to filter (e.g., "qualified" for flagged-only, or "-rejected" to exclude rejected). Returns items array, cursor for next page, and has_more boolean.

Get the URL for an IDAP media resource (screenshot, photo, document). Returns a URL to the media proxy endpoint — does not return binary data. The URL supports: - ?thumb=true — 400px thumbnail - ?download=true — Content-Disposition: attachment - Conditional requests (If-None-Match, If-Modified-Since → 304) Use the URL in markdown, HTML, or pass it to other tools.

Resolve a single resource by external identifier instead of UUID. Use this when you have an external identifier (Google place_id, domain, email, VAT, LEI, etc.) and need the canonical IDAP record without first listing or searching. Accepted (resource_type, identifier) pairs — server enforces this allowlist: - businesses → place_id, domain pin_name, pin_data_set_id, account_id, pin_subscription_id (Wave D.1 — joined via pins.business_id) - domains → domain - emails → email - contacts → email, linkedin, twitter - linkedin_profiles → url - company_registry → vat, registration_number, lei, tax_id, source_id - pins → pin_name, pin_data_set_id, account_id, pin_subscription_id (IDAP PR 2) Wave D.1 (2026-05-24): the 4 VayaPin pin keys now also resolve a `businesses` row directly — the service joins through `pins.business_id` so you can look up a business by any of the pin identifiers without first resolving the pin and then the business. Exactly ONE identifier must be supplied — supplying two or zero returns a 400 envelope. Supplying an identifier that isn't valid for the resource_type returns a 400 envelope listing the allowed keys. Returns 404 if no row matches in the client's tenant scope. Added by IDAP PR 1 (2026-05-19); pins resource added by PR 2 (2026-05-24); businesses-by-pin-key joined lookup added by Wave D.1 (2026-05-24).

Full-text search within a resource type. Uses PostgreSQL tsvector for relevance-ranked results. Search fields vary by type: - businesses: name, address, category - domains: domain, title - contacts: name, email, title - emails: address - phones: phone_number Returns the same format as idap_list_resources.

Get aggregate statistics for a resource type. Returns total count, flag distribution (how many resources have each flag), source breakdown (which workers generated the data), and last-24h activity counts. Useful for dashboards, health checks, and understanding data coverage.

Add or remove flags on a resource. Flags are bidirectional metadata for lead qualification, workflow control, and agent coordination. Common flags: qualified, priority, rejected, do_not_contact, duplicate, reviewed, needs_enrichment. Behavioral flags: - "rejected" → excluded from default list responses - "do_not_contact" → respected by outreach workers - "duplicate" → triggers FuzzIQ merge Flags are idempotent (adding an existing flag is a no-op). Removes are soft-deletes (history preserved).

Find leads for a search query in a location. Full pipeline: Google Maps → website crawl → email verification → VayaPin profile. Returns job_id to poll for results via get_job_results.

List your campaigns with optional status filtering.

List available countries (with location counts) you can target with a campaign. To target the US by ZIP, pick a STATE instead (the US is too large to scrape whole) — use list_regions(country_code="US"), or list_selectable_units which returns the 50 US states as country-equivalent units alongside real countries.

List your submitted jobs with optional filtering.

List the admin regions (US states / provinces) of a country, each with its city_count and postcode_count. This is how you discover valid state names for a US ZIP campaign: pick ONE state, then create_campaign with filter { mode: "regions", admin_regions: [state], include_postcodes: true }. A state's postcode_count is roughly how many Maps searches the ZIP run fans out into.

List selectable geo units for a typeahead picker — countries plus, by default, the 50 US states as top-level "country-equivalent" units (so you target "Florida" the same way as "Germany"). Each unit has unit_id ("DE" or "US:Florida"), label, and kind ("country"|"state"). With states_as_units=true (default), "all of US" is intentionally NOT selectable (a US ZIP campaign must scope to one state). Set states_as_units=false to get plain countries (US as a whole) for non-ZIP use.

List all configured workspaces and their authentication status.

Remove stored authentication credentials.

Get the SpiderPR wire-distribution result for a job — provider order id, distribution status (queued|submitted|published|failed), published URL, and wire report URL. Convenience wrapper for get_job_results.

Submit a press release to the wire for distribution (SpiderPR). You author the release (title + body, plus optional summary/category/tags/contact); the job is dispatched to the SpiderPR wire worker, which renders it to wire-ready HTML, submits it to the provider, and polls until it is published. This is a convenience wrapper for submit_job with type=spiderPR. Poll get_job_results (or pr_get_result) for the {provider_order_id, status, published_url, wire_report_url}. Status flows queued → submitted → published (or failed).

Request access to SpiderIQ API. This sends an approval email to the admin. After calling this, use check_access_status to poll for approval. Once approved, the token is automatically saved for subsequent API calls.

Retry one location in a campaign (re-dispatches worker jobs). Use the location's `id` from list_campaign_jobs (campaign_locations.id), NOT the job_id. - retry_mode "full": re-run the whole workflow from SpiderMaps - retry_mode "site": keep Maps results, re-run SpiderSite + SpiderVerify - retry_mode "verify": keep Site results, re-run SpiderVerify only Max 3 retries per location.

Retry every failed location in a campaign (up to max_locations, default 10). Locations that already hit the 3-retry cap are skipped, not errored. Useful after a campaign finishes with some failed locations.

Scrape a website to extract contact information, social links, and content. This is a convenience wrapper for submit_job with type=spiderSite.

Search Google Maps for businesses. This is a convenience wrapper for submit_job with type=spiderMaps.

Search for people on LinkedIn — profile lookup, search, research, or company employee extraction. Modes: - profile: Get a single LinkedIn profile by URL - search: Search people by natural language query (e.g., "CTO fintech Israel") - research: Deep research on a LinkedIn profile - company: Extract employees from a LinkedIn company page This is a convenience wrapper for submit_job with type=spiderPeople.

Stop an active campaign. Can be resumed later with continue_campaign.

Submit a new scraping job to SpiderIQ. Available job types: - spiderSite: Scrape website content and extract contact info - spiderMaps: Search Google Maps for businesses - spiderMapsEnrich: Enrich Google Maps place with details - spiderVerify: Verify email addresses - spiderPeople: Find people information - spiderPhone: Extract phone-related data - spiderFacebookPage: Scrape Facebook pages - spiderPublicInstagram: Scrape public Instagram profiles - spiderPublicLinkedin: Scrape public LinkedIn profiles - spiderLanding: Capture landing page screenshots - spiderVideo: Generate video content - spiderMail: Send emails - spiderCompanyData: Research company information - spiderVayapin: VayaPin export - spiderSocial: Social Media Enrichment — recover a missing email/phone/website/socials for one business from its social handles Each job type requires different payload fields. See API documentation for details.

Recover a missing email / phone / real website / social links for ONE business from its public social handles (Social Media Enrichment). Given the business's known social handles (Facebook preferred, then Instagram) and optionally a single social-only website (linktr.ee / facebook / instagram URL), the job recovers whatever contact info it can and folds it in additively (never overwrites what you passed). If the business already has a usable email, the job self-skips (`has_email`) — recovery is only spent where it's needed. Requires the account's **Social Media Enrichment** plan to be enabled (entitlement-gated). Provide at least one social handle or a social-only website, or the job self-skips (`no_social_handle`). This is a convenience wrapper for submit_job with type=spiderSocial. Poll get_job_results for the recovered {email, phone, website, socials} — or the typed skip reason.

Create a VayaPin business profile from enriched data. Requires business basics (name, country, coordinates) and website content (markdown URL or direct content). This is a convenience wrapper for submit_job with type=spiderVayapin.

Subscribe to real-time job events (SSE). Opens a short-lived connection and returns a buffer of recent events. Event types: job.queued, job.started, job.completed, job.failed, connected.

Update a campaign's configuration. Workflow config changes are merged with existing settings. Use this to change the search query, max results, or toggle workflow steps (site scraping, email verification) on an active campaign.