Overview

Welcome to the developer documentation for the EDGE Refresh Product.

EDGE Refresh allows you to request updated account data and insights for a connected account, providing the latest EDGE report with refreshed details. This guide outlines the steps to effectively utilize EDGE Refresh.

Prerequisites

Before using EDGE Refresh, ensure that:

• You have an API key for accessing the EDGE platform.
• The account has an existing connection.
• The account has been connected and a report has been generated previously.

Overview of the APIs

The following API actions are supported by the EDGE Refresh feature:

Detailed API Information

1. Initiate Account Refresh

Use the POST method on the following endpoint to initiate an account refresh and generate an updated EDGE report based on the latest data:

POST /api/v1/ibv/requests/refresh/[client_consumer_id]

Headers:
x-api-key: [your_api_key]
Accept: application/json

This API call will submit a new product request, leveraging the existing account information and the latest active connection to the financial institution. The product request will be added to the standard queue, and the API will return an accepted response indicating the request is in progress.

Response Example (200):

{
   "ibv_report": "https://ninjafetch.com/api/v1/ibv/requests/IBV78CBEAD95DF78B8D92C2",
   "product_request_id": "IBV78CBEAD95DF78B8D92C2",
   "ibv_report_status": "initiated",
   "ibv_connection_link": "https://c.edgescore.com/c1b5027063",
   "message": "Refresh request submitted",
   "status": "in_progress"
}

Errors

EDGE Refresh errors are listed below:

Response fields and descriptions:

1. Invalid Connection

If the account connection is no longer valid, account refresh will not be possible.

Example Response:

{
    "ibv_report": "https://ninjafetch.com/api/v1/ibv/requests/IBV3EF04785C9046BC1209A",
    "product_request_id": "IBV3EF04785C9046BC1209A",
    "ibv_report_status": "initiated",
    "ibv_connection_link": "https://ninjafetch.com/connect/c0beb407b8",
    "message": "Unable to pull IBV data. Ask the consumer to reconnect to <FI Name> using the connection link."
}

2. Data Pull Failure

If the account refresh fails to pull data, account refresh will not be possible. This will trigger the ‘data_pull_via_connection_failed’ webhooks event, and the response will show the ibv_report_status as “ibv_data_acquired_failed”.

Example Response:

{
    "ibv_report": "https://ninjafetch.com/api/v1/ibv/requests/IBV3EF04785C9046BC1209A",
    "product_request_id": "IBV3EF04785C9046BC1209A",
    "ibv_report_status": "ibv_data_acquire_failed",
    "ibv_connection_link": "https://ninjafetch.com/connect/c0beb407b8",
    "message": "Unable to pull IBV data. Ask the consumer to reconnect to <FI Name> using the connection link."
}

3. Consumer Not Found

If the consumer ID does not exist, account refresh will not be possible.

Example Response

{
   "message": "Consumer id123456 does not exist"
}

4. Too Many Requests

EDGE Refresh can be used once every 24 hours. If a POST request is sent within 24 hours of a previous request, account refresh will not be possible.

Example Response:

{  
    "ibv_report": "<https://ninjafetch.com/api/v1/ibv/requests/IBVDA50C1E1D026E31803C6">,  
    "product_request_id": "IBVDA50C1E1D026E31803C6",  
    "ibv_report_status": "initiated",  
    "ibv_connection_link": "<https://ninjafetch.com/connect/c0beb407b8">,  
    "message": "Reports can only be refreshed once every 24 hours. Wait to refresh or ask the consumer to reconnect to <FI Name> using the connection link." 
    "status": "refresh_not_ready" 
}

5. Refresh Failed

If the account refresh fails to generate, the API call will return an error message.

Example Response:

{
    "message": "The product request failed to initiate"
}

2. Retrieve Refreshed Report

Once the account refresh is complete, the platform will send a webhook callback.

Webhook fields and descriptions:

Example Webhook:

{  
  "consumer_id": "919617",  
  "product_request_id": "IBV420CE406A15E1EBF3B43",  
  "ibv_report": "<https://ninjafetch.com/api/v1/ibv/requests/IBV420CE406A15E1EBF3B43">,  
  "ibv_report_status": "complete",  
  "event": "report_generated"  
}

After receiving the webhook callback, use the GET method on the following endpoint to retrieve the updated report:

GET https://ninjafetch.com/api/v1/ibv/requests/<product_request_id>

Headers:
x-api-key: [your_api_key]
Accept: application/json