Developer Guides

Update Findings

As part of a patch response, partners can update the status of previously created findings.

Suggest Edits

An integration can update findings that it previously sent to the lender with the CREATE_FINDINGS action. To do so, patch a transaction with a response that includes a response result object with the action UPDATE_FINDINGS. A common use is updating the status of a finding as the underlying issue is worked.

📘

Prerequisite

The product must be entitled to the UPDATE_FINDINGS action to use it in a transaction PATCH.

To entitle a product, add the action to the response.results array of the relevant request type within $.entitlements.data.transaction:

  {
    "action": "UPDATE_FINDINGS",
    "formats": [
      "application/vnd.findings-update-1.0.0.json"
    ]
  }

{
   "status": "completed",
   "loanFormat": "application/vnd.plm-2.0.0+json",
   "result": {
      "format": "application/vnd.findings-update-1.0.0.json",
      "action": "UPDATE_FINDINGS",
      "details": {
         ... // Update findings action details
      }
   },
   "partnerStatus": "partner status"
}

📘

format and action

The Encompass Partner Connect (EPC) Platform uses $.result.format and $.result.action to determine how to process the action details sent in the transaction PATCH payload. Make sure you use:

"format": "application/vnd.findings-update-1.0.0.json"
"action": "UPDATE_FINDINGS"

Fields in the UPDATE_FINDINGS result action

FieldAdditional Information
$.result.details.findings[].idRequired. Identifier of the previously created finding to update.
$.result.details.findings[].codeRequired. Code of the finding, as registered in product registration. Maximum 128 characters.
$.result.details.findings[].descriptionOptional. Updated description of the finding. Must not be empty or whitespace.
$.result.details.findings[].statusOptional. Updated status of the finding. Must not be empty or whitespace.

The findings array must contain at least one item.

The complete list of supported fields in the UPDATE_FINDINGS action details object is defined in the JSON schema below. You can use online tools such as JSON Schema Validator to manually validate the contents of a details object.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "validationMessage": {
    "invalid-string": "a valid String. Please provide a valid string."
  },
  "properties": {
    "findings": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/findingItem"
      },
      "minItems": 1,
      "description": ""
    }
  },
  "required": [
    "findings"
  ],
  "additionalProperties": false,
  "definitions": {
    "non-empty-string": {
      "type": "string",
      "pattern": "^(?!\\s*$).+",
      "validationMessage": {
        "$ref": "#/validationMessage/invalid-string"
      }
    },
    "non-empty-code-string": {
      "type": "string",
      "pattern": "^(?!\\s*$).+",
      "maxLength": 128
    },
    "findingItem": {
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/definitions/non-empty-string",
          "description": "Represents the id of the finding."
        },
        "description": {
          "$ref": "#/definitions/non-empty-string",
          "description": "Represents the description of the finding."
        },
        "code": {
          "type": "string",
          "pattern": "^(?!\\s*$).+",
          "maxLength": 128,
          "description": "Represents the code of the finding."
        },
        "status": {
          "$ref": "#/definitions/non-empty-string",
          "description": "Represents the status of the finding."
        }
      },
      "required": [
        "id",
        "code"
      ],
      "additionalProperties": false
    }
  }
}

Below is a sample update findings request payload:

{
  "status": "completed",
  "result": {
    "format": "application/vnd.findings-update-1.0.0.json",
    "action": "UPDATE_FINDINGS",
    "details": {
      "findings": [
        {
          "id": "ee25fc28-fa94-449b-8ae0-d571fd8912f5",
          "code": "INC-030",
          "description": "Review Borrower Profile screen to determine if there are identity related issues. Determine if the name identified has been disclosed.",
          "status": "Pending"
        },
        {
          "id": "65811e27-3444-4416-8d56-902553c35e97",
          "code": "INC-040",
          "status": "Completed"
        },
        {
          "id": "d147be87-5e11-46c6-b9e7-956c4a8f11f0",
          "code": "INC-048",
          "status": "Completed"
        }
      ]
    }
  }
}

Updated about 1 year ago