—
–
/

to search

Introducing Setu Changelog Check it out ↗

Reading time — 4 minutes

Edit this page ↗

#API integration

Here are the URLs you would need for calling Setu Insights APIs—

#Data ingestion APIs

#Create FI Data block API

Call this API to create an FI data block for the customer data you would like to feed into Setu Insights.

Request

Send the financial data as payload in the body. The payload should be same as the data provided by the FIP. The JSON schema for different data types is available in FI Data Types. The ReBIT schema is available here.

If you need to pass multiple accounts of same type for a customer, you can go about it in one of the following ways,

  1. Pass the data for all accounts in a single call to the ingest API.
  2. If you feel the data is too large, you can pass the data for each account in a separate call to this API. Remember to pass the same refId parameter in each call.

We recommend using the first approach. There should be no issues with JSON data of upto 1 MB.


If you want to pass accounts of different types, ie deposit, mutual_fund, etf etc. we recommend the second approach. Remember to pass the same refId parameter in each call. We plan to support this with a single API call approach in the future.


POST /v3/fiData?refId=your-unique-ref-id
  --header 'Content-Type: application/json'
  --header 'x-client-id: <client_id>'
  --header 'x-client-secret: <client_secret>'
  --header 'x-product-instance-id: <product_instance_id>'
  --data-raw '[{
        "account": {
            "linkedAccRef": "8a467ff9-51a5-4c8e-9cec-396d56acda13",
            "maskedAccNumber": "XXXXXXXXXX2381",
            "type": "deposit",
            "version": "1.2",
            "profile": {
                "holders": {
                    "holder": [
                        {
                            "name": "Ashok Kumar",
                            "dob": "2019-08-24",
                            "mobile": "9999999999",
                            "nominee": "REGISTERED",
                            "landline": "1234567890",
                            "address": "123 Main Street",
                            "email": "ashok@xyz.com",
                            "pan": "ABCD1234X",
                            "ckycCompliance": true
                        }
                    ],
                    "type": "SINGLE"
                }
            },
            "summary": {
                "balanceDateTime": "2022-11-08T20:45:48+05:30",
                "branch": "BALTANA",
                "currency": "INR",
                "currentBalance": "680.56",
                "status": "ACTIVE",
                "type": "SAVINGS"
            },
            "transactions": {
                "startDate": "2021-09-01",
                "endDate": "2023-09-07",
                "transaction": [
                    {
                        "amount": "1000",
                        "currentBalance": "20000",
                        "mode": "OTHERS",
                        "narration": "CDM Service Charges",
                        "transactionTimestamp": "2021-10-02T23:59:59+05:30",
                        "type": "CREDIT",
                        "valueDate": "2021-10-02"
                    }
                ]
            }
        }
    }]
Response

The response confirms the data has been received and provides the `refId` and an expiry date for the data.

{
    "status": "Success",
    "version": "0.73.1",
    "body": {
        "refId": "test-single-account-15",
        "fiSchema": [
            "deposit"
        ],
        "expiryDate": "2025-07-06 07:03:12.312"
    }
}

#Insight generation APIs

The Insights API is a two-step process. First, you request insight generation for a given refId. Then, you poll another endpoint to retrieve the results.

#1. Request Insight Generation

This endpoint triggers an asynchronous job to generate insights on the data previously submitted with a refId.

You can use the same refId for multiple data blocks for a single customer.

Request

Send the customer refId and the templateId as the payload. You can also provide an optional accounts filter to generate insights only for specific accounts.

POST /v3/insight
  --header 'Content-Type: application/json'
  --header 'x-client-id: <client_id>'
  --header 'x-client-secret: <client_secret>'
  --header 'x-product-instance-id: <product_instance_id>'
  --data-raw '{
    "templateId": "b6418647-6397-47a8-8219-1bff5f7ddfe5",
    "refId": "test-single-account-15",
    "filters": {
        "accounts": []
    }
  }'
Response

A successful request queues the insight generation job and returns a `reportId`. A notification will be posted after successful generation of insights. See notifications.

The reportId also can be used fetch the Insights report using 2. Retrieve Insights API.

{
    "status": "Success",
    "version": "0.73.1",
    "statusDescription": null,
    "body": {
        "reportId": "05a5a389-b922-4197-be03-b309cdcc575a",
        "status": "queued",
        "reason": "NA"
    }
}

#2. Retrieve Insights

Use the reportId from the previous step to poll this endpoint for the insight report.

Request
GET /v3/insight?reportId={reportId}
--header 'Accept: application/json'
--header 'x-client-id: <client_id>'
--header 'x-client-secret: <client_secret>'
--header 'x-product-instance-id: <product_instance_id>'
Response

The response will contain the generated insights. The `status` field for each account indicates whether insights were generated successfully.

{
    "status": "Success",
    "version": "0.73.1",
    "statusDescription": null,
    "body": {
        "accounts": [
            {
                "accountIdentifierKey": "8a467ff9-51a5-4c8e-9cec-396d56acda13",
                "insights": [
                    {
                        "indicatorName": "fraud_flags",
                        "value": [
                            {
                                "title": "Mostly Cash Mode",
                                "description": "Maximum transactions (80%) involving cash deposit or withdrawals",
                                "value": "100% of transactions were cash based"
                            }
                        ],
                        "meta": null
                    }
                ],
                "status": "success",
                "reason": "NA",
                "fiType": "deposit"
            },
            {
                "accountIdentifierKey": "99967ff9-51a5-4c8e-9cec-396d56acda13",
                "insights": [],
                "status": "skipped",
                "reason": "NA",
                "fiType": "NA"
            }
        ],
        "aggregatedInsights": null
    }
}

Was this page helpful?