That difference shaped the API behind UK Tender Check. The product searches notices indexed from official UK procurement sources, then lets a supplier compare a selected notice with facts it provides. The output is a decision-support checklist, not an eligibility decision. This article describes the design choices that make that boundary visible.

1. Preserve provenance as product data

A source URL should not be a footnote added after ranking or scoring. It should travel with the tender record. At minimum, the client needs the source system, source notice identifier, official URL, retrieval context, and the fields as they were available to the application.

That lets the interface offer two equally important actions: continue the product workflow, or open the official notice. The second is not a failed conversion. It is how the user verifies what the software is summarising.

Provenance also changes error handling. If the source identifier is unknown, return a real not-found result. If a known record lacks a value or deadline, preserve the record and return the field as missing. Redirecting both cases to a generic result page would erase useful distinctions.

2. Model “unknown” separately from “does not match”

Suppose a supplier profile says the company holds Cyber Essentials, but a notice record contains no accessible security requirement. The API must not say the company fails the requirement. It must also not say the company satisfies it. The supportable answer is that the observable record does not provide enough evidence for that check.

A fit response therefore needs more than a total score. It should expose:

• the profile fact used;
• the notice evidence used;
• the rule or comparison that ran;
• the result of that comparison;
• missing information and follow-up questions;
• confidence or evidence quality where defined;
• the scoring-rule version.

This structure makes a “fit” result auditable. It also lets the UI distinguish a mismatch from a question the supplier must verify in the procurement documents.

3. Keep supplied facts separate from inferred facts

A public tender record describes an opportunity. It does not prove a supplier’s turnover, certifications, delivery regions, references, capacity, or conflicts. Those facts should come from the supplier or an explicitly authorised source.

The API input makes that separation visible: a profile contains supplier-provided capabilities, regions, and evidence, while a tender identifies the source notice. The service can compare the two without pretending it independently verified the private company data.

The production OpenAPI document is available at https://uktendercheck.co.uk/openapi.json. Before copying an example into another system, check the current schema rather than relying on this article: API fields can evolve, while the provenance boundary should remain stable.

4. Version deterministic rules

“Deterministic” does not mean permanent. A scoring rule can change after a bug fix, a better field mapping, or a clearer product policy. If the response includes a rule version, a user can tell whether two reports were produced under the same logic.

Versioning is also useful for support. A report can be discussed in terms of its source record and rule version rather than a screenshot of an unexplained number.

5. Make the limitation part of the interface

The most important copy in a scoring product may be the sentence explaining what the score is not. For UK Tender Check, the result is not legal or procurement advice, a definitive eligibility/compliance determination, bid-writing output, or an award prediction. Users must review the official notice and procurement documents.

This is not a disclaimer pasted over an otherwise overconfident product. The API shape, source link, missing-field behaviour, and rule metadata should all support the same boundary.

A developer path

After production verification, developers can inspect the OpenAPI document, use the Postman collection, or connect through MCP. A typical Bearer-authenticated tender search uses:

GET https://uktendercheck.co.uk/api/v1/tenders?q=software&source=all&limit=10
Authorization: Bearer <YOUR_API_KEY>

The fit endpoint is:

POST https://uktendercheck.co.uk/api/v1/fit
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

Use the live OpenAPI schema for the request body and current response. Do not put an API key, session cookie, customer record, or wallet proof into an article, public collection, issue, or code sample.

Closing question

The broader design lesson is simple: incomplete public data does not become complete because an API returns a number. A useful decision-support system preserves the source, represents the unknown, and explains the rule it applied.

If you build ranking or fit systems over sparse data, what information do you retain so a user can reconstruct why a result appeared?

Disclosure: UK Tender Check publishes this article about its own API. AI-assisted editorial drafting was reviewed and fact-checked before publication. Product: UK Tender Check developer documentation.