Source
Discover the first-mile supply base of a company you don't yet have
suppliers for — potentially dozens of candidate supplier/operating locations.
Asynchronous: dispatch a discovery task, poll its status, then fetch the
discovered locations. A common flow is to source a company to surface
candidates, then validate the specific ones you want to act on.
▶Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /discovery/source | Discover a company's first mile — many candidate supplier/operating locations (async; returns a task to poll) |
| GET | /discovery/source/{taskId}/status | Poll an async source-discovery task |
| GET | /discovery/source/{taskId}/results | Fetch a completed task's discovered locations |
| POST | /discovery/source/{taskId}/ingest | Stage a completed task's candidates as locations, in one call |
| POST | /discovery/source/{taskId}/decisions | Expand, prune or record one candidate of a running task |
| GET | /discovery/source/{taskId}/decisions | List the decisions on a task |
▶Task lifecycle
Dispatch returns 202 with a source_discovery_task id. Poll
GET /discovery/source/{taskId}/status until status is completed (then
fetch …/results) or failed. Results are a JSON:API collection of
computed, non-persisted source_location candidates with stable candidate
ids and discovery metadata on meta. A candidate may have no usable pin.
Discovery does not supply verified plot boundaries.
A finished traversal can be continued with continue_from and expand.
The new task keeps its nodes and candidate ids and sweeps only the selected
candidates, using the original search settings. See Discover Source
Locations for the request and budget rules.
▶From discovery into ingestion
POST /discovery/source/{taskId}/ingest stages the candidates directly — no
client-built file, and no re-geocode of the coordinates discovery produced. It
returns an ordinary asset_task, so it is polled at
GET /ingestions/{id} like any upload. See the
discovery-to-ingestion guide.
For assessed EUDR work, use the upload fast path in that guide. The bridge checks linkage, lineage and pin precision, but skips the validation call that produces ingestion assessments and has no audit-trail fast-path option.
▶Live review
While a task runs, …/status reports generation and provisional_count.
GET …/results?partial=true&since_generation=N returns only the candidates
that changed after snapshot N, each flagged provisional: true. A reviewer
can then expand, prune or record a candidate at …/decisions. A running
traversal reads the decisions before it enqueues child sweeps. Provisional
candidates are never ingested: …/ingest reads the finished result only.
Each candidate streams once its own location checks finish. Its pin stays
fixed once shown; evidence and selection can still change. Read
selection, meta.progress, meta.removed_ids and the generation delta
to keep a running view current. A retained pin can become approximate and
cease to be suitable for ingestion.
Required scope:
discovery:writeto dispatch and to record a decision, because both spend the organization's Traces and daily trace-sweep limit.geocode:readfor status, results and the decision list.ingestions:writefor…/ingest, which creates locations.