Data Integrations

How to connect to third-party data source in the DigiFi platform.

Overview Of Data Integrations

DigiFi's platform includes the ability to set up and manage data integrations that can request information from external sources. Once set up, data integrations can be placed within decision strategies to run automatically and have the outputs assigned to variables (i.e. data fields).

Common examples of data integrations include connecting to credit bureaus, collateral valuation data, fraud scores and internal company systems.

👍

The DigiFi platform can be connected to almost any external data source!


Integration Types

DigiFi's data integrations feature provides a standardized approach to managing these integrations using JSON configuration files. Two types of integrations can be set up within the DigiFi platform - Basic and Advanced.

Integration Type

Description

Example

Implemented By

Basic Integration

Requests that retrieve JSON or XML files and extract fields directly with no computation performed.

An integration that directly extracts the Credit Score from a credit report.

Set up by DigiFi's services team unless you have purchased a Private or Self-Hosted plan, in which case you'll have access to this option.

Advanced Integration

Requests that retrieve JSON or XML files and perform computations to calculate fields.

An integration that counts the number of tradelines in a credit report to calculate the Number Of Tradelines.

Set up by DigiFi's services team. If you have a Private or Self-Hosted plan, you can make changes to these integrations once set up.


How To Add A Data Integration

To add a new Data Integration:

  • Navigate to Company Settings > Developers > Custom Data Integrations.
  • Click the "Add Integration" button.
  • Provide an Integration Name (required) and Description (optional).
  • Upload a Configuration file (required), Data Parser file (optional) and Security Certification (optional). These items are discussed below in detail.

Configuration File: Overview

Data integrations are configured using JSON documents, which are used as a reference to dynamically populate API requests and parse API responses.

👍

The configuration files in JSON can be programmatically converted to XLM, SOAP or standard HTTP requests.

The Configuration file is required for every integration. It contains the following types of information:

  • Endpoint location and details.
  • Integration security credentials.
  • Fields required as inputs to run the integration (including descriptions and data formats).
  • Fields receive as outputs from the integration (including descriptions and data formats).
  • Other configuration parameters and options.

Configuration File: Example File

Below please find an example Configuration JSON file.

{
   "name": "Integration Display Name",
   "data_provider": "Name Of Data Provider",
   "description": "A description of the integration",
   "status": "active",
   "request_type": "json",
   "stringify": true,
   "response_option_configs": {
       "skip_status_message_check": true
   },
   "request_option_configs": {
       "set_content_length": true
   },
   "active_request_options": {
       "hostname": "domain.com",
       "path": "/pathname",
       "method": "POST",
       "headers": {
           "Content-Type": "application/json",
           "Cookie": "",
           "Authorization": "xyz"
       }
   },
   "request_options": {
       "hostname": "domain.com",
       "path": "/pathname",
       "method": "POST",
       "headers": {
           "Content-Type": "application/json",
           "Cookie": "",
           "Authorization": "xyz"
       }
   },
   "active_default_configuration": {
       "CreditBureauRequest": {
           "FirstName": "",
           "LastName": "",
           "StreetAddress": "",
           "City": "",
           "State": "",
           "Zip": ""
          }
   },
   "default_configuration": {
       "CreditBureauRequest": {
           "FirstName": "",
           "LastName": "",
           "StreetAddress": "",
           "City": "",
           "State": "",
           "Zip": ""
          }
   },
   "inputs": [
       {
           "data_type": "String",
           "input_name": "name_first",
           "display_name": "First Name",
           "description": "The Borrower's first name",
           "example": "Jane",
           "traversal_path": "CreditBureauRequest.FirstName"
       },
       {
           "data_type": "String",
           "input_name": "name_last",
           "display_name": "Last Name",
           "description": "The Borrower's last name",
           "example": "Smith",
           "traversal_path": "CreditBureauRequest.LastName"
       },
       {
           "data_type": "String",
           "input_name": "address",
           "display_name": "Address",
           "description": "The Borrower's street address",
           "example": "25 Broadway Street",
           "traversal_path": "CreditBureauRequest.StreetAddress"
       },
       {
           "data_type": "String",
           "input_name": "city",
           "display_name": "City",
           "description": "The Borrower's city",
           "example": "Brooklyn",
           "traversal_path": "CreditBureauRequest.City"
       },
       {
           "data_type": "String",
           "input_name": "state",
           "display_name": "State",
           "description": "The Borrower's state",
           "example": "NY",
           "traversal_path": "CreditBureauRequest.State"
       },
       {
           "data_type": "String",
           "input_name": "zip",
           "display_name": "ZIP",
           "description": "The Borrower's ZIP code",
           "example": "12345",
           "traversal_path": "CreditBureauRequest.Zip"
       },
   ],
   "outputs": [
       {
           "data_type": "Number",
           "api_name": "credit_score",
           "display_name": "Credit Score",
           "description": "The Borrower's credit score",
           "example": "850",
           "traversalPath": "CreditBureauResponse.Result.Score"
       }
   ],
   "timeout": 30000,
   "return_data_sources": true,
   "require_security_cert": false,
   "required_credentials": [], 
   "ip_addresses": [],
   "custom_inputs": []
}

Configuration File: Parameters

Please find below a list and descriptions of the Configuration file's parameters.

Parameter

Data Type

Description

"name"

String

Display name of the data integration (for DigiFi's UI).

"data_provider"

String

Display name of the data provider being integrated.

"description"

String

Display description of the data integration (for DigiFi's UI).

"status"

String

Status of the integration within DigiFi (either "active" or "inactive"). You should set to "active" in most cases.

"request_type"

String

Set to "xml" or "json". Setting to "xml" will parse the "default_configuration" object to XML.

"stringify"

Boolean

Set to true if the request_type is set to json.

"response_option_configs"

Object

You can set one field in this configuration (see below).

"response_option_configs".
"skip_status_message_check"

Boolean

If true, the https request will skip checking the status code and continue to the data parsing step.

"request_option_configs"

Object

You can set two fields in this configuration (see below).(set_content_length (Boolean) and pfx (Boolean)).

"request_option_configs".
"set_content_length"

Boolean

If "true", the content length will be set in the headers of the https request.

"request_option_configs".
"pfx"

Boolean

If "true", the pfx file will be generated and set as a Buffer on the headers.

"active_request_options"

Object

Request options that would be entered as a parameter during an https request. Set the hostname, path, port, method, headers, and other relevant fields.

This should contain production integration credentials and will be used for decision strategies set to "Active".

"active_request_options".
"hostname"

String

The hostname.

"active_request_options".
"path"

String

The path.

"active_request_options".
"method"

String

The request method.

"active_request_options".
"headers"

[Object]

HTTPS request headers, which may include your API credentials.

"request_options"

[Object]

Same as "active_request_options" but these should contain testing credentials and will be used for decision strategies that are not set to "Active".

"active_default_configuration"

Object

The template request body of the HTTPS API request. It will differ based on the specific integration that you're setting up.

It is saved as a JSON object and it is updated based on the "inputs" array, which contains objects that each have a "traversal_path" to inform the integration regarding what data to populate requests with (see below).

This is for decision strategies set to "Active" in DigiFi. For testing, please use "default_configuration" (below).

Please see the "Input Traversal Example" sections below for details.

"default_configuration"

Object

Same as "active_default_configuration" but used for decision strategies that are not set to Active.

"inputs"

Arrays Of Objects

Array of inputs that you want to use in the API request. These should correspond to the "default_configuration" and will populate with values with integrations run.

Each "input" object should contain the properties below.

Please see "Input Traversal Example" (below) for more information.

"inputs".
"data_type"

String

Data type for the value that this input will contain (either String, Number, Boolean, or Date).

"inputs".
"input_name"

String (must be unique)

Data key where the value to be placed on the "default_configuration" exists.

For example, if "name_last" is the data point to place somewhere inside of "default_configuration", set "input_name": "name_last").

"inputs".
"display_name"

String

Display name for the field within the DigiFi UI.

"inputs".
"example"

String

Example value for the field, to be displayed in the DigiFi UI.

"inputs".
"traversal_path"

String

Path on "default_configuration" to traverse and replace with the value stored on state.

"outputs"

Array Of Objects

Array of values you want to receive from the integration. Each "output" object should contain the properties below.

If you don’t want to receive any values, set this field to an empty array.

Please see "Output Traversal Example" (below) for more information.

"outputs".
"data_type"

String

Data type for the value that this output will contain (either String, Number, Boolean, or Date).

"outputs".
"api_name"

String (must be unique)

Field where the output value will be placed.

"outputs".
"display_name"

String

Display name for the field within the DigiFi UI.

"outputs".
"example"

String

Example value for the field, to be displayed in the DigiFi UI.

"outputs".
"traveral_path"

String

Path on the 3rd-party API response to traverse and retrieve the value from.

"timeout"

String

Set to "30000".

"return_data_sources"

Boolean

Set to true if you want to save the raw integration response.

"require_security_cert"

Boolean

Set to true if the data integration requires a security certificate (you must also upload the Security Certificate).

"required_credentials"

Object

Leave empty if "require_security_cert" is false. If "require_security_cert" is true, see below for details in the Security Certificate section.

"credentials"

Object

Do not provide if "require_security_cert" is false. If "require_security_cert" is true, see below for details in the Security Certificate section.

"ip_addressess"

String

Leave empty unless DigiFi suggests otherwise (advanced).

"custom_inputs"

Object

Leave empty unless DigiFi suggests otherwise (advanced).

"outputs".
"arrayConfigs"

String (optional)

Allows "find" operations during traversal of a response object when there are arrays with specific codes that need to be found.

"raw_data_parse"

Boolean (optional)

If your request is an XML or SOAP request that will return a raw data string within the response, setting "raw_data_parse" to true (along with a "raw_data_traversal_path") will convert the inner raw data string into usable JSON that can then be traversed for additional data.

"raw_data_traversal_path"

String (optional)

Please see "raw_data_parse".

"xml_configs"

Object (optional)

If the integration has a "request_type" of "xml", you can override the default xml_configurations that are used in the ConvertJSON2XML Parser Library when converting the REQUEST_JSON to XML. Follow the documentation to change the "xml_configs" as needed.

"xml_parser_configs"

Object (optional)

If the data integration has a "request_type" of "xml", you can override the default xml_configurations that are used in the ConvertJSON2XML Parser Library when converting the REQUEST_JSON to XML. Follow the documentation to change the "xml_parser_configs" as needed.


Configuration File: Input Traversal Example

Here is an example "input" array:

{
           "data_type": "String",
           "input_name": "name_first",
           "display_name": "First Name",
           "description": "The Borrower's first name",
           "example": "Jane",
           "traversal_path": "CreditBureauRequest.FirstName"
}
  • The "input_name" is "name_first" and the "traversal_path" is "CreditBureauRequest.FirstName".
  • When the integration runs, if "name_first" has a value of "Kevin" then the integration will traverse the "default_configuration" at "default_configuration.CreditBureauRequest.FirstName" and replace the empty string currently there with "Kevin".
  • Once all of the input traversals are complete, the module will either keep the request into the JSON form, or, if specified as an xml request, it will use the ConvertJSON2XML Parser Library to convert the JSON object to an XML string. The result of this will be submitted as the body of the node https request.

Configuration File: Output Traversal Example

Here is an example "output" array:

{
           "data_type": "Number",
           "api_name": "credit_score",
           "display_name": "Credit Score",
           "description": "The Borrower's credit score",
           "example": "850",
           "traversalPath": "CreditBureauResponse.Result.Score"
       }

When an API response is received, DigiFi converts it into JSON (regardless of the response format). This response can be traversed through the output’s "traversal_path". When an output value is found through traversal, it will save the traversed value onto a response object via the "api_name" that is in the output.


Data Parser File: Overview

The Data Parser file is only used for advanced integrations. It contains logic that tells the integration what calculations to run on the underlying integration response. Data Parsers can only be set up by DigiFi's services team, however customers with Private or Self-Hosted plan can edit Data Parser files after they're set up.

Within the DigiFi platform, you can use a Data Parser to:

  • Count the number of tradelines, inquiries and other things within a raw integration response.
  • Sum the total amount of debt, payments and other things within a raw integration response.
  • Perform complex loops and calculations using raw code before integration results are produced.
  • ... and much more!

From a technical point of view, Data Parser files contain JavaScript functions to execute pieces of logic.


Security Certificate Details

If your integration requires a security certificate, you'll need to provide it as part of the integration.

For integrations that require a security certificate, please also add the following structure to the Configuration file.

"credentials": {
       "testing": {
           "hostname": "",
           "pathname": "",
           "subscriber_code": "",
           "subscriber_password": "",
           "description": "",
           "sys_id_pw": ""
       },
 
   },
"required_credentials": [
       "hostname",
       "pathname",
       "subscriber_code",
       "subscriber_password",
       "description",
       "sys_id_pw"
   ],

DigiFi Professional Services

Want help setting up an integration? DigiFi offers end-to-end implementation services, which are performed by our in-house professional services team of analysts and engineers.

👍

Contact us to discuss our implementation services!