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

Name	Description	Example	Type	Format	Required
access_token	Received by calling the /auth/tokens endpoint	eyJjbGllbnR...	String	JWT	Yes
container_id	ID of the container element added at step 2	widgetContainer	String		Yes
consumer_id	A unique identifier provided by the client for each consumer. The same ID that was used to generate the access token	123456	String		Yes
application_id	Unique identifier for an application, such as a loan. Used to build data analytics reports.	loan12345	String		No
first_name	First name of the consumer	John	String		Yes
last_name	Last name of the consumer	Smith	String		Yes
ssn	Social security number.	322-32-5345	String	DDD-DD-DDDD	No
routing_number	Routing number of the account the consumer wants to use for IBV. Used to pre-select bank for verification	No routing number or 000111449 or 074000101.	String	/^\d{9}$/	No
account_number	Account number of the account specified by the consumer to use for IBV analysis	523423512	String	/^[0-9]*$/	No
birth_date	Date of birth	1776-07-04	String (Date)	YYYY-MM-DD	No
street_address	Street number and name	222 South Riverside Plaza	String		No
street_address2	Address unit designator and number	Suite 2200	String		No
city	City	Chicago	String		No
state_code	U.S. State Code	IL	String		No
zip_code	U.S. Postal Code (5-digit OR 9-digit)	60606	String	/^[0-9]{5}(?:-[0-9]{4})?$/	No
home_phone	Landline number	855-646-5201	String	DDD-DDD-DDDD	No
email	Email address of the consumer.	[email protected]	String	/\A[^@\s]+@[^@\s]+\z/	No
mobile_phone	Mobile phone number	855-646-5201	String	DDD-DDD-DDDD	No
additional_data	Additional data for data analytics based on agreements	{“vantage_score”:500, “housing”:”rent”, “existing_customer”:true …	String		No
intent_url	URL for OAuth redirect in native mobile apps	myApp://	String		Yes, native mobile apps only
partner_name	Name of the partner	Edge	String		Yes 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:

Message	Description
Generation failed	Failed to generate features or scores due to corrupted data etc
Pull process timed out	It’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 Message	Actual 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.