DEVELOPER GUIDE

View as Markdown

Beta

Getting Started

Overview

This guide takes you from a workflow you already have to a finding you’ve reviewed. You read the workflow’s summary to see how it scores, fetch its findings, pick one that needs attention, check what you’re allowed to change, record your review in one call, and then read the summary again to see the score move.

You need a workflow to point this at. If you don’t have one yet, see the Getting Started in the Sessions and Workflows guide for how a workflow is created. Every call below takes the same workflowId you already use elsewhere for that workflow.

Step 1: Read the workflow’s summary

Start with the summary. It tells you how the workflow scores and how its findings break down by severity, without returning the findings themselves.

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

{
  "workflowId": "wfpop_0000000000002082611",
  "score": 78,
  "severityCounts": [
    { "severity": "HIGH", "reviewed": false, "count": 1 },
    { "severity": "MEDIUM", "reviewed": true, "count": 3 },
    { "severity": "CLEAR", "reviewed": true, "count": 8 }
  ],
  "reports": [
    {
      "name": "report.pdf",
      "contentType": "application/pdf",
      "links": {
        "download": {
          "src": "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/reports/_latestpdf/content"
        }
      }
    }
  ]
}

The summary is worked out each time you read it, so it always reflects the findings as they are now. Reading it changes nothing, and it’s safe to poll.

Reading the score

score reads backwards from what you’d expect: higher is worse. Don’t build a “higher is better” health indicator on it.

score runs from 0 to 99. 75 and above means there are unreviewed findings of HIGH severity. The workflow above scores 78 because of its one unreviewed HIGH finding.

score can be missing. When the workflow’s data can’t be scored right now, the key is left out. Treat a missing score as “not known yet”, never as 0, and never as a sign that the workflow has no findings. severityCounts and reports are still there.

Reading the rest of the summary

severityCounts has one entry for each combination of severity and reviewed that occurs in the workflow, with a count of the findings that have it. { "severity": "HIGH", "reviewed": false, "count": 1 } above is the finding this guide goes on to review. severity isn’t a closed set of values, so handle a severity you don’t recognize rather than dropping it. For the same tallies split out by category, with counts of outstanding reviews, see Get a Workflow’s Category Counts.

reports lists the workflow’s generated report, or is [] when none has been generated yet. It’s metadata only.

Don’t follow reports[].links.download just to check whether a report exists. Reading the reports array has no side effects, but fetching the download records that the report was read and acknowledges the workflow’s pending report notification. On some configurations it also regenerates the report. Download the report only when a person wants the document. See Get a Workflow’s Findings Summary.

Step 2: Get the workflow’s findings

The score tells you there’s something to review; the findings tell you what. The simplest way to get them is the flat list: every finding in the workflow, with no category grouping.

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

The workflow has twelve findings. The sample below shows only the one this guide works with.

{
  "workflowId": "wfpop_0000000000002082611",
  "findings": [
    {
      "findingId": "fndg_0000000000006051384",
      "code": "HP.ST",
      "displayName": "High-priority stated income mismatch",
      "category": ["Income"],
      "references": [
        { "correlationId": "borrower-1", "type": "person" },
        { "correlationId": "subject-property", "type": "property" }
      ],
      "severity": "HIGH",
      "result": "Fail",
      "resultOrOverriddenResult": "Fail",
      "userMessage": ["Stated income does not match the verified source document."],
      "userSuggestion": ["Confirm the applicant's income against the attached document before proceeding."],
      "reviewed": false,
      "reviewRequired": true,
      "updatedAt": "2026-08-07T14:52:10Z",
      "hasAttachments": true,
      "hasHistory": true,
      "authorization": {
        "allow": [
          "riskinsight:JournalResolvedValueReview",
          "riskinsight:JournalResolvedValueUpdateNote",
          "riskinsight:JournalResolvedValueUpdateAttachment"
        ]
      }
    }
  ]
}

If you want findings grouped the way the workflow owner organized them, see Get a Workflow’s Findings by Category. The flat list, the categorized view and a direct GET of one finding all return the same Finding object, field for field, so pick whichever shape fits what you’re building.

Step 3: Pick a finding that needs attention

A finding needs attention when reviewRequired is true and reviewed is false. The finding above is in that state. Filter on both fields to build a work queue: neither answers the question alone. Reading reviewed with reviewRequired explains all four combinations.

severity tells you what to prioritize, and result tells you what the check concluded: HIGH and Fail here. Neither is a closed set of values: a workflow configured differently, or an older finding, can carry a value you don’t recognize. Keep a default branch rather than assuming you’ve seen every value that will ever appear.

userMessage and userSuggestion are the message and next steps written for a person. Show them to whoever does the review.

Step 4: Check what you’re allowed to change

The finding’s authorization.allow says what you may change, one token per permission you hold:

Token Lets you
riskinsight:JournalResolvedValueReview Mark the finding reviewed or unreviewed, and override its result.
riskinsight:JournalResolvedValueUpdateNote Set, replace or clear its review note.
riskinsight:JournalResolvedValueUpdateAttachment Add or remove its attachments.

The caller above holds all three. Offer a person only the changes their tokens allow.

authorization.allow is worked out for whoever is asking, on every request. Two users looking at the same finding can see different tokens, so a missing token is a fact about the caller, not about the finding. And it is a guide, not a guarantee: every call checks permission again, so be ready for a 403 even when the token is there (for example, when you may not update the workflow).

Step 5: Record your review

Send a note and mark the finding reviewed in one POST to the finding’s own address:

curl -X POST "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384" \
  -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.", "reviewed": true}'

This call needs both the note permission and the review permission, because it changes both fields. If either is missing, the whole call is refused with a 403 and nothing changes.

The response is the updated finding. It now reads "reviewed": true and carries your reviewNote, and it usually names a reviewer. reviewRequired stays true, so the finding has moved from outstanding to review done. result still reads Fail: reviewing a finding doesn’t change its result. To record a different outcome, send overrideResult too; see Reviewing a Finding.

Step 6: Read the summary again

Read the summary again with the same call as in Step 1:

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

{
  "workflowId": "wfpop_0000000000002082611",
  "score": 13,
  "severityCounts": [
    { "severity": "HIGH", "reviewed": true, "count": 1 },
    { "severity": "MEDIUM", "reviewed": true, "count": 3 },
    { "severity": "CLEAR", "reviewed": true, "count": 8 }
  ],
  "reports": [
    {
      "name": "report.pdf",
      "contentType": "application/pdf",
      "links": {
        "download": {
          "src": "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/reports/_latestpdf/content"
        }
      }
    }
  ]
}

The HIGH finding now counts as reviewed, and with nothing left unreviewed the score drops from 78 to 13, below 75. You don’t need to wait or refresh anything for this: the next read reflects the review.

Next steps

Copyright © Pitchpoint Solutions. All rights reserved.