# API FAQs

### Understand deforestation risk

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

<details>

<summary>Response</summary>

`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):

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

**Example: fetch plots including `riskLevel`**

```bash
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)

</details>

#### How do I find LOW-risk plots via API?

<details>

<summary>Response</summary>

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:

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

**Step 1) Fetch plots including `riskLevel`**

```bash
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:

```bash
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'
```

</details>

### Set assessment status on Plots & Suppliers

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

<details>

<summary>Response</summary>

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](https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/api-reference/risk-assessments/plot-risk-assessments/create-a-plot-risk-assessment) Use when your business has not created a plot risk assessment for that plot yet.

```bash
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](https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/api-reference/risk-assessments/plot-risk-assessments/update-a-plot-risk-assessment) Use when a plot risk assessment already exists and you want to change its status.

```bash
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:

```bash
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.

</details>

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

<details>

<summary>Response</summary>

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 (](https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/api-reference/risk-assessments/supplier-risk-assessments/create-a-supplier-risk-assessment)`POST`), or
* [updating an existing supplier risk assessment ](https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/api-reference/risk-assessments/supplier-risk-assessments/update-a-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.

```bash
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.

```bash
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).

</details>

### Build transactions from reviewed plots

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

<details>

<summary>Response</summary>

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

1. List plots from a supplier (and its upstream) and filter by `riskAssessmentStatus`
2. Extract the `plotIds` from the response
3. 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.)

```bash
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.

```bash
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).

</details>