Insights APIs
DeviceConnect: Insights API#
FinBox DeviceConnect REST API enables "server to server data" fetching of customers' Android device data. The customer's data can be fetched using the CUSTOMER_ID. API accepts JSON-encoded request bodies, returns JSON-encoded responses.
NOTE
Following will be shared by FinBox team at the time of integration:
SERVER_API_KEYSERVER_HASHDC_PREDICTORS_VERSION
Authentication#
FinBox provides a valid and signed certificate for all API methods and endpoints. To access the API methods requester must ensure that their connection library supports HTTPS.
Authentication for the APIs are based on SERVER_API_KEY provided by the FinBox. Server to server communication can commence when IP of requester are whitelisted on the FinBox servers. This can be easily done upon request.
Endpoints#
Base URL
For all the endpoints, the base URL for different environments are as follows:
| Environment | Base URL |
|---|---|
| Production | https://insights.finbox.in/v2/ |
| Development | https://insights.finbox.in/staging/ |
| Insights | Endpoint | Request Type | Description |
|---|---|---|---|
| General Predictors | /risk/predictors | POST | General features extracted from customer's data |
Predictors
Other than general predictors, there are also more predictor endpoints which will be shared based on the requirement by the FinBox team.
Request#
Request Header and Body#
For all the Insights API request structure is the same, all requests must have x-api-key field in header having the value as the SERVER_API_KEY shared by FinBox team. The following keys must be passed in every request body as keys to a JSON document:
Request Body
| Key | Type | Description |
|---|---|---|
| customer_id | String | CUSTOMER_ID for which feature vector is required |
| version | Integer | Version of the feature set shared by FinBox team as DC_PREDICTORS_VERSION |
| salt | String | A salt which is computed basis logic mentioned in the Salt Generation section |
metadata (optional) | Json | A dictionary which can be used to pass additional information for example loan_type, loan_amount or any tags |
Sample Metadata value
| Key | Type | Description |
|---|---|---|
| loan_type | String | Can be a string denoting the type of loan e.g. business_loan, msme_loan, personal_loan |
| loan_amount | Integer | Can be an integer value denoting the amount of loan in INR e.g. 3000, 25000, 50000 |
IMPORTANT
Please note that this CUSTOMER_ID is the same used as the unique identifier used in Android SDK while syncing the data.
Sample Request#
Headers
Request Body
Response#
API will give a JSON Response with the following keys:
Response Keys#
| Key | Description | Type | Nullable |
|---|---|---|---|
| customer_id | CUSTOMER_ID for which data was requested | STRING [260] | Yes |
| request_id | A unique string for each request | STRING [32] | Yes |
| status | Status of the operation. | STRING [20] | No |
| message | Description of status | STRING [200] | No |
| date_requested | Timestamp of processing request | STRING with YYYY-MM-DDThh:mm:ss:mil format | Yes |
| date_processed | Timestamp of processing completion | STRING with YYYY-MM-DDThh:mm:ss:mil format | Yes |
| data | An array of objects, each object representing the predictors, having keys name indicating the predictor name and value indicating the values | JSON | Yes |
::: danger data key
The list of predictors in the data key will be different based on the result API endpoint, feature set version and requester. This list will hence be shared separately by the FinBox team during the integration.
:::
::: warning NOTE Some of the keys in response may be missing based on the availability of data and HTTP Status code. Please refer to examples for each of the cases listed here. :::
status values#
Depending on the availability of data, there can be different cases with different status values as follows:
| Case | status value | HTTP Status Code | Description / Action |
|---|---|---|---|
| Calculation in progress | "in_progress" | 202 | The request input is correct and a webhook callback is registered |
| Calculation complete and data is available | "complete" | 200 | The request input is correct and processing has completed. Response contains the predictors |
| Calculation complete and data is unavailable | "no_data" | 200 | The request input is correct and processing has completed but response contains no predictors because of lack of data from user's device |
| Data fetch for request Id before webhook callback or after 24 hours | "webhook_not_found" | 200 | The request has no data assosciated with it because the request id was never sent from webhook callback or it is deleted because 24 hours passed from when it was sent |
| Invalid customer ID | "not_found" | 200 | User does not exist in FinBox system |
| Bad request | "error" | 400 | The request input is incorrect / malformed. More details available in message key |
| Unauthorized | "error" | 403 | This happens in case SERVER_API_KEY is incorrect or IP address in not whitelisted |
| Internal Server Error | "error" | 5xx | The request processing failed because of some internal error. In this case, please retry twice with an exponential backoff i.e. retry after 2 seconds, then retry after 5 seconds. If the issue persists, please contact support |
| Rate Limit Exceeded | "error" | 429 | This happens in case the maximum allowed rate limit on API exceeds. In this case, please retry twice with an exponential backoff i.e. retry after 2 seconds, then retry after 5 seconds. Contact FinBox to know your rate limits. |
::: danger IMPORTANT In case your are running a daily CRON that fetches data using insights API, ensure you are not breaching the rate limit. Please contact FinBox to know your rate limits. :::
Case 1 - Calculation in Progress#
HTTP Status Code: 202
Sample Response Body:
Case 2 - Calculation complete and data is available#
HTTP Status Code: 200
Sample Response Body:
Case 3 - Calculation complete and data is unavailable#
HTTP Status Code: 200
Sample Response Body:
Case 4 - Data fetch for request Id before webhook callback or after 24 hours#
HTTP Status Code: 200
Sample Response Body:
Case 5 - Invalid Customer ID#
HTTP Status Code: 200
Sample Response Body:
Case 6 - Bad Request#
HTTP Status Code: 400
Sample Response Body:
Case 7 - Unauthorized#
HTTP Status Code: 403
Sample Response Body:
Case 8 - Internal Server Error#
HTTP Status Code: 5xx
Sample Response Body:
Case 9 - Rate Limit Exceeded#
HTTP Status Code: 429
Sample Response Body:
Webhook Integration#
FinBox fires a webhook when a user's results are updated. The response received in the callback is same as the Insights API Response.
IMPORTANT
You have to register your webhook address with FinBox. Please get in touch with us for the same.
Pre-Computed Results#
If you already have a request_id, you can make a POST request of the insights API using the param source = webhook and request_id = {request_id}. This will return the updated data to you instantly.
https://insights.finbox.in/v2/risk/predictors?source=webhook&request_id={request_id}
IMPORTANT
- You must only use the
sourceparam once you have received the webhook. - Param
request_idmust be the same as the request_id received in the response payload of the webhook. - The
request_idexpires in 24 hours.