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

MethodPathDescription
POST/discovery/sourceDiscover a company's first mile — many candidate supplier/operating locations (async; returns a task to poll)
GET/discovery/source/{taskId}/statusPoll an async source-discovery task
GET/discovery/source/{taskId}/resultsFetch a completed task's discovered locations
POST/discovery/source/{taskId}/ingestStage a completed task's candidates as locations, in one call
POST/discovery/source/{taskId}/decisionsExpand, prune or record one candidate of a running task
GET/discovery/source/{taskId}/decisionsList 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:write to dispatch and to record a decision, because both spend the organization's Traces and daily trace-sweep limit. geocode:read for status, results and the decision list. ingestions:write for …/ingest, which creates locations.