4 Validate a Supplier
โถStep 4: Validate a Supplier
Resolve a single named supplier to one point with a confidence_level.
This is Path B โ the counterpart to POST /discovery/source, not a step
after it. Where source takes a company and discovers many candidates,
validate takes one supplier you already know (by name, optional address)
and returns its single most-likely facility.
Use it as an independent entry point: if you already have supplier names,
start here โ no company-wide discovery needed. You do not run validate on
Path A candidates: source already returns each one geocoded and
confidence-scored. The one exception is a Path A hit that resolved to a
region only (no precise point) but carries a supplier name โ pass that name
here to try to pin a point.
โถWhat this step does
It geocodes the supplier (name + optional address) to a single point and
runs it through the first-mile validation pipeline to derive a
confidence_level (high / medium / low, or null when validation was
inconclusive) plus a human-readable confidence_comment. geocoding_precision
reports how sharp the geocode itself was (ROOFTOP โ APPROXIMATE); it is
not a confidence that the site is there, which is what confidence_level is for.
โถWhy it's needed
When you already know a supplier by name, this is the most direct way to get
its location: it pins that one supplier to a single point with a confidence
tier โ the sharper, single-supplier counterpart to source's company-wide
sweep. (It's also how you pin a Path A candidate that came back as a region
rather than a point.) Treat low (and null) as not safe to ingest; keep
high / medium.
โถVisualization
Renders a supplier card โ confidence-gated (green when safe to ingest, red
otherwise) with the resolved fields โ plus a single-point map marker
coloured by confidence. A safe (high/medium) result is stashed in
{{validated_candidate}} for Step 5.
โถ202 vs 200
202 vs 200Geocoding and the confidence tier run in the background, so the call returns at once:
202โ the usual response: ageocode_confidence_taskwithstatus: pending. PollGET /discovery/validate/:id/status; itsresultshows the geocoded point (withconfidence_level: null) as soon as it is known. Oncestatusiscompleted,GET /discovery/validate/:id/resultsreturns thegeocode_resultwith the tier filled in. This step polls for you.200โ a served candidate, already carrying its tier. Nothing to poll.
โถRequest
POST /discovery/validate with Content-Type: application/json
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Supplier name |
address | string | No | Sharpens the geocode; if omitted, name is used as the query |
commodity_type | string | No | Any commodity; aliases like palm oil resolve to palm. Shapes the confidence check, so omit it rather than guess |
company_identifier | string | No | Echoed back on the result |
refresh | boolean | No | Bypass the resolution cache and recompute (default false) |
โถErrors
| Status | Cause |
|---|---|
| 400 | Missing or malformed field |
| 429 | The organization's supplier-resolution rate limit |
| 502 | The task could not be started; retry |
failed task | error_code GEOCODE_NO_RESULT (the address resolved to no point) or GEOCODE_UPSTREAM_ERROR (retry) |
| 404 | Unknown or another organization's task (status/results) |
โถNext Step
โ Step 5: Ingest Discovered Locations โ promote the point(s) you trust into the ingestion pipeline.