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 with 400.

Body

FieldTypeRequiredDescription
location_type"facility" | "plot" | "shed"yesLocation type to stage the candidates as.
candidate_idsstring[]noCandidate ids from the results response. Omit to ingest every candidate the filters admit. An empty array is rejected with 400.
filtersobjectnoNarrow which candidates are admitted โ€” see below.
commodity_typestringnoDeclared commodity, used for any candidate that carries none.
tagsstring[]noTags applied to the created asset task.
assessmentsobjectnoAccepted 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.
supplierobjectnoUpload-wide supplier fallback for the staged rows.

Selection: named ids, or everything admitted

BodyMeaning
candidate_ids: [...]Ingest exactly these, subject to the filters.
omittedIngest 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:

FilterTypeDefault
min_confidence"high" | "medium" | "low"unset โ€” the default tier rule above
location_precisionstring[]["EXACT"]
linkage("deterministic" | "inferred" | "probabilistic")[]["deterministic"]
node_typestring[]unset: plot, primary processing and aggregation sites only. Set, it replaces that rule.
relationshipstring[]unset โ€” no constraint
countrystring[] (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, plus meta describing the selection.
  • 400 โ€” taskId is not a UUID, or the body is invalid (including candidate_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.details carries 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

ReasonMeaning
unknown_candidateNo candidate in the results carries that id.
missing_geometryThe candidate has no point geometry with coordinates.
not_ingestableThe candidate fails the default gate (low confidence, an unaccepted precision tier, an unconfirmed link or path, or not a sourcing site).
filtered_outThe candidate fails a filter the request set; detail names which.

Response schema โ€” meta

FieldTypeDescription
selectednumberCandidates staged.
rejectionsarrayNamed 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).
filteredarrayCandidates the filters excluded under the ingest-all form.
filters_appliedobjectFilters used, defaulted values included.
discovery_task_idstringThe 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)