Verdicts & confidence

Every validation returns exactly one verdict, one 0–100 confidence score, and a provider-consensus report. The engine verifies answers against your input first, then uses independent provider agreement to adjust confidence.

The three verdicts

How the verdict is decided

In order, for the consensus-selected candidate:

1. No candidate at all: invalid, reason no_results.
2. You supplied a house number and the best result's house number is missing or mismatch: invalid, reason no_house_number_match. A confident street-level hit is deliberately not treated as a deliverable address.
3. Confidence at or above the valid threshold and nothing corrected, mismatched, or missing: valid, no reasons.
4. Confidence at or above the correctable threshold: correctable, with reason components_corrected when something was corrected.
5. Otherwise: invalid, reason low_confidence, plus components_incomplete when a component was mismatched or missing.

Reasons taxonomy

A closed set of five values. reasons is an array and is empty for a clean valid.

Component verdicts

The components object reports how each part of your input compared to the result. Only checked components appear.

The confidence score

Confidence is a unified 0–100 integer, comparable across providers. It is built from weighted component agreement:

Each component contributes points by its verdict: match scores 1, corrected 0.7, missing 0.2, mismatch 0, and not-checked is excluded from the weighting entirely. When a provider reports its own confidence, the adapter normalizes it to 0–1 and it blends in at weight 0.25. A per-provider, per-country calibration prior can scale the result (currently 1.0 for every provider, so it has no effect today).

Free-form query input is scored with presence-in-query checks; structured components input gets exact per-field comparison. Structured input therefore produces the more precise score when you have separate form fields.

Provider consensus

Each provider gets one vote: its highest input-verification candidate. Results form the same address cluster when their identifying components agree and, when both include coordinates, they are within 25 metres. One provider cannot create a majority by returning duplicate candidates.

With two or more providers, consensus.score is the percentage supporting the selected cluster. The final confidence blends 80% of the selected candidate's input-verification score with 20% of that consensus score. Unanimous agreement can raise confidence; disagreement lowers it. The report preserves baseConfidence and confidenceDelta so the adjustment is auditable.

disagreements names every conflicting provider and lists the differing fields. Coordinate conflicts also include distanceMeters. These details are available without debug mode and are stored in the console request log and Quality analytics.

Matching rules worth knowing

• House numbers carry real postal semantics: 2/B, 2-b, 2 B, and 2B are the same. A letter range 2A-2D contains 2B. A numeric range 2-8 respects street-side parity, so it contains 4 but not 3. The same number with a different suffix scores corrected.
• Postcodes compare digits and letters separately: a Dutch 1234 AB against 1234 AC is corrected, not a mismatch.
• Street and city use normalization (diacritics, casing), Levenshtein similarity, and token/abbreviation containment.

Thresholds

The valid threshold defaults to 85 and is configurable directly on each project between 50 and 99. The correctable threshold is derived: 25 points below the valid threshold, never lower than 40. At the default that means valid ≥ 85 and correctable ≥ 60.

Raising the threshold makes valid stricter and pushes borderline results into correctable. Lowering it does the opposite. Changing the threshold also changes the cache key, so new settings take effect on the next lookup rather than being masked by cached responses.

Providers behind the verdict

Provider credentials belong to the platform, so you never bring your own keys. Which providers are active is a platform setting; GET /healthz reports the current list, and projects can restrict and reorder the ones they use. Providers that do not cover the requested country are skipped and traced as no-coverage.