Hlídač Státu + ARES

Search the Czech Register of Contracts with Hlídač státu intelligence, enrich every identified buyer and supplier with the official ARES business register, or schedule the same search and receive only newly seen contracts.

The Actor uses official APIs directly. No browser or proxy is required. Results are designed for Apify tables, CSV/Excel export, automation, and downstream APIs.

Why use this Actor?

• Search without learning Hlídač query syntax: buyer/supplier IČOs, keywords, dates, value, and contract categories have dedicated inputs.
• Receive one analysis-ready row per contract, including flat spreadsheet columns and complete nested source data.
• Enrich Czech entities with official ARES identity, address, legal-form code, tax ID, CZ-NACE activities, registration status, and source update date.
• Screen contracts using explainable Hlídač indicators: issues, missing price, procurement-threshold proximity, political connections, and invalid/superseded records.
• Monitor a saved search for new contracts without repeat output on every scheduled run.
• See explicit coverage on every result, including unavailable, partial, and not-requested enrichment.
• Retain source attribution and licence provenance in every record.

Attention indicators are screening aids. They are not fraud scores, allegations, legal conclusions, or substitutes for due diligence.

No API key setup

Hlídač státu API access is managed by the Actor. Customers do not need to register on the Czech-language source website or provide a token. The managed credential is stored as an encrypted Actor secret and is never written to logs, datasets, monitor state, or run summaries.

The undocumented firmy/GetDetailInfo company-profile integration is disabled for public runs because the live endpoint currently returns an unexplained 403. Contract collection and ARES enrichment do not depend on it.

Guided contract search

{
  "operation": "search",
  "searchTerms": "cloud",
  "buyerIcos": ["00007064"],
  "publishedFrom": "2026-01-01",
  "minValueCzk": 1000000,
  "categories": ["it"],
  "maxItems": 100,
  "aresEnrichment": true
}

Guided filters are combined with AND. Multiple values inside buyerIcos, supplierIcos, or categories are combined with OR. The generated query uses the documented icoPlatce, icoPrijemce, zverejneno, podepsano, cena, and oblast prefixes.

Expert users can add advancedQuery; it is ANDed with all guided filters. See the official Hlídač search help for its Elastic-style syntax.

Attention-indicator filters

The following options filter normalized Hlídač results locally because Hlídač does not document stable search prefixes for them:

• onlyWithIssues
• onlyMissingPrice
• onlyNearProcurementLimit
• onlyPoliticalLink

When any is enabled, scanLimit controls how many source matches are inspected to find up to maxItems qualifying output records. Customers are charged only for emitted dataset results, not scanned or rejected source records.

Monitor for new contracts

{
  "operation": "monitor",
  "buyerIcos": ["00007064"],
  "categories": ["it"],
  "maxItems": 500,
  "monitorKey": "interior-ministry-it",
  "firstRunBehavior": "baseline_only",
  "aresEnrichment": true
}

Create an Apify Task, schedule it, and keep the same monitorKey and filters. The default first run stores a quiet baseline; later runs emit only previously unseen contract IDs as NEW. Choose emit_current to return the initial result set too.

This release deliberately promises new-contract detection, not complete amendment detection. A newest-first search cannot guarantee that an old amended contract will return to the result window. Updates observed inside the active window are counted in the run summary but are not emitted as guaranteed alerts.

Monitor configuration is fingerprinted. Changing its query, post-filters, scan window, enrichment, or attachment settings requires a new monitorKey or resetState: true. An unexpected empty result protects established state rather than silently replacing it.

Events use deterministic eventId values for downstream deduplication. Delivery is intentionally at-least-once.

Monitor state stores compact IDs, fingerprints, and timestamps rather than full enriched records. It retains the 20,000 most recently observed contracts to remain safely below key-value-store record limits during long-running schedules.

Output

Every contract includes flat export columns:

{
  "recordType": "contract",
  "eventType": "SNAPSHOT",
  "detectedAt": "2026-08-14T14:25:40.250Z",
  "contractId": "39127674",
  "subject": "IT services",
  "publishedAt": "2026-08-14T13:41:29+02:00",
  "signedAt": "2026-08-10T00:00:00+02:00",
  "valueCzk": 981016.58,
  "buyerIco": "00007064",
  "buyerName": "Ministerstvo vnitra",
  "supplierIcos": ["04767543"],
  "supplierNames": ["Example s.r.o."],
  "issueCount": 0,
  "missingPrice": false,
  "nearProcurementLimit": false,
  "politicalLink": false,
  "validRecord": true,
  "hlidacUrl": "https://www.hlidacstatu.cz/Detail/39127674",
  "coverage": {
    "hlidacContract": "available",
    "hlidacCompanyProfile": "not_requested",
    "aresBuyer": "available",
    "aresSuppliers": "complete"
  }
}

The same item also contains nested event, contract, buyer, suppliers, signals, and provenance objects. This preserves detail for API users while keeping Apify's table and CSV exports immediately usable.

Attachment metadata is optional. Binary copies and full extracted attachment text are always removed to control dataset size and reduce unnecessary personal-data processing.

Disabled company-profile integration

The implementation for Hlídač company profiles is retained behind the owner-only HLIDAC_COMPANY_PROFILES_ENABLED=true feature flag, but there is no public input that enables it. Raw customer input cannot activate the integration while the flag is off.

If the endpoint becomes reliable, the integration can be restored without rebuilding it from scratch. Profiles remain allowlist-normalized, and related-person and subsidiary arrays remain excluded.

Pay-per-event setup

The code contains these atomic dataset-and-billing hooks:

• contract-result
• ares-enriched-contract
• new-contract
• ares-enriched-new-contract
• company-dossier (legacy compatibility hook; the workflow is disabled unless the Actor owner sets HLIDAC_COMPANY_DOSSIERS_ENABLED=true)

Configure event prices in Apify Console. Quiet monitor baselines, unchanged checks, rejected post-filter candidates, summaries, and failures are not charged. Suggested launch tests remain approximately $0.003 for a plain contract and $0.006 for an ARES-enriched contract or new-contract event; adjust after measuring conversion and API cost.

Before every paid dataset write, the Actor checks whether the customer's remaining spending limit can cover that event. When the limit is exhausted, the run ends successfully, reports delivered and deferred counts, and does not attempt an over-budget charge. Monitor state records only newly detected contracts that were actually delivered, so deferred events remain eligible for the next scheduled run.

The legacy company-dossier workflow is also retained behind an owner-only feature flag but disabled for public runs. Its pricing event can be removed while the flag remains off.

Sources, licence, and responsible use

Hlídač státu data is used under CC BY 3.0 CZ unless you have a separate commercial agreement. Each result contains attribution, the licence URL, and a modification marker. Do not remove or obscure attribution when redistributing results unless your licence permits it.

ARES is operated by the Ministry of Finance of the Czech Republic and is used as the official entity/registry enrichment layer. Customers remain responsible for source terms, lawful use, retention, and personal-data obligations applicable to their workflow.

Before operating a managed multi-customer Hlídač token or enabling restricted/commercial endpoints, confirm the intended commercial arrangement with Hlídač státu.

Operational behavior

• Hlídač requests are rate-limited below the documented four requests per second and retry throttling/server failures with exponential backoff.
• maxItems and scanLimit are capped at 2,500 because contract search exposes at most 250 pages.
• ARES lookups are deduplicated by IČO within each run.
• IČOs are normalized to eight digits and checksum-validated. Entity names are never fuzzy-matched to an IČO.
• Required Hlídač contract-search or ARES failures fail the run rather than implying complete output.
• Customer spending limits stop output gracefully without lowering the Actor success rate or silently losing monitor events.
• Full-text query totals describe the source result set before local attention-indicator filters.

Local development

npm install
npm run check
npm run build
apify run --input-file input.local.json

Use ./examples/search.json or ./examples/monitor.json as a starting point. For local development, either set HLIDAC_STATU_API_TOKEN or keep a legacy hlidacApiToken only in input.local.json, which is ignored by Git.