Facility / Supplier Ingestion Workflow

End-to-end workflow for ingesting facility locations with their supplier identity attached, validating them, processing deforestation and emissions metrics, and visualizing results as a table with a map. Processing a facility resolves the supply shed and the plots beneath it, so this is the path for onboarding a supplier's footprint from a facility file.

This workflow keeps validation and metric processing as separate steps on purpose: onboarding a new supplier is exactly when you want a human review gate. You stage the facilities, inspect the confidence levels and matched fields, optionally filter out low-confidence rows, and only then commit to the metric runs. If your data is already trusted and you don't need that gate, Quick Ingestion folds processing into the upload instead.

Attaching supplier fields

This workflow's distinguishing step is binding each uploaded location to a supplier at upload time, so the data can later be rolled up per supplier (and a DDS built per supplier — see EUDR Compliance). There are two ways to supply it on POST /ingestions/assets:

Per-row supplier columns in the file — one supplier per location row. Recognised columns include supplier_name, supplier_external_id (your own id, which deduplicates the registry row), and the address fields supplier_address_line1 / supplier_address_line2 / supplier_city / supplier_region / supplier_postcode / supplier_country.

An upload-wide supplier object on the request body — applies one supplier to every row in the file:

POST /ingestions/assets
{
  "location_type": "facility",
  "commodity_type": "cocoa",
  "supplier": { "name": "Café Verde Cooperativa", "external_id": "CV-001", "country": "BR" }
}

The same supplier identity deduplicates to one registry row, so a supplier spanning several files or facilities reuses a single entry — give every upload the same identity. See Suppliers and Asset Upload — Attaching a supplier for the full field reference; the per-supplier rollup later surfaces at GET /regulations/eudr/audit-trail/:recordId/suppliers.

Use cases

New supplier onboarding — upload a supplier's facilities (with the supplier attached) and review validation results before processing metrics
Selective metric processing — review staged entities and choose which ones to process, filtering out low-confidence matches
Risk dashboard population — generate deforestation and emissions data for all locations to feed into risk dashboards
Manual review workflows — inspect validation confidence levels and correct data before committing to metric processing

Overview

Upload File ──→ Poll Validation ──→ View Validated Assets ──→ Process Metrics ──→ Poll Processing ──→ Get Assets
     │                                    (table)                                                        │
     │                                                                                                   ▼
     └── tags: batch-q1                                                              Combined Visualization (Step 7)
                                                                                      ├── Get Facilities (6a)
                                                                                      ├── Get Plots (6b)
                                                                                      ├── Get Deforestation (6c)
                                                                                      └── Get Emissions (6d)
                                                                                                 │
                                                                                                 ▼
                                                                                       HTML Table + Map

Endpoint map

Step	Method	Path	Threads to next
1	POST	`/ingestions/assets` (`location_type: facility`, supplier fields, `tags`)	task id, signed `upload_url`
1b	PUT	`{upload_url}` — the signed URL from step 1 (raw file bytes)	uploads the bytes; no API key
2	GET	`/ingestions/:id/summary` (poll until `staged`)	status + confidence counts
3	GET	`/ingestions/assets/:id?include=normalised_data,assessments`	validated assets (table)
4	PUT	`/ingestions/assets` (filter by task; `metrics:["deforestation","emissions"]`)	metrics task
5	GET	`/ingestions/:id/summary` (poll until `completed`)	—
6	GET	`/ingestions/assets/:id`	processed assets (base for the map)
6a	GET	`/locations/facilities`	facility polygons
6b	GET	`/locations/plots`	plot polygons
6c	GET	`/metrics/sheds/deforestation`	per-facility deforestation
6d	GET	`/metrics/sheds/emissions`	per-facility emissions

Step 1b is the signed-URL byte PUT — an explicit HTTP request, not a docs-UI action. Step 1 returns the signed URL in meta.client_actions[0].href (mirrored on data.attributes.upload_url); PUT the raw file bytes to it with the headers from the descriptor. The task stays pending until the upload finalises, which is what step 2 waits for. See 1 Upload Assets for the descriptor and the exact PUT headers.

Required scopes

Scope	Used by
`ingestions:write`	Steps 1, 4 (upload, metrics)
`ingestions:read`	Steps 2, 3, 5, 6 (poll + read assets)
`locations:read`	Steps 6a, 6b (facility / plot polygons)
`metrics:read`	Steps 6c, 6d (shed metrics)

Upload file format

A file of facility locations — one facility per row/feature, with a point or polygon geometry and the supplier fields above. Supported: CSV, GeoJSON / NDJSON, Parquet, GeoPackage, Shapefile (ZIP), .xlsx, .xls (up to 100 MB). Shapefiles truncate column names to 10 characters, so attach the supplier via the upload-wide supplier object rather than per-row columns. See Asset Upload for the full reference.

Steps

1. Upload Assets (`POST /ingestions/assets`)

Upload a file with supplier/facility locations. Attach tags for grouping. Returns a task ID for tracking. Entities are validated and staged asynchronously.

Frontend: Show upload confirmation with task ID.

2. Check Validation Status (`GET /ingestions/:id/summary`)

Poll until overall_status is staged. Shows entity counts by status and confidence level.

Frontend: Progress bar from status_counts. Confidence breakdown chart.

3. Get Validated Assets (`GET /ingestions/assets/:id`)

Retrieve validated entities with include=normalised_data,assessments. Display as a table with name, location, commodity, confidence, status.

Frontend: Validation results table with sortable columns and confidence badges.

4. Process Metrics (`PUT /ingestions/assets`)

Trigger deforestation and emissions batch processing on validated entities. Filter by asset_task_id to select which entities to process.

Frontend: Show "Processing N entities" confirmation.

5. Check Processing Status (`GET /ingestions/:id/summary`)

Poll until overall_status is completed. Same endpoint as Step 2.

Frontend: Processing progress bar.

6. Get Assets with Metrics (`GET /ingestions/assets/:id`)

Retrieve processed entities. This is the base data for the combined visualization.

6a. Get Facilities (`GET /locations/facilities`)

Facility polygons for map rendering. Includes geo (GeoJSON), name, country_code, area.

6b. Get Plots (`GET /locations/plots`)

Plot polygons nested within facility areas. Includes geo, commodity, producer_name, area.

6c. Get Deforestation Metrics (`GET /metrics/sheds/deforestation`)

Per-facility deforestation data: noncompliance_area, forest_area, annual_defor, area.

6d. Get Emissions Metrics (`GET /metrics/sheds/emissions`)

Per-facility emissions data: luc, nonluc, removal, soc, biogenic, area.

7. Combined Visualization

Chains steps 6a–6d using bru.runRequest() to gather all data in one request. Joins metrics to locations by facility/shed relationship IDs and renders:

Assets table with metric columns
Leaflet.js map with facility/plot polygons colored by risk
Tooltips showing metric data on click

Visualization Guide

Assets Table

Column	Source
Name	`asset_data.name` or `normalised_data.normalized_name`
Location	`normalised_data.normalized_country` + coordinates
Commodity	`normalised_data.commodity_type`
Confidence	`validation.confidence_level` + `confidence_score`
Status	`attributes.status`
Deforestation Risk	`noncompliance_area` / `area` from deforestation metrics
Forest Area (ha)	`forest_area` from deforestation metrics
LUC Emissions (tCO2e/yr)	`luc` from emissions metrics
Non-LUC Emissions (tCO2e/yr)	`nonluc` from emissions metrics

Map

Facility polygons from GET /locations/facilities → geo attribute
Plot polygons from GET /locations/plots → geo attribute
Color by risk level (deforestation noncompliance_area / area ratio)

Facility: name, country, area, noncompliance_area, forest_area, LUC emissions, non-LUC emissions
Plot: producer_name, commodity, area, noncompliance_area, forest_area, LUC emissions, non-LUC emissions

Data Joining

Metrics include relationships.facility.data or relationships.shed.data
Match these IDs to facility/plot IDs from the locations endpoints
Metric ID format: {shed_id}:{monitoring_end_date}

Prerequisites

Valid API key in x-api-key header

Facility / Supplier Ingestion Workflow

Attaching supplier fields

Use cases

Overview

Endpoint map

Required scopes

Upload file format

Steps

1. Upload Assets (POST /ingestions/assets)

2. Check Validation Status (GET /ingestions/:id/summary)

3. Get Validated Assets (GET /ingestions/assets/:id)

4. Process Metrics (PUT /ingestions/assets)

5. Check Processing Status (GET /ingestions/:id/summary)

6. Get Assets with Metrics (GET /ingestions/assets/:id)

6a. Get Facilities (GET /locations/facilities)

6b. Get Plots (GET /locations/plots)

6c. Get Deforestation Metrics (GET /metrics/sheds/deforestation)

6d. Get Emissions Metrics (GET /metrics/sheds/emissions)