Contract & Grant Fit Scout

Turn a company profile into a ranked shortlist of live public opportunities.

The Actor scans official US and UK sources, cheaply screens every notice, then uses AI only on the strongest candidates. Each returned match includes the deadline, value, buyer or agency, risks, next steps, and short evidence excerpts so a user can decide what deserves human attention.

Why buyers use it

• Stop reading dozens of irrelevant notices.
• Find newly published work on a schedule.
• Explain why an opportunity fits instead of returning keyword-only search results.
• Surface disqualifiers and uncertainty before a team spends hours on a bid.
• Export the result to JSON, CSV, Excel, Zapier, Make, or the Apify API.

This is a qualification tool, not an automated bid writer. It deliberately links back to the original notice for final verification.

Official sources

• Grants.gov search API and opportunity-detail API for US federal grants. These retrieval endpoints do not require a customer API key.
• UK Contracts Finder OCDS API for current UK public-sector tender notices. Public retrieval does not require a customer account.

SAM.gov is intentionally not included in version 1 because its API requires each user to protect a private SAM.gov API key. It can be added later as an optional source without weakening the current no-extra-key setup.

How it works

1. The user describes their organization and supplies a few search terms.
2. The Actor retrieves live notices from the selected official sources.
3. A deterministic scorer ranks phrase matches, company-profile overlap, exclusions, deadline timing, notice status, and available value.
4. Only the top maxAiAnalyses candidates go to the hosted AI reviewer.
5. The reviewer must return strict JSON, cite evidence from the notice, and list uncertainty and risks.
6. Only results at or above minScore are stored. Automatic-exclusion terms always win.
7. In pay-per-event mode, the Actor charges the qualified-opportunity event only when that result is pushed to the dataset.

This two-stage design keeps model usage controlled and prevents a customer from paying the result fee for rejected notices.

Inputs

The generated Apify form is suitable for nontechnical users. The most important fields are:

Field	Purpose	Good starting value
companyProfile	Capabilities, customers, regions, credentials, and exclusions	1–3 specific paragraphs
searchKeywords	Services, industries, or problems to find	3–8 phrases
positiveKeywords	Signals that improve fit	Certifications, buyer types, delivery models
negativeKeywords	Hard exclusions	Work the company cannot or will not perform
minScore	Strictness of returned results	60
maxAiAnalyses	Maximum candidates receiving AI review	10
maxResultsPerSource	Source candidates retained for scoring	25
daysBack	Newly published UK tender window	14

See examples/INPUT.json for a complete sample.

Output

Every dataset item is one qualified opportunity:

{
  "rank": 1,
  "fitScore": 84.5,
  "verdict": "STRONG",
  "title": "Example data platform opportunity",
  "source": "UK Contracts Finder",
  "organization": "Example public buyer",
  "deadline": "2026-09-14T11:00:00+01:00",
  "value": 125000,
  "currency": "GBP",
  "summary": "The requested data integration and training align with the supplied profile.",
  "matchedCapabilities": ["Data integration", "Training"],
  "risks": ["The notice does not confirm required security accreditation."],
  "nextSteps": ["Verify accreditation requirements in the tender documents."],
  "evidence": [
    {"claim": "Training is in scope", "sourceText": "provide user training"}
  ],
  "url": "https://www.contractsfinder.service.gov.uk/Notice/example"
}

The default dataset offers a compact “Best matches” view and a detailed “Qualification detail” view. A RUN_SUMMARY record reports fetched, scored, qualified, stored, and failed-source counts.

AI and privacy

AI review uses the Apify OpenRouter integration. On the Apify platform, the Actor receives APIFY_TOKEN automatically, so users do not paste an OpenAI or OpenRouter key into the input.

The company profile and selected opportunity text are sent through that hosted gateway to the selected model provider. Do not put passwords, private keys, personal records, export-controlled data, or confidential bid strategy in the profile. Source notices are treated as untrusted data; their text cannot change the review instructions.

Set includeAiAnalysis to false for deterministic-only screening. That mode is cheaper but less nuanced.

Accuracy boundaries

• A high score is not proof of eligibility or a prediction of winning.
• Dates, values, and requirements can be amended at the source.
• Currency values are not converted; a single numeric floor is applied to the source currency.
• Grants.gov search results are limited by the supplied terms and official API behavior.
• Contracts Finder provides date/stage filtering but no text query on its public OCDS search endpoint, so the Actor retrieves a wider recent set and filters it locally.
• A missing published value is retained rather than incorrectly treated as zero.
• Always read the original notice and attached documents before bidding or applying.

Run locally

Python 3.11 or newer is required.

python -m venv .venv
.venv/Scripts/pip install -r requirements.txt
copy examples\INPUT.json storage\key_value_stores\default\INPUT.json
.venv/Scripts/python -m src

For a hosted AI review, set APIFY_TOKEN in the environment. Never commit it. Without a token, use "includeAiAnalysis": false.

Run the offline checks:

$python -m unittest discover -s tests -v

The Dockerfile follows Apify's current Python Actor template and can be built by the Apify platform.

Monetization and schedules

Configure pay-per-event in Apify Console with the event name qualified-opportunity. The code already respects the customer's maximum total charge and stops when the event limit is reached. Pricing is configured in Console, not hard-coded in source.

For recurring prospecting, save a configured input as an Apify Task and add a weekly or weekday schedule. Results remain accessible through the task's dataset and standard integrations.

Follow PUBLISHING.md for the beginner-friendly launch steps and ECONOMICS.md for the pricing guardrails.

Reliability

• Three-attempt retry policy for official HTTP sources.
• Source failures are isolated; one healthy source can still produce results.
• Grants.gov detail retrieval uses bounded concurrency.
• AI output is schema-checked, length-limited, and score-clamped.
• Exact negative terms are hard exclusions.
• Dataset items are stored with pay-per-event charging in one SDK operation.
• The run summary records partial source failures and spending-limit stops.

Built with the Apify Python SDK and its pay-per-event safeguards.