A flag-clear request acknowledges a review of one flag. It should be the result of an authorized decision, not an automatic side effect of opening a record. Keep the original answer, the review action and any separate activity decision distinguishable in your interface.
Show only what the reviewer needs
Retrieve the relevant waiver using waivers:read and identify the specific flag. Full record retrieval contains personal information and is access-logged. Do not fetch or expose all participant answers on a queue-facing status screen just to show that a review remains outstanding.
The reviewer should understand the flag’s label and the task assigned under the organization’s process. A highlighted row is not enough if nobody knows which role owns the next decision.
Clear the specific flag after review
Use the waiver ID and flag ID from the authorized record. The mutation requires waivers:write:
POST /v1/waivers/{id}/flags/{flagId}/clear
Authorization: Bearer YOUR_API_KEY
The flag-clear response includes id, waiverId and clearedAt. The flag row remains, and the answer that raised it is not changed. Treat the timestamp as evidence of this review action rather than deletion of the issue’s history.
Separate interface states
Use a pending state while the request is in flight and disable accidental repeated activation. If the response is uncertain, inspect the current record before issuing another mutation. Do not optimistically remove the row in a way that makes the operator believe a review was saved when it was not.
An appropriate interface distinguishes “review requested,” “review action recorded” and “request failed.” It should not rename the successful state to “approved for all activities” unless a separate organizational process actually supports that statement.
Verify the audit meaning
Test a record with more than one flag and ensure only the intended flag is targeted. Reopen the record after success and confirm the review state is visible without losing the original answer. Test a user or key without the required scope and ensure the interface presents the permission issue clearly.
For staff procedures, pair this implementation with private front-desk review. For API failures, preserve the request identifier from the error envelope while keeping participant values out of routine logs.