Skip to content
BookendBookend Docs

Escalate a finding

POST
/v1/findings/{id}/escalate
curl --request POST \
  --url http://localhost:8080/v1/findings/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/escalate \
  --header 'Content-Type: application/json' \
  --data '{ "reasonCode": "example", "note": "example" }'

Flags a finding to management: the action is recorded (the status is unchanged) and every active manager and administrator is emailed. Optional body { note }. Requires a signed-in admin, manager or specialist. 404 for an unknown finding, 409 when it belongs to an earlier run or the loan is not in review.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Request Body

Section titled “Request Body”
Media typeapplication/json
One of:
null
Examplegenerated
{
  "reasonCode": "example",
  "note": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

A finding with its action history; the row the workstation panel shows.

object
finding
required
object
id
required
string format: uuid
runId
required
string format: uuid
loanId
required
string format: uuid
ruleId
required
string
severity
required
string
status
required
string
title
required
string
detail
required

Stored as findings.detail_json: the human sentence plus every source the finding points at.

object
message
required
string
sources
required
Array<object>

Where a finding points (document / page / box); the provenance the workstation deep-links to.

object
documentId
required
string format: uuid
source
required
string
field
required
null | string
value
required
null | string
pageNo
required
null | integer | string format: int32
/^-?(?:0|[1-9]\d*)$/
bbox
required
One of:
null
data
required
createdAt
required
string format: date-time
blocksApproval
required
boolean
actions
required
Array<object>
object
id
required
integer | string format: int64
/^-?(?:0|[1-9]\d*)$/
findingId
required
string format: uuid
action
required
string
reasonCode
required
null | string
note
required
null | string
actorId
required
string format: uuid
actorName
required
string
occurredAt
required
string format: date-time
Examplegenerated
{
  "finding": {
    "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "runId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "loanId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "ruleId": "example",
    "severity": "example",
    "status": "example",
    "title": "example",
    "detail": {
      "message": "example",
      "sources": [
        {
          "documentId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
          "source": "example",
          "field": "example",
          "value": "example",
          "pageNo": 1,
          "bbox": {
            "x": 1,
            "y": 1,
            "w": 1,
            "h": 1
          }
        }
      ],
      "data": "example"
    },
    "createdAt": "2026-04-15T12:00:00Z",
    "blocksApproval": true
  },
  "actions": [
    {
      "id": 1,
      "findingId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "action": "example",
      "reasonCode": "example",
      "note": "example",
      "actorId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "actorName": "example",
      "occurredAt": "2026-04-15T12:00:00Z"
    }
  ]
}