Developer Guides

Create Findings

Suggest Edits

Service providers can now register Findings as part of product registration. Registering the findings enables an Encompass Admin to map findings to an Encompass Condition or Task.

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.

📘

Pre-requisite

Product has to be entitled to CREATE_FINDINGS action in order to use it during transaction patch.

A product can be entitled to CREATE_FINDINGS action by adding it in the response.results array of the specific 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.

{
  "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 have been disclosed.",
          "referenceId": "76698c45-8bd1-40d5-a963-4508c2fefd7e",
          "status": "Fail",
          "scope": {
            "type": "application",
            "id": "id"
          },
          "comments": [
            {
              "comment": ""
            }
          ]
        }
      ]
    }
  }
}

📘

format and action

The Encompass Partner Connect (EPC) Platform uses $.result.format and $.result.action to properly handle 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"

The full list of supported fields in the create disclosure tracking log action details are captured in the JSON-schema object definition below. There are several resources available online, such as https://www.jsonschemavalidator.net/, where a result details objects content can be manually validated.

{
  "$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
    }
  }
}