Batch Verdict Override
Flip every subject on one axis in one call, or only the plots named in
subject_ids, instead of one PUT .../verdict-overrides per subject.
One request clears a whole consignment.
โถRequest body
{
"axis": "plot_compliance" | "legality" | "exclusion", // required
"from": "compliant" | "non_compliant", // required
"to": "compliant" | "non_compliant", // required, EXCEPT on "exclusion", which refuses it
"narrative": "max 5000 chars", // required
"reason": "max 2000 chars", // required
"subject_type": "plot" | "entity" | "record", // default "plot"
"subject_ids": ["uuid", ...], // optional, plot grain only, 1-10000
"basis": "max 200 chars", // optional
"document_attachment_id":"uuid" | null, // optional
"evidence_urls": ["https://...", ...], // optional, max 50
"valid_from": "ISO-8601" | null, // optional
"valid_to": "ISO-8601" | null // optional
}
โถfrom is required, and it is a guard, not ergonomics
from is required, and it is a guard, not ergonomicsOnly subjects whose effective verdict currently equals from
are written. The effective verdict is the active override when one
exists, else the computed verdict โ the same reading the submit
gate and the report use.
This makes the call safe to repeat. A second call with the same
from matches nothing, because the subjects it moved last time no
longer read as from. There is no separate idempotency key: from
is the guard.
โถsubject_ids narrows the batch to named plots
subject_ids narrows the batch to named plotsOmit it and every plot on the record is considered. Send it and only those
plots are, so a caller can resolve a filtered subset โ one supplier's
plots, say โ in one call. The from guard still applies to each named
plot, and every plot written still gets its own finding row.
A named plot the current version does not hold is skipped and counted in
skipped.not_on_version; a duplicate id counts once. A named plot that is
already excluded is counted on every axis, not only on exclusion: in
skipped.system_exclusion when the platform excluded it, otherwise in
skipped.already_excluded. Refused with 400 on a record-grain axis
(legality), whose only subject is the record.
โถto is refused on exclusion
to is refused on exclusionAn exclusion carries no verdict transition โ there is nothing to
move a subject to. Send axis: "exclusion" with no to field;
including one answers 400.
Every other axis requires to. Omitting it there also answers 400.
The response mirrors the request: on the exclusion axis the to
field is absent from data.attributes. It is never null.
โถResponse body
| Field | Meaning |
|---|---|
subject_ids | Every subject the call actually wrote |
affected_count | subject_ids.length |
skipped_count | Subjects considered but not written |
skipped.verdict_mismatch | Effective verdict was not from |
skipped.system_exclusion | Subject carries a provenance: "system" exclusion |
skipped.already_excluded | Subject already carries an operator exclusion: on exclusion, or a named plot on any axis |
skipped.inactive_window | Subject already carries a finding on this axis that is outside its validity window, and this call would not bring it back into force |
skipped.not_on_version | A subject_ids entry the current version does not hold |
skipped_count is the total of the five reasons.
A system exclusion is skipped, not failed. The call still answers
200 and reports the skip in skipped.system_exclusion, because a
system-owned exclusion is not this operator's to override in one call.
On the exclusion axis a subject that already carries an exclusion
written by a person (provenance manual or document) is skipped
too, and counted in skipped.already_excluded. Overwriting it would
destroy that operator's narrative, basis and backing document. The
two buckets stay apart so the caller can tell a preserved human
attestation from a platform-owned exclusion.
โถAn expired validity window is skipped, not overwritten
A subject already holding a finding on this axis whose valid_from /
valid_to window does not cover now is skipped, and counted in
skipped.inactive_window.
Such a subject reads its computed verdict, because an out-of-window
finding is retired โ so it can match from and look like a candidate. The
write, though, is an update onto that same row: the verdict would move but
the stale window would keep the row inactive. The subject would appear in
subject_ids, in affected_count and in the audit event, asserting a
transition no consumer ever reads.
The stored window is left exactly as it was. Clearing it here would discard an expiry an operator stated deliberately.
The test is the window the row ends up with, not the one you send. A
bound you omit keeps its stored value, so the skip asks whether the merged
window covers now. Send a fresh valid_to (or valid_to: null) and the
subject is written and counted in affected_count โ that is how you renew a
batch of expired clearances in one call. Send only valid_from against a row
whose valid_to is already past and it is still skipped, because the write
leaves that stale expiry in place and the row stays out of force.
On the legality axis the grain is the record itself, so a call
writes at most one row and subject_ids holds at most one id.
โถOne audit event, not N
A batch write appends exactly one config.finding_batch_set
event, whatever the plot count. It carries a null target_plot_id
and names every subject it moved in payload.subject_ids โ every
other finding action is plot-scoped and carries target_plot_id
directly.
Because it is one event, it invalidates a live submit authorisation
once, not once per plot. That is the operator-facing benefit
over issuing the single-subject PUT in a loop: a hundred plots
clearing together cost the submit grant a single invalidation, not
a hundred.
โถWhen to use this versus the single-subject PUT
PUTUse PUT .../verdict-overrides for one subject, or when subjects
need different narratives, bases, or documents. Use this endpoint
when many subjects move together for the same reason โ a single
FLEGT licence clearing a whole consignment, for example โ and the
audit trail should record that as one decision, not many.
โถErrors
| Status | Code | When |
|---|---|---|
| 400 | BAD_REQUEST | Unknown axis; missing from, narrative, or reason; to sent with axis: "exclusion"; missing to on any other axis; subject_ids empty, or sent on legality |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | Key lacks eudr:write |
| 404 | NOT_FOUND | Record is not visible to the caller |
| 409 | CONFLICT | The version is filed to TRACES and frozen |
Required scope:
eudr:write