Reviewing a Finding

Overview
reviewStatus and alertState
- A retired value: AUTO_REVIEWED
Setting a review note
Marking a finding reviewed
Clearing a review
What editStates tells you before you call anything
The audit trail
Categories

Overview

Reviewing a finding is a small state machine: unreviewed (either waiting for review, or never requiring it) moves to reviewed once you record a note and mark it resolved. This guide covers that state machine end to end — reviewStatus, setting and reading a note, resolving, clearing a review, the permission rules behind each step, and the audit trail a review leaves behind.

reviewStatus and alertState

Every finding carries a reviewStatus, always one of three values:

Value	Meaning
`NOT_REQUIRED`	Review was never required for this finding.
`PENDING`	Review is required and has not happened yet. Filter on this to build a work queue.
`REVIEWED`	The finding has been resolved — by a person, or by an automated process such as a rule-based auto-clear or a whitelist match.

reviewStatus is not a closed enum you can safely switch on with no default. A fourth value could be introduced later without notice, precisely so a deployment skew between two versions of this API is never fatal to a client that already has a default branch. Always keep one.

alertState is the outcome to act on: the check’s own authored result, unless the finding has been reviewed, in which case alertState always reads "Cleared" regardless of what the check originally found. Resolving a finding through this API is treated as authoritative over the check’s own outcome. Like reviewStatus, this is not a closed set of values — keep a default branch here too.

A retired value: AUTO_REVIEWED

If you integrated against an earlier version of this surface, you may have code that filters on a fourth value, AUTO_REVIEWED, for findings resolved with no person involved. That value has been retired: filter on REVIEWED with reviewer absent instead. reviewer continues to name whoever or whatever resolved the finding when that identity can be resolved to a display name, human or automated, so its absence is the closest available signal that no person was involved — though it is not a guarantee either way, since not every automated path is required to leave reviewer unset.

Setting a review note

A review note explains the decision. Set one with Set a Finding’s Review Note:

curl -X POST "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384/note" \
  -H "Authorization: Bearer your_access_token_here" \
  -H "Content-Type: application/json" \
  -d '{"reviewNote": "Confirmed with borrower via phone on 8/7; income supported by attached paystub."}'

This replaces the note outright — it’s a single current value, not a list you append to. The prior note, if any, isn’t lost; it’s still visible in the finding’s history (see below).

The note has a hard limit: 110 UTF-8 bytes, measured in bytes of the note text, not characters. Plain ASCII gets you the most room; accented characters, curly quotes, em dashes, and emoji each cost more than one byte, so a note that looks well under 110 typed characters can still be rejected. If you’re building a UI around this field, count UTF-8 bytes client-side rather than relying on your text input’s character counter.

Marking a finding reviewed

Once a note exists, Mark a Finding Reviewed sets reviewStatus to REVIEWED:

curl -X POST "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384/resolve" \
  -H "Authorization: Bearer your_access_token_here" \
  -H "Content-Type: application/json"

A finding cannot be resolved with no note recorded — calling this before a note exists is a 400. That’s a real ordering requirement, not a suggestion: set the note first, every time.

Clearing a review

Clear a Finding’s Review State undoes both the note and the resolved state in one call — reviewStatus goes back to whatever it would otherwise be (PENDING or NOT_REQUIRED), and reviewNote goes back to null:

curl -X POST "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384/reset" \
  -H "Authorization: Bearer your_access_token_here" \
  -H "Content-Type: application/json"

alertState reverts to the check’s own original outcome once the finding is no longer REVIEWED — it doesn’t stay "Cleared" after a reset.

What editStates tells you before you call anything

Every finding carries an editStates block naming which of the calls above will currently succeed for whoever is asking — evaluated fresh on every request, so two different users looking at the same finding can see different keys.

Key	Present when
`note`	You may update this finding’s review note.
`resolve`	You may mark the finding reviewed and a note already exists.
`reset`	You hold both the review permission and the note permission — resetting clears both fields, so it needs both.
`attachment`	You may modify this finding’s attachments (see Attachments).

Keys are independent — don’t infer one from another. A user permitted to update the note but not resolve the finding sees note only, with resolve/reset/attachment all absent. And editStates itself can be missing entirely if none of the four are available to you right now.

editStates is for discovery, not enforcement — every endpoint it points to re-checks your permission on its own, since nothing stops you from constructing the URL directly without reading editStates first. Use it to decide what UI to show or what to attempt, not as a substitute for handling a 403 you get anyway.

The audit trail

Every change to reviewed or reviewedNotes is recorded, and you can read it back with Get a Finding’s History:

curl -X GET "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384/history" \
  -H "Authorization: Bearer your_access_token_here"

{
  "workflowId": "wfpop_0000000000002082611",
  "findingId": "fndg_0000000000006051384",
  "history": [
    {
      "field": "reviewed",
      "previousValue": "false",
      "newValue": "true",
      "reviewer": "Jane Reviewer",
      "changedAt": "2026-08-07T15:04:09Z"
    },
    {
      "field": "reviewedNotes",
      "previousValue": null,
      "newValue": "Confirmed with borrower via phone on 8/7; income supported by attached paystub.",
      "reviewer": "Jane Reviewer",
      "changedAt": "2026-08-07T15:01:42Z"
    }
  ],
  "links": {
    "self": { "href": "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384/history" },
    "finding": { "href": "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384" }
  }
}

Each entry is one field change, not one save. The note-then-resolve sequence above produced two calls and appears here as two entries, newest first — the note-setting entry sits below the resolve entry because it happened earlier. An edit that changes two fields in a single call (like a reset) produces two entries sharing the same reviewer and changedAt.

previousValue is worth reading carefully: it’s null, explicitly, when there’s nothing to report — not the same thing as an empty string, which would mean the prior value was actually blank text. This is the one field on a history entry that distinguishes those two cases.

This trail is capped at 500 entries and is not paginated. If a finding somehow accumulates more than 500 field changes, anything past the cap is simply not retrievable through this endpoint — there’s no next page to ask for. This is a safety bound, not something any real finding is expected to approach.