# Getting Started Source: https://docs.pitchpointsolutions.com/developer_guides/findings/getting-started/ **Beta** ## 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. > **Before Starting:** You need a workflow to point this at. If you don't have one yet, see the [Getting Started](https://docs.pitchpointsolutions.com/developer_guides/sessions_and_workflows/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. ```bash curl -X GET "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611" \ -H "Authorization: Bearer your_access_token_here" ``` ```json { "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 > **Warning:** **`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. > **Warning:** **`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](https://docs.pitchpointsolutions.com/api/findings/get_workflow_category_counts). `reports` lists the workflow's generated report, or is `[]` when none has been generated yet. It's metadata only. > **Warning:** **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](https://docs.pitchpointsolutions.com/api/findings/get_workflow_findings#reports). ## 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. ```bash 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. ```json { "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](https://docs.pitchpointsolutions.com/api/findings/get_workflow_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](https://docs.pitchpointsolutions.com/api/findings/get_workflow_findings_list#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. > **Warning:** `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: ```bash 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](https://docs.pitchpointsolutions.com/developer_guides/findings/reviewing). ## Step 6: Read the summary again Read the summary again with the same call as in Step 1: ```bash curl -X GET "https://api.pointservices.com/riskinsight-services-ws/resources/v1/findings/workflows/wfpop_0000000000002082611" \ -H "Authorization: Bearer your_access_token_here" ``` ```json { "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 - [Reviewing a Finding](https://docs.pitchpointsolutions.com/developer_guides/findings/reviewing): the full review lifecycle, overrides, undoing a review, permissions and the audit trail. - [Attachments](https://docs.pitchpointsolutions.com/developer_guides/findings/attachments): uploading, downloading and removing supporting documents. - [Get a Workflow's Findings Summary](https://docs.pitchpointsolutions.com/api/findings/get_workflow_findings): every field on the summary, and downloading the report. - The [Findings API reference](https://docs.pitchpointsolutions.com/api/findings/index) for every field and error on every call.