Validate Supplier
Resolve a single supplier to its most-likely facility location (latitude/longitude) with a confidence tier.
Backed by the geocoder (AI schema detection, geocoding, and country/admin
lookup), then enriched with the first-mile validation pipeline so the
result carries a confidence_level (high / medium / low) with parity
to the screening app's ingest gate. It auto-picks the top result โ there is
no supply-shed generation. Use it as the first step of a "resolve a
supplier" flow before any downstream metrics or compliance work; treat low
(and null) confidence as not safe to ingest.
Confidence is enrichment, not a gate: if validation is inconclusive or
unavailable, the geocoded point is still returned with
confidence_level: null.
โถ202 vs 200
202 vs 200The call never waits on the geocoder or the validation pipeline:
202โ the usual response: ageocode_confidence_taskwithstatus: pendingandlinks.confidence_status/links.confidence_results. PollGET /discovery/validate/{taskId}/statusuntilcompleted(itsresultshows the geocoded point as soon as it is known), then readGET /discovery/validate/{taskId}/results.200โ a served candidate: ageocode_resultwith its tier, noidand nothing to poll.
Handle both 202 and 200.
โถRequest
โถMethod & Path
POST /discovery/validate
โถHeaders
x-api-keyโ required.Accept: application/jsonContent-Type: application/json
โถBody
name(string, required) โ supplier name.address(string, optional) โ supplier address. If omitted, the name is used as the geocoder query (name-only resolution; precision is lower).commodity_type(string, optional) โ any commodity, EUDR or not (e.g.mica). Alias spellings resolve to the canonical name (palm oilโpalm); anything else is lowercased. It shapes the confidence check, so omit it rather than guess. Blank,nulland"unknown"are treated as omitted.company_identifier(string, optional) โ your identifier for the supplier, echoed back on the result.refresh(boolean, optional, defaultfalse) โ bypass the resolution cache and force a fresh geocode + validation instead of serving a previously resolved candidate.
โถResponse
- 202 โ a
geocode_confidence_taskwithstatus: pendingand links to poll. If the task then fails, its status carrieserror_codeGEOCODE_NO_RESULT(the geocoder found no usable location; do not retry) orGEOCODE_UPSTREAM_ERROR(retry). - 200 โ a served
geocode_result(schema below) with noid. - 400 โ invalid body: missing
name, or a malformedcommodity_type(letters, digits, single spaces,_,:and-only). - 401 / 403 โ missing or invalid key, or the key lacks
geocode:read. - 429 โ the organization's supplier-resolution rate limit is spent;
see
Retry-After.data.details.limitisdiscovery_validate. A served200does not count against it. - 502 โ the task could not be started. Safe to retry.
โถResponse schema
The 200 data payload; the meta / links envelope is documented
centrally. The 202 task has the shape of Get Supplier Confidence Status.
| Field | Type | Description |
|---|---|---|
type | string | Always geocode_result. |
attributes.name | string | Resolved facility name. |
attributes.latitude | number | Geocoded latitude (WGS84). |
attributes.longitude | number | Geocoded longitude (WGS84). |
attributes.country | string | null | Normalized country name. |
attributes.country_code | string | null | Normalized country code. |
attributes.city | string | null | Normalized city. |
attributes.admin1 | string | null | First-level admin area (state / region). |
attributes.geocoding_precision | string | null | How sharply the address geocoded (ROOFTOP / RANGE_INTERPOLATED / GEOMETRIC_CENTER / APPROXIMATE), or for a registry-matched facility the map-pin tier (EXACT / LOCALITY / DISTRICT / REGION / BASIN / UNRESOLVED). Not a confidence that the site is there; see confidence_level. |
attributes.confidence_level | "low" | "medium" | "high" | null | Confidence tier; see Resolution and confidence on the Validate folder page. Null when pending, inconclusive, unavailable or invalid (including failed commodity checks). Review low/null before compliance use. The overall proxy score is not returned. |
attributes.confidence_comment | string | null | Human-readable rationale behind confidence_level. |
attributes.commodity_type | string | null | Commodity type applied to the geocode; null when none was sent. |
attributes.company_identifier | string | The request's company_identifier; absent when none was sent. |
attributes.imagery_confidence_score | number | null | Satellite-imagery confidence (0..1) that the point shows the facility. Absent when the imagery check did not return; null when it ran but could not score the point. |
attributes.imagery_confidence_comment | string | null | One-sentence explanation of imagery_confidence_score. Absent and null as for the score. |
attributes.supply_chain_role | string | null | first_mile | downstream | unknown. Derived from intake material, then node type, as on source. Guides whether traversal stops or goes upstream. For ingestion, also review node classification, intake material, pin and link evidence; the role alone is not an ingestability verdict. Absent when validation has not returned. |
attributes.node_type | string | null | Node kind (mill, port, collection_centre, โฆ). Absent when validation has not returned. |
attributes.node_category | string | null | Canonical category of node_type: primary_processing | secondary_processing | aggregation | plot | logistics | commercial. |
attributes.intake_material | string | null | What the site takes in: raw_harvest | processed_intermediate | unknown. |
Required scope:
geocode:read