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

Only 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

Omit 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

An 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

FieldMeaning
subject_idsEvery subject the call actually wrote
affected_countsubject_ids.length
skipped_countSubjects considered but not written
skipped.verdict_mismatchEffective verdict was not from
skipped.system_exclusionSubject carries a provenance: "system" exclusion
skipped.already_excludedSubject already carries an operator exclusion: on exclusion, or a named plot on any axis
skipped.inactive_windowSubject 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_versionA 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

Use 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

StatusCodeWhen
400BAD_REQUESTUnknown axis; missing from, narrative, or reason; to sent with axis: "exclusion"; missing to on any other axis; subject_ids empty, or sent on legality
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENKey lacks eudr:write
404NOT_FOUNDRecord is not visible to the caller
409CONFLICTThe version is filed to TRACES and frozen

Required scope: eudr:write