Recording appeals about your AI's decisions

When a person affected by a decision your AI made asks for a human review, an explanation or a correction, record the request and your answer with ComplyEdge. They are kept next to that decision, so you can show that you replied, how, and when.

Enterprise plan. Two calls: one when the request arrives, one when your team answers. Python SDK complyedge 0.2.26 or later, TypeScript SDK @complyedge/sdk 0.2.10 or later, or plain HTTP.

1. The whole integration

You already keep the event_id of each decision (section 6). Then:

import os
from complyedge import ComplyEdge

ce = ComplyEdge(api_key=os.environ["COMPLYEDGE_API_KEY"])

# 1. When the person asks (ticket created). Safe to retry.
ticket.complyedge_request_id = ce.record_appeal(
    decision.complyedge_event_id, "human_intervention",
    requested_at=ticket.created_at,
)

# 2. When your team answers (ticket solved). Safe to retry.
ce.record_answer(
    ticket.complyedge_request_id, "upheld",
    statement_ref=f"ticket:{ticket.id}", reviewer=f"staff:{ticket.assignee_id}",
)

That is all. The agent and the system version are read from the decision. The due date is worked out for you, and a late appeal shows on the dashboard and in list_appeals(). The sections below explain each value, the law behind it, and how to wire a help desk.

2. How it works in your app

Take an app where an AI agent turns down a loan application. The person affected should be able to ask a person to look at it. Your app gives them that option and handles it. ComplyEdge keeps the record.

  1. 1. Your app shows the option. Next to the AI's decision, a button such as "Ask a person to review this", or a support form that names the decision.
  2. 2. The person uses it. Your backend opens a ticket in your own support tool, as it would for any request, and sends ComplyEdge one request record that points at the decision by its event_id. It keeps the request id that comes back on the ticket.
  3. 3. Your team handles it in your own tool. Their message, the review and your reply to them stay in your systems. ComplyEdge never sees the text.
  4. 4. Your team closes the ticket. Your backend sends ComplyEdge the answer with that request id: the outcome, who reviewed it and the ticket id of the reply you sent the person.

Nobody has to open the dashboard for this to work. The Appeals page is the record: each request, the decision it is about, when the answer is due, and the answer once your app sends it. Show it to an auditor who asks whether, how and when you answered. Requests and answers are also in your audit trail export.

3. Why record it here

Months after your AI turned someone down, they complain to a regulator or a court, and you are asked to show that you answered their request, and in time. A support ticket shows someone wrote in. It does not show which AI decision they meant, and your own systems can be edited after the fact.

How long it is kept: appeals follow your account's audit retention, 184 days unless you lengthen it on Enterprise. The decision was logged first, so it expires first. Set the retention to cover the time a person can still complain or go to court.

What it cannot do: ComplyEdge only knows the requests your app sends. It cannot show that you recorded every request you received. That part is your process.

4. When the answer is due

The GDPR asks you to answer without undue delay, and within one month at the latest. ComplyEdge works out that latest date for each request, following the European Data Protection Board's guidelines on the right of access (paragraphs 160 and 161):

Dates are counted in UTC and end at the end of the day. A request near midnight can fall on another day in UTC than where you are, so the due date can be a day earlier or later than your own count: answer by the due_at the API returns. In Python, a datetime without a time zone is read as UTC, so send times with their zone. The month runs from requested_at, so send the time the person actually wrote in, such as your ticket's created time, not the time your code runs.

The dashboard flags a request with no answer by its due date, on the Appeals page and on the Status page, and marks an answer recorded after it. It never calls either a breach. To check from your own code, for example in a daily job:

for appeal in ce.list_appeals("open"):
    if appeal["late"]:
        alert(f"Appeal {appeal['request_id']} was due {appeal['due_at']}")

5. What the law says

These rights belong to the person. The law puts the duty to honour them on you, and asks you to be able to prove it. Whether a right applies to your system depends on the conditions written into each article.

Human review, the person's view, and contesting: GDPR Article 22(3)

"In the cases referred to in points (a) and (c) of paragraph 2, the data controller shall implement suitable measures to safeguard the data subject’s rights and freedoms and legitimate interests, at least the right to obtain human intervention on the part of the controller, to express his or her point of view and to contest the decision."

Article 22(1) sets the scope: a decision "based solely on automated processing, including profiling, which produces legal effects concerning him or her or similarly significantly affects him or her". Regulation (EU) 2016/679 on EUR-Lex

An explanation: GDPR Article 15(1)(h), or EU AI Act Article 86

For a decision made solely by automated means, the right to an explanation comes from the GDPR, with its one-month deadline. Article 15(1)(h) gives the person:

"the existence of automated decision-making, including profiling, referred to in Article 22(1) and (4) and, at least in those cases, meaningful information about the logic involved, as well as the significance and the envisaged consequences of such processing for the data subject."

The EU AI Act adds a right to an explanation for decisions taken on the basis of a high-risk AI system, where no other EU law already gives it. Article 86(1):

"Any affected person subject to a decision which is taken by the deployer on the basis of the output from a high-risk AI system listed in Annex III, with the exception of systems listed under point 2 thereof, and which produces legal effects or similarly significantly affects that person in a way that they consider to have an adverse impact on their health, safety or fundamental rights shall have the right to obtain from the deployer clear and meaningful explanations of the role of the AI system in the decision-making procedure and the main elements of the decision taken."
"This Article shall apply only to the extent that the right referred to in paragraph 1 is not otherwise provided for under Union law." (Article 86(3))

Article 86 sets no deadline of its own. Use explanation for either; for an Article 86 request the dashboard uses the GDPR's month as a guide, not as the law's date. Check whether Article 86 applies to your system yet: the Act's rules for high-risk systems listed in Annex III apply from 2 December 2027, and a system already in service before then is covered only after a significant change in its design (Article 111(2), as amended by Regulation (EU) 2026/1744). Regulation (EU) 2024/1689 on EUR-Lex

A correction of their data: GDPR Article 16

"The data subject shall have the right to obtain from the controller without undue delay the rectification of inaccurate personal data concerning him or her. Taking into account the purposes of the processing, the data subject shall have the right to have incomplete personal data completed, including by means of providing a supplementary statement."

The deadline: GDPR Article 12(3)

"The controller shall provide information on action taken on a request under Articles 15 to 22 to the data subject without undue delay and in any event within one month of receipt of the request. That period may be extended by two further months where necessary, taking into account the complexity and number of the requests. The controller shall inform the data subject of any such extension within one month of receipt of the request, together with the reasons for the delay. Where the data subject makes the request by electronic form means, the information shall be provided by electronic means where possible, unless otherwise requested by the data subject."

Refusing a request: GDPR Article 12(4) and 12(5)

"If the controller does not take action on the request of the data subject, the controller shall inform the data subject without delay and at the latest within one month of receipt of the request of the reasons for not taking action and on the possibility of lodging a complaint with a supervisory authority and seeking a judicial remedy."

You need a legal ground to refuse: for example, the right does not apply to this decision, or the request is manifestly unfounded or excessive. Article 12(5):

"Where requests from a data subject are manifestly unfounded or excessive, in particular because of their repetitive character, the controller may either: (a) charge a reasonable fee taking into account the administrative costs of providing the information or communication or taking the action requested; or (b) refuse to act on the request. The controller shall bear the burden of demonstrating the manifestly unfounded or excessive character of the request."

Platform work reviews: Directive (EU) 2024/2831, Article 11(2)

"The digital labour platform shall respond to such request by providing the person performing platform work with a sufficiently precise and adequately substantiated reply in the form of a written document, which may be in electronic form, without undue delay and in any event within two weeks of receipt of the request."

Member States apply this directive from 2 December 2026, through their own laws. Directive (EU) 2024/2831 on EUR-Lex

Proving it: GDPR Article 5(2)

"The controller shall be responsible for, and be able to demonstrate compliance with, paragraph 1 (‘accountability’)."

Not covered by these records: an objection under GDPR Article 21, to processing based on Article 6(1)(e) or (f). It is still a request: tell the person what you did within one month (Article 12(3)). Stop the processing unless you show compelling legitimate grounds or need it for legal claims, and always stop for direct marketing (Article 21(3)). Also outside these records: restricting the data while its accuracy is checked (Article 18(1)(a)), and telling those you shared the data with about a correction (Article 19). Other laws give similar rights in their own fields, for example the Consumer Credit Directive (EU) 2023/2225, Article 18(8), and Colorado's AI law, C.R.S. 6-1-1705. When the same request is also a GDPR request, as a loan refused by automated means usually is, use the matching kind above so its one-month date is tracked. Use review only when no GDPR right applies. The open Rulebook maps each record field to the articles it serves.

6. Keep the event_id of every decision

An appeal points at a decision by its event_id, the one every /v1/check returns. Save it next to your own record of the decision, as audit reconciliation describes. Without it you cannot say which decision the person is appealing.

result = ce.check(answer, direction="output", agent_id="credit-assistant",
                  decision_context={"deciding_system": {"version": "2026.10.1"},
                                    "purpose_ref": "purpose:credit-decisions",
                                    "data_categories": ["financial"]})
decisions.save(applicant_id, outcome="declined", complyedge_event_id=result.event_id)

Send the system version with the decision, as above, and the appeal can read it from there. If the decision has none, pass system_version to record_appeal.

7. Record the request when it arrives

When the person asks, for example by pressing "Ask a person to review this" in your app or by writing to your support team, send one request record. Choose the kind that matches what they asked for. If you are unsure, use human_intervention.

Python

ticket.complyedge_request_id = ce.record_appeal(
    decision.complyedge_event_id,   # the decision's event_id
    "human_intervention",
    requested_at=ticket.created_at, # when they wrote in; the month runs from here
)

TypeScript

import { ComplyEdgeClient } from '@complyedge/sdk';

const ce = new ComplyEdgeClient({ apiKey: config.complyedgeApiKey });

ticket.complyedgeRequestId = await ce.recordAppeal({
  decisionId: decision.complyedgeEventId,
  kind: 'human_intervention',
  requestedAt: ticket.createdAt,
});

HTTP

POST /v1/audit/contest
{ "decision_ref": "uuid-of-decision", "request_kind": "human_intervention",
  "requested_at": "2026-11-13T08:44:00Z" }

200
{ "event_id": "uuid-of-request", "event_type": "contest", "already_recorded": false }

8. Record your answer

A person at your company reconsiders the decision itself, using your own record of it. When your team closes the ticket, your app sends the answer with the request id it kept. Records are never overwritten: the answer is a second record next to the request. Send:

OutcomeUse it whenShown as
upheldYou considered the request and the decision stands. For an explanation request: you gave the explanation. For a request to give their view: you heard it. For a correction: the data was right and stays as it was. That is a refusal to correct, so treat it like refused: give the reasons and the right to complain, within one month.Decision stands, Explanation given, View heard, Data kept as it was
rectifiedYou changed the decision, or for a correction, the data it used. Send rectified_at.Decision corrected, Data corrected
withdrawnThe person withdrew the request.Request withdrawn
refusedYou will not act on the request, on a legal ground (section 5). Your reply must give the reasons and tell the person they can complain to a supervisory authority and go to court. Due within one month, even after an extension (Article 12(4)).Request refused
extendedYou told the person you need more time, and why. This is not the answer: the appeal stays open, now due three months after the request, until you send one of the outcomes above. It counts only if you told them within the first month (Article 12(3)).Extended

Python

ce.record_answer(
    ticket.complyedge_request_id, "upheld",
    statement_ref=f"ticket:{ticket.id}", reviewer=f"staff:{ticket.assignee_id}",
)

TypeScript

await ce.recordAnswer(ticket.complyedgeRequestId, {
  outcome: 'upheld',
  statementRef: `ticket:${ticket.id}`,
  reviewer: `staff:${ticket.assigneeId}`,
});

HTTP

POST /v1/audit/reviews/uuid-of-request/answer
{ "review_outcome": "rectified", "statement_ref": "ticket:88213",
  "reviewer": "staff:4471", "rectified_at": "2026-11-14T15:10:00Z" }

200
{ "event_id": "uuid-of-answer", "event_type": "contest",
  "request_id": "uuid-of-request", "already_recorded": false }

To tell the person you need more time, send extended with a reference to the message that gave the reasons, then the real answer later to the same request id:

ce.record_answer(request_id, "extended",
    statement_ref="ticket:88213-delay", reviewer="staff:4471")
# later
ce.record_answer(request_id, "upheld",
    statement_ref="ticket:88213", reviewer="staff:4471")

9. Connect your help desk

Most teams already handle these requests in a help desk. Two webhooks from it to your backend are enough. In Zendesk:

  1. 1. Add three ticket fields. A text field for the request id, filled by your backend. A text field for the decision's event_id, filled by your app when it opens the ticket, and a dropdown "Appeal outcome" whose option values are upheld, rectified, withdrawn, refused and extended. Your team picks the outcome when they reply.
  2. 2. A trigger when an appeal ticket is created calls a webhook to your backend with {{ticket.id}}, {{ticket.created_at_with_timestamp}} and the decision field, {{ticket.ticket_field_DECISION_FIELD_ID}}. Your backend calls record_appeal and saves the request id on the ticket.
  3. 3. A trigger when the outcome field changes calls a second webhook with {{ticket.id}}, {{ticket.ticket_field_OUTCOME_FIELD_ID}}, {{ticket.assignee.id}} and {{ticket.updated_at_with_timestamp}}, used as the time a correction took effect. Your backend calls record_answer.
# Your webhook handlers. The JSON body is the one you set in each trigger;
# zendesk is your own Zendesk API client.
from datetime import datetime

@app.post("/webhooks/appeal-opened")
def appeal_opened(p: dict):
    request_id = ce.record_appeal(p["decision_event_id"], "human_intervention",
                                  requested_at=p["created_at"])
    zendesk.set_field(p["ticket_id"], REQUEST_ID_FIELD, request_id)

@app.post("/webhooks/appeal-answered")
def appeal_answered(p: dict):
    request_id = zendesk.get_field(p["ticket_id"], REQUEST_ID_FIELD)
    set_at = at(p["updated_at"])  # when your team set the outcome
    appeal = ce.get_appeal(request_id)["review"]
    recorded = [at(a["responded_at"]) for a in appeal["answers"] + appeal["extensions"]]
    if any(t > set_at for t in recorded):
        return  # a late retry of an older outcome: a newer one is already recorded
    ce.record_answer(request_id, p["outcome"],
                     statement_ref=f"ticket:{p['ticket_id']}",
                     reviewer=f"staff:{p['assignee_id']}",
                     responded_at=set_at,
                     rectified_at=set_at if p["outcome"] == "rectified" else None)

def at(value: str) -> datetime:
    return datetime.fromisoformat(value.replace("Z", "+00:00"))

Both calls are safe to retry, so a webhook that fires twice records each step once, and a retry that arrives after a newer outcome is skipped. Other help desks work the same way: a field for the decision, a field for the outcome, and two webhooks. Zendesk's placeholders: Zendesk Support placeholders reference.

10. References, errors and reading back

decision_ref, statement_ref and reviewer are references, never content: no spaces, not an email address, not a password or API key. Use ids such as ticket:88213 or staff:4471. Anything else is refused with 422.

StatusWhenWhat to do
403Your plan has no rights records.Enterprise plan.
404No request with that id on your account.Check the id you kept, or find it with list_appeals.
422A value is wrong: a time in the future (more than five minutes ahead), responded_at before the request, rectified_at missing, not allowed or before the request, a reference that is not an id, decision_facts_missing when the decision was not found and you sent no agent and version, decision_facts_mismatch when the agent_id you sent did not make the decision, or decision_ref_not_a_decision when you sent an appeal's id as the decision.Fix the value. The message names the field. Do not retry as is.
503The record could not be written or read.Retry, unless the code is review_not_recorded: then trying again will not help, so contact support. The code is e.code in Python, which also marks it retryable=False, and err.response.data.detail.code in TypeScript.

The SDKs raise these with the API's own message: ComplianceError in Python, the request error in TypeScript with the message in error.message. The appeal calls always raise when the API cannot be reached or answers with an error. They never return an empty id, whatever fail_mode is set to. In Python, retryable says whether to try again: true for a network failure and a 503, false for 403, 404, 422 and review_not_recorded. The status is in the message.

from complyedge import ComplianceError

try:
    request_id = ce.record_appeal(event_id, "human_intervention",
                                  requested_at=ticket.created_at)
except ComplianceError as e:
    if e.retryable:
        queue_retry(ticket.id)  # same requested_at, so the retry is recorded once
    else:
        alert(f"appeal not recorded for ticket {ticket.id}: {e} (code {e.code})")
    raise

To read appeals back: list_appeals(status) / listAppeals(status) (GET /v1/audit/reviews?status=open|answered|all, late ones first) and get_appeal(request_id) / getAppeal(requestId), which also return the decision (GET /v1/audit/reviews/{request_id}). Each appeal carries due_at, late and answered_late.

11. Where to read more