DEVELOPER GUIDE

Beta

Getting Started

Overview

This guide takes you from a workflow you already have to a finding you’ve reviewed. You fetch the workflow’s findings, look at one that needs attention, check whether you’re allowed to act on it, and record your review.

You need a workflow to point this at. If you don’t have one yet, see 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: Get the workflow’s findings

The simplest starting point 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"

{
  "workflowId": "wfpop_0000000000002082611",
  "findings": [
    {
      "findingId": "fndg_0000000000006051384",
      "code": "HP.ST",
      "displayName": "High-priority stated income mismatch",
      "category": ["Income"],
      "severity": "HIGH",
      "alertState": "Alert",
      "userMessage": ["Stated income does not match the verified source document."],
      "userSuggestion": ["Confirm the applicant's income against the attached document before proceeding."],
      "reviewStatus": "PENDING",
      "reviewNote": null,
      "hasAttachments": true,
      "hasHistory": false,
      "links": {
        "self": { "href": "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384" },
        "history": { "href": "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384/history" },
        "attachments": { "href": "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384/attachments" }
      },
      "editStates": {
        "note": {
          "href": "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611/findings/fndg_0000000000006051384/note",
          "method": "POST"
        }
      }
    }
  ]
}

If you’d rather start from a summary — just the workflow’s computed score and severity breakdown, no findings — see Get a Workflow’s Findings Summary in the reference. If you want findings grouped the way the workflow owner organized them, see Get a Workflow’s Findings by Category. All three return the same Finding object field for field — pick whichever shape fits what you’re building.

score reads backwards from what you’d expect: higher is worse. 75 and above means there are unreviewed HIGH-severity findings sitting in this workflow. Don’t build a “higher is better” health indicator on it.

Step 2: Look at one finding that needs attention

The finding above has "reviewStatus": "PENDING" — review is required and hasn’t happened yet. That’s the value to filter on to build a work queue: findings with "reviewStatus": "NOT_REQUIRED" never needed a look in the first place, and "REVIEWED" ones are already handled.

severity and alertState tell you what to prioritize and what the check itself concluded — "HIGH" and "Alert" here. Neither is a closed set of values on the wire: a workflow configured differently, or a legacy row, can carry a value you don’t recognize. Always 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 these to whoever is doing the review.

Step 3: Check what you’re allowed to do

editStates names which of this finding’s mutation endpoints will currently succeed if you call them, evaluated fresh for whoever is asking. The finding above carries only note — this caller can record a review note but cannot yet mark it reviewed. That’s not a mistake: Mark a Finding Reviewed requires a note to already exist, so resolve only appears in editStates once one has been recorded.

Each key in editStates is independent. Holding permission for note says nothing about resolve, reset, or attachment — check whichever key you’re about to act on, not just whether the block is present at all.

editStates is generated against the logged-in user’s own permissions, not the finding’s. If the user making the call doesn’t have permission to add notes, note simply won’t appear — even though the finding itself supports it. Call the same endpoint as a different user who does hold that permission, and note shows up. Don’t treat an absent key as a fact about the finding; it’s a fact about the caller.

Step 4: Record your review

Set a note explaining the decision, then mark the finding reviewed. This is the same two-call sequence covered in depth in Reviewing a Finding — here’s the short version:

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."}'

The response’s editStates now carries resolve too, so the next call succeeds:

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"

The finding now reads "reviewStatus": "REVIEWED" and "alertState": "Cleared" — read Reviewing a Finding for the full lifecycle, including clearing a review, the history it leaves behind, and why resolve and reset need different permissions.

Next steps

Copyright © Pitchpoint Solutions. All rights reserved.