Ingest Discovered Candidates
For assessed EUDR work, use the upload fast path. This bridge checks linkage, lineage and pin precision, but skips the validation call that produces ingestion assessments and accepts no audit-trail fast-path options. See Discovery โ ingestion.
Ingest the candidates of a completed source-discovery task in one server call. No client-built file, and no re-geocode: the candidates already carry server-produced WGS-84 coordinates, so they are staged at exactly the point discovery found.
The response is an ordinary asset_task โ the same resource
POST /ingestions/assets returns โ so poll it at GET /ingestions/{id} like
any upload. Note that an upload is finished at overall_status: staged, not
completed.
Call this once GET /discovery/source/{taskId}/status reports
status: completed.
โถRequest
โถMethod & Path
POST /discovery/source/{taskId}/ingest
โถPath parameters
taskId(UUID, required) โ the discovery task id. A non-UUID value is rejected with400.
โถBody
| Field | Type | Required | Description |
|---|---|---|---|
location_type | "facility" | "plot" | "shed" | yes | Location type to stage the candidates as. |
candidate_ids | string[] | no | Candidate ids from the results response. Omit to ingest every candidate the filters admit. An empty array is rejected with 400. |
filters | object | no | Narrow which candidates are admitted โ see below. |
commodity_type | string | no | Declared commodity, used for any candidate that carries none. |
tags | string[] | no | Tags applied to the created asset task. |
assessments | object | no | Accepted for parity with POST /ingestions/assets, but inert on this endpoint. The bridge skips validate_locations, which is the only producer of assessment results, so no assessment runs and none is billed. To run assessments on the staged rows, reprocess them with PUT /ingestions/assets filtered to the returned task. |
supplier | object | no | Upload-wide supplier fallback for the staged rows. |
โถSelection: named ids, or everything admitted
| Body | Meaning |
|---|---|
candidate_ids: [...] | Ingest exactly these, subject to the filters. |
| omitted | Ingest every candidate the filters admit. |
candidate_ids: [] | 400. Selecting nothing and selecting everything must not be spelled the same way. |
Omitting the ids is the usual choice for an agent or a "screen everything credible" flow: it removes the fetch-results-then-echo-ids round-trip.
A candidate you name that no filter admits is reported in rejections
with its reason โ you made a claim about it, so the response says why it
failed. Under the ingest-all form the same candidate appears in filtered
instead. Same rule, different reporting.
โถFilters
The default gate admits a candidate with a point geometry and
coordinates, whose location_precision is EXACT (a point pinned to a
street address), whose confidence_level is high, medium or absent, and
whose linkage_type is deterministic (a source ties it to the company).
An inferred or probabilistic node is reported as not_ingestable with
the detail "link to the company not confirmed"; list it in linkage to
stage it anyway.
On a traversal, every link above a deeper node must be confirmed too: its
lineage_linkage_type (the weakest link from the company down to its
parent) must be in linkage. A node under an unconfirmed parent is reported
with the detail "path to the company not confirmed". When a traversal did not
record that path, it is rebuilt from the node's ancestors in the same result;
if an ancestor is missing, the node passes only when linkage lists all
three types.
Only a sourcing site is staged by default: a plot, a primary processor or an
aggregation site. An office, port, trader or bare entity is reported as
not_ingestable with the detail "not a first-mile or aggregation site"; list
its type in node_type to stage it anyway. A site that takes processed
material (a secondary processor) is never staged, whatever the filters ask.
A LOCALITY point is a town centroid, not a site: it is reported as
not_ingestable with the detail "approximate location (town only): needs a
street address", whatever its confidence. Get the street address from the
supplier, or list LOCALITY in location_precision to admit it anyway. The
body may narrow the gate:
| Filter | Type | Default |
|---|---|---|
min_confidence | "high" | "medium" | "low" | unset โ the default tier rule above |
location_precision | string[] | ["EXACT"] |
linkage | ("deterministic" | "inferred" | "probabilistic")[] | ["deterministic"] |
node_type | string[] | unset: plot, primary processing and aggregation sites only. Set, it replaces that rule. |
relationship | string[] | unset โ no constraint |
country | string[] (ISO-3166 alpha-2) | unset โ no constraint |
Setting min_confidence: "low", widening linkage or setting node_type
deliberately admits candidates the default gate excludes. No filter can
admit a candidate without a point geometry and coordinates: there would be
nothing to stage.
meta.filters_applied echoes the filters actually used, defaults included, so
a response explains its own candidate count.
โถResponse
- 201 โ an
asset_task, plusmetadescribing the selection. - 400 โ
taskIdis not a UUID, or the body is invalid (includingcandidate_ids: []). - 401 / 403 โ missing or invalid key, or the key lacks
ingestions:write. - 404 โ
NOT_FOUND: the task is unknown or belongs to another organization.DISCOVERY_RESULTS_EXPIRED: the task's cached results have expired โ re-run discovery and ingest from the new task. - 409 โ
CONFLICT: the task is still processing, keep pollingโฆ/status.DISCOVERY_IDS_UNAVAILABLE: the task's results predate candidate ids, so no candidate can be named โ re-run discovery. - 422 โ
DISCOVERY_NO_CANDIDATES: nothing was admitted, so no task was created.data.detailscarries the per-candidate reasons. - 502 โ the discovery service is unavailable.
- 503: retry the request.
DISCOVERY_DELETED_CHECK_UNAVAILABLE: the check for facilities your organization deleted could not run, so nothing was created.STORAGE_ERROR: the selected candidates could not be stored.
โถRejection reasons
| Reason | Meaning |
|---|---|
unknown_candidate | No candidate in the results carries that id. |
missing_geometry | The candidate has no point geometry with coordinates. |
not_ingestable | The candidate fails the default gate (low confidence, an unaccepted precision tier, an unconfirmed link or path, or not a sourcing site). |
filtered_out | The candidate fails a filter the request set; detail names which. |
โถResponse schema โ meta
meta| Field | Type | Description |
|---|---|---|
selected | number | Candidates staged. |
rejections | array | Named candidates that could not be staged: { id, reason, detail, to_ingest }. to_ingest is the one thing that would let the candidate be staged, e.g. "confirm the supplier relationship of Trader B", or null when nothing would (a port, an office, or a site that takes processed input). |
filtered | array | Candidates the filters excluded under the ingest-all form. |
filters_applied | object | Filters used, defaulted values included. |
discovery_task_id | string | The discovery task the candidates came from. |
โถProvenance of a staged discovery row
A discovered location is recorded as not geocoded, and carries no
location_source: that field's vocabulary is customer / geocoded /
re_anchored, and a discovered point is none of those. Do not read the
ingestability gate as a statement that a location is correct โ it decides
only what is safe to stage.
โถResults can expire
A discovery task served from the response cache has no stored blob of its own.
If its cache entry has expired and no other task holds a blob for the same
query, this endpoint answers 404 DISCOVERY_RESULTS_EXPIRED. The remedy is to
re-run discovery โ the candidates are recomputed, not lost.
Required scope:
ingestions:write(this endpoint creates locations; neither discovery scope is sufficient)