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

Geocoding and the confidence tier run in the background, so the call returns at once:

  • 202 โ€” the usual response: a geocode_confidence_task with status: pending. Poll GET /discovery/validate/:id/status; its result shows the geocoded point (with confidence_level: null) as soon as it is known. Once status is completed, GET /discovery/validate/:id/results returns the geocode_result with 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

FieldTypeRequiredDescription
namestringYesSupplier name
addressstringNoSharpens the geocode; if omitted, name is used as the query
commodity_typestringNoAny commodity; aliases like palm oil resolve to palm. Shapes the confidence check, so omit it rather than guess
company_identifierstringNoEchoed back on the result
refreshbooleanNoBypass the resolution cache and recompute (default false)

Errors

StatusCause
400Missing or malformed field
429The organization's supplier-resolution rate limit
502The task could not be started; retry
failed taskerror_code GEOCODE_NO_RESULT (the address resolved to no point) or GEOCODE_UPSTREAM_ERROR (retry)
404Unknown or another organization's task (status/results)

Next Step

โ†’ Step 5: Ingest Discovered Locations โ€” promote the point(s) you trust into the ingestion pipeline.