Add custom data output

Add CUSTOM_DATA_OUTPUT to the supported_features field on your Configuration endpoint.

"supported_features": ["CUSTOM_DATA_OUTPUT"]

Specify details of each custom data field.

Only the following data types are supported by custom output fields, specified under output_custom_fields:

When naming your custom data output fields, the field name must start with the letter and an underscore associated with the data type you're using:

The output_custom_fields field has the following structure, with comments added inline:

{
  // Other fields from a typical check config schema are omitted.
  "output_custom_fields": {
    // Version and fields are not directly at the top level,
    // to allow for future non-breaking additions to the
    // output data schema
    "version": "1",
    "fields": {
      // The name of entries in the "fields" object represents the
      // name of the field in the actual output.
      // The name MUST be unique.
      // Any fields not defined in the schema will be ignored in validation and dropped from the output.
      // The name MUST follow custom field naming conventions, meaning:
      // * Name starts with type prefix (`n_` for "number", `s_` for "string", `b_` for "boolean")
      // * Name following prefix only contains characters in the set `[a-z0-9_]`
      "n_esg_score": {
        // Field schemas are directly modelled after the structure of
        // custom fields.

        // Reflects the type of the data field.
        // Initially only simple types will be supported:
        // "BOOLEAN" | "DECIMAL" | "STRING"
        // The value MUST match the prefix given for the field name.
        // This field MUST be set to one of the above strings.
        "type": "DECIMAL",

        // A human readable name for the data field.
        // Initially this will be "language invariant" (i.e. not multilingual)
        // Not directly used in initial implementation, but should be
        // included as displaying these will be desirable at some point.
        // This field MUST be set.
        // The value of this field MUST follow these rules:
        // * The value MUST be a string.
        // * The value MUST NOT be an empty string.
        // * The value MUST NOT consist entirely of characters considered to be whitespace.
        // * The value MUST NOT contain Unicode Cc control codes, including TAB (\t), CR (\r), LF (\n).
        "label": "ESG Score"
      },
      // Some additional fields without commentary for clarity.
      "n_esg_e_score": {
        "type": "DECIMAL",
        "label": "ESG Environment Sub-score"
      },
      "n_esg_s_score": {
        "type": "DECIMAL",
        "label": "ESG Social Sub-score"
      },
      "n_esg_g_score": {
        "type": "DECIMAL",
        "label": "ESG Governance Sub-score"
      }
    } 
  }
}

As best practice, you should always use the data type that is most suitable to the data in each field.

Avoid using STRING data types unless the data is text. This is a general rule and there may be exceptions to this.

For example, a STRING value of "30%" can't be used in combination with other numbers in the risk engine and so offers little to no value. A DECIMAL value of "0.3" can be compared to other numbers or used against various thresholds, so it offers much greater functionality. Keeping this in mind ensures that users get the most out of your data.

Now that you've added support for CUSTOM_DATA_OUPUT, you need to be able to correctly respond to the associated test during the validation suite.

One of the requests sent during the validation suite has a demo_result value of CUSTOM_DATA_OUTPUT. If your integration receives a request with this demo_result value, it must return a valid response that contains the properly formatted custom data that matches the schema that you specified in your /config endpoint.

The following is an example config response including custom output fields:

{
  "check_type": "COMPANY_DATA",
  "check_template": {
    "type": "ONE_TIME_SYNCHRONOUS",
    "timeout": 240
  },
  "pricing": {
      "supports_reselling": false
  },
  "supported_countries": ["GBR", "CAN", "USA"],
  "supported_features": [
    "COMPANY_SEARCH",
    "CUSTOM_DATA_OUTPUT",
  ],
  "credentials": {
    "fields": [
      {
        "type": "string",
        "name": "username",
        "label": "Username"
      },
      {
        "type": "password",
        "name": "password",
        "label": "Password"
      }
    ]
  },
  "config": {
    "fields": []
  },
  "output_custom_fields": {
      "version": "1",
      "fields": {
        "n_esg_score": {
          "type": "DECIMAL",
          "label": "ESG Score"
        },
        "n_esg_e_score": {
          "type": "DECIMAL",
          "label": "ESG Environment Sub-score"
        },
        "n_esg_s_score": {
          "type": "DECIMAL",
          "label": "ESG Social Sub-score"
        },
        "b_product_assessment": {
          "type": "BOOLEAN",
          "label": "Passes ESG assessment"
        }
      } 
    }
  }
}

Once the /config endpoint has been completed, to use your custom output fields in the check response, you use the field names you created in the output_custom_fields field of your /config endpoint and place these in the custom_fields_data field in the check_output field of your response.

For example:

{
  "provider_data": "Made up example response.",
  "errors": [],
  "warnings": [],
  "external_resources": [],
  "result": {
    "decision": "PASS",
    "summary": "The overall result is a pass."
  },
  "check_output": {
    "entity_type": "INDIVIDUAL",
    "custom_fields_data": 
          { 
            "n_esg_score": 123.4, 
            "n_esg_e_score": 43,
            "n_esg_s_score": 1.13,
            "b_product_assessment": true
          }            
  }
}