API FAQs

Common API workflows for plot & supplier risk: read deforestation risk, set your assessment status for plots and suppliers, and build transactions using only reviewed plots.

Understand deforestation risk

What is `riskLevel` and how should I use it?

Response

riskLevel is a computed field derived from plot analyses and exposed to both the Web App and API. It is returned on a Plot only when you explicitly request it via ?includes=riskLevel.

Important: riskLevel is system-computed (read-only signal). riskAssessmentStatus is customer-controlled (your assessment) and is set via Plot Risk Assessments.

What `riskLevel` represents

TradeAware computes riskLevel from the most relevant available analysis for a plot:

If a PRECISION analysis exists, it overrides Open Source (OS) for the purpose of riskLevel.
If there is no PRECISION analysis, the system uses the OS analysis.

This matches the behavior in the Web App, so customers can automate based on what they see in the UI.

How `riskLevel` is calculated

Case 1: PRECISION analysis exists (overrides OS)

risk > 0 → riskLevel = high
risk = 0 → riskLevel = none

Case 2: No PRECISION analysis (use OS)

risk > 0 → riskLevel = medium
risk = 0 → riskLevel = low

Processing / not ready yet (null vs missing)

If you do not include includes=riskLevel, the riskLevel field may be absent from the response (because you didn’t request it).
If you do include includes=riskLevel and the plot has no completed analysis yet, riskLevel can be null. Treat this as “not ready yet” and retry later.

How API users should use `riskLevel` (best practice)

When building automations based on analysis results (example: you may choose to mark LOW-risk plots as compliant based on your internal policy):

Request plots with includes=riskLevel
Filter for the values you care about (low, medium, high, none)
If riskLevel is null, do not act yet (analysis not ready / not available)

Example: fetch plots including riskLevel

curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/plots?includes=riskLevel&page=1&limit=500' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Accept: application/json'

Example filtering rules (customer-defined policy)

If riskLevel == "low" → some customers choose to set riskAssessmentStatus = EUDR_COMPLIANT
If riskLevel == null → analysis not ready / not available → do not act yet
If riskLevel == "medium" or "high" → typically requires review/mitigation (customer decision)
If riskLevel == "none" → indicates “no risk” when PRECISION is present (per the logic above)

How do I find LOW-risk plots via API?

Response

This FAQ explains how to retrieve plots and identify the ones with riskLevel = low, so you can apply your own follow-up actions.

Concept

riskLevel is returned only when explicitly requested via includes=riskLevel. Recommended flow:

Fetch plots with includes=riskLevel
Filter client-side for riskLevel: "low"
Treat riskLevel: null as “not ready yet” (skip / retry later)

Step 1) Fetch plots including `riskLevel`

curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/plots?includes=riskLevel&page=1&limit=500' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Accept: application/json'

Step 2) Filter for `riskLevel = "low"`

In your integration/script, keep only plots where:

riskLevel == "low"

Also handle:

riskLevel == null → analysis not ready / not available → skip / retry later

Pagination

If you have more than 500 plots, repeat the request with the next page:

curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/plots?includes=riskLevel&page=2&limit=500' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Accept: application/json'

Set assessment status on Plots & Suppliers

How do I create or update a Plot `riskAssessmentStatus`?

Response

This FAQ covers how an API user can set/update the plot “Status” shown in the UI (e.g., UNDER_REVIEW, EUDR_COMPLIANT) — i.e., the plot risk assessment status set by the assessing business.

Concept (system vs customer-controlled)

riskLevel is computed by TradeAware from analyses (read-only signal).
riskAssessmentStatus is your assessment, stored as a separate entity (Plot Risk Assessment).

Even though riskAssessmentStatus appears on the Plot object, it is managed through a separate entity (a Plot Risk Assessment). TradeAware does not set this status automatically when analyses complete. To change it, you must create or update a plot risk assessment.

Supported values

NEW, UNDER_REVIEW, IN_RISK_MITIGATION, EUDR_COMPLIANT, EUDR_NON_COMPLIANT

A) Create a Plot Risk Assessment (first time you set a status)

API Reference: POST /plot-risk-assessments Use when your business has not created a plot risk assessment for that plot yet.

curl --request POST \
  --url 'https://api.tradeaware.live-eo.com/plots/{plotId}/plot-risk-assessments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "status": "EUDR_COMPLIANT",
    "notes": "Marked compliant after internal review"
  }'

notes is optional (max length: 1000)
The response returns an id — store it. This is the plot risk assessment id you need for updates.

B) Update a Plot Risk Assessment (change an existing status)

API Reference: PATCH /plot-risk-assessments Use when a plot risk assessment already exists and you want to change its status.

curl --request PATCH \
  --url 'https://api.tradeaware.live-eo.com/plot-risk-assessments/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "status": "UNDER_REVIEW",
    "notes": "Waiting for supporting documents"
  }'

{id} is the plot risk assessment id (returned when you create the plot risk assessment), not the plot id.

Bulk updates

There is no bulk endpoint for plot risk assessments. You must call the create/update endpoints per plot.

How do I find the plot risk assessment id (`{id}`) later?

If you don’t have the id saved from the creation response, fetch plots and include the riskAssessmentStatus relation:

curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/businesses/{businessId}/plots?includes=riskAssessmentStatus&page=1&limit=500' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Accept: application/json'

Then, for the plot you want to update:

find the plot by its plot id
read riskAssessmentStatus.id → use this value as {id} in PATCH /plot-risk-assessments/{id}

If riskAssessmentStatus is missing for a plot, no plot risk assessment exists yet for your business → use Create (POST) first.

How do I create or update a Supplier `riskAssessmentStatus`?

Response

This FAQ explains how API users can set / update the status of a supplier risk assessment (e.g., UNDER_REVIEW, EUDR_COMPLIANT) for a supplier business.

Concept

Supplier status is managed via a separate entity called Supplier Risk Assessment. You set the status by:

creating a supplier risk assessment for a supplier (POST), or
updating an existing supplier risk assessment (PATCH).

Supported values

NEW, UNDER_REVIEW, READY_FOR_ASSESSMENT, CMS_ASSESSMENT_REQUESTED, CMS_ASSESSMENT_COMPLETED, IN_RISK_MITIGATION, EUDR_COMPLIANT, EUDR_NON_COMPLIANT

*For CMS_ASSESSMENT_REQUESTED, CMS_ASSESSMENT_COMPLETED require entitlements.

A) Create a Supplier Risk Assessment (first time you set a status)

Use this when your business has not created a supplier risk assessment for that supplier yet.

curl --request POST \
  --url 'https://api.tradeaware.live-eo.com/businesses/{supplierId}/supplier-risk-assessments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "status": "UNDER_REVIEW",
    "notes": "Initial assessment started",
    "attachmentIds": []
  }'

Notes:

notes is optional (max length: 1000).
attachmentIds is optional. If you include it, provide the full list (the API treats it atomically). To remove all attachments, set "attachmentIds": [].

Response: returns the supplier risk assessment id plus supplierId and buyerId.

B) Update a Supplier Risk Assessment (change an existing status)

Use this when a supplier risk assessment already exists and you want to update its status, notes, or attachments.

curl --request PATCH \
  --url 'https://api.tradeaware.live-eo.com/supplier-risk-assessments/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "status": "EUDR_COMPLIANT",
    "notes": "Approved after review",
    "attachmentIds": []
  }'

Important:

{id} is the supplier risk assessment id (returned when you create the supplier risk assessment), not the supplier business id.
attachmentIds is atomic: always send the full list you want stored.

Bulk updates

The public endpoints above are single-resource operations. If you need to apply a status to many suppliers, you must iterate supplier-by-supplier (create or patch per supplier risk assessment).

Build transactions from reviewed plots

How do I create a Transaction using only `EUDR_COMPLIANT` plots?

Response

If you want to create a transaction that includes only plots whose riskAssessmentStatus (set by your business) is EUDR_COMPLIANT, the recommended flow is:

List plots from a supplier (and its upstream) and filter by riskAssessmentStatus
Extract the plotIds from the response
Create the transaction using those plotIds

This is useful when you want the transaction to include only plots you have already reviewed and marked compliant in TradeAware.

1) Fetch EUDR_COMPLIANT plots for a supplier (and upstream)

Use the “List all plots of your supplying business and upstream” endpoint and apply filter.riskAssessmentStatus.

Note: the API uses the query parameter format filter.riskAssessmentStatus=... with operations like $eq. Use EUDR_COMPLIANT as the value. (Docs show $eq as supported.)

curl --request GET \
  --url 'https://api.tradeaware.live-eo.com/businesses/{businessId}/plots?filter.riskAssessmentStatus=$eq:EUDR_COMPLIANT&page=1&limit=500' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Accept: application/json'

businessId = your direct supplier business id
Response returns plots supplied by that business (including upstream)
Each plot object includes the plot id (this is what you put into plotIds)
riskAssessmentStatus values include: NEW, UNDER_REVIEW, IN_RISK_MITIGATION, EUDR_COMPLIANT, EUDR_NON_COMPLIANT

2) Extract plot IDs

From the response, collect the id values of all returned plots. These are the plotIds you will include in the transaction request.

3) Create the transaction with those `plotIds`

Use POST /transactions and include the selected plot IDs inside each component.

curl --request POST \
  --url 'https://api.tradeaware.live-eo.com/transactions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "customId": "DEC-24-238620",
    "activityType": "EXPORT",
    "countryOfActivity": "IT",
    "legalEntityId": "123e4567-e89b-12d3-a456-426614174000",
    "components": [
      {
        "hsn": "1201",
        "quantity": 123.45,
        "unit": "KGM",
        "description": "text",
        "namePairs": [
          { "commonName": "soybean", "scientificName": "Glycine max" }
        ],
        "dateOfProduction": "2021-01-01T00:00:00.000Z",
        "endDateOfProduction": "2022-01-01T00:00:00.000Z",
        "supplierBusinessId": "02c36247-1aad-41ba-aa49-f114ca4c263f",
        "plotIds": [
          "a78c1a68-d326-4217-a131-893f3c47a064",
          "e8d2e3e6-2c7c-4c4e-98a9-3e3f4e2c1a68"
        ],
        "ddsReferences": [
          { "id": "24DKYIGLPU3439", "verificationNumber": "4NAB3QYM" }
        ]
      }
    ],
    "isGeoLocationConfidential": false,
    "customData": {
      "key1": "someValue",
      "key2": true,
      "key3": 1234
    },
    "status": "DRAFT"
  }'

Can I bulk-update plot status to EUDR_COMPLIANT via one API call? No — currently only single create/update exists for plot risk assessments. Automation requires iterating plot-by-plot (create or patch per plot risk assessment).

PreviousVersion NextContact Support

Last updated 1 day ago

hashtagUnderstand deforestation risk

hashtagWhat is riskLevel and how should I use it?

hashtagWhat riskLevel represents

hashtagHow riskLevel is calculated

hashtagHow API users should use riskLevel (best practice)

hashtagHow do I find LOW-risk plots via API?

hashtagConcept

hashtagStep 1) Fetch plots including riskLevel

hashtagStep 2) Filter for riskLevel = "low"

hashtagPagination

hashtagSet assessment status on Plots & Suppliers

hashtagHow do I create or update a Plot riskAssessmentStatus?

hashtagConcept (system vs customer-controlled)

hashtagSupported values

hashtagA) Create a Plot Risk Assessment (first time you set a status)

hashtagB) Update a Plot Risk Assessment (change an existing status)

hashtagBulk updates

hashtagHow do I find the plot risk assessment id ({id}) later?

hashtagHow do I create or update a Supplier riskAssessmentStatus?

hashtagConcept

hashtagSupported values

hashtagA) Create a Supplier Risk Assessment (first time you set a status)

hashtagB) Update a Supplier Risk Assessment (change an existing status)

hashtagBulk updates

hashtagBuild transactions from reviewed plots

hashtagHow do I create a Transaction using only EUDR_COMPLIANT plots?

hashtag1) Fetch EUDR_COMPLIANT plots for a supplier (and upstream)

hashtag2) Extract plot IDs

hashtag3) Create the transaction with those plotIds

Understand deforestation risk

What is `riskLevel` and how should I use it?

What `riskLevel` represents

How `riskLevel` is calculated

How API users should use `riskLevel` (best practice)

How do I find LOW-risk plots via API?

Concept

Step 1) Fetch plots including `riskLevel`

Step 2) Filter for `riskLevel = "low"`

Pagination

Set assessment status on Plots & Suppliers

How do I create or update a Plot `riskAssessmentStatus`?

Concept (system vs customer-controlled)

Supported values

A) Create a Plot Risk Assessment (first time you set a status)

B) Update a Plot Risk Assessment (change an existing status)

Bulk updates

How do I find the plot risk assessment id (`{id}`) later?

How do I create or update a Supplier `riskAssessmentStatus`?

Concept

Supported values

A) Create a Supplier Risk Assessment (first time you set a status)

B) Update a Supplier Risk Assessment (change an existing status)

Bulk updates

Build transactions from reviewed plots

How do I create a Transaction using only `EUDR_COMPLIANT` plots?

1) Fetch EUDR_COMPLIANT plots for a supplier (and upstream)

2) Extract plot IDs

3) Create the transaction with those `plotIds`