Skip to main content
Talk to salesStart

Preview a discovery monitor

Sample a jobs or LinkedIn post search without saving a monitor, or count Job changes candidates before choosing a paid sample.

POST/api/sales-signals/discovery-monitors/preview
HTTP referenceScope (signals:read OR companies:read) AND (signals:read OR leads:read) AND (signals:read OR search:run) AND (signals:run OR companies:read) AND (signals:run OR leads:read) AND (signals:run OR search:run)Updated October 29, 2026

This page documents the canonical HTTP contract for this endpoint.

Developer keys need signals:read and signals:run, or the complete legacy combination of companies:read and leads:read and search:run. Signals scopes do not grant general CRM or Search access.

This reference describes the Signals discovery-monitor contract. Check the selected server’s capabilities and Signals catalog for supported sources, criteria, cadences and current billing. API availability does not enable monitoring or establish provider readiness, completed collection or delivered Signals.

Preview requires signals:read and signals:run, or the complete legacy combination of both CRM read scopes and search:run, including the free count: a count still searches the external source. It does not persist a monitor, schedule recurrence, add events to the Signals feed, or create CRM Leads.

Job openings and LinkedIn posts

Use the same source criteria as a saved monitor. LinkedIn posts accept keywordPhrases, combined into one quoted OR query, with shared industry and author-profile filters. Jobs/posts previews collect up to ten candidates before relevance qualification; fewer sample rows may be returned. They do not continue through the full search. Uncertain or unclassified candidates can be retained for review; inspect qualification status and warnings. Their sample size is separate from collection, which has no maxResults cap. Preview does not prove that all matching posts were collected. The previewMode count/sample choice applies only to Job changes.

Free Job changes count

For source=job_changes, previewMode=count returns previewOnly=true, items=[], candidateCount and zero provider credits used. matchedCount=0 is not the count result; read candidateCount. The count covers source role/date candidates before verified company/person filters. With multiple role searches, counts can overlap; honor countIsEstimate and the warnings. It is not a count of unique qualified Leads or guaranteed deliveries.

Explicit paid sample

Send previewMode=sample with a different request ID only after deciding to purchase a candidate. The sample cap is one regardless of the monitor draft’s maxCandidates. The current rate is at most 2 organization credits for one unlocked candidate; an empty purchase settles at zero. Read creditsUsed for the actual application charge. A purchased sample can be shown even if required company facts cannot all be verified; it is never added to the Signals feed. Read its qualification, whyMatched and warnings instead of assuming it qualifies.

{
  "name": "New sales leaders",
  "source": "job_changes",
  "criteria": {
    "departments": [
      "sales"
    ],
    "seniorities": [
      "vp"
    ],
    "industries": [
      "Software Development"
    ],
    "companySizes": [
      "51-100",
      "101-250"
    ],
    "companyCountries": [
      "US"
    ],
    "personCountries": [],
    "maxCandidates": null,
    "maxCreditsPerCheck": null
  },
  "frequency": "weekly",
  "enabled": true,
  "runNow": false,
  "requestId": "job-change-sample-example-1",
  "previewMode": "sample"
}

Read billing.sources.job_changes for the selected server’s enabled state, rate and policy. providerCreditsUsed describes source usage and is separate from the application’s creditsUsed.

A completed retry with the same request ID and source/criteria/frequency/mode returns the persisted preview. Changed inputs require a new explicit action. An in-flight or uncertain provider outcome returns 409; do not automatically start a new paid request to bypass it. Source capacity or availability can return 503.

Daily and weekly Job changes previews use source date windows based on one- and seven-day lookbacks. The source’s event date can differ; these are not exact rolling 24-hour occurrence guarantees. Jobs/posts previews are bounded samples and do not establish complete coverage.

Job monitor windows and employment types

For source=jobs, frequency=daily is the default and selects a past-day search; weekly selects the past seven days. The same window applies to preview, create, update and fresh scheduled checks. Omit the deprecated datePosted and linkedinDateRestrict inputs: they do not override monitor frequency.

Automatic routing can use Indeed, Google Jobs and LinkedIn when the other filters are compatible. Google Jobs uses its native posting-date filter. LinkedIn uses Scrappa’s Google-based search-date restriction, which is not an independently verified job-posting cutoff. Indeed checks returned posting dates before preview or delivery and excludes old, future, missing or unreadable dates; first-seen time never substitutes for posting time. Indeed requests date sorting unless another sort was saved, and still pages past old rows within bounded batches. Glassdoor has no supported lookback and is excluded from automatic date-window searches.

Omit jobType or use an empty string for Any job type. Current filters are part_time, contract, internship and remote. Legacy full_time/fulltime values are unrestricted. Paid continuation batches keep their saved search, date bounds and cursors; fresh checks use the current cadence. Selected-server deployment is separate from CLI 0.2.127 and these source-contract docs; inspect its catalog before relying on new behavior.

For source=fda, preview is free: it reads openFDA and returns counts and up to ten matching records from the last 35 days without identifying firms or saving anything.

For source=sec_filings, preview is free: it returns counts and up to ten matching filings from the last 7 days, read from the shared SEC store with every filter applied. Before the store's first refresh it searches EDGAR instead, and private raise counts are then estimates before vehicle, sector and amount filters.

Body parameters

  • namerequired

    string

    Required by the shared input model, 1–120 trimmed characters. A preview does not save this name.

  • sourcerequired

    string

    jobs, linkedin_posts, job_changes, fda, or sec_filings. The source is immutable after creation.

  • criteriarequired

    object

    Complete source-specific criteria. Read discovery.sources[].criteriaSchema from the Signals catalog; JobsCriteria, LinkedInPostsCriteria and JobChangesCriteria are expanded below.

  • frequency · optional

    string

    Jobs: daily (default) searches the past day; weekly searches the past seven days, using each source’s date semantics. Job changes: daily/weekly, default weekly. LinkedIn posts: hourly/daily/weekly polling, default daily, with no post lookback. FDA activity: weekly only (default), matching FDA's weekly publication. SEC filings: daily or weekly, default weekly; checks read the last 2 or 8 days.

  • maxResults · optional

    integer|null

    Deprecated legacy field, 1–50 when supplied. Ignored by collection; returned as null. Use criteria.maxCandidates for the Job changes candidate bound.

  • enabled · optional

    boolean

    Accepted by the shared input model; previews ignore this flag and never create a saved monitor or schedule.

  • runNow · optional

    boolean

    Defaults true. On create, enabled=true queues the initial asynchronous check; false saves for the next scheduled check. Preview never creates a monitor or schedule.

  • requestId · optional

    string

    Optional retry identity, 8–120 ASCII letters, digits, underscores or hyphens. Reuse only for the same explicit action and unchanged payload; a completed replay returns its saved result. A changed payload or an uncertain/in-flight preview can return 409.

  • previewMode · optional

    string

    Job changes: count (default) returns a free count; sample explicitly purchases at most one candidate for up to 2 app credits. Jobs/posts retain bounded provider acquisition; count does not make those sources a free count request.

Definitions

JobsCriteria

source=jobs. New clients can request automatic compatible-source selection. Existing manual provider lists remain supported.

Fields

  • providerSelection · optional

    string

    automatic is the default for new monitor authoring and derives every compatible source. Explicit manual mode preserves a selected provider list.

  • providers · optional

    array<string>

    Manual source list: indeed, google, linkedin or glassdoor; 1–4 unique sources. Omit for automatic routing. A supplied list cannot override the automatic plan. Date-window searches can use Indeed, Google Jobs and LinkedIn; other filters can narrow this further.

  • query · optional

    string

    Role/title query, 2–300 characters when nonempty. May be blank only with jobType=remote.

  • location · optional

    string

    Indeed location, at most 200 characters.

  • country · optional

    string

    Optional ISO-2 search market (Indeed) or localization (Google/LinkedIn), not employer HQ or worker eligibility. New automatic monitors default blank; legacy manual criteria can retain their saved market.

  • jobType · optional

    string

    Omit or use an empty string for Any job type. Current filters: part_time, contract, internship or remote (Indeed/Google). Legacy full_time/fulltime values normalize to unrestricted; they do not filter for full-time jobs. Remote-only acquisition retains explicit provider remote evidence.

  • radius · optional

    integer

    Indeed only, 0–100; radiusUnit is MILES (default) or KILOMETERS.

  • radiusUnit · optional

    string

    MILES or KILOMETERS; used with radius.

  • datePosted · optional

    string

    Deprecated compatibility input. New monitors derive today/week from daily/weekly frequency; this field cannot override that monitor window. Existing paid batches retain their saved search criteria. Omit in new requests.

  • sort · optional

    string

    Indeed only: blank, relevance or date. A required lookback uses date sorting unless an explicit sort was saved; posting dates are still checked after retrieval. Sorting is not proof of complete coverage.

  • language · optional

    string

    Optional two-letter lowercase language for Indeed/Google/LinkedIn.

  • linkedinDateRestrict · optional

    string

    Deprecated compatibility input. The lower-level LinkedIn search uses Google date restrictions such as d1/d7, but new monitors derive the restriction from daily/weekly frequency. Omit in monitor requests; search-result dates are not verified job-posting dates.

  • linkedinCountryRestriction · optional

    string

    LinkedIn only: country plus an ISO-2 country, for example countryUS.

  • linkedinLanguageRestriction · optional

    string

    LinkedIn only: lang_ plus a lowercase two-letter language, for example lang_en.

LinkedInPostsCriteria

criteria when source=linkedin_posts. Supply keywordPhrases for added literal terms, or keywords for a raw query. Unknown fields are rejected. All author filters apply to the same search.

Fields

  • keywordPhrases · optional

    array<string>

    1–10 literal post phrases, each at least 2 characters after normalization. Required unless keywords is supplied. Whitespace and surrounding quotes are normalized; blank entries are removed and phrases deduplicate without case. Embedded double quotes, backslashes and remaining non-printable characters are rejected. The compiled quoted OR query, including quotes and separators, must fit 300 characters. When supplied, this list determines keywords.

  • keywords · optional

    string

    Raw post-text query, 2–300 characters. Required unless keywordPhrases is supplied. Existing Boolean queries remain unchanged when keywordPhrases is omitted. With keywordPhrases, the server replaces this value with the compiled quoted OR query.

  • authorsIndustryId · optional

    string

    Canonical industry IDs from the industries lookup, comma-separated for multiple choices, for example 4 or 4,17. Filters the author’s employer industry. Defaults to an empty string with no industry restriction.

  • authorKeywords · optional

    string

    Optional author-profile search text, at most 300 characters. Applies to all post phrases in the query. Defaults to an empty string.

  • excludePromotions · optional

    boolean

    Exclude promotional posts during qualification. Defaults true.

JobChangesCriteria

criteria when source=job_changes. At least one nonempty roles, departments or seniorities list is required. Company filters alone cannot authorize an unrestricted search. Required company/person facts must be verified before delivery.

Fields

  • roles · optional

    array<string>

    0–10 optional role phrases of 2–150 characters. Each title is a query variant sharing the candidate allowance; title-free department/seniority queries are supported.

  • departments · optional

    array<string>

    Up to 12 supported values: marketing, sales, engineering, product, design, operations, finance, people, data, customer_success, growth, legal. Defaults [].

  • seniorities · optional

    array<string>

    Up to 7 values: founder, c_level, vp, director, head, lead, manager. Defaults [].

  • industries · optional

    array<string>

    Up to 20 canonical labels from the industries lookup, such as Software Development. Use labels, not numeric IDs. Defaults [].

  • companySizes · optional

    array<string>

    Any of 1-10, 11-50, 51-100, 101-250, 251-500, 501-1000, 1000-plus. The final band starts at 1,001 employees. Defaults [].

  • companyCountries · optional

    array<string>

    Up to 25 two-letter ISO country codes for the employer headquarters. Codes normalize to uppercase. Defaults [].

  • personCountries · optional

    array<string>

    Up to 25 two-letter ISO country codes for the person location, separate from Company HQ. Defaults [].

  • maxCandidates · optional

    integer | null

    Optional strict positive whole candidate cap. Omit or null collects all available candidates within organization credits. No fixed maximum of five.

  • maxCreditsPerCheck · optional

    integer | null

    Optional strict positive whole app-credit ceiling. Omit or null means no user-set ceiling. Collection also respects maxCandidates and an affordable allowance frozen from the organization balance; raw duplicates/invalid/excluded candidates consume that acquisition allowance.

FdaCriteria

criteria when source=fda. All fields are optional; each filter applies only to records that carry its field. Filters apply to FDA's own record fields; there is no relevance qualification.

Fields

  • activities · optional

    array<string>

    What to include. Medical devices: device_recalls, device_clearances (510(k)), pma_approvals, pma_supplements (incl. 30-day manufacturing-change notices), device_warning_letters. Drugs & biologics: drug_recalls, drug_approvals (original NDA/BLA), generic_approvals (original ANDA), drug_warning_letters. Food & supplements: food_recalls, food_warning_letters. Other: other_warning_letters. Defaults to device_recalls, device_clearances and device_warning_letters; at least one is required when sent. Legacy recalls and clearances map to device_recalls and device_clearances.

  • recallClasses · optional

    array<string>

    I, II and/or III. Defaults to I and II. Class I is the most serious. Applies to all recalls.

  • recallRootCauses · optional

    array<string>

    Device recalls only: design, manufacturing, supplier, labeling, undetermined or other, grouped from FDA's recorded root cause. Empty means all.

  • specialties · optional

    array<string>

    Device review panel codes such as CV (Cardiovascular), OR (Orthopedic) or RA (Radiology). Applies to 510(k) and PMA records; recall records carry no specialty. Empty means all.

  • letterViolations · optional

    array<string>

    Warning letters only: quality_system (21 CFR 820), drug_cgmp, food_safety, reporting (21 CFR 803, 806), unapproved_products or clinical_research, from the regulations each letter cites. Empty means all.

  • countries · optional

    array<string>

    ISO-2 countries of the firm's FDA address, at most 50. Empty means all countries. Drug approvals carry no address and never match a location filter.

  • usStates · optional

    array<string>

    Two-letter US states. When set, only US firms in those states match.

  • productKeywords · optional

    array<string>

    Up to ten terms of 2–80 characters; a record matches any term in its product, recall reason, root cause, device name or warning letter text.

SecCriteria

criteria when source=sec_filings. All fields are optional. Filters apply to EDGAR search facts and, for Form D, the filed offering details; there is no relevance qualification.

Fields

  • filingKinds · optional

    array<string>

    Which filings to include. Funding: funding_rounds (Form D private raises), public_offerings (8-K Item 3.02, 424B4/424B5), debt_financing (8-K Item 2.03), ipo_filings (S-1/F-1). Leadership & ownership: executive_changes (8-K Item 5.02), change_in_control (8-K Item 5.01), activist_stakes (Schedule 13D; the signal is on the target company). Deals: acquisitions (8-K Item 2.01), mergers_tender_offers (S-4/F-4, SC TO-T), material_agreements (8-K Item 1.01), terminated_agreements (8-K Item 1.02). Risk & distress: restructuring (8-K Item 2.05), cybersecurity_incidents (8-K Item 1.05), auditor_changes (8-K Item 4.01), delisting_notices (8-K Item 3.01). Other: earnings (8-K Item 2.02), other_events (8-K Item 8.01), annual_reports (10-K/20-F; best with filingKeywords). Defaults to funding_rounds, executive_changes and acquisitions. Amendments are excluded.

  • sectors · optional

    array<string>

    Sector keys such as software_it, biotech_pharma, medical_devices or banking_finance. Mapped to SIC codes for 8-K and S-1/F-1 filers and to the Form D industry group. Empty means all.

  • states · optional

    array<string>

    Two-letter US states of the filer's business address. Empty means all.

  • filingKeywords · optional

    array<string>

    Up to five EDGAR full-text search terms of 2–80 characters; a filing matches any term.

  • includeFunds · optional

    boolean

    Private raises only: also include funds and investment vehicles (pooled funds, SPVs, trusts, foundations, holding and single-property LLCs). Defaults false; vehicles are still collected.

  • minOfferingAmount · optional

    integer

    Form D only: minimum total offering amount in US dollars. Indefinite offerings do not pass a minimum.

Errors

StatusMeaning
401Missing or invalid authentication or organization/user context.
403The developer key lacks one or more listed scopes.
402Insufficient organization credits for the explicitly requested paid sample.
409Request ID conflicts, or a preview is active or has an uncertain provider outcome.
422Invalid source-specific criteria, cadence, request ID or preview mode.
503Source unavailable, capacity deferred, provider failure or unconfirmed sample credit receipt.

Docs