🚀 Get Started with the Bankuity API
Welcome to the Bankuity API integration guide. This documentation is tailored for server-to-server integration, where your backend system interacts directly with Bankuity's services.
Before proceeding with any API calls, your organization must receive and securely store two distinct API keys from Bankuity:
- Bankuity API Key (
[apikey]): Used in theAuthorizationheader for identity verification and access control. - Subscription Key (
Ocp-Apim-Subscription-Key): Used in theOcp-Apim-Subscription-Keyheader for subscription management and routing.
These keys must be handled only on the backend. Never expose them in client-side code.
The Bankuity Income Analyzer relies on data sourced from an Instant Bank Verification (IBV) provider. Before starting your integration tests, you must:
- Coordinate Provider Choice: Select the IBV provider your company wishes to use (e.g.,
Chirp). - Coordinate Access: Work with your IBV provider and Bankuity to ensure that Bankuity has the necessary access permissions to retrieve the specified client data. Access methods depend entirely on the specific IBV provider's configuration.
Before initiating data analysis, confirm that your API keys are working correctly by calling the simple /api/ping endpoint. This step ensures that both your Ocp-Apim-Subscription-Key and Authorization credentials are valid and recognized by the API gateway.
Endpoint Details
| Method | Endpoint | Description |
|---|---|---|
GET | https://apisbx.bankuity.com/incomeanalyzer-apiv2/api/ping | Verifies connectivity and credential recognition. |
Expected Responses
| Status Code | Response Body | Description |
|---|---|---|
200 OK | { "message": "Hello <your-name>" } | Success. Your Subscription Key and Authorization have been validated. |
400 Unauthorized | (No body) | Failure. Check both your Subscription Key (Ocp-Apim-Subscription-Key) and your Bankuity API Key (Authorization header). |
cURL Example
Use this cURL command to verify your connection. Both the Ocp-Apim-Subscription-Key and the Authorization header with your Bankuity API Key ([apikey]) are required for this infrastructure test.
curl --location --request GET \
"https://apisbx.bankuity.com/incomeanalyzer-apiv2/api/ping" \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: [ocpkey]" \
-H "Authorization: [apikey]"Once the connection test is successful (200 OK), you can proceed to generate an income analysis report using the main endpoint.
This endpoint requests Bankuity to fetch the raw data from the specified IBV provider, calculate the analysis, and return the final report.
Endpoint Details
| Method | Endpoint | Description |
|---|---|---|
GET | https://apisbx.bankuity.com/incomeanalyzer-apiv2/v2/analysis/income | Initiates and returns the income analysis report. |
cURL Example
Use this cURL command to make your first request. Remember to replace [ocpkey], [apikey], and XXX with your actual subscription key, API key, and a unique request code, respectively.
curl --ssl-no-revoke \
--location --request GET \
"https://apisbx.bankuity.com/incomeanalyzer-apiv2/v2/analysis/income?requestCode=XXX&ibvProviderName=Chirp" \
-H "Ocp-Apim-Subscription-Key: [ocpkey]" \
-H "Content-Type: application/json" \
-H "Authorization: [apikey]"Required Query Parameters
| Parameter | Example | Description |
|---|---|---|
requestCode | X123X12 | Your provider-specific identifier for this specific client request. |
ibvProviderName | Chirp | The name of the integrated IBV provider from which data should be sourced. |
Report Response and requestID
Upon successful completion, this call returns the full analysis report as specified in the detailed API documentation. Crucially, the returned report JSON will include a requestID.
The requestID is a unique, Bankuity-generated identifier for this analysis instance. It can be used in subsequent calls to other API endpoints to access the data.
A. Data Snapshot Control (asOfDate)
The /v2/analysis/income method includes one optional query parameter:
| Parameter | Format | Description |
|---|---|---|
asOfDate | YYYY-MM-DD | Specifies the exact date for which the analysis should be calculated. |
Default Behavior: If asOfDate is not specified, the system will use the snapshot date of the data returned by the IBV provider. For example, if the IBV provider's client data snapshot is one month old, the report will be calculated as if you ran it one month ago.
Comparison Use Case: For comprehensive due diligence, you may want to run two reports: one for the origination date and one for the current date to review changes in the customer profile. Note that this only works if the IBV provider has historical data available for the selected dates.
Tip: Our API has a specific method to compare two generated reports: /v2/analysis/insights. We suggest using this dedicated endpoint for reviewing changes between snapshots.
B. Asynchronous Event Integration (Webhooks)
For faster and more robust integration, Bankuity supports event-driven workflows using webhooks at multiple points.
IBV Provider Webhooks
Some IBV providers allow setting up webhooks within their profiles. When configured, Bankuity receives a notification as soon as new or updated data is available. This enables Bankuity to pre-fetch and process the data asynchronously. If the data is already pre-fetched, subsequent calls to the /v2/analysis/income endpoint will execute much faster.
Bankuity Webhooks
You can specify a Customer URL where Bankuity will send a webhook notification when the analysis report is fully calculated and ready for a given requestCode. This allows for a fully asynchronous integration pattern:
- The client initiates the request.
- The client server receives a webhook notification from Bankuity containing a small JSON payload with basic data, including the
requestID. - The client system can then use Bankuity endpoints to retrieve the final report using the provided
requestIDorrequestCode, ensuring optimal performance and resource utilization.