DashboardOpportunitiesAnalyticsIngestConnectorsCron jobsAI usageAPI keysSupport
Back to Support

GVCA Opportunity Platform — User Guide

Welcome to the GVCA AI Opportunity Platform. This guide walks through how opportunities get into the system, how they are validated, and how your team manages them from intake to approval.

Getting started

What the platform does

The platform ingests construction tender and bid opportunities from multiple sources — connectors that poll public portals, an inbound email channel, and manual uploads — normalizes them with AI assistance, and queues anything uncertain for human review before it lands in the main Opportunities list.

The main areas

  • Dashboard — operational overview: counts by status and recent activity.
  • Opportunities — the canonical list of all ingested opportunities.
  • Review queue — items that need a human decision before approval.
  • Ingest — manual paste/upload entry point for one-off opportunities.
  • Connectors — configure and monitor the automated source feeds.

Ingesting opportunities

Automated connectors

Connectors run on a schedule and pull lists from supported portals. Today the platform supports:

  • CanadaBuys — federal tender portal (JSON API).
  • Bonfire — municipal/regional procurement portal.
  • Bids & Tenders — multi-portal municipal platform, rendered via Firecrawl so the JavaScript-driven list table populates correctly.

Each connector instance has its own polling interval and filter. New items are fetched on the regular run; supporting documents are fetched on a separate pass.

Inbound email

Forward a tender notification email to the platform's inbound address. The email is parsed, attachments are extracted, and a draft opportunity is created.

Manual ingest

Use Ingest when you want to drop in a one-off opportunity from a source that isn't connected. Paste the text or upload a PDF and the platform will extract the key fields.

Managing opportunities

Status lifecycle

  • Draft — created but not yet validated.
  • Approved — vetted and visible to downstream consumers (Partner API, exports).
  • Archived — closed/awarded/cancelled or otherwise out of rotation.

Construction-relevant opportunities are auto-promoted from review to approved once enrichment pushes their completeness score to 90% or higher. You don't need to manually clear a queue — the pipeline does it.

Needs attention

The Opportunities list has a Needs attention view that surfaces construction-relevant rows still under 90% completeness and not yet approved, sorted by lowest score first. Use it to find rows that need a manual nudge: add a missing close date, paste in a scope, or trigger another enrichment pass. Anything that crosses 90% disappears from this view automatically.

Editing and attachments

Open any opportunity to edit metadata, attach related documents, or link a related buyer/agency record. Document fetches from connectors arrive on a separate pass, so attachments may appear a few minutes after the initial listing.

Connectors

Adding a connector instance

Go to Connectors → New, pick the source, and supply the instance-specific configuration (portal URL, jurisdiction, keyword filters, poll interval).

Health and last run

Each connector card shows its last run time, items fetched, and any error from the most recent attempt. A red badge means the last run failed; open the connector to see the error detail.

Firecrawl-rendered sources

Bids & Tenders requires JavaScript rendering. The platform routes those fetches through Firecrawl automatically when a Firecrawl connection is configured — no per-instance setting needed.

Partner API (3rd-party integrations)

The platform exposes a read-only REST API so partner systems — supplier portals, contractor CRMs, and matching engines — can pull construction opportunities, documents, contacts, and classification taxonomies.

Base URL and docs

  • Base: https://gvca.heitechsoft.com/api/public/v1
  • Interactive docs (Swagger UI): /api/docs
  • OpenAPI 3.1 spec: served alongside the docs page.

Authentication

Every request (except /health) requires a bearer token:

Authorization: Bearer gvca_live_xxxxxxxxxxxx

Keys are issued per partner from Admin → API keys and are shown once at creation — copy them immediately. Revoke a key at any time from the same screen; revocation takes effect on the next request. A best-effort rate limit (default 120 requests/minute per key, per worker) protects the API from runaway clients.

What's available

  • GET /opportunities — paginated list filtered to construction tenders. Supports filters for status, jurisdiction, close-date window, and an updated_since cursor for incremental syncs.
  • GET /opportunities/:id — full opportunity record.
  • GET /opportunities/:id/documents — file metadata plus signed download URLs valid for one hour.
  • GET /opportunities/:id/contacts — structured contact list.
  • GET /opportunities/:id/classifications — CSI divisions, trades, market sectors, and product categories tagged on the opportunity.
  • GET /reference/{csi-divisions|trades|market-sectors|product-categories} — full taxonomy lookups for partner-side matching.

Issuing a key for a partner

  1. Go to Admin → API keys.
  2. Click Issue key, give it a label (partner name + environment).
  3. Copy the gvca_live_… value shown once and share it with the partner over a secure channel.
  4. Point the partner at /api/docs for the full endpoint reference.

Getting help

If something looks wrong — a connector returning zero results, a duplicate that wasn't caught, or an extraction that's consistently off — note the opportunity ID and reach out to the platform team. The Release notes page covers what shipped in each update.