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
| Name | Description | Example | Required |
|---|---|---|---|
| x-api-key | A unique API Key for the environment | 19YYgyZecTaSs2N0gjlq32Vh6D | Yes |
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-_.@]+$/ | 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 | 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 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 feature and score calculation. The date is used to evaluate recent account activities, so it has a direct impact on the result. | 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 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"
}
Updated 8 months ago