Create Findings

Service providers can register findings as part of product registration. Registering the findings enables an Encompass administrator to map findings to an Encompass condition or task. For more information, see Findings Registration.

An integration can send findings to Encompass by patching a transaction with a response that returns the required field values, and with a response result object with the action CREATE_FINDINGS.

📘
Prerequisite
The product must be entitled to the CREATE_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": "CREATE_FINDINGS",
    "formats": [
      "application/vnd.findings-create-1.0.0.json"
    ]
  }

The specific fields that are sent as part of the response loan data follow the standard data entitlement model and process.

{
   "status": "completed",
   "loanFormat": "application/vnd.plm-2.0.0+json",
   "loan": {
      ... // Additional loan data, sent as part of standard transaction loan update
   },
   "result": {
      "format": "application/vnd.findings-create-1.0.0.json",
      "action": "CREATE_FINDINGS",
      "details": {
         ... // Create 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-create-1.0.0.json"
"action": "CREATE_FINDINGS"

Field	Additional Information
`$.result.details.findings[].code`	Required. Code of the finding, as registered in product registration. Maximum 128 characters.
`$.result.details.findings[].title`	Required. Title of the finding. Maximum 1,000 characters.
`$.result.details.findings[].description`	Optional. Description of the finding.
`$.result.details.findings[].referenceId`	Optional. Partner reference ID for the finding.
`$.result.details.findings[].status`	Optional. Status of the finding.
`$.result.details.findings[].scope`	Optional. When present, requires `type` (allowed value: `application`) and `id`, the ID of the borrower application the finding applies to.
`$.result.details.findings[].comments[].comment`	Optional. Comments on the finding. Each comment must not be empty.

String fields must not be empty or contain only whitespace.

The complete list of supported fields in the CREATE_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": {
        "title": {
          "type": "string",
          "pattern": "^(?!\\s*$).+",
          "maxLength": 1000,
          "description": "Represents the title of the finding."
        },
        "description": {
          "$ref": "#/definitions/non-empty-string",
          "description": "Represents the description of the finding."
        },
        "code": {
          "$ref": "#/definitions/non-empty-code-string",
          "description": "Represents the code of the finding."
        },
        "referenceId": {
          "type": "string"
        },
        "status": {
          "$ref": "#/definitions/non-empty-string",
          "description": "Represents the status of the finding."
        },
        "scope": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "application"
              ],
              "description": "Determines the scope of the finding."
            },
            "id": {
              "$ref": "#/definitions/non-empty-string",
              "description": "Contains a reference to a particular application. If not present, the finding is applicable to all applications."
            }
          },
          "required": [
            "type",
            "id"
          ],
          "additionalProperties": false
        },
        "comments": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/definitions/commentItem"
          }
        }
      },
      "required": [
        "title",
        "code"
      ],
      "additionalProperties": false
    },
    "commentItem": {
      "type": "object",
      "properties": {
        "comment": {
          "$ref": "#/definitions/non-empty-string"
        }
      },
      "required": [
        "comment"
      ],
      "additionalProperties": false
    }
  }
}

Below is a sample create findings request payload with all of the supported fields:

{
  "status": "completed",
  "loanFormat": "application/vnd.plm-2.0.0+json",
  "result": {
    "format": "application/vnd.findings-create-1.0.0.json",
    "action": "CREATE_FINDINGS",
    "details": {
      "findings": [
        {
          "code": "INC-040",
          "title": "Borrower name not found on the Credit Header Search.",
          "description": "Review Borrower Profile screen to determine if there are identity related issues. Determine if the name identified has been disclosed.",
          "referenceId": "76698c45-8bd1-40d5-a963-4508c2fefd7e",
          "status": "Fail",
          "scope": {
            "type": "application",
            "id": "d6a4b5c2-1f3e-4b7a-9c8d-2e1f0a3b4c5d"
          },
          "comments": [
            {
              "comment": "Name variation found on the credit report."
            }
          ]
        }
      ]
    }
  }
}

To update findings after they are created, use the UPDATE_FINDINGS action.

Create Findings

📘
Prerequisite

📘
format and action

📘Prerequisite

📘format and action

📘
Prerequisite

📘
format and action