IBV Report without IBV Data

The IBV REST APIs are specifically crafted to facilitate server-to-server communication. Clients can make a POST request to https://ninjafetch.com/api/v1/ibv/requests 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

Header

NameDescriptionExampleRequired
x-api-keyA unique API Key for the environment19YYgyZecTaSs2N0gjlq32Vh6DYes

Body

Name

Description

Example

Type

Expected Format

Required

consumer_id

A unique identifier provided by the client for each consumer

233433552

String

/^[a-zA-Z0-9-_.@][a-zA-Z0-9-_.@]+$/

Yes

application_id

Unique identifier for an application, such as a loan. Used to build data analytics reports.

loan12345

String

No

ssn

Social security number

322-32-5345

String

DDD-DD-DDDD

Yes

first_name

First name of the consumer

John

String

Yes

middle_name

Middle name of the consumer

Edge

String

No

last_name

Last name of the consumer

Smith

String

Yes

birth_date

Date of birth

1776-07-04

String

YYYY-MM-DD

No

full_address

Full consumer address. Use when the address is not split into multiple fields

222 South Riverside Plaza Suite 2200, Chicago, IL 60010

String

No

street_address

Street number and name
Address unit designator and number

222 South Riverside Plaza

String

No

street_address2

Suite 2200

String

No

city

City

Chicago

String

No

state

State, full name or two-letter abbreviations

IL, Illinois

String

No

zip _code

Zip code. Allows both 5 digits and 9 digits

60606, 60606-0001

String

/^[0-9]{5}(?:-[0-9]{4})?$/

No

home_phone

Landline number

8556465201

String

DDD-DDD-DDDD

No

mobile_phone

Mobile phone number

8556465201

String

DDD-DDD-DDDD

Yes

email

Email address of the consumer

[email protected]

String

/\A[^@\s]+@[^@\s]+\z/

Yes

secondary_email

Secondary email address of the consumer

[email protected]

String

/\A[^@\s]+@[^@\s]+\z/

No

employer_name

Name of consumer's employer

EDGE LLC

String

No

secondary_employer_name

Name of consumer's secondary employer

EDGE LLC

String

No

bank_name

Name of the bank

Chase Bank

String

No

routing_number

Routing number of the account the consumer wants to use for IBV. Used to pre-select bank for verification

740000101

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

debit_card_number

Number of the debit card

5555 5555 5555 4444

String

No

additional_data

Additional data for data analytics based on agreements with clients

{“vantage_score”:500, “housing”:”rent”, “existing_customer”:true …

Json Object

No

reference_date

As of date for attribute and score calculation, used to evaluate recent account activities. Default is the current date.

2022-04-14

String

YYYY-MM-DD

Yes

partner_name

Name of the partner

Edge

String

Yes for partners only

Example

{
  "consumer_id": "CN32892349",
  "application_id": "loan12345",
  "ssn": "322-32-5345",
  "first_name": "John",
  "middle_name": "Edge",
  "last_name": "Smith",
  "birth_date": "1776-07-04",
  "full_address": "full address",
  "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",
  "partner_name": "<only applies to partners>"
}

Responses

👍

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 EDGE Connect 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"
}