Contestation API spec
Endpoints, required fields, and the receipt returned on filing.
Contestation APIs
Let the person decided about, or someone acting for them, challenge a decision through a published API and get an answer by a deadline. An upheld challenge changes the decision.
- 1 Evidence
- 2 Authority
- 3 Decision
- 4 Consequence
- 5 Challenge acts here
- 6 Reconsideration
- 7 Correction
Where it acts
At Challenge, one of the seven stages every consequential decision passes through. It lets a person, or someone acting for them, dispute a decision through an interface that must answer by a deadline.
Steps
Put the mechanism in motion
4 steps, in order. Check each one off as it is done; the records below show the work was done.
0 of 4 steps complete
Records this mechanism keeps
What a team running this mechanism keeps, and what each record is for.
Receipt and status schema
The status updates a challenger receives, and the escalation details each one carries.
State-change log
Each upheld challenge, the decision it reversed, and the remedy given.
Standing register
Who may challenge what, with admissible evidence, obliged responder, deadline, standard of review, and possible transitions.
Reuse-ready snippets
Copy policy, audit, and incident language
Use these snippets in requirements, audits, and postmortems with the mechanism permalink.
Policy requirement
Policy requirement (MEC-08 Contestation APIs) - Publish a challenge API with an obliged responder and an answer deadline, and let an upheld challenge change the decision's state without manual re-entry. - Publish the standing register: who may challenge what, the admissible evidence, the responder, the deadline, and the standard of review. - Count upheld challenges by the rule that produced the decision, and send the count to the rule's owner. Reference: https://ethotechnics.org/mechanisms/patterns/contestation-apis
Product requirement
Product requirement (MEC-08) - Each challenge returns a receipt naming the responder, the deadline, and where it escalates if the deadline passes. - An upheld challenge updates the decision's state and notifies the person it concerns. - Each upheld challenge records the reason code of the rule it overturned.
Audit evidence checklist
Audit evidence checklist (MEC-08) [ ] The API contract and its authentication policy are versioned. [ ] Receipts carry timestamps, the responder, and the escalation path. [ ] State-change logs link each upheld challenge to the decision it changed and the remedy given. [ ] Upheld challenges are counted by rule, and the count reaches each rule's owner.
Postmortem trigger
Postmortem trigger (MEC-08) Trigger review when an upheld challenge has not changed the decision's state by the deadline.
Example usage
A challenge API for eligibility reversals
One scenario with each part of the mechanism in place.
How it plays out
A benefits platform lets legal aid groups file challenges for their clients through an API. Each filing returns a receipt naming the eligibility unit as responder and a 72-hour deadline. When a reviewer upholds a challenge, eligibility updates with no re-entry, and the upheld count for that rule goes to its owner.
Anti-patterns
Common failure cases and counterfactuals
Each case passes on paper and fails in operation. The counterfactual shows what would have worked.
Challenges that change nothing
Challenges are accepted and even upheld, but the decision record never changes, so the person stays denied.
Counterfactual: An upheld challenge writes to the decision's state through the same workflow that made the decision.
Exception: A manual update is acceptable when the log shows it landed before the deadline.
Channel without standing
The API accepts submissions but never says who is entitled to a response, by when, or against what standard it will be judged.
Counterfactual: The contract names the responder, the deadline, the standard of review, and the transitions a successful challenge can produce.
Exception: A broad standing rule is fine; leaving standing unstated is not.
Diagnostics for this mechanism
Tools that size the risk this mechanism addresses.
Diagnostic
Delegation audit
Walks a team through one workflow against six questions and returns an exposure score, the permissions nobody can justify, and whether its decisions can be undone. Start here when the system keeps no decision records yet; use the record conformance checker once it does.
Cite this page · v1.2.1 · updated Oct 6, 2026 · CC BY-SA 4.0
APA
Ethotechnics Institute. (2026). Contestation APIs (MEC-08). Ethotechnics Institute. https://ethotechnics.org/mechanisms/patterns/contestation-apis
MLA
Ethotechnics Institute. "Contestation APIs (MEC-08)." Ethotechnics Institute, 2026, https://ethotechnics.org/mechanisms/patterns/contestation-apis.
Chicago
Ethotechnics Institute. "Contestation APIs (MEC-08)." Ethotechnics Institute. Oct 6, 2026. https://ethotechnics.org/mechanisms/patterns/contestation-apis.
BibTeX
@misc{mechanism_contestation-apis,
title={Contestation APIs (MEC-08)},
author={Ethotechnics Institute},
year={2026},
howpublished={Ethotechnics Institute},
url={https://ethotechnics.org/mechanisms/patterns/contestation-apis},
version={v1.2.1}
}
RIS
TY - WEB TI - Contestation APIs (MEC-08) AU - Ethotechnics Institute PY - 2026 UR - https://ethotechnics.org/mechanisms/patterns/contestation-apis ER -