Adding Widget to Application

Steps to Add the NinjaFetch Widget to your application

To launch NinjaFetch from your web application, include ninjafetch.js in the HTML and call NinjaFetchWidget.mount() from JavaScript.

1. Import ninjafetch.js

Add this line to your HTML code.

<script type='text/javascript'
src="https://ninjafetch.com/v1/ninjafetch.js"></script>

2. Add a container

You can apply custom styles to the container element to change the position of the widget.

<div id="widgetContainer"/>

3. Add JavaScript code

<script>
    function launch() {
        //Build consumer data
        var consumerData = {
            access_token: 'eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRf...',
            container_id: 'widgetContainer',
            consumer_data: {
                consumer_id: '123456', //the same that was used to generate the access token
                application_id: 'abc12345', //a unique identifier of the application, such as a loan id
                reference_date: '2023-03-14', //usually the current date
                first_name: 'John',
                middle_name: 'Edge',
                last_name: 'Smith',
                nickname: 'John',
                birth_date: '1995-01-01',
                ssn: '322-32-5345',
                full_address: '222 South Riverside Plaza Suite 200, Chicago, IL 60606',
                street_address: '222 South Riverside Plaza',
                street_address2: 'Suite 200',
                city: 'Chicago',
                state_code: 'IL',
                zip_code: '60606',
                home_phone: '855-646-5201',
                mobile_phone: '855-646-5201',
                email: '[email protected]',
                secondary_email: '[email protected]',
                employer_name: 'Edge LLC',
                secondary_employer_name: 'Edge LLC2',
                bank_name: 'Bank of America',
                routing_number: '000111449',
                account_number: '2302389238923',
                debit_card_number: '1234567890123456',
                additional_data: {
                    vantage_score: 500,
                    housing: 'rent'
                },
                partner_name: '<only applies to partners>'
            },
            data_pull_timeout: 300,

            //Optional timeout setting for data pulls. Default is 300 seconds (5 minutes)
            intent_url: 'myApp://',
            //required only for native mobile apps to handle OAuth callbacks
            onSuccess: (data) => {
                console.log(data)
                //NinjaFetchWidget.unmount()
            },
            onError: (data) => {
                //Handle Technical errors. 
                console.log(data)
                if (data.hasOwnProperty("isLastVendor") && data.isLastVendor) {
                    NinjaFetchWidget.unmount()
                }
            },
            onClose: (data) => {
                //Reserved for future features
                console.log(data)
            }
        }
        //Initialize widget
        try {
            NinjaFetchWidget.mount(consumerData)
        }
        catch (err) {
            //Handle mounting errors here
            console.log(err)
        }
    }
</script>

3.1 Supported Fields

NameDescriptionExampleTypeFormatRequired
access_tokenReceived by calling the /auth/tokens endpointeyJjbGllbnR...StringJWTYes
container_idID of the container element added at step 2widgetContainerStringYes
consumer_idA unique identifier provided by the client for each consumer. The same ID that was used to generate the access token123456StringYes
application_idUnique identifier for an application, such as a loan. Used to build data analytics reports.loan12345StringNo
first_nameFirst name of the consumerJohnStringYes
last_nameLast name of the consumerSmithStringYes
ssnSocial security number.322-32-5345StringDDD-DD-DDDDNo
routing_numberRouting number of the account the consumer wants to use for IBV. Used to pre-select bank for verificationNo routing number or 000111449 or 074000101.String/^\d{9}$/No
account_numberAccount number of the account specified by the consumer to use for IBV analysis523423512String/^[0-9]*$/No
birth_dateDate of birth1776-07-04String (Date)YYYY-MM-DDNo
street_addressStreet number and name222 South Riverside PlazaStringNo
street_address2Address unit designator and numberSuite 2200StringNo
cityCityChicagoStringNo
state_codeU.S. State CodeILStringNo
zip_codeU.S. Postal Code (5-digit OR 9-digit)60606String/^[0-9]{5}(?:-[0-9]{4})?$/No
home_phoneLandline number855-646-5201StringDDD-DDD-DDDDNo
emailEmail address of the consumer.[email protected]String/\A[^@\s]+@[^@\s]+\z/No
mobile_phoneMobile phone number855-646-5201StringDDD-DDD-DDDDNo
additional_dataAdditional data for data analytics based on agreements{“vantage_score”:500, “housing”:”rent”, “existing_customer”:true …StringNo
intent_urlURL for OAuth redirect in native mobile appsmyApp://StringYes, native mobile apps only
partner_nameName of the partnerEdgeStringYes for partners only

4. Handle Initialization Errors

   //Initialize widget
   try{
       NinjaFetchWidget.mount(consumerData)
   }
   catch(err){
       //Handle mounting errors here
       console.log(err)
   }

The widget will validate the data and throw validation errors. The client application will need to correct the data being passed into the widget and retry.

Example

{
 "message": "Invalid data",
 "fields": {
 	<field 1>: <value 1>,
 	<field 2>: <value 2>
}

5. Handling Callbacks

The Widget will send results back through the three callback functions: onSuccess(), onError(), and onClose().

5.1 onSuccess()

The widget will invoke a first callback once the consumer successfully connects a bank. The callback will have the ibv_report_status value set to “initiated”. Clients who do not make real-time decisions should unmount the widget after the first callback, so the consumer does not need to wait while the NinjaFetch platform downloads transactions and creates the report.

{
    “ibv_report”: “https://ninjafetch.com/api/v1/ibv/requests/IBVF15CE1FD5FADC7663604”,
    “product_request_id”: “IBVF15CE1FD5FADC7663604",
    “ibv_report_status”: “initiated”,
    “ibv_connection_link”: “https://ninjafetch.com/connect/a06bbd625a”
}

The widget will invoke a second callback once the NinjaEdge report is complete. Ibv_report_status will be ”complete”. Only clients who make real-time decisioning based on the NinjaEdge report should wait for the second callback. The returned product_request_id is the unique identifier of the NinjaEdge report, available for download via backend APIs.

{
    “product_request_id”: “IBVF15CE1FD5FADC7663604",
    “ibv_report”: “https://ninjafetch.com/api/v1/ibv/requests/IBVF15CE1FD5FADC7663604”,
    “ibv_report_status”: “complete”
}

5.2 onError()

Called when a technical error occurs. The actual error message will be passed to the callback function.

There is a flag in the parameters called isLastVendor. Unmount the Widget and proceed to error handling only when isLastVendor is true. The consumer can attempt connections with a different IBV aggregator when isLastVendor is false.

{
    "message": "Network error",
    "isLastVendor": false
}

Possible error messages:

MessageDescription
Generation failedFailed to generate features or scores due to corrupted data etc
Pull process timed outIt’s taking longer than the timeout limit to download IBV data using the connection. Default timeout is 5 minutes. The backend will keep attempting data download for up to 30 minutes.
Other Technical MessageActual technical error message

5.3 onClose()

Reserved for future features.

6. Handle Data Pull Timeout

After the Consumer connects their bank accounts, a backend process will start to download IBV data through the connection.

Usually, this step takes less than 2 minutes to complete. However, depending on the quality of the data aggregator’s bank connection, it may take a few tries and up to 30 minutes for the NinjaFetch platform to acquire the data. By default, the NinjaFetch widget will send a timeout callback to the onError() function and unmount itself after 5 minutes.

The Client can change the timeout by passing a custom data_pull_timeout value to the widget to optimize the user experience. The Client can either try to download the report at a later time (it is recommended to wait for at least 2 minutes before the next attempt), or implement Webhooks to receive updates from the NinjaFetch platform.

When the Client recognizes a timeout it may make any number of retry attempts, which should eventually lead to one of the following responses:

  • IBV Report - HTTP 200
  • IBV Report Pending - HTTP 202

7. Report download

After receiving the product_request_id from the widget, the Client application backend can retrieve the full report with a GET to the [/ibv/requests/{request id}](/ibv/requests/{request id}) endpoint. Refer to the IBV Product API Specification document for details about interacting with the API.