> For the complete documentation index, see [llms.txt](https://docs.live-eo.com/tradeaware/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/assess-risk-in-your-supply-chain.md). # Assess risk in your supply chain ### What is risk assessment in TradeAware? Risk assessment splits into two halves over the API, and they use different endpoints. TradeAware calculates an Automated Supplier Risk Score from 0 to 100 for each of your suppliers, based on the deforestation analysis of their plots and the due diligence questionnaires they have submitted. You read it from the supplier connections endpoint, and it is read-only. Once you have reviewed what the score is pointing at, you record your decision as a supplier or plot risk assessment — a status, notes, and any documents you want attached. Those you write through the risk assessment endpoints. This record, not the score, is what your audit trail is built from. Note: only your business can see risk statuses and their notes, for both suppliers and plots. So can only your business see which questionnaire answers were flagged. Your suppliers cannot see any of it. ### What the Automated Supplier Risk Score is not Three boundaries to preserve in anything built on top of it. It is not a compliance verdict. The score is a prioritisation signal, and the due diligence decision on each supplier and each shipment remains the operator's. Do not surface it downstream as an approve-or-reject flag. It does not classify countries. Country risk classification under the EUDR is a European Commission determination under Article 29. Nothing in TradeAware, and nothing a supplier answers, changes a country's benchmarked risk level. It does not replace Article 9. Per-shipment information — product description, quantity, plot geolocations, production dates, and evidence of legal and deforestation-free production — is required whatever the risk level, and is handled by the plot and transaction endpoints. See [Manage your transactions](https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/manage-your-transactions). ### ⚠️ Prerequisites Examples below use the production base URL and a bearer token. See[ Authentication](http://../authentication) for obtaining one, and[ Endpoints enabled for programmatic access](https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/authentication/endpoints-enabled-for-programmatic-access) for machine-to-machine coverage. Reading the risk score requires the canViewSupplierRiskScore entitlement on your account. It defaults to false. Entitlements are returned by GET /users/me, and only for a human-authenticated client: ``` curl -L \ --url 'https://api.tradeaware.live-eo.com/users/me' \ --header 'Authorization: Bearer JWT' ``` The response carries an `entitlements` object containing `canViewSupplierRiskScore`. If it is false and you expected scoring, contact your Customer Success Manager. A machine-to-machine token cannot read this. Entitlements are returned for human clients only, so an m2m integration has no way to check the entitlement before building. Detect it from the data instead: if the score fields come back null or absent across every supplier connection — including ones you know have analysed plots or submitted questionnaires — treat the entitlement as absent. Writing supplier and plot risk assessments does not require that entitlement. Setting the two CMS statuses requires `canManageCmsSupplierRiskAssessmentStatuses`. Note also that the supplier and plot risk assessment endpoints are not currently on the list of[ endpoints enabled for programmatic access](https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/authentication/endpoints-enabled-for-programmatic-access) via an OAuth 2.0 machine-to-machine client. Check that list before building a write path around them. #### Two assessment routes, and what each returns Which of these your account has determines what you get back, so check before building against the score. **Automated scoring on the EUDR Due Diligence Questionnaire.** The supplier submits the questionnaire, TradeAware scores it and combines it with the deforestation analysis of their plots, and the result is the `riskScore` described below. **CMS legal review, available as an add-on.** A specialist legal review carried out by people, running on its own questionnaires which the supplier completes separately. It produces no score. The outcome is recorded through the supplier risk assessment status, using `CMS_ASSESSMENT_REQUESTED` and `CMS_ASSESSMENT_COMPLETED`. CMS responses are not part of the automated calculation. Two consequences for an integration: * On a **CMS-only** account there is no automated score to read. Build for status and attachments, not for riskScore. * On an account with both, the questionnaire drives the score across every supplier and CMS is the escalation route for individual ones. A completed CMS review does not move riskScore — only the status and the attached report change. ### Reading the Automated Supplier Risk Score The score is returned with each supplier connection, rather than as a resource of its own. ``` curl -L \ --url 'https://api.tradeaware.live-eo.com/business-connections/suppliers' \ --header 'Authorization: Bearer JWT' ``` This returns every connection between your business and your suppliers, each with its current score and the supply chain context behind it: ``` [ { "id": "3f2b91c4-77ad-4a1e-9f0b-2c5d8e6a1b33", "sourceBusiness": { "id": "9d78ac05-038b-49c0-a35c-6295669138d8", "name": "Your Business GmbH" }, "targetBusiness": { "id": "1cdaa481-2136-4b4d-b2cc-e996a49c24d0", "name": "Example Cocoa Ltd" }, "createdAt": "2026-03-04T09:12:00.000Z", "updatedAt": "2026-08-09T02:15:44.000Z", "customData": { "internalVendorId": "V-10024" }, "plotsCount": 47, "plotsCommodities": ["cocoa"], "riskScore": 34, "isRiskScorePartial": false, "partialRiskScoreReasons": { "missingPlots": false, "missingSurveys": false }, "plotRiskLevelsBreakdown": { "none": 2, "low": 4, "medium": 23, "high": 8, "processing": { "OS": 9, "PRECISION": 1 } } } ] ``` The score is on the supplier direction only. GET /business-connections/buyers returns the same connection shape without any of the score fields — your buyers do not carry a score you can read. #### Response fields | Field | Type | Description | | ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `riskScore` | number \| null | The Automated Supplier Risk Score, 0 to 100, where 0 is the lowest risk. null when there is nothing to score, or when your account lacks the entitlement. | | `isRiskScorePartial` | boolean \| null | true when the evidence behind the score does not cover every sourcing country. null when your account lacks the entitlement. See [Handling partial scores](https://docs.google.com/document/d/175tseSTK6feARc4zBlS-yVK8cRMwX0jGwuHeR0FReZI/edit#heading=h.az6h65uaqx3h). | | `partialRiskScoreReasons` | object \| null | Which side of the picture is incomplete: missingPlots and missingSurveys, each a boolean. null when your account lacks the entitlement. | | `plotRiskLevelsBreakdown` | object | Distribution of the supplier's plots by deforestation risk level, plus a processing object counting plots still being analysed, split by OS and PRECISION. | | `plotsCount` | number | Total plots in this supplier's supply chain. | | `plotsCommodities` | string\[] | Commodities produced across this supplier's supply chain. | | `customData` | object | Your own metadata for this business connection. Only visible to the buyer who set it. | #### Entitlement, nulls, and generated clients Three things about the shape of this response that will save you a debugging session. Treat both null and an absent key as "no score available." The four score fields are marked required in the OpenAPI schema, so a strict reading says the keys are always present with null values where there is nothing to report. Do not rely on that. Write the check as "is there a usable number here", not "does the key exist", and neither branch should be treated as a data error. riskScore can be null even though the schema types it as a number. isRiskScorePartial and partialRiskScoreReasons are declared nullable; riskScore is not, despite defaulting to null. If you are using a generated client or a typed SDK, it will most likely type this field as a non-nullable number and fail at runtime on an unscored supplier. Widen the type by hand. plotRiskLevelsBreakdown is an untyped object in the schema. The keys documented above — none, low, medium, high and processing — come from the example, not from a defined shape, so a generated client will hand you a free-form map. Read defensively and do not assume every key is present. #### Four things to build around **The score belongs to the relationship, not to the supplier.** It sits on the connection between your business and that supplier, and is calculated from the data visible in your supply chain. Two buyers of the same supplier can legitimately see different scores. Key it by connection. **Do not confuse the two ids.** The id at the top of each object is the connection id. The supplier's business id is targetBusiness.id, and that is what the risk assessment endpoints take as supplierId. **The score is read-only.** No endpoint writes riskScore, and it cannot be overridden. It moves only when the data underneath it moves — so if you want to influence it, change the data. Marking a plot as EUDR compliant, for example, takes that plot out of the supplier's detection count. **The endpoint takes no query parameters.** There is no server-side filtering, sorting or pagination, and no page-size cap — one call returns every supplier connection you have, each with a nested business object and the plot breakdown. On a large supplier base that is a substantial response, so fetch it once and filter client-side rather than per-supplier: ``` curl -sL \ --url 'https://api.tradeaware.live-eo.com/business-connections/suppliers' \ --header 'Authorization: Bearer JWT' \ | jq '[.[] | select(.riskScore != null and .riskScore > 0)] | sort_by(-.riskScore)' ``` ### Interpreting the score The score has two components: deforestation risk and legal risk. When both have data, they are weighted equally — the score is the average of the two. When only one has data, the score is that component on its own; the missing component is not treated as zero. A supplier with analysed plots and no submitted questionnaire is scored purely on deforestation risk, and a supplier with a submitted questionnaire and no plots purely on legal risk. Deforestation risk is the share of the supplier's analysed plots carrying a positive detection. Plots still being analysed are excluded from both the numerator and the denominator — they are counted separately in `plotRiskLevelsBreakdown.processing` . Precision results are used where available and open-source screening results otherwise, and a plot marked as EUDR compliant no longer counts as a positive detection. This means `plotsCount` is not the denominator. `plotsCount` is every plot in the supplier's supply chain; the deforestation component is calculated over `none + low + medium + high` in `plotRiskLevelsBreakdown`. Where analysis is still running the two can differ substantially, so compare them if you want to know how much of the supplier the score actually covers. Legal risk comes from the supplier's submitted EUDR Due Diligence Questionnaire responses. Each response is scored from 0 to 100, where 0 means none of its scoreable questions were answered in a way that indicates risk and 100 means all of them were. The supplier's legal risk is the average of their submitted response scores. Only completed, non-archived responses are included, and a response's score is fixed at submission. CMS questionnaire responses are excluded entirely. Because it is an average, response count matters: a second, cleaner questionnaire from the same supplier pulls their legal risk down even if the first one is unchanged. Read the number of responses alongside the score. Two suppliers can therefore carry the same score for very different reasons — one from detections on plots, one from flagged answers, one from a bit of each. `isRiskScorePartial` and `partialRiskScoreReasons` tell you which, so read them alongside the score rather than after it. No country weighting is applied in this release: a plot in a country benchmarked low risk by the European Commission contributes exactly as much as a plot in a high-risk country. Nor is the deforestation component weighted by area — a 0.3-hectare plot and a 300-hectare plot count the same. Treat the current score as geography- and size-blind. One consequence worth designing for now: a score can change without any change to the supplier data you sent. Recalculation is triggered by events on our side, and the methodology will develop over releases. If you cache the value or threshold on it, make a shift something your integration absorbs rather than treats as an incident. #### Mapping to the badge in the web app If you are mirroring the TradeAware interface, the badge is a direct function of the score: exactly 0 shows as Low, and anything above 0 shows as Medium. There is deliberately no High state, and integrations should not synthesise one. In particular, do not map the score onto a severity level that triggers automated supplier actions downstream — blocking, deprioritising, or flagging a supplier as non-compliant. The score is a triage signal indicating where a human should look, and treating it as an approve-or-reject flag misrepresents what it measures. ### Handling partial scores `isRiskScorePartial` tells you whether the evidence behind the score covers everywhere the supplier operates. The two reasons in `partialRiskScoreReasons` are independent, and either or both can be true: * `missingPlots` — the supplier has completed a questionnaire for at least one country but has registered no plots in that country. Geographic evidence for that country is absent. * `missingSurveys` — the supplier has plots in a country not covered by a completed, non-archived questionnaire. The legal declaration for that country is absent. **The score itself is never held back or reduced because of a gap.** It is always calculated from everything available at the moment of calculation — every analysed plot across every country, and every submitted questionnaire — and recalculated as more arrives. Nor is the calculation scoped by country: a questionnaire for one country and plots in another both feed the same single score. So the flag and the number answer different questions, and you should surface both wherever you surface either. The number is a real reading of the evidence held; the flag tells you how much of the supplier that evidence covers. A score covering three of five sourcing countries says nothing about the other two. In the web app the same information is delivered as banners on the supplier's Plots and Questionnaires tabs, naming the countries. The API gives you the two booleans, not the country names. Where the supplier has nothing to score at all, riskScore is null. This is an empty state and is distinct from partial, which means some countries are covered and others are not. Do not coerce a null score to 0 — an absent score and a zero score mean opposite things, and conflating them will make unscored suppliers look clean. ### Keeping scores up to date TradeAware recalculates a score when the data underneath it changes: an analysis completing, a questionnaire being submitted, a plot being deleted, or a new business connection being created. Marking a plot as EUDR compliant is different: it takes effect immediately rather than waiting on a recalculation, because compliant plots are simply subtracted from the detection count at read time. **There is no webhook event for automated risk score changes.** Web app users receive an in-app notification when their suppliers' scores move; there is no API equivalent. To keep a downstream system in sync, poll `GET /business-connections/suppliers` on a schedule and diff against your last snapshot. Because recalculation is event-driven rather than continuous, a daily poll is enough for most workflows, and hourly is the most any integration should need. The endpoint returns your whole supplier base in one call, so a tight polling loop buys you nothing and risks being throttled.
### Recording your assessment Once you have reviewed a score, record your decision as a supplier risk assessment. Each supplier has at most one assessment record from your business. Create it with POST the first time; after that, update it with `PATCH`. Posting a second assessment for a supplier that already has one returns `400`. Supplier risk assessments carry a status, notes of up to 1000 characters, and attachments. The statuses are: * **NEW** — the default status when you connect with a supplier for the first time. * **UNDER\_REVIEW —** you have started looking at the data the supplier provided. * **READY\_FOR\_ASSESSMENT** — the supplier has provided their data and is ready to assess. * **CMS\_ASSESSMENT\_REQUESTED** — a request to CMS to assess the provided data. Requires the CMS entitlement. * **CMS\_ASSESSMENT\_COMPLETED** — CMS have completed their assessment. Requires the CMS entitlement. * **IN\_RISK\_MITIGATION** — a risk assessment has been completed and mitigation actions are ongoing. * **EUDR\_COMPLIANT** — the supplier has been assessed as compliant with EUDR. * **EUDR\_NON\_COMPLIANT** — the supplier has been assessed as non-compliant with EUDR. #### Create a Supplier Risk Assessment Create a risk assessment for a supplier with the following request, using the supplier's business id — `targetBusiness.id` from the connections response, not the connection id. ``` curl -L \ --request POST \ --url 'https://api.tradeaware.live-eo.com/businesses/{supplierId}/supplier-risk-assessments' \ --header 'Authorization: Bearer JWT' \ --header 'Content-Type: application/json' \ --data '{ "status": "NEW", "notes": "text" }' ``` `status, notes` and `attachmentIds` are all optional, so you can add notes without setting a status, set a status without notes, or attach evidence at creation. The status defaults to **NEW**. When successfully created you will see a response like the following. This includes an id for the supplier risk assessment. ``` { "id": "22cd2eab-ce2a-47e3-9dad-aae40735711c", "status": "NEW", "notes": "Still providing information", "createdAt": "2025-05-13T15:13:48.801Z", "updatedAt": "2025-05-13T15:13:48.801Z", "supplierId": "1cdaa481-2136-4b4d-b2cc-e996a49c24d0", "buyerId": "9d78ac05-038b-49c0-a35c-6295669138d8", "attachments": [] } ``` #### Update a Supplier Risk Assessment Update an assessment using its own id: ``` curl -L \ --request PATCH \ --url 'https://api.tradeaware.live-eo.com/supplier-risk-assessments/{id}' \ --header 'Authorization: Bearer JWT' \ --header 'Content-Type: application/json' \ --data '{ "status": "UNDER_REVIEW", "notes": "text" }' ``` The response echoes the updated record: ``` { "id": "22cd2eab-ce2a-47e3-9dad-aae40735711c", "status": "UNDER_REVIEW", "notes": "I have the data now and we can start to investigate.", "createdAt": "2025-05-13T15:13:48.801Z", "updatedAt": "2025-05-13T15:18:01.173Z", "supplierId": "1cdaa481-2136-4b4d-b2cc-e996a49c24d0", "buyerId": "9d78ac05-038b-49c0-a35c-6295669138d8", "attachments": [] } ``` #### Attaching evidence Supporting documents, a legal opinion, a CMS report, a supplier certificate — are attached by id. Upload the file through the [Attachments](http://../file-upload-attachments) endpoints first, then reference the ids on the assessment. attachmentIds works on both POST and PATCH. ``` curl -L \ --request PATCH \ --url 'https://api.tradeaware.live-eo.com/supplier-risk-assessments/{id}' \ --header 'Authorization: Bearer JWT' \ --header 'Content-Type: application/json' \ --data '{ "status": "EUDR_COMPLIANT", "notes": "Legal opinion received, plot detections reviewed and cleared.", "attachmentIds": [ "c1dbc78d-a127-454a-961b-ef30becf37fd", "a8593d6b-1d23-47d0-9396-72d1a4862d19" ] }' ``` Setting attachmentIds is atomic, so always send the full list for the assessment. Sending a subset removes the ones you left out, and sending an empty array removes all of them. Removing an attachment from an assessment does not delete the attachment itself — for that, see the API documentation on Attachments. #### Retrieve Supplier Risk Assessments Retrieve one assessment by its id: ``` curl -L \ --url 'https://api.tradeaware.live-eo.com/supplier-risk-assessments/{id}' \ --header 'Authorization: Bearer JWT' ``` Or all of them in one go: ``` curl -L \ --url 'https://api.tradeaware.live-eo.com/supplier-risk-assessments' \ --header 'Authorization: Bearer JWT' ``` These endpoints return your assessment records only. They do not include the automated risk score, which lives on `GET /business-connections/suppliers`. To build a combined view, join the two on `supplierId` and `targetBusiness.id`. #### Retrieve the History The examples above show only the current status and note. Retrieve the full history using the assessment id: ``` curl -L \ --url 'https://api.tradeaware.live-eo.com/supplier-risk-assessments/{id}/history' \ --header 'Authorization: Bearer JWT' ``` Using the previous example, this returns: ``` [ { "entityId": "22cd2eab-ce2a-47e3-9dad-aae40735711c", "changedByUserType": "USER", "changedByUser": null, "action": "CREATE", "changedAt": "2025-05-13T15:13:48.815Z", "beforeData": null, "afterData": { "id": "22cd2eab-ce2a-47e3-9dad-aae40735711c", "status": "NEW", "notes": "Still providing information", "createdAt": "2025-05-13T15:13:48.801Z", "updatedAt": "2025-05-13T15:13:48.801Z", "supplierId": "1cdaa481-2136-4b4d-b2cc-e996a49c24d0", "buyerId": "9d78ac05-038b-49c0-a35c-6295669138d8" } }, { "entityId": "22cd2eab-ce2a-47e3-9dad-aae40735711c", "changedByUserType": "USER", "changedByUser": null, "action": "UPDATE", "changedAt": "2025-05-13T15:18:01.176Z", "beforeData": { "id": "22cd2eab-ce2a-47e3-9dad-aae40735711c", "status": "NEW", "notes": "Still providing information", "createdAt": "2025-05-13T15:13:48.801Z", "updatedAt": "2025-05-13T15:13:48.801Z", "supplierId": "1cdaa481-2136-4b4d-b2cc-e996a49c24d0", "buyerId": "9d78ac05-038b-49c0-a35c-6295669138d8" }, "afterData": { "id": "22cd2eab-ce2a-47e3-9dad-aae40735711c", "status": "UNDER_REVIEW", "notes": "I have the data now and we can start to investigate.", "createdAt": "2025-05-13T15:13:48.801Z", "updatedAt": "2025-05-13T15:18:01.173Z", "supplierId": "1cdaa481-2136-4b4d-b2cc-e996a49c24d0", "buyerId": "9d78ac05-038b-49c0-a35c-6295669138d8" } } ] ``` `changedByUserType` records what made each change — `USER, M2M or SYSTEM` — which is useful for telling apart a status a colleague set in the web app from one written by an integration. Note that the history covers your assessment record. It is not a history of the automated score, and there is no endpoint that returns how a score has moved over time. ### Risk assessment for plots Plots work much the same way as suppliers, with one difference: plot risk assessments carry a status and notes only. Attachments are supported on supplier risk assessments, not on plot ones. The plot statuses are **NEW, UNDER\_REVIEW, IN\_RISK\_MITIGATION, EUDR\_COMPLIANT and EUDR\_NON\_COMPLIANT**. NEW is the default when a plot is first added. Notes are limited to 1000 characters. Setting a plot to **EUDR\_COMPLIANT** is the one assessment action that changes a supplier's automated score. That plot is excluded from the positive detections in the supplier's deforestation risk, and the change takes effect immediately — the next read of GET /business-connections/suppliers returns the new score. No recalculation cycle is involved. #### Create a Plot Risk Assessment ``` curl -L \ --request POST \ --url 'https://api.tradeaware.live-eo.com/plots/{plotId}/plot-risk-assessments' \ --header 'Authorization: Bearer JWT' \ --header 'Content-Type: application/json' \ --data '{ "status": "NEW", "notes": "text" }' ``` Both `status` and `notes` are optional. The status defaults to NEW. #### Update a Plot Risk Assessment ``` curl -L \ --request PATCH \ --url 'https://api.tradeaware.live-eo.com/plot-risk-assessments/{id}' \ --header 'Authorization: Bearer JWT' \ --header 'Content-Type: application/json' \ --data '{ "status": "EUDR_COMPLIANT", "notes": "text" }' ``` #### Retrieve Plot Risk Assessments One assessment by id: ``` curl -L \ --url 'https://api.tradeaware.live-eo.com/plot-risk-assessments/{id}' \ --header 'Authorization: Bearer JWT' ``` All of them: ``` curl -L \ --url 'https://api.tradeaware.live-eo.com/plot-risk-assessments' \ --header 'Authorization: Bearer JWT' ``` #### Retrieve the history ``` curl -L \ --url 'https://api.tradeaware.live-eo.com/plot-risk-assessments/{id}/history' \ --header 'Authorization: Bearer JWT' ``` Plot risk assessment status is also available as a filter and an include on the business-plots endpoint — `filter.riskAssessmentStatus` and `includes=riskAssessmentStatus` on `GET /businesses/{businessId}/plots` — which is the practical way to pull every plot of a supplier that you have already cleared or that still needs review. ### Not available via the API in this release A few things are visible in the web app but not yet returned by the API, so you can plan around them. Only the combined riskScore is exposed. The separate deforestation and legal components, and the score of each individual questionnaire response, are not returned — plotRiskLevelsBreakdown is the closest available proxy for the deforestation side. The individual flagged answers driving legal risk are likewise not available programmatically. There is no webhook for score changes, and no history of score movements; poll instead, as described in [Keeping scores up to date](https://app.gitbook.com/o/LVp69MjrJJ3k89rpETv6/s/benSEfMyYbRWLaKU6iTs/~/edit/~/changes/272/using-the-tradeaware-api/assess-risk-in-your-supply-chain#keeping-scores-up-to-date). There is no server-side filtering, sorting or pagination by score. Country risk level is not part of this release in either the web app or the API. Recommended actions and risk report export are also not in this release. For common integration patterns, see [API FAQs](http://../api-faqs). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.live-eo.com/tradeaware/using-the-tradeaware-api/assess-risk-in-your-supply-chain.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.