--- title: "List the prospects one discovery run found (per-run view)." method: GET path: "/api/v1/discoveries/{jobId}/prospects" tags: ["discoveries"] --- # List the prospects one discovery run found (per-run view). `GET /api/v1/discoveries/{jobId}/prospects` ## Request - Base URL: `https://api.prosp.cc` - URL: `https://api.prosp.cc/api/v1/discoveries/{jobId}/prospects` - Auth: OAuth 2 (client credentials, token URL `https://prosp-mcp-641053169627.auth.eu-central-1.amazoncognito.com/oauth2/token`, scopes: `mcp/execute`) The discovery-scoped sub-resource: "what did **this** run find." Always a single job, returning its per-discovery rows (one per company↔job edge) — not de-duplicated against the caller's other jobs. Undelivered prospects only, unless `include_delivered=true`. Tenant-scoped by the token; the `jobId` never crosses tenants. This is the per-run equivalent of `GET /api/v1/prospects?job_id={jobId}`. For the de-duplicated view across all of the caller's discoveries, use `GET /api/v1/prospects` with no `job_id`. ## Query parameters - `limit` integer - `offset` integer - `include_delivered` boolean - `country` string ## Response `200` Customer-safe prospects for the job. - ProspectList: A page of discovered companies (customer-safe fields only). - `prospects` Prospect[], required: The discovered companies in this response. - `domain` string, required: The company's primary website domain. The stable identifier for the prospect. - `name` string, nullable: The company's name. - `description` string, nullable: Short description of what the company does. - `industry` string, nullable: The company's primary industry (coarse-grained). Free-text, but normalized from a canonical taxonomy: `fashion_retail`, `electronics_retail`, `grocery_retail`, `home_furniture`, `furniture_manufacturing`, `automotive`, `manufacturing`, `chemicals_materials`, `agriculture_food_production`, `logistics`, `b2b_services`, `technology_software`, `healthcare`, `financial_services`, `cosmetics_beauty`, `jewelry_accessories`, `hospitality_restaurant`, `energy`, `sporting_goods`, `recreation`, `education`, and the specialty-retail categories `florist_flowers`, `bakery_pastry`, `butcher_delicatessen`, `optician_eyewear`, `pharmacy_drugstore`, `pet_shop`, `toy_hobby`, `stationery_office_supplies`, `bookstore`, `garden_center`, `musical_instruments`, and `hardware_diy`. The list is not strict — a value outside it may occasionally be returned — so treat it as the expected vocabulary rather than a closed enum. - `employee_count` integer, nullable: Estimated number of employees. - `employee_count_source` 'official_registry' | 'public_knowledge_base' | 'professional_network' | 'web_research' | 'company_website' | 'unverified_estimate' | 'verified' | 'null', nullable: Authority band of `employee_count` — a source-agnostic label for the kind of source that won the precedence contest when the value was last written (`official_registry` > `public_knowledge_base` > `professional_network` > `web_research` > `company_website` > `unverified_estimate`, with `verified` an operator override). `official_registry` is an official government/company registry; `public_knowledge_base` is a public, structured, source-referenced knowledge base; `professional_network` is a public professional-network profile; `web_research` is a third-party OSINT figure researched from cited public sources; `company_website` is the company's own website; `unverified_estimate` is an UNVERIFIED third-party or model-derived estimate — nothing was measured, filed or self-declared, so treat it as the pipeline's best guess and NOT as a sourced figure. Surfaced customer-side so the freshness/authority of the headcount can be audited (provenance of a delivered fact) without naming any internal pipeline/vendor. Null when no source has been recorded. - `employee_count_as_of` string, date-time, nullable: ISO-8601 UTC timestamp of when `employee_count` was last written by a winning source (server-stamped). The freshness marker paired with `employee_count_source`. Null when no source has been recorded. - `size_certainty` 'verified' | 'estimated' | 'unknown': How much to trust company_size/employee_count: verified = official registry or declared; estimated = third-party or model estimate; unknown = no size. - `company_size` 'micro' | 'small' | 'medium' | 'large' | 'enterprise' | 'null', nullable: Company size bucket by employee headcount (lowercase; null when undetermined). `micro` (≤10 employees), `small` (≤50), `medium` (≤200), `large` (≤500), `enterprise` (500+). Uses the SAME lowercase tokens as the `company_sizes` INPUT filter (DiscoveryCriteria.company_sizes), so a value read off a result can be re-submitted verbatim as a filter without a 400. `micro` companies are returned by a `small` `company_sizes` filter. - `headquarters_location` string, nullable: Headquarters location as a "City, Country" string. - `country` string, nullable: The company's country. - `country_code` string, nullable: The company's country as an ISO-3166-1 alpha-2 code. - `city` string, nullable: The company's city. - `state` string, nullable: The company's state, province, or region. - `postal_code` string, nullable: The company's postal or ZIP code. - `street` string, nullable: The company's street address. - `street_romanized` string, nullable: Latin-script transliteration of `street`, for companies in non-Latin-script markets. - `contacts` Contact[]: People discovered at the company. - `name` string, nullable: The person's full name. - `email` string, nullable: The person's email address, where discovered. - `position` string, nullable: The person's job title or role. - `title` string, nullable: The person's job title or role, as surfaced during discovery (alternative source to `position`). - `phone` string, nullable: A direct phone number for the person. - `department` string, nullable: The department or function the person works in. - `organization` string, nullable: The organization or company the person is associated with. - `linkedin_url` string, nullable: The person's LinkedIn profile URL. - `instagram_url` string, nullable: The person's Instagram profile URL. - `facebook_url` string, nullable: The person's Facebook profile URL. - `twitter_url` string, nullable: The person's X (Twitter) profile URL. - `youtube_url` string, nullable: The person's YouTube channel URL. - `telegram_url` string, nullable: The person's Telegram contact URL. - `viber_url` string, nullable: The person's Viber contact URL. - `whatsapp_url` string, nullable: The person's WhatsApp click-to-chat URL. - `contact_address` string, nullable: The person's street address, where discovered. - `contact_city` string, nullable: The person's city. - `contact_country` string, nullable: The person's country. - `contact_country_code` string, nullable: The person's country as an ISO-3166-1 alpha-2 code. - `contact_region` string, nullable: The person's sub-country region (e.g. state or province). - `registry_source` string, nullable: The government registry this person was verified against, when applicable. - `email_source` string, nullable: Provenance of `email` when it was INFERRED rather than directly discovered. `derived_domain_pattern` = a name-coupled mailbox reconstructed from the company's own observed local-part convention (confidence ~0.5, never verified); `micro_company_generic_pairing` = a sole owner paired to the company's generic mailbox. Absent (null) for a crawled/verified email. Use it to weight an inferred address (which carries bounce risk) before outreach. - `is_officer` boolean: True when this person matches a statutory officer listed in a government registry. - `phones` string[]: Company phone numbers. - `company_emails` string[]: General company email addresses (e.g. info@, sales@), as opposed to a specific person's. - `city_romanized` string, nullable: Latin-script transliteration of city (non-Latin source markets). - `state_romanized` string, nullable: Latin-script transliteration of state (non-Latin source markets). - `linkedin_url` string, nullable: The company's LinkedIn page URL. - `instagram_url` string, nullable: The company's Instagram profile URL. - `facebook_url` string, nullable: The company's Facebook page URL. - `twitter_url` string, nullable: The company's X (Twitter) profile URL. - `youtube_url` string, nullable: The company's YouTube channel URL. - `telegram_url` string, nullable: The company's Telegram channel or click-to-chat URL. - `viber_url` string, nullable: The company's Viber click-to-chat URL. - `whatsapp_url` string, nullable: The company's WhatsApp click-to-chat URL. - `weibo_url` string, nullable: The company's Weibo profile URL. - `douyin_url` string, nullable: The company's Douyin (Chinese TikTok) profile URL. - `wechat_id` string, nullable: WeChat account ID (WeChat has no public profile URL). - `qq_id` string, nullable: QQ account ID (QQ has no public profile URL). - `business_model` 'manufacturer' | 'retailer' | 'distributor' | 'service_provider' | 'unknown' | 'null', nullable: The company's classified business model — `manufacturer`, `retailer`, `distributor`, or `unknown`. Null when not classified. - `estimated_annual_revenue_usd` integer, nullable: Estimated annual revenue in whole USD dollars, derived from a model (based on employee count). Null when undetermined — never a fabricated zero. - `estimated_revenue_currency` string, nullable: ISO-4217 alpha-3 currency for the revenue estimate (currently always USD). - `founded_year` integer, nullable: Year the company was founded (company-maturity signal). Null when unknown. - `reported_revenue_usd` integer, nullable: Reported annual revenue in whole USD dollars, sourced from public company financials (distinct from the model-based `estimated_annual_revenue_usd`). Null when not reported. - `funding_total_usd` integer, nullable: Total capital raised to date in whole USD dollars, from public company financials. Null when not reported. - `funding_latest_round` object, nullable: Latest funding round (round name/type, date, amount, currency). Returned as a decoded object — the API decodes the stored JSON for you at the boundary, so do NOT decode a second time. The key set comes from the financial source and is not closed: read the keys you need and ignore the rest. Often null. - `web_traffic` object, nullable: Website-traffic snapshot. Returned as a decoded object — the API decodes the stored JSON for you at the boundary, so do NOT decode a second time. The properties below are the ones commonly present; the key set comes from the traffic source and is not closed, so read the keys you need and ignore the rest. Often null. - `visitsMonthly` number, nullable: Visits in the most recent complete month. - `countryRank` number, nullable: Traffic rank of the site within its own country (lower is busier). - `avgDurationSeconds` number, nullable: Average visit duration in seconds. - `history` object[], nullable: Month-by-month visit history, oldest period first. - `value` number, nullable: Visits in that period. - `dateFrom` string, nullable: Start of the period, `YYYY-MM`. - `dateTo` string, nullable: End of the period, `YYYY-MM`. - `hq_address` string, nullable: Full one-line formatted headquarters address (companion to city/country/postal). - `logo_url` string, uri, nullable: Company logo/image URL. - `source_published_date` string, nullable: Publication date of the web source this prospect was surfaced from (per-source freshness). - `source_last_updated` string, nullable: Last-updated date of the web source this prospect was surfaced from (per-source freshness). - `registry_id` string, nullable: The company's government registry identifier (e.g. IČO, HRB, KRS), where matched. - `registry_source` string, nullable: Which government registry `registry_id` came from. - `lei` string, nullable: Legal Entity Identifier (ISO 17442), where the company is present in the GLEIF register. Null otherwise. - `uscc` string, nullable: Chinese Unified Social Credit Code. Populated only for Chinese companies. Null otherwise. - `social_profiles` object[], nullable: Per-platform public social profiles discovered for the company, beyond the singular per-platform `*_url` fields (which carry only the headline platform). One entry per platform, returned as decoded objects — the API decodes the stored JSON for you at the boundary, so do NOT decode a second time. - `platform` string, required: Which public platform this entry is from, and the provenance for the rest of the entry's fields (e.g. `linkedin`, `youtube`, `twitter`, `instagram`). - `url` string, required: The public profile URL on that platform. - `follower_count` integer, nullable: Audience size on that platform (followers, or subscribers on video platforms). Null when the profile published no count. - `description` string, nullable: The company's own business summary as published on that platform, verbatim. Null when the profile published none. - `legal_name` string, nullable: Registered legal-entity name CANDIDATE taken from that profile's own title or summary. A candidate only — it never overrides the company name. Null when the profile published no distinct legal name. - `extra_links` string[], nullable: External links the profile itself lists (subsidiary, other-market or store domains). Null for platforms that publish no such block. - `employer_reputation_tier` 'strong' | 'mixed' | 'limited' | 'null', nullable: Coarse, un-attributed employer-reputation band — `strong`, `mixed`, or `limited`. A derived legitimacy/size-corroboration signal; NOT a third-party review platform's verbatim rating (which is never returned) and carrying NO source name. Null when no reputation signal is available. - `beian_number` string, nullable: China MIIT web-filing number (beian = the ICP备案 recordal, e.g. 湘ICP备17001547号) mined from the site footer. A MIIT-registered-commercial-site provenance signal — NOT a corporate registry id (registry_source is set to 'MIIT-BEIAN' when present). - `footer_legal_name` string, nullable: Market-agnostic registered legal-name candidate anchored in the page footer / legal-notice region. Two producers today: the CN beian (ICP备案)/copyright footer (Chinese …有限公司 or English … LIMITED/LTD) and the DE/AT §5 TMG Impressum legal name (…GmbH/AG). Verbatim — never translated. A candidate that never overwrites company_name. Which producer supplied it is on footer_legal_name_source. - `footer_legal_name_source` 'beian' | 'impressum' | 'copyright' | 'null', nullable: Where `footer_legal_name` was taken from — `beian` (Chinese MIIT web-filing footer), `impressum` (German/Austrian legal-notice footer), or `copyright` (a plain copyright line). Null when `footer_legal_name` is null. - `social_description` string, nullable: Business summary harvested from the prospect's public social profile page (no login). Winning-platform priority LinkedIn > YouTube > Twitter; the source platform is on social_source. - `social_follower_count` integer, nullable: Audience-size traction proxy from the winning social profile — LinkedIn follower count OR YouTube subscriber count (which one is on social_source). - `social_legal_name` string, nullable: Registered legal-entity name candidate from a social profile's og:title / og:description (never overwrites company_name; names never translated). - `social_source` 'linkedin' | 'youtube' | 'twitter' | 'null', nullable: Which public social profile the social intel above came from — `linkedin`, `youtube`, or `twitter`. Null when no social profile was found. - `social_extra_links` string[], nullable: YouTube channel About-tab external links (subsidiary / other-market / store domains). A YouTube-only signal. - `nace_code` string, nullable: The company's NACE industry-classification code, from its registry entry where available. - `legal_form` string, nullable: The company's legal form (e.g. GmbH, s.r.o., Ltd), from its registry entry where available. - `officers` string[], nullable: Names of the company's statutory officers, from its government registry entry where available. - `registration_date` string, nullable: Date the company was registered, from its registry entry where available. - `discovered_at` string, date-time, nullable: When this company was first discovered for you (ISO-8601). - `detected_language` string, nullable: ISO-639-1 language detected for the company's content. - `vat_id` string, nullable: VAT/tax identifier where available. - `detected_industry` string, nullable: Finer-grained detected industry (companion to the coarse `industry`). Drawn from the same canonical taxonomy listed under `industry` — including the specialty-retail categories (`florist_flowers`, `bakery_pastry`, `butcher_delicatessen`, `optician_eyewear`, `pharmacy_drugstore`, `pet_shop`, `toy_hobby`, `stationery_office_supplies`, `bookstore`, `garden_center`, `musical_instruments`, `hardware_diy`) — and likewise not a strict closed set. - `company_status` string, nullable: The company's operational status, where a government registry reports it (e.g. `active`, `liquidated`, `dissolved`). Free-text — not a fixed set. - `has_wikipedia_article` boolean, nullable: Notability / enterprise signal — a Wikipedia article was found. - `domain_age_days` integer, nullable: Age of the registered domain in days — company maturity/stability signal. - `branch_regions` string[], nullable: Registry-authoritative ISO-3166-2 branch-office regions (multi-location footprint). - `sub_country_region` string, nullable: The ISO-3166-2 sub-country region (e.g. `ES-VC`, `DE-BY`) the company's own headquarters geography places it in — resolved from its stored `state`, `city` and `postal_code`, so it can be checked against the address on the same record. It is the region a `sub_country_regions` discovery filter is matched against. Null when that geography does not resolve to a region; it is cleared again if a later correction to the address stops supporting it. A single HQ region, distinct from `branch_regions`. - `certifications` string[], nullable: Quality/compliance certifications the company publicly claims (e.g. ISO 9001:2015, IATF 16949, IPC-A-610, RoHS, REACH), extracted from the company's public web presence. - `customer_count` integer, nullable: Self-reported count of customers/clients served — a traction proxy (distinct from employee_count). - `export_markets` object, nullable: Export / market-distribution snapshot. Returned as a decoded object — the API decodes the stored JSON for you at the boundary, so do NOT decode a second time. Two shapes are emitted depending on what the source disclosed: `{"regions":{"Europe":48,...}}` (share per region) or `{"export_share_pct":80,"regions":[...]}` (headline share plus a region list). The key set is not closed. Often null. - `production_capacity` string, nullable: Manufacturing-capacity snapshot (e.g. "30,000 sq.m; 3,000 part numbers; 10+ SMT lines") — a capability signal for manufacturing/EMS prospects. - `served_industries` string[], nullable: Verticals/end-markets the company states it serves — a multi-value companion to detected_industry. - `branch_footprint` string[], nullable: Multi-site branch/office city names the company publicly lists (GeoNames-gated) — a human-readable companion to the ISO-3166-2 branch_regions. - `events` object[], nullable: Trade fairs, conferences and similar events the company itself publicly lists taking part in, within the last 24 months or the next 12 (at most 2, the ones closest to today). Each entry was verified against a quote on the company's own site; `source_url` is that page. Null when none is on record. - `name` string: The event's name as the company writes it. - `start_date` string: ISO yyyy-MM-dd start date. - `city` string, nullable: City the event takes place in. - `role` 'EXHIBITOR' | 'SPEAKER' | 'SPONSOR' | 'AWARD_WINNER' | 'ORGANISER' | 'OTHER' | 'PARTNER' | 'null', nullable: The company's role at the event. - `kind` 'TRADE_FAIR' | 'CONFERENCE' | 'SUMMIT' | 'WEBINAR' | 'AWARD_CEREMONY' | 'SHAREHOLDER_MEETING' | 'OWN_EVENT' | 'OTHER' | 'null', nullable: What kind of event it is (a trade fair, a conference or a summit survive the extractor's filter). - `source_url` string, nullable: The company page the participation was read from. - `origin_country` string, nullable: The company's inferred country of origin, as an ISO-3166-1 alpha-2 code. Helps distinguish a headquarters from a local subsidiary. - `facts` object[]: Extracted business facts about the company — leadership, products/services, market positioning, history, and certifications — each as a short natural-language statement WITH provenance (origin + when it was extracted) for SDR briefing. Present on every prospect; an empty array when no facts are available. Capped per prospect to keep the response bounded. - `text` string, required: The business fact, as a short natural-language statement. - `source` 'web' | 'wikidata' | 'wikipedia', required: Origin the fact was derived from — `web` (extracted from the company's public web content), `wikidata` (a structured Wikidata claim), or `wikipedia` (the resolved Wikipedia article). - `source_url` string, uri, nullable: Stable click-through link to the company HOMEPAGE — the entry point to the company's public web content. This is NOT necessarily the exact sub-page the fact was extracted from; the exact per-page source URL is not retained, so this field is the company homepage rather than an overclaimed extraction URL. - `extracted_at` string, date-time, nullable: ISO-8601 timestamp of when the fact was extracted. - `first_party` boolean: `true` when the fact is VERIFIED to come from the company's OWN web presence — a citation whose registrable (eTLD+1) domain equals the prospect's. `false` means "not verified as first-party", which covers TWO different situations and is never a positive claim of third-party origin: the fact was mined from a third-party page (a directory, aggregator, news site or filing, and note Wikipedia/Wikidata count as third-party here however well their entity was resolved), OR its provenance cannot be established because no citation host was ever stored for it. The second case is not marginal — MEASURED on the production corpus, 46% of facts carry no stored citation host at all; they are legacy points and the inspectable sample was model-derived rather than site-derived. A consumer must therefore read `false` as "unconfirmed", not as "independently sourced". Why it is customer-visible: a first-party claim is the company describing itself, while a third-party claim is someone else describing it, and an SDR should weigh a self-description differently from an independent one before quoting it. Third-party facts also carry the residual entity-confusion risk that first-party facts cannot: DNS ownership is collision-free, whereas a shared brand token, ticker or surname is not. Off-domain facts pass an entity-identity check, but that check can let a fact through when it is unavailable — which is exactly why the customer still gets to see the distinction. ABSENCE IS NOT `false`. The key is omitted on facts stored before it was introduced, and such a fact's provenance is UNKNOWN, not third-party — a consumer that defaults a missing value to `false` will silently mislabel every It is therefore deliberately NOT in `required`. - `knowledge_graph` unknown[], nullable: Extracted knowledge-graph facts about the company (relationship triples). Returned only by the detail endpoint (`GET /api/v1/prospects/{domain}`). - unknown - `knowledge_graph_grouped` object, nullable: The same knowledge-graph facts, grouped by relationship type for convenience. Returned only by the detail endpoint. - `pages` unknown[], nullable: References to the company web pages that were read during discovery. Returned only by the detail endpoint. - unknown - `semantic_score` number, nullable: Relevance score for this company against the search query. Returned only by the search endpoint (`GET /api/v1/prospects/search`). - `total` integer: PAGINATION count — the number of prospects returned in THIS list response. This is a LIST result-set count over your de-duplicated inbox (optionally scoped by `job_id`), a DIFFERENT concept from a single discovery's delivery count (`JobResult.total_prospects` / `JobStatus.total_prospects`) — do not group the two together. Named `total` to match the sibling search list (`ProspectSummaryList.total`); note that sibling counts total MATCHES (which can exceed the page), whereas this one counts the rows in this page. - `customer_id` string: The authenticated tenant these prospects belong to. - `suggestions` Suggestion[]: On the per-run view (`GET /api/v1/discoveries/{jobId}/prospects`), the same data-driven next-step recommendation(s) `JobResult.suggestions` carries — present only when the run underperformed. Empty on successful runs and on the de-duplicated `GET /api/v1/prospects` list. - `code` 'WIDEN_LOCATION' | 'ALLOW_LARGER_SIZE' | 'ALLOW_SMALLER_SIZE' | 'BROADEN_QUERY' | 'LIMITED_MARKET_DATA' | 'LOWER_TARGET' | 'icp_realignment' | 'TRANSIENT_INTERRUPTION' | 'PIPELINE_LIMITED' | 'ALREADY_DELIVERED' | 'FILTER_RELAXED' | 'REGION_PREFERENCE_APPLIED', required: Bounded code (NOT a rejection reason). The first seven values are advice codes; `FILTER_RELAXED` is a mandatory relaxation disclosure, `TRANSIENT_INTERRUPTION` advises a plain re-run after an infra stall, `PIPELINE_LIMITED` and `ALREADY_DELIVERED` are honest non-actionable outcomes that deliberately carry NO broadening advice, and `REGION_PREFERENCE_APPLIED` is an informational note that a `sub_country_regions` preference shaped this run. - `message` string, required: Customer-safe, human-readable recommendation or disclosure. Contains no internal rejection reasons or funnel counts. - `suggested_parameters` SuggestedCriteria: A partial `DiscoveryCriteria` delta. Merge it over your original request (the delta wins) and start a new discovery. Every field is optional; only the changed values are present. An empty array (e.g. `sub_country_regions: []`) explicitly clears that field. When the run under-delivered, an LLM improvement pass may also rewrite the free-text `query` itself — when present, `query` REPLACES your original `query` verbatim (it is not merged token-wise); apply it alongside the other fields to re-run the improved ICP. - `query` string: LLM-rewritten replacement for the free-text `query`, refined from this run's outcome to surface more matching companies. Present only when the improvement pass produced a better query; use it as-is in place of your original `query` on the re-run. - `locations` string[]: Suggested replacement for `locations` (e.g. a wider set of countries). - `company_sizes` string[]: Suggested replacement for `company_sizes`. - `sub_country_regions` string[]: Suggested replacement for `sub_country_regions`. An empty array clears the field. - `industries` string[]: Suggested replacement for `industries`. - `keywords` string[]: Suggested replacement for `keywords`. - `maxResults` integer: Suggested replacement for `maxResults`. ## Other responses - `400`: Malformed request (missing/invalid field or header). - `401`: Missing/invalid/expired Bearer token. - `405`: HTTP method not allowed on this endpoint (rejected before any credit debit). - `429`: Rate limit exceeded (100 requests / 60s per customer). --- [API](https://skmtc.dev/prosp/apis/prosp-discovery-api.md) · [All operations](https://skmtc.dev/prosp/apis/prosp-discovery-api/llms.txt) · [OpenAPI document](https://skmtc.dev/prosp/apis/prosp-discovery-api/revisions/1f2e0c55da22?raw)