Logo

RIBBIT API (v4)

Download OpenAPI specification:Download

URL: https://www.ribbit.ai

REST API service for clients of RIBBIT

Authentication

bearer

Enter JWT Bearer token only

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Introduction

One RESTful API Connection

Integrate our CONNECT, INSIGHTS, and TRANSACT services directly into your platform using our CONNECT widget and JSON based REST API. Get the best of both worlds by pairing our CONNECT widget with the API. Your customers will have the option to CONNECT by logging into their bank account or entering their account information manually. RIBBIT will store and tokenize your customer's information so you do not have to worry about the storing, security, and compliance of PII and account information. You will receive an account token which will allow you to create payments or perform INSIGHTS analytics on your customers and their bank accounts using our API'.

Getting Started

Getting Started with our API

Our RESTful API allows you to integrate our services directly into your applications. Store customers and accounts, create and manage payments, and perform account and risk verifications. Services available in our API are also available through this website to interact within a user-friendly interface.

Much of our website is interactive, and most of the functions of our API are also available in a designed portal through our website. For example, you can add customers through the API, but then see these same customers on our website. You can add customers through the website and pull them from the API.

Environments

All customers, payments, risk verifications, API endpoints, etc. accessed through our test environment are separate from production. Payments created through our test website or test API will not process.

Once your implementation is complete, you can use our production environment to go live. This involves a different API address and different integration keys.

Test website: https://test.ribbit.ai
Production website: https://portal.ribbit.ai

Sandbox API: https://sandbox.ribbit.ai
Production API: https://prod.ribbit.ai


Access Control and IP Address Restrictions

The public IP address that is calling our API must be added to the white-list, or else you will be unable to complete a call. In the test environment, you can white-list your own IP address from the API home page. To white-list an IP address in production, you must contact your CFSI representative. In both environments, you can see your white-listed IP addresses from the API home page

If your public IP is not added to the list, any API call (aside from obtaining a token) will fail with an Unauthorized response.
To add an IP address to the whitelist in production, you must contact us.

Obtaining A Token

The first step to interacting with our API is to obtain a BEARER token. To do this, you will need your ClientID and ClientSecret. Credentials are available on the API home page

Your token will expire 20 minutes from creation (time frame subject to change). When you obtain your token, cache the token and use it for every call to our server until it expires. The expiration time will accompany your token.

To obtain a token, make a POST call to /token

    
    {
        "clientId" : "<your_client_id>",
        "clientSecret" : "<your_client_secret>"
    }

Next Steps

Now that you have successfully obtained a token, you can make calls specific to what you are trying to do.

Generate Token

Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
application/*+json
clientId
string
clientSecret
string
grantType
string

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
application/*+json
{
  • "clientId": "<your client_id>",
  • "clientSecret": "<your client_secret>",
  • "grantType": "client_credentials"
}

Response samples

Content type
application/json
{
  • "accessToken": "<your long token string>",
  • "tokenType": "Bearer",
  • "expiresOn": "2023-04-16T03:09:05.8036188+00:00"
}

CONNECT

Get Accounts

Retrieving Accounts

You can retrieve an account using the token that was provided at the time the account was created. If you have an enrollment token rather than an account token, you will first need to save the account using the enrollment token, which will provide an account token. You can also obtain all accounts for a customer using the associated customer Id. This is helpful in scenarios where you add a customer's account to their portfolio, then let the user chose at the time of payment what account to use. This scenario eliminates the need to capture account tokens using the widget - The use of the widget will save the account and associate it with your customer. Then, when you are ready to create a payment, call this endpoint without an accountTokenId or customerId parameter to bring back a list of all enrolled accounts.

To retreive the latest balance you will need to pass the query parameter updateBalance=true. The service will attempt to get the balance from the customers account; however, the financial institution may request additional login information or MFA answers from the customer before retrieving the balance on the account. You will need to look at the date and time returned in the lastUpdated field. If the date and time has not been updated within last 24 hours, then you will need to launch the enrollment widget in update mode to update the credentials and/or answer MFA on the account before a new balance is pulled for the account.
Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
query Parameters
accountTokenId
string

The accountTokenId for the retrieve accounts request

customerId
string

The customerId for the retrieve accounts request

merchantId
integer <int32>
Default: 0

The merchantId associated with the account record

updateBalance
boolean
Default: false

If set to true, the service will attempt to retrieve the latest balance on the account

Responses

Request samples 

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class Program
{
  public static async Task Main(string[] args)
  {
    using (var client = new HttpClient())
    {
      client.DefaultRequestHeaders.Add("Authorization", "Bearer <YOUR_JWT_HERE>");
      var request = await client.GetAsync("https://sandbox.ribbit.ai/v4/accounts?accountTokenId=string&customerId=string&merchantId=0&updateBalance=false");
      var response = await request.Content.ReadAsStringAsync();

      Console.WriteLine(response);
    }
  }
}

Response samples

Content type
application/json
{
  • "accountResults": [
    ]
}

Create/Modify Accounts

Creating an Account

We recommend adding accounts using our enrollment widget. Using our enrollment widget keeps all sensitive data, such as account numbers and online banking credentials, out of your environment and stored securely in our environment. In addition, our enrollment widget offers alternative methods of enrolling your bank account, such as using your online banking credentials to obtain the routing and account numbers. For more information about our enrollment widget, or to see a demo of how the widget works, please visit our Widgets home page.

If you create an account using our enrollment widget, the use of the widget replaces this step. The widget will create the account and return an account token (account ID), which you can use the same way you would use the account token returned from this API call

To create account(s) directly from the API (not the widget), you will need to obtain your customer's routing number, account number, and account type for each account.

You will also need to create a customer first. You will provide the CustomerId in your POST call for each account add, which will associate the account with the customer.

To create the account, send a POST call to /accounts/ You can provide a unique account token to reference this account, or leave the token empty and a unique GUID will be created as the token. This token can then be used to reference this account in the future or to make a payment using this account.

Once an account is added to a customer, it will be visible through our website by looking up the customer. To update the account, you must delete it and create a new account.

You may also be required to create an address and phone number, and have their respective IDs available
Depending on your contract with RIBBIT, address and/or phone number may be required
If an address or phone number is required, and it is not provided, you will receive a 400 - Bad Request error

Routing Number Validation
You are required to validate the authenticity of each routing number before being submitted for processing. This step should be performed at the time the routing number is accepted or entered.
To validate a routing number:
  • Multiply the first, fourth, and seventh digits of the routing number by three (3)
  • Multiply the second, fifth, and eigth digits of the routing number by seven (7)
  • Multiply the third, sixth, and ninth digits of the routing number by one (1)
  • Add all of the products of the above three steps together
  • If the sum of step 4 is divisible by 10, then the routing number is valid
For example: 
```int sum = (RT[0] x 3) + (RT[1] x 7) + RT[2] + (RT[3] x 3) + (RT[4] x 7) + RT[5] + (RT[6] x 3) + (RT[7] x 7) + RT[8];
if (sum % 10 == 0) return true; else return false;
```
If you submit a routing number that does not pass the above algorithm, you will receive a 400 - Bad Request error

Account Tokenization

When an account is created, it's sensitive information is securely stored and becomes inaccessible. This protects you and your customer's sensitive data, so that no account information can be retrieved from our API. A token is then used to reference the account any time a payment is created or information about an account is requested.

You can provide your own account token to this endpoint. The token you provide could be a reference number to something in your own system. If no token is provided when you create the account, a unique GUID will be created as the token. You can store this token in your system and use it for reference or rely on our GET /accounts endpoint to bring up a list of accounts each time a payment is created.

There are no endpoints available to return a full account number from our API. (Limit 1000 changes per batch)
Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
application/*+json

AccountPostBatchRequest object

Array of objects (AccountRequest)

The list of AccountRequest objects for the posting batch.

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
application/*+json
{
  • "accountRequests": [
    ]
}

Response samples

Content type
application/json
{
  • "accountBatchResponses": [
    ],
  • "accountResults": [
    ]
}

Delete Account

Deleting/Closing Accounts

To remove an account, make a DELETE call to this endpoint. Deleted accounts are soft-deleted from our system, and will have a status of Closed. Once deleted (closed), you will still be able to access this account, but will be unable to schedule payments from it.
Once an account has been deleted, it cannot be re-opened.

This will stop future scheduled payments from processing from this account. Payments that are scheduled to run the current business day may still process.

(Limit 1000 deletes per batch)
Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
query Parameters
accountTokenIdList
Array of strings

The list of accountTokenIds associated with accounts to delete. (either generated when the account was initially provided, or provided by you)

Responses

Request samples 

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class Program
{
  public static async Task Main(string[] args)
  {
    using (var client = new HttpClient())
    {
      client.DefaultRequestHeaders.Add("Authorization", "Bearer <YOUR_JWT_HERE>");
      var request = await client.DeleteAsync("https://sandbox.ribbit.ai/v4/accounts?accountTokenIdList=string");
      var response = await request.Content.ReadAsStringAsync();

      Console.WriteLine(response);
    }
  }
}

Response samples

Content type
application/json
{
  • "accountBatchResponses": [
    ]
}

Get Customers

This procedure returns all customers (with applicable parameters) that the user has permission to access

Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
query Parameters
customerId
string

customerId parameter

addressId
string

addressId parameter (customer Id must also be supplied)

phoneId
string

phoneId parameter (customer Id must also be supplied)

Responses

Request samples 

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class Program
{
  public static async Task Main(string[] args)
  {
    using (var client = new HttpClient())
    {
      client.DefaultRequestHeaders.Add("Authorization", "Bearer <YOUR_JWT_HERE>");
      var request = await client.GetAsync("https://sandbox.ribbit.ai/v4/customers?customerId=string&addressId=string&phoneId=string");
      var response = await request.Content.ReadAsStringAsync();

      Console.WriteLine(response);
    }
  }
}

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Create/Modify Customer(s)

  • A customer can be either a person or a business. If a customer is a person then both the first and last name fields are required. If the customer is a business then the business name field is required.
  • A customerId can be provided for a new customer, or one can be automatically generated. If the customerId property is left empty, a GUID will be generated for you to reference this customer
  • An address can be added/modified for the customer in the same call as adding/modifying the customer (optional). To add an address in the same call, a NewCustomerAddress object should be included in the CustomerAddress property
  • A phone number can be added/modified for the customer in the same call as adding/modifying the customer (optional). To add an address in the same call, a NewPhoneNumber object should be included in the CustomerPhoneNumber property

Creating Customers

There are several methods available to create customers:
  1. An API call can be made to this endpoint
  2. Using our enrollment widget.
    For more information on our widget, please visit the Widgets home page.
  3. Using our web payments portal, when anonymous customer registration is enabled.
    For more information about our web payments portal, please visit the Web Payments Portal home page
  4. Directly through our website
Regardless of what method is used to create a customer, the customer can be accessed from any method.
Customers created via API can be accessed via API, through our website, or from our widget

To create or modify a customer using our API, you will make a POST call to /customers/.

  • Customer IDs
    • When creating a customer, provide your unique ID that references the customer, and we will use that ID to reference the customer in our system. If you do not provide a Customer ID, a unique GUID will be created as your customer ID and returned to you in the response. You should save this ID back to your system and use it any time you want to reference this customer (such as creating a payment for this customer).
  • Addresses and Phone Numbers
    • You can specify addresses and phone numbers when creating a customer. You can use the same endpoint to add these pieces of data afterwards by submitting the current customer object information and w/ the new addresses and phones to add.
Limit 1000 changes per batch.
Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
application/*+json

customerPostBatchRequest Object

Array of objects (CustomerRequest) Nullable

The list of customerRequests in the post batch.

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
application/*+json
{
  • "customerRequests": [
    ]
}

Response samples

Content type
application/json
{
  • "customerBatchResponses": [
    ],
  • "customerResults": [
    ]
}

Delete Customers

  • The following customer objects can be deleted: customer Ids, address Ids tied to a specific customer, email addresses tied to a specific customer, and phone numbers tied to a specific customer.
  • Deleting a customer Id will remove the customer from your view
  • A deleted customer will still be able to access their customer profile online using their email address
  • This will stop future scheduled payments associated with this customer from processing
  • Warning: Payments that are scheduled to run the current business day may still process
Limit 1000 deletes per batch.
Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
query Parameters
customerIdList
Array of strings

List of all customerIds to remove.

addressIdList
Array of strings

List of all addressIds to remove. Passed in list as customerid_addressId combo keys

phoneIdList
Array of strings

List of all phoneIds to remove. Passed in list as customerid_phoneId combo keys

Responses

Request samples 

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class Program
{
  public static async Task Main(string[] args)
  {
    using (var client = new HttpClient())
    {
      client.DefaultRequestHeaders.Add("Authorization", "Bearer <YOUR_JWT_HERE>");
      var request = await client.DeleteAsync("https://sandbox.ribbit.ai/v4/customers?customerIdList=string&addressIdList=string&phoneIdList=string");
      var response = await request.Content.ReadAsStringAsync();

      Console.WriteLine(response);
    }
  }
}

Response samples

Content type
application/json
{
  • "customerBatchResponses": [
    ]
}

New CONNECT Session

This endpoint creates a new CONNECT session. It is required to be called every time before a CONNECT session is launched. This endpoint does not require an Authorization header. Supply the CONNECT ClientId and ClientSecret (different from your API credentials) in the body.

When a CONNECT session is created, you can do a few different things with it

  • Launch it in your app or website
  • Send the user a text message with a link to access CONNECT
  • Send the user an e-mail with a link to access CONNECT
  • Capture the URL and provide it to your customer

To launch CONNECT within your app or website

  1. Include our library in your app or website
  2. Call this endpoint to create a session
  3. Supply the token returned from this endpoint to your app or website

To send your customer a text/e-mail with a link

  1. When calling this endpoint, specify notificationType=1 for SMS or 2 for e-mail TIP: You can provide your webhook URL to know when your customer completes CONNECT

To give your customer a URL to access CONNECT

  1. Call this endpoint
  2. In the response, capture the URL. This URL can be provided to your customer up until the expiration time.

For integration details, please see https://test.RIBBIT.ai/CONNECT

Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
application/*+json

A CONNECT request object that contains your CONNECT token, customer PII, and startup options

object (TokenRequest)
object (CONNECTWidgetTokenRequestCustomer)
object (CONNECTWidgetTokenRequestTerms)
object (CONNECTWidgetTokenRequestSettings)
notificationType
integer <int32> (WidgetRequestNotificationType)
Enum: 0 1 2

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
application/*+json
{
  • "token": {
    },
  • "customer": {
    },
  • "terms": {
    },
  • "settings": {
    },
  • "notificationType": 0
}

Response samples

Content type
application/json
{}

Get Account Details from CONNECT session

The client has 24 hours to retrieve an account from our bank linking process. The enrollment token is required in order to retrieve the account information.

Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
path Parameters
accountTokenId
required
string

The accountTokenId of the account registered to RIBBIT.

Responses

Request samples 

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class Program
{
  public static async Task Main(string[] args)
  {
    using (var client = new HttpClient())
    {
      client.DefaultRequestHeaders.Add("Authorization", "Bearer <YOUR_JWT_HERE>");
      var AccountTokenId = "YOUR_accountTokenId_PARAMETER";
      var request = await client.GetAsync("https://sandbox.ribbit.ai/v4/accounts/" + AccountTokenId + "/export");
      var response = await request.Content.ReadAsStringAsync();

      Console.WriteLine(response);
    }
  }
}

Response samples

Content type
application/json
{
  • "institutionName": "Fifth Third Bank",
  • "accountType": "Checking",
  • "accountHolderName": "John M Doe",
  • "routingNumber": "042000314",
  • "accountNumber": "1234567",
  • "accountNickname": "Johns Free Checking Account x4234",
  • "lastAvailableBalance": 1220,
  • "lastCurrentBalance": 1220
}

Transaction History

This endpoint will return transactions for a specific linked account. This endpoint can only be called after a user login has been created and the account has been synced. Transactions can be returned by a webhook or through the endpoint. Default date range is set to 90 days before todays date. You can set a date range using this object. Just make sure the date range is between 90 days.
Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
path Parameters
accountTokenId
required
string

The account token (either generated when the account was initially created, or provided by you)

accountToken
required
string
query Parameters
startDateTime
string <date-time>

Custom date range start date time.

endDateTime
string <date-time>

Customer date range end date time.

Responses

Request samples 

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class Program
{
  public static async Task Main(string[] args)
  {
    using (var client = new HttpClient())
    {
      client.DefaultRequestHeaders.Add("Authorization", "Bearer <YOUR_JWT_HERE>");
      var AccountTokenId = "YOUR_accountTokenId_PARAMETER";
      var AccountToken = "YOUR_accountToken_PARAMETER";
      var request = await client.GetAsync("https://sandbox.ribbit.ai/v4/connect/transactions/" + AccountToken + "?startDateTime=2019-08-24T14%3A15%3A22Z&endDateTime=2019-08-24T14%3A15%3A22Z");
      var response = await request.Content.ReadAsStringAsync();

      Console.WriteLine(response);
    }
  }
}

Response samples

Content type
application/json
{
  • "userId": "5823BD01-13F6-4D1C-99F2-33B0F3607216",
  • "tokenId": "9279BC87-0A9C-4152-8DCD-4F30D7735FF3",
  • "syncStatus": "Synced",
  • "syncInstructions": "Next step instructions",
  • "challenges": [
    ]
}

INSIGHTS

Run INSIGHTS Analytics

Run INSIGHTS Analytics

Our data network identifies how often a bank account has been presented for payment and analyzes the bank/payment behavior to better predict financial outcomes.RIBBIT's proprietary database of linkages between accounts and PII elements results in a set of verification and payment behavior attributes that can be used to identify risk, fraud, and ability to afford payment(s) for underwriting / onboarding of bank accounts.

This endpoint can be used to run any of our insights products.You must provide the correct ProductId in the request.

ProductId 1: Bank QUALIFY
BankQUALIFY identifies account ownership, flags potential fraud and assesses payment affordability risk based on six simple attributes.


ProductId 2: Bank VERIFY+
BankVERIFY+ identifies fraud and payment affordability risk based on an applicant’s bank account history with routing and account numbers and a few pieces of PII.
List of Errors for Bank QUALIFY and Bank VERIFY+
  • Status Code 2 - Account Validation Failure
    • 1 - Invalid Routing Number
    • 2 - Invalid Account Number
    • 3 - Account Structure: The account number may be incorrect or malformed for the routing number submitted
  • Status Code 3 - Account Format Error
    • 4 - Account number is invalid. Account number can only have numeric values.
    • 5 - Account number cannot exceed 17 characters in length.
    • 6 - Routing number is invalid. Routing number can only have numeric values.
    • 7 - The account number length is invalid.
    • 8 - Routing number can only be 9 characters long.
    • 9 - Account number must be at least 5 characters long.
    • 10 - The routing and account numbers cannot match
  • Status Code 4 - Input Detail Error
    • 11 - Business email cannot exceed 100 characters in length.
    • 12 - Business email is not a valid email address.
    • 13 - Business name is required.
    • 14 - Business name length cannot be longer than 150 characters.
    • 15 - Business phone number cannot exceed 12 characters in length.
    • 16 - Business phone number length is invalid.
    • 17 - First and last names are required.
    • 18 - First name is required.
    • 19 - Last name is required.
    • 20 - Email cannot exceed 100 characters in length.
    • 21 - ReferenceId cannot exceed 100 characters.
    • 22 - First name must be at least 2 characters long.
    • 23 - First name cannot exceed 100 characters long.
    • 24 - Middle name cannot exceed 100 characters in length.
    • 25 - Last name must be at least 2 characters in length.
    • 26 - Last name cannot exceed 100 characters in length.
    • 27 - Length of the first name: (FirstName returned) needs to be at least 2 characters in length.
    • 28 - Length of the last name: (LastName returned) needs to be at least 2 characters in length.
    • 29 - Phone number cannot exceed 12 characters in length.
    • 30 - Email is not a valid email address.
    • 31 - Phone number length is invalid.
    • 35 - Signer is required for business
    • 36 - You can only submit a business or consumer request not both.
    • 37 - A business or consumer request is required.
    • 38 - Terms can only be 'daily_oblig', 'weekly_oblig', 'biweekly_oblig', 'monthly_oblig'
    • 39 - Payment amount cannot be less than zero.
    • 40 - Offer amount cannot be less than zero.
    • 41 - Consumer address cannot be null
    • 42 - Consumer city cannot be null
    • 43 - Consumer state cannot be null
    • 44 - Consumer zip cannot be null
    • 45 - Business address cannot be null
    • 46 - Business city cannot be null
    • 47 - Business state cannot be null
    • 48 - Business zip cannot be null
  • Status Code 5 - Processing Request Error
    • 32 - There was a problem with connecting to our internal bank account network.
    • 33 - There was a problem generating insights due to an analytics server issue.
    • 34 - There count of identities may indicate potential fraud issues. Please request additional information.
ProductId 3: Bank LOGIN+
BankLOGIN+ performs analytics on bank account transaction data by using transaction and account data from any aggregator.You must pass your third-party aggregator data into this endpoint. To use RIBBIT’s CONNECT widget to capture credentialed account details, please see theCONNECT Documentation.
List of Errors for Bank LOGIN+
  • 200 Response with Error Message
    • There was an issue with the service. If this issue continues, please contact RIBBIT Support for assistance.
    • No transactions or no valid account types with transactions
    • The provider number entered does not match a supported third party data provider
  • 400 Response Error Messages
    • The request is in the wrong format. Please check the request body example and try again.
    • ProductId must be 1 for BankQUALIFY, 2 for BankVERIFY+ or 3 for BankLOGIN+
Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
application/*+json

Insights request object

productId
integer <int32> [ 1 .. 3 ]

This value must be 1 for BankQUALIFY, 2 for BankVERIFY+, or 3 for BankLOGIN+

referenceId
string

Provide the unique application or customer id from your system.

inquiryId
string

RIBBIT's InquiryId

object (InsightAccount)
offerAmount
number <double>

The total amount of the loan, the offer amount for a credit product, or the maximum amount of spending allowed. If you do not have a total amount at this time, use an estimate or average. When being used at the top of an underwriting waterfall, the median amount is recommended.

terms
string

The terms of the repayment schedule. Available options are daily_oblig, weekly_oblig, biweekly_oblig, or monthly_oblig.

paymentAmount
number <double>

The amount of each payment, or the median payment/spending amount.

refresh
boolean

Defualt value is set to false.

object (InsightsConsumer)

Insights Consumer Request

object (InsightsBusiness)

Insights Business Request

object (InsightsBLP)

Insights BankLOGIN+ Request

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
application/*+json
Example
BankQUALIFY
BankQUALIFY
BankVERIFY+
BankLOGIN+
{
  • "productId": 1,
  • "referenceId": "A72F817B-744F-4D1F-B347-71E026D0B181",
  • "inquiryId": null,
  • "account": {
    },
  • "offerAmount": 6000,
  • "terms": "daily_oblig",
  • "paymentAmount": 500,
  • "refresh": false,
  • "consumer": {
    },
  • "business": null,
  • "blp": null
}

Response samples

Content type
application/json
Example
BankQUALIFY
BankQUALIFY
BankVERIFY+
BankLOGIN+
Account Validation Failure
Account Format Error
Input Detail Error
Processing Request Error
{
  • "inquiryId": "c3ba1b15-8972-43b2-a6c8-e68de24bea56",
  • "inquiryDate": "2023-04-16T02:09:06.2331332Z",
  • "status": {
    },
  • "bqAccountAnalyticsResult": {
    }
}

Get INSIGHTS Result

Get INSIGHTS Results

Use this endpoint to retrieve the results from a previous run of BankQUALIFY, BankVERIFY+, or BankLOGIN+.

For inquiries previously ran via an API call, provide the inquiryId returned from the original API results.

For inquiries previously ran using the CONNECT widget, use the inquiryId and inquiryType received from the complete event. For more information about CONNECT event handling, see https://test.RIBBIT.ai/Widgets/Events. For details on using the CONNECT widget, please visit the CONNECT documentation here: https://test.RIBBIT.ai/CONNECT
  • ProductId 1 : Bank QUALIFY
  • ProductId 2 : Bank VERIFY+
  • ProductId 3 : Bank LOGIN+
Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
path Parameters
productId
required
integer <int32>

The productId from the INSIGHTS request

inquiryId
required
string

The id of the inquiry id returned from the INSIGHTS request

Responses

Request samples 

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class Program
{
  public static async Task Main(string[] args)
  {
    using (var client = new HttpClient())
    {
      client.DefaultRequestHeaders.Add("Authorization", "Bearer <YOUR_JWT_HERE>");
      var ProductId = "YOUR_productId_PARAMETER";
      var InquiryId = "YOUR_inquiryId_PARAMETER";
      var request = await client.GetAsync("https://sandbox.ribbit.ai/v4/" + ProductId + "/" + InquiryId);
      var response = await request.Content.ReadAsStringAsync();

      Console.WriteLine(response);
    }
  }
}

Response samples

Content type
application/json
Example
BankQUALIFY
BankQUALIFY
BankVERIFY+
BankLOGIN+
Account Validation Failure
Account Format Error
Input Detail Error
Processing Request Error
{
  • "inquiryId": "f8fec781-f7cc-4d85-8436-cf6b58dc2594",
  • "inquiryDate": "2023-04-16T02:09:06.2953383Z",
  • "status": {
    },
  • "bqAccountAnalyticsResult": {
    }
}

Run AffordAI

The AffordAI Affordability Report is an easy-to-read presentation of BankLOGIN+ insights results. With AffordAI, your users will get instant access to identity and account verification, cash flow trends, affordability recommendations and transaction histories—all in a single PDF document.

Click here for the AffordAI integration guide, sample reports, and an operations reference guide.

Run the AffordAI Report

To generate the PDF report, send a BankLOGIN+ inquiry ID to this endpoint. The advanced calculations made in this report rely on the latest data, so the AffordAI report must be requested with a BankLOGIN+ v2.0 inquiry ID. You may optionally provide your own referenceId to tie this report to a specific customer or event in your system.

Response types

The AffordAI response object contains a status module for HTTP 200 and 400 responses. There are 4 possible statusCodes:
  1. Success
  2. Success with non-fatal errors
  3. Fatal error from request format
  4. Fatal error from dependency
StatusCode 1 or 2 responses will contain a fileData object. The report file is returned as a base 64 string in fileData.report. You can convert this base 64 string into a PDF file.

Error codes and simulation

Errors are listed in the response as an array in the status.errors object.
errorCodedescription
1Fatal: blpInquiryId could not be found in the request body
2Fatal: blpInquiryId was not in the correct format
3Fatal: This blpInquiryId does not exist or you are not authorized to access this request
4Fatal: This blpInquiryId is not supported. AffordAI requires BankLOGIN+ 2.0 or above
5Fatal: This blpInquiryId was not a successful BankLOGIN+ inquiry
6Fatal: Could not connect to BankLOGIN+
7Caution: Limited data available
8Caution: blpInquiryId was found but ReferenceId does not match
9Fatal: Could not connect to Microsoft Power BI
10Fatal: Microsoft Power BI did not recognize the requested report
11Fatal: Microsoft Power BI failed to return the requested report
12Caution: Microsoft Power BI was successful but took longer than expected
13Fatal: Could not parse this blpInquiryId
15Fatal: Database error

To simulate a given error, include the optional simulate integer field in the request body. For instance, the following request will return an HTTP 400 response with status.statusCode = 3 and status.errors[0].errorCode = 13.

```{
"blpInquiryId": "9ff19261-a380-4a37-807e-e40002060f7c",
"referenceId": "A72F817B-744F-4D1F-B347-71E026D0B181",
"simulate": 13
}```

To simulate a full success with no errors (statusCode 1), enter “simulate”: 0. The response fields will mimic a live report pull but does not return a full base64 string, making it a much faster option for network or endpoint testing than the non-simulated option.

Authorizations:
bearer (Policy:Roles:AuthenticationSchemes:)
Request Body schema:
application/json-patch+json
application/json-patch+json
application/json
application/*+json
blpInquiryId
required
string non-empty

The InquiryId from a BankLOGIN+ result

referenceId
string <= 100 characters

The ID of the customer in your system. If this ReferenceId does not match with the CustomerId specified in the BankLOGIN+ inquiry, the CustomerId in the BankLOGIN+ inquiry is used instead.

simulate
integer <int32> Nullable

Enables the simulation of AffordAI error codes

Responses

Request samples

Content type
application/json-patch+json
application/json-patch+json
application/json
application/*+json
{
  • "blpInquiryId": "9ff19261-a380-4a37-807e-e40002060f7c",
  • "referenceId": "A72F817B-744F-4D1F-B347-71E026D0B181"
}

Response samples

Content type
application/json
{
  • "reportId": "64B65EDA-0A61-407A-B83F-EE1D5E991B70",
  • "referenceId": "A72F817B-744F-4D1F-B347-71E026D0B181",
  • "status": {
    },
  • "fileData": {
    }
}