Retrieve IBV Report

When the platform has processed the request the API will return the IBV report. If the IBV report request is still in progress the API will return the current status of the process.

GET

Request

Clients may retrieve IBV reports with a GET to:
https://ninjafetch.com/api/v1/ibv/requests/{request id}

Clients may request IBV reports in PDF format. Only IBV reports in the ‘complete’ status have the PDF version available.

Header

NameDescriptionExampleRequired
x-api-keyA unique API Key for the environment19YYgyZecTaSs2N0gjlq32Vh6DYes
AcceptIBV reports formatapplication/pdfYes

Example

curl --location --request GET 'https://ninjafetch.com/api/v1/ibv/requests/IBV8781156D1C6256FADCEB' \
--header 'x-api-key: 3f8493dca05ffee1aa221fd93...'\
--header 'Accept: application/pdf'

Response

👍

Retrieve IBV Report - HTTP 200

The Client will receive the IBV Report.

  <th>
    Description
  </th>

  <th>
    Example
  </th>

  <th>
    Type
  </th>
</tr>
  <td>
    The request id passed to the endpoint  
  </td>

  <td>
    IBV32892389  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    client\_id  
  </td>

  <td>
    Id of the Client          
  </td>

  <td>
    3011  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    consumer\_id  
  </td>

  <td>
    A unique identifier provided by the client for each consumer  
  </td>

  <td>
    CN328923498  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    reference\_date  
  </td>

  <td>
    As of date for feature and score calculation. The date is used to evaluate recent account activities, so it has a direct impact on the result.  
  </td>

  <td>
    2022-04-22
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    created\_at  
  </td>

  <td>
    Time when the report was generated. yyyy-MM-dd HH:mm:ss             
  </td>

  <td>
    2022-04-22 13:03:45
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    ibv\_report\_status  
  </td>

  <td>
    Status of the request.  
  </td>

  <td>
    complete  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    accounts  
  </td>

  <td>
    Array of result Json objects for each account  
  </td>

  <td>
    "[\
         \{\
            ""provider\_name"": ""PNC Bank"",\
            ""account\_name"": ""TOTAL CHECKING-1234"",\
            ""account\_type"": ""CHECKING"",\
            ""account\_number"":  ""32892348943"",\
            ""routing\_number"": ""071921891""\
            ""owner\_name"": ""John Smith"",\
            ""balance"": 123.45,\
            …\
         }\
    ][  
         \{  
            ""provider_name"": ""PNC Bank"",  
            ""account_name"": ""TOTAL CHECKING-1234"",  
            ""account_type"": ""CHECKING"",  
            ""account_number"":  ""32892348943"",  
            ""routing_number"": ""071921891""  
            ""owner_name"": ""John Smith"",  
            ""balance"": 123.45,  
            …  
         }  
    ]"  
  </td>

  <td>
    Json Array
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x][“provider\_name”][“provider_name”]  
  </td>

  <td>
    Name of the bank  
  </td>

  <td>
    PNC  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x] [“account\_name”][“account_name”]  
  </td>

  <td>
    Name of the account  
  </td>

  <td>
    TOTAL CHECKING-1234  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x] [“account\_type”][“account_type”]  
  </td>

  <td>
    Type of the account  
  </td>

  <td>
    CHECKING  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x][“routing\_number”][“routing_number”]  
  </td>

  <td>
    Routing number of the account  
  </td>

  <td>
    3071921891  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x][“account\_number”][“account_number”]  
  </td>

  <td>
    Account number of the bank account  
  </td>

  <td>
    32892348943  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x] [“owner\_name”][“owner_name”]  
  </td>

  <td>
    Name of the account owner  
  </td>

  <td>
    John Smith  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x][“balance”]  
  </td>

  <td>
    Current balance of the account  
  </td>

  <td>
    123.45  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x][“items”]  
  </td>

  <td>
    List of features and scores  
  </td>

  <td>
    "[\
              \{\
                ""item\_code"": ""ibv\_validate\_metrics"",\
                ""item\_name"": ""Validate 2"",\
                ""item\_version"": ""3.0.1"",\
                ""data"": \{\
                  ""ne\_income\_feature\_1"": ...,\
                ... # multiple features\
              },\
              …more items\
    ][  
              \{  
                ""item_code"": ""ibv_validate_metrics"",  
                ""item_name"": ""Validate 2"",  
                ""item_version"": ""3.0.1"",  
                ""data"": {  
                  ""ne_income_feature_1"": ...,  
                ... # multiple features  
              },  
              …more items  
    ]"  
  </td>

  <td>
    Json Array
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x][“items”][item_name]  
  </td>

  <td>
    Name of the subscribed EDGE product  
  </td>

  <td>
    Validate 2  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x][“items”][item_code]  
  </td>

  <td>
    Code of the subscribed EDGE product  
  </td>

  <td>
    ibv\_validate\_metrics  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x][“items”][item_version]  
  </td>

  <td>
    Version of the subscribed EDGE product  
  </td>

  <td>
    3.0.1  
  </td>

  <td>
    String
  </td>
</tr>

<tr>
  <td>
    [“accounts”][x][“items”][data]
  </td>

  <td>
    List of features or scores
  </td>

  <td>
    "\{\
    ""ninjaedge\_income\_feature\_31"": true,\
    ""ninjaedge\_income\_feature\_32"": true,\
    ""ninjaedge\_historical\_feature\_1"": true,\
    ""ninjaedge\_historical\_feature\_2"": false,\
    ""ninjaedge\_balance\_feature\_1"": 230.64,\
    …\
    }\
    \{\
    ""ninja\_score"": 358,\
    ""score\_factors"": [""Unable to verify income"",  ""Limited credit experience""],\
    ""score\_factor\_codes"": [""002"",  ""008""]\
    ……\
    }"
  </td>

  <td>
    JSON Object
  </td>
</tr>
Name
product\_request\_id

Report Status

StatusDescription
initiatedRequest has been received.
reconnect_requiredThe bank connection did not work due to incorrect credentials or incomplete MFA process. The EDGE platform will not take further actions until the consumer reconnects the bank.
ibv_data_acquire_failedFailed to pull data from the data aggregator. This may happen after the user successfully connects the bank account. The EDGE platform will not take further actions.
ibv_data_acquiredSuccessfully downloaded the IBV data. The EDGE platform is generating features and scores. This is a temporary state. The status will eventually change to “complete” or “generation_failed”.
generation_failedFailed to create features and scores. The EDGE platform will not take further actions.
completeReport was created successfully. The EDGE platform will not take further actions.

Example

{
 "product_request_id": "IBV32892389",
 "client_id": "3011",
 "consumer_id": "CN328923498",
 "reference_date": "2021-08-15",
 "created_at": "2021-09-01 15:21:53",
 "ibv_report_status": "complete",
   "accounts": [
     {
       "provider_name": "PNC Bank",
       "account_name": "TOTAL CHECKING-1234",
       "account_type": "CHECKING",
       "routing_number": "071921891",
       "account_number": "32892348943",
       "owner_name": "John Smith",
       "balance": 123.45,
       ... # other custom fields
       "items":[
         {
           "item_code": "ibv_validate_metrics",
           "item_name": "Validate 2",
           "item_version": "3.0.1",
           "data": {
             "ne_income_feature_1": ...,
             ... # multiple features
           },
           ... # multiple items
         },
       ]
     },
     ... # multiple accounts       
   ]
 }
}

🚧

IBV Report Pending - HTTP 202

The Client will receive the processing status when the requested IBV report is not yet ready.

Example:

{
 "product_request_id": "IBV3B2BB0C30B0FB770E157",
 "ibv_report": "https://ninjafetch.com/api/v1/ibv/requests/IBV3B2BB0C30B0FB770E157",
 "ibv_report_status": "initiated",
 "message": "Check for results later",
 "ibv_connection_link": "https://ninjafetch.com/connect/438da2e3b1b321506c3cd4cbb4…"
}

Handling Timeouts

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

Webhooks

The EDGE platform can initiate a Webhooks callback when the requested report is generated and ready for retrieval, or when the report generation fails. Two events, “report_generated” and “report_generation_failed” are supported. The response payload includes the following fields:

Field NameDescription
consumer_idA unique identifier provided by the client for each consumer
product_request_idA unique identifier of the IBV report
ibv_reportURL for retrieval of the IBV report
ibv_report_status“complete” or “generation_failed”
eventName of the system event that triggered the Webhooks. Supported events are “report_generated” and “report_generation_failed”

Example

{
 "consumer_id": "12345",
 "product_request_id": "IBVCE90DDCCED4A0F0E5217",
 "ibv_report": "https://ninjafetch.com/api/v1/ibv/requests/IBVCE90DDCCED4A0F0E5217",
 "ibv_report_status": "complete",
 "event": "report_generated"
}

{
 "consumer_id": "67890",
 "product_request_id": "IBV2529C60A40F2B651639B",
 "ibv_report": "https://ninjafetch.com/api/v1/ibv/requests/IBV2529C60A40F2B651639B",
 "ibv_report_status": "generation_failed",
 "event": "report_generation_failed"
}

Please provide your Webhooks endpoint to the EDGE Customer Success Team if you would like to use this feature.