IBV Report with IBV Data

The IBV REST APIs are specifically crafted to facilitate server-to-server communication. If the client possesses IBV data, they can utilize a POST request to https://ninjafetch.com/api/v1/ibv/requests and include the pre-existing IBV data to request a report.

To gain access to this endpoint, API calls must incorporate an API key within the header. Upon onboarding, Edge will furnish distinct API keys for each access level, ensuring stringent access control and bolstering security measures.

Request Details


x-api-keyA unique API Key for the environment19YYgyZecTaSs2N0gjlq32Vh6DYes


NameDescriptionExampleTypeExpected FormatRequired
consumer_id A unique identifier provided by the client for each consumer 233433552String/^[a-zA-Z0-9-_.@]+$/Yes
application_idUnique identifier for an application, such as a loan. Used to build data analytics reports.loan12345StringNo
ssn Social security number 322-32-5345 StringDDD-DD-DDDDYes
first_name First name of the consumer John StringYes
middle_nameMiddle name of the consumerEdgeStringNo
last_name Last name of the consumer Smith StringYes
birth_date Date of birth 1776-07-04 StringYYYY-MM-DDYes
full_addressFull consumer address. Use when the address is not split into multiple fields222 South Riverside Plaza Suite 2200, Chicago, IL 60010StringNo
street_address Street number and name
Address unit designator and number
222 South Riverside Plaza StringNo
street_address2 Suite 2200 StringNo
city City Chicago StringNo
state State, full name or two-letter abbreviations IL, Illinois StringNo
zip Zip code. Allows both 5 digits and 9 digits 60606, 60606-0001 String/^[0-9]{5}(?:-[0-9]{4})?$/No
home_phone Landline number855-646-5201StringDDD-DDD-DDDDNo
mobile_phone Mobile phone number855-646-5201StringDDD-DDD-DDDDYes
emailEmail address of the consumer [email protected]String/\A[^@\s]+@[^@\s]+\z/Yes
secondary_emailSecondary email address of the consumer[email protected]String/\A[^@\s]+@[^@\s]+\z/No
employer_nameName of consumer's employerEdge LLCStringNo
secondary_employer_nameName of consumer's secondary employerEdge LLCStringNo
bank_nameName of the bankChase BankStringNo
routing_number Routing number of the account the consumer wants to use for IBV. Used to pre-select bank for verification 740000101String/^\d{9}$/No
account_number Account number of the account specified by the consumer to use for IBV analysis523423512String/^[0-9]*$/No
debit_card_numberNumber of the debit card5555 5555 5555 4444StringNo
additional_data Additional data for data analytics based on agreements with clients{“vantage_score”:500, “housing”:”rent”, “existing_customer”:true … Json ObjectNo
reference_date 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. 2022-04-14StringYYYY-MM-DDYes
ibv_vendor "Name of the ibv vendor if ibv data is attached.
Supported vendors are: Plaid, Yodlee, DecisionLogic, Flinks, LendMate, and Sophtron"
DecisionLogic StringNo space, one wordYes
ibv_data Raw ibv data obtained by the clients """ibv_data"": {
""encoding"": ""base64"",
""raw_data"": ""77u/PD94bW..."",
""raw_data_format"": ""xml""
Json ObjectYes
[ibv_data]. [encoding] Algorithm used to encode the raw IBV report. Currently only base64 is supported base64StringOnly “base64” is supportedYes
[ibv_data]. [raw_data] Encoded string of the raw IBV report downloaded from the IBV aggregator c77u/eyJSZ… StringEncoded stringYes
[ibv_data]. [raw_data_format]Format of the raw IBV reportxmlStringxml or jsonYes
partner_nameName of the partnerEdgeStringYes for partners only


  "consumer_id": "32892349",
  "application_id": "loan12345",
  "ssn": "322-32-5345",
  "first_name": "John",
  "middle_name": "Edge",
  "last_name": "Smith",
  "birth_date": "1776-07-04",
  "full_address": "222 South Riverside Plaza Suite 2200, Chicago, IL 60010",
  "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",
  "secondary_employer_name": "Edge2",
  "bank_name": "Bank of America",
  "routing_number": "0740000101",
  "account_number": "2302389238923",
  "debit_card_number": "1234567890123456",
  "additional_data": {
    "vantage_score": 500,
    "housing": "rent",
    "existing_customer": true
  "reference_date": "2023-08-01",
  "ibv_vendor": "Plaid",
  "ibv_data": {
  	"encoding": "base64",
  	"raw_data": "77u/eyJSZ…",
  	"raw_data_format": "json"
  "partner_name": "<only applies to partners>"



IBV Report - HTTP 200

The Client will usually receive the IBV Report when a request with IBV data has been successfully received. A request without IBV data may also receive the IBV report immediately if the consumer has an active IBV connection on the platform.


Processing Request - HTTP 202

The Client will receive this response when a request has been successfully received, but there is a delay in generating the IBV Report. In this case, the Client should try to retrieve the report using a GET method at a later time. It is recommended to include a delay for at least 5 seconds before attempting the Get method. An alternative method is to use Webhooks. The NinjaFetch platform can initiate a Webhooks call when report generation is complete. The Client should check whether the report has already been downloaded upon receiving the Webhooks call and only download the report when necessary.

Please do not repost the same payload when receiving a 202 response. A duplicate request will be created for the same consumer.

See Retrieve IBV Report for details about retrieving the report at a later time.
The 202 response will contain a reference URL to retrieve the IBV Report when it is available. Format of the URL is: https://ninjafetch.com/v1/ibv/requests/IBV<digits>.

The response will also contain a URL for the Consumer to link their bank account if it is a new Consumer or an existing Consumer whose IBV connection is no longer valid. The Client needs to send this link to the Consumer to establish a new connection to their bank accounts. Format of the link is https://ninjafetch.com/connect/<token>.

 "ibv_report": "https://ninjafetch.com/api/v1/ibv/requests/IBV23328923489",
 "product_request_id": "IBV23328923489”,
 "ibv_report_status": "initiated”,
 "ibv_connection_link": "https://ninjafetch.com/connect/438da2e3b1b3211e8d4a899c206c506c3cd4cbb055c5545aa5d6e79a6acb2752c9757f99bcf6bd8a9e45ca04ffdcae4a661b947ee66a681604a572d3c39a44"


Invalid Data - HTTP 400

The API will return a payload with information about invalid field values.

 "ibv_report": "https://ninjafetch.com/api/v1/ibv/requests/IBV23328923489",
 "product_request_id": "IBV23328923489”,
 "ibv_report_status": "initiated”,
 "ibv_connection_link": "https://ninjafetch.com/connect/438da2e3b1b3211e8d4a899c206c506c3cd4cbb055c5545aa5d6e79a6acb2752c9757f99bcf6bd8a9e45ca04ffdcae4a661b947ee66a681604a572d3c39a44"