# Hilma Tender Watcher (`aihu/hilma-tender-watcher`) Actor Daily scan of Finnish public-procurement notices (Hilma) with AI relevance scoring. Bring your ICP — get back only tenders worth pitching, with Finnish-language rationale per match. Webhook for hot leads (score 70+). Uses Hilma's official free API + your Anthropic key. - **URL**: https://apify.com/aihu/hilma-tender-watcher.md - **Developed by:** [tuba](https://apify.com/aihu) (community) - **Categories:** Lead generation, Automation, AI - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $150.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Hilma Tender Watcher Daily AI-scored stream of Finnish public-procurement notices that match your ICP. ### What this does [Hilma](https://www.hankintailmoitukset.fi) is where every Finnish public-sector tender gets published. Cities, hospitals, ministries, state agencies — if they buy anything over the national threshold, it shows up there. The portal is open data, but unusable for sales: thousands of notices a year across every sector. This Actor runs on a schedule and gives you only the notices that actually match your ICP, scored 0-100 with a Finnish-language rationale you can paste straight into a sales note. ### What you get Per notice in the output Dataset: - buyer, CPV codes, declared value (EUR), submission deadline, link to the official Hilma listing - AI-generated relevance score (0-100) against your ICP description - One-paragraph Finnish rationale explaining the score - `buying_signal` flag (`high` / `medium` / `low`) - Optional Slack/webhook fan-out for hot leads (score 70+) Output is downloadable as JSON, CSV, or Excel from the Apify Console. ### How to use 1. Describe your ICP in Finnish or English. One paragraph is enough. 2. Optionally narrow with CPV-code prefixes (e.g. `72` = IT services, `80` = education), keywords, buyer-org filters, minimum value. 3. Bring your own **Anthropic API key** (https://console.anthropic.com) — we use Claude to score each notice. Your costs scale with how tight your pre-filter is, not with our pricing. 4. Bring your own **Hilma API key** — free, self-service registration at https://hns-hilma-prod-apim.developer.azure-api.net/ (subscribe to the **avp-read** product, copy the primary key). 5-minute setup. 5. Run it manually or schedule it daily in Apify. Results land in the Dataset; high-scoring notices fire your webhook. ### Legal posture This Actor uses Hilma's **official** `avp-read` API, which is **explicitly designed for value-added services** by the Finnish Ministry of Finance and operated by Hansel Oy. From their public docs: *"The interface is designed so that data is not served directly from the interface to the end user. The value-added service provider is intended to import notices into their own service, enrich and process them as they wish, and serve their users from their own system."* That is exactly this Actor's design. Free of charge. Rate-limited per user (your own key), which is why you bring your own. ### Why it's not just "ChatGPT over Hilma" Three things make it usable for daily sales work: - **Deduplication.** Notices are seen once across runs. You won't get the same tender twice. - **Cheap pre-filter.** CPV / keyword / buyer / value filters run in code before any LLM call. You pay for AI scoring only on candidates that already structurally fit. - **Finnish-native scoring.** The prompt is in Finnish, the rationale comes back in Finnish, and the model handles Finnish procurement vocabulary (hankintayksikkö, puitejärjestely, kynnysarvo). ### What it's not - Not a CRM. Outputs are a Dataset and webhook payloads — pipe it into your own stack. - Not a tender-writing tool. We help you find which tenders to pitch, not draft the response. - Not real-time. Hilma notices land daily; the Actor pulls a configurable lookback window per run (default 24h). ### Pricing Rental: 49 EUR/month flat, unlimited runs. Plus your own Anthropic API costs (typically under 1 EUR/month if you pre-filter sensibly). ### Built by [Aihu Agency](https://aihuagency.com) — AI + Human. Work smarter. Built because we needed it ourselves for finding AI-consulting tenders in the Finnish public sector. We use it daily on our own pipeline and figured you'd want the same. ### Status Early access. Output schema may evolve before v1.0. ### Support # Actor input Schema ## `icp_description` (type: `string`): Describe your ideal procurement target in Finnish or English. The LLM uses this to score each notice's fit. One paragraph is enough. ## `keywords` (type: `array`): Notice title or description must include at least one keyword. Leave empty for no keyword filter. ## `cpv_code_prefixes` (type: `array`): Match notices with any CPV code starting with one of these prefixes (e.g. '72' for IT services, '80' for education). ## `buyer_includes` (type: `array`): Buyer organization name must contain at least one of these substrings (case-insensitive). ## `buyer_excludes` (type: `array`): Buyer organization name must NOT contain any of these substrings (case-insensitive). ## `min_value_eur` (type: `integer`): Skip notices with declared value below this. Leave empty for no minimum. Notices without a declared value are kept by default. ## `min_relevance_score` (type: `integer`): Only output notices scoring at or above this (0-100). Default 60. ## `webhook_url` (type: `string`): POST a JSON payload here for every notice scoring 70 or above. Use a Slack incoming webhook, n8n, or your own endpoint. ## `anthropic_api_key` (type: `string`): Your own Anthropic API key. Get one at https://console.anthropic.com. Used to score notice relevance with Claude Haiku. ## `hilma_api_key` (type: `string`): Your free Hilma API key from https://hns-hilma-prod-apim.developer.azure-api.net/ — register, subscribe to the avp-read product, copy the primary key. Sanctioned official endpoint, designed for value-added services like this Actor. ## `max_notices_to_fetch` (type: `integer`): Safety cap on total notices fetched per run. Useful for testing. ## `since_hours` (type: `integer`): How far back to look for new notices. Default 24h matches a daily schedule. Increase to 48-72 for safety on first runs. ## Actor input object example ```json { "icp_description": "AI- ja automaatiohankkeet suomalaisille kunnille, kaupungeille ja valtionhallinnolle. Budjetti vähintään 50 000 EUR. Vältetään pelkkiä laitehankintoja.", "keywords": [], "cpv_code_prefixes": [], "buyer_includes": [], "buyer_excludes": [], "min_relevance_score": 60, "max_notices_to_fetch": 500, "since_hours": 24 } ```` # Actor output Schema ## `scoredNotices` (type: `string`): Dataset of Hilma procurement notices that passed your filters and were scored against your ICP. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "icp_description": "AI- ja automaatiohankkeet suomalaisille kunnille, kaupungeille ja valtionhallinnolle. Budjetti vähintään 50 000 EUR. Vältetään pelkkiä laitehankintoja." }; // Run the Actor and wait for it to finish const run = await client.actor("aihu/hilma-tender-watcher").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "icp_description": "AI- ja automaatiohankkeet suomalaisille kunnille, kaupungeille ja valtionhallinnolle. Budjetti vähintään 50 000 EUR. Vältetään pelkkiä laitehankintoja." } # Run the Actor and wait for it to finish run = client.actor("aihu/hilma-tender-watcher").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "icp_description": "AI- ja automaatiohankkeet suomalaisille kunnille, kaupungeille ja valtionhallinnolle. Budjetti vähintään 50 000 EUR. Vältetään pelkkiä laitehankintoja." }' | apify call aihu/hilma-tender-watcher --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=aihu/hilma-tender-watcher", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Hilma Tender Watcher", "description": "Daily scan of Finnish public-procurement notices (Hilma) with AI relevance scoring. Bring your ICP — get back only tenders worth pitching, with Finnish-language rationale per match. Webhook for hot leads (score 70+). Uses Hilma's official free API + your Anthropic key.", "version": "0.1", "x-build-id": "GNfEC3V7uKEE1u1WY" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/aihu~hilma-tender-watcher/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-aihu-hilma-tender-watcher", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/aihu~hilma-tender-watcher/runs": { "post": { "operationId": "runs-sync-aihu-hilma-tender-watcher", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/aihu~hilma-tender-watcher/run-sync": { "post": { "operationId": "run-sync-aihu-hilma-tender-watcher", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "icp_description", "anthropic_api_key", "hilma_api_key" ], "properties": { "icp_description": { "title": "ICP description", "type": "string", "description": "Describe your ideal procurement target in Finnish or English. The LLM uses this to score each notice's fit. One paragraph is enough." }, "keywords": { "title": "Keywords (case-insensitive)", "type": "array", "description": "Notice title or description must include at least one keyword. Leave empty for no keyword filter.", "default": [], "items": { "type": "string" } }, "cpv_code_prefixes": { "title": "CPV code prefixes", "type": "array", "description": "Match notices with any CPV code starting with one of these prefixes (e.g. '72' for IT services, '80' for education).", "default": [], "items": { "type": "string" } }, "buyer_includes": { "title": "Buyer-org includes", "type": "array", "description": "Buyer organization name must contain at least one of these substrings (case-insensitive).", "default": [], "items": { "type": "string" } }, "buyer_excludes": { "title": "Buyer-org excludes", "type": "array", "description": "Buyer organization name must NOT contain any of these substrings (case-insensitive).", "default": [], "items": { "type": "string" } }, "min_value_eur": { "title": "Minimum value (EUR)", "minimum": 0, "type": "integer", "description": "Skip notices with declared value below this. Leave empty for no minimum. Notices without a declared value are kept by default." }, "min_relevance_score": { "title": "Minimum relevance score", "minimum": 0, "maximum": 100, "type": "integer", "description": "Only output notices scoring at or above this (0-100). Default 60.", "default": 60 }, "webhook_url": { "title": "Webhook URL (optional)", "type": "string", "description": "POST a JSON payload here for every notice scoring 70 or above. Use a Slack incoming webhook, n8n, or your own endpoint." }, "anthropic_api_key": { "title": "Anthropic API key", "type": "string", "description": "Your own Anthropic API key. Get one at https://console.anthropic.com. Used to score notice relevance with Claude Haiku." }, "hilma_api_key": { "title": "Hilma API key (avp-read)", "type": "string", "description": "Your free Hilma API key from https://hns-hilma-prod-apim.developer.azure-api.net/ — register, subscribe to the avp-read product, copy the primary key. Sanctioned official endpoint, designed for value-added services like this Actor." }, "max_notices_to_fetch": { "title": "Max notices per run", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Safety cap on total notices fetched per run. Useful for testing.", "default": 500 }, "since_hours": { "title": "Lookback window (hours)", "minimum": 1, "maximum": 168, "type": "integer", "description": "How far back to look for new notices. Default 24h matches a daily schedule. Increase to 48-72 for safety on first runs.", "default": 24 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```