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

The call never waits on the geocoder or the validation pipeline:

  • 202 โ€” the usual response: a geocode_confidence_task with status: pending and links.confidence_status / links.confidence_results. Poll GET /discovery/validate/{taskId}/status until completed (its result shows the geocoded point as soon as it is known), then read GET /discovery/validate/{taskId}/results.
  • 200 โ€” a served candidate: a geocode_result with its tier, no id and nothing to poll.

Handle both 202 and 200.

Request

Method & Path

POST /discovery/validate

Headers

  • x-api-key โ€” required.
  • Accept: application/json
  • Content-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, null and "unknown" are treated as omitted.
  • company_identifier (string, optional) โ€” your identifier for the supplier, echoed back on the result.
  • refresh (boolean, optional, default false) โ€” bypass the resolution cache and force a fresh geocode + validation instead of serving a previously resolved candidate.

Response

  • 202 โ€” a geocode_confidence_task with status: pending and links to poll. If the task then fails, its status carries error_code GEOCODE_NO_RESULT (the geocoder found no usable location; do not retry) or GEOCODE_UPSTREAM_ERROR (retry).
  • 200 โ€” a served geocode_result (schema below) with no id.
  • 400 โ€” invalid body: missing name, or a malformed commodity_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.limit is discovery_validate. A served 200 does 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.

FieldTypeDescription
typestringAlways geocode_result.
attributes.namestringResolved facility name.
attributes.latitudenumberGeocoded latitude (WGS84).
attributes.longitudenumberGeocoded longitude (WGS84).
attributes.countrystring | nullNormalized country name.
attributes.country_codestring | nullNormalized country code.
attributes.citystring | nullNormalized city.
attributes.admin1string | nullFirst-level admin area (state / region).
attributes.geocoding_precisionstring | nullHow 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" | nullConfidence 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_commentstring | nullHuman-readable rationale behind confidence_level.
attributes.commodity_typestring | nullCommodity type applied to the geocode; null when none was sent.
attributes.company_identifierstringThe request's company_identifier; absent when none was sent.
attributes.imagery_confidence_scorenumber | nullSatellite-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_commentstring | nullOne-sentence explanation of imagery_confidence_score. Absent and null as for the score.
attributes.supply_chain_rolestring | nullfirst_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_typestring | nullNode kind (mill, port, collection_centre, โ€ฆ). Absent when validation has not returned.
attributes.node_categorystring | nullCanonical category of node_type: primary_processing | secondary_processing | aggregation | plot | logistics | commercial.
attributes.intake_materialstring | nullWhat the site takes in: raw_harvest | processed_intermediate | unknown.

Required scope: geocode:read