diff --git a/content/data/insights/quickstart.mdx b/content/data/insights/quickstart.mdx
index 004443a1..6ef0d3f9 100644
--- a/content/data/insights/quickstart.mdx
+++ b/content/data/insights/quickstart.mdx
@@ -9,7 +9,7 @@ visible_in_sidebar: true
Here is a quick summary of steps to help you integrate with Setu’s Insights API. Before you start, there are some key terms that will be referred to periodically in the documentation—
-- **Reference Id**—Developers can define an identifier to manage and track one customer's data points. This identifier is used throughout the lifecycle to push data, generate insights and finally purge any data from the system.
+- **Reference Id**—Developers can define an identifier to manage and track one customer's data points. This `refId` groups together all data for a single analysis session and is used throughout the lifecycle to push data and generate insights.
- **FI Data block**—FI Data blocks are the data received from the FIP (Financial information provider), via the AA. Currently, we support bank statement, equities, mutual_fund and etf datablocks. In addition, we support ePDF-based bank statements for Indian banks.
- **Template**—A template is a pre-configured format that determines the structure of the generated report, including which insights to generate. You can pick and choose exactly what insights should be added to a template, based on your needs.
For example, if you only want to generate income and expense insights of a customer, the template can contain only those two insights.
@@ -41,9 +41,9 @@ Send the following details to [insights@setu.co](mailto:insights@setu.co) —
| **Insights required** | A list of required Insights. Send an email to [insights@setu.co](mailto:insights@setu.co) for full list of insights. |
| **Output format** | Format in which you need the output — currently we support `JSON`, and `XLSX`. |
-#### Option 2: Use API to create/update template
+#### Option 2: Use API to create a template
-You can create (`POST /v2/template`) or update (`PUT /v2/template`) templates via API. See API Integration for details.
+You can create templates via API using `POST /v3/template`. See API Integration for details.
Setu will respond with a `templateId`, which is required to generate insight reports.
@@ -51,30 +51,30 @@ Setu will respond with a `templateId`, which is required to generate insight rep
### Step 2—Ingest data
-Once you have the user’s financial data, you can push it to Setu Insights using:
+Once you have the user’s financial data, you can push it to Setu Insights. Use a single `refId` for each customer to group all their data for an analysis session. You can call the endpoint multiple times with the same `refId` to upload data for different accounts.
-- **AA-sourced JSON** – Use `/v2/fiData`
-- **Bank PDF statements** – Use `/v2/pdf-ingest` for PDF uploads
+- **AA-sourced JSON** – Use `POST /v3/fiData`. The request body can contain data for a single account or an array of accounts.
+- **Bank PDF statements** – Use `/v3/pdf-ingest` for PDF uploads
Use a single `refId` per customer. See the API Integration section for details.
-### Step 3—Generate insights
-You can generate insights for each customer that is created in the previous step. To generate insights, pass the `templateId` and `refId` from the previous steps.
+### Step 3—Generate and retrieve insights
-Use the `templateId` and `refId` to generate insights with the `/v2/report` API.
+You can generate insights for each customer using the `refId` from the data ingestion step. This is a two-step process:
-- You’ll receive a `reportId` in response
-- Insights will be sent to your webhook URL
-- You can fetch reports later using this `reportId`
-- Refer API integration to integrate with Insight generation APIs.
+First, you trigger an asynchronous job to generate insights by calling `POST /v3/insight` with a `refId` and a `templateId`. A successful request queues the job and returns a `reportId`.
+
+Then, you retrieve the results. The generated insights can be sent to your webhook URL, or you can poll the `GET /v3/insight?reportId={reportId}` endpoint to get the report.
+
+Refer API integration to integrate with Insight generation APIs.
### Step 4 — (Optional) Purge Customer Data
-You can delete a customer’s data from Setu using the `refId` via the `/v2/purge` API. This is useful for meeting data minimization and regulatory compliance requirements such as user data deletion requests under privacy laws.
+You can delete a customer’s data from Setu using the `refId` via the `/v3/purge` API. This is useful for meeting data minimization and regulatory compliance requirements such as user data deletion requests under privacy laws.
When a purge is triggered:
diff --git a/content/data/insights/quickstart/api-integration.mdx b/content/data/insights/quickstart/api-integration.mdx
index 8b0553a3..fcf43d6a 100644
--- a/content/data/insights/quickstart/api-integration.mdx
+++ b/content/data/insights/quickstart/api-integration.mdx
@@ -45,76 +45,61 @@ If you need to pass multiple accounts of same type for a customer, you can go ab
- {`POST /v2/fiData?refId=4e0ba220-9575-11eb-a8b3-0242ac130003
+ {`POST /v3/fiData?refId=your-unique-ref-id
--header 'Content-Type: application/json'
--header 'x-client-id: '
--header 'x-client-secret: '
--header 'x-product-instance-id: '
--data-raw '[{
- "account": {
- "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": {
- "pending": {"transactionType": "CREDIT", "amount": 0},
- "currentBalance": "20000",
- "currency": "INR",
- "balanceDateTime": "2019-08-24T14:15:22Z",
- "type": "SAVINGS",
- "branch": "NARKATIAGANJ BH",
- "facility": "OD",
- "ifscCode": "ABCD1234X",
- "micrCode": "123456789",
- "openingDate": "2019-08-24",
- "currentODLimit": "20000",
- "drawingLimit": "20000",
- "status": "ACTIVE"
- },
- "transactions": {
- "transaction": [
- {
- "type": "CREDIT",
- "mode": "CASH",
- "amount": 0,
- "currentBalance": "20000",
- "transactionTimestamp": "2019-08-24T14:15:22Z",
- "valueDate": "2019-08-24",
- "txnId": "123456789",
- "narration": "string",
- "reference": "string"
+ "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"
+ }
+ ]
+ }
}
- ],
- "startDate": "2019-08-24",
- "endDate": "2019-08-24"
- },
- "type": "deposit",
- "maskedAccNumber": "XXXXXXXXXXX1234",
- "version": "2.0",
- "linkedAccRef": "123456789"
- }
-},
-// second account in the same API call
-{
- "account": {
- // similar to above one
- }
-}
-]`}
+ }]
+`}
@@ -129,19 +114,21 @@ If you need to pass multiple accounts of same type for a customer, you can go ab
content: (
<>
- A dataId is assigned for this FI data block for usage
- in other APIs.
+ The response confirms the data has been received and provides the `refId` and an expiry date for the data.
{`{
- "status": "Success",
- "version": "1.0",
- "body": {
- "refId": "4e0ba220-9575-11eb-a8b3-0242ac130003",
- "fiSchema": "deposit",
- "expiryDate": "2023-05-16 09:23:39.115"
- }
-}`}
+ "status": "Success",
+ "version": "0.73.1",
+ "body": {
+ "refId": "test-single-account-15",
+ "fiSchema": [
+ "deposit"
+ ],
+ "expiryDate": "2025-07-06 07:03:12.312"
+ }
+}
+`}
),
@@ -167,31 +154,30 @@ If you need to pass multiple accounts of same type for a customer, you can go ab
### 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.
-#### Create Insight report
+#### 1. Request Insight Generation
-Call this API to generate an Insights report based on the customer's FI data block created earlier. Each customer is identified by it's `refId`. Pass the `templateId` obtained from template creation step, which will determine the ouput insights parameters that will be present in the report.
+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.
-
-Currently, only one refId is supported in the request body.
-
+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 /v2/insight
+ {`POST /v3/insight
--header 'Content-Type: application/json'
--header 'x-client-id: '
--header 'x-client-secret: '
--header 'x-product-instance-id: '
--data-raw '{
- "templateId": "4777db7e-e604-4c0c-a410-51be9d17d00b",
- "refIds": [
- "4e0ba220-9575-11eb-a8b3-0242ac130003"
- ]
+ "templateId": "b6418647-6397-47a8-8219-1bff5f7ddfe5",
+ "refId": "test-single-account-15",
+ "filters": {
+ "accounts": []
+ }
}'`}
@@ -207,15 +193,18 @@ Send the customer refId and the templateId as the payload.
content: (
<>
- A reportId is returned along with the status of the Insights generation job. A notification will be posted after successful generation of insights. See notifications.
The reportId also can be used fetch the Insights report using Get Insight report API, if the report status is Success.
+ 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",
- "body": {
- "reportId": "4b108e83-07b6-47a4-84cd-a77d0e9e2b3d",
- "status": "in-progress"
- }
+ "status": "Success",
+ "version": "0.73.1",
+ "statusDescription": null,
+ "body": {
+ "reportId": "05a5a389-b922-4197-be03-b309cdcc575a",
+ "status": "queued",
+ "reason": "NA"
+ }
}`}
@@ -241,14 +230,18 @@ Send the customer refId and the templateId as the payload.
-#### Get Insight report
+#### 2. Retrieve Insights
-Call this API to fetch the Insights report. Pass the `reportId` as a URL parameter, which was returned in the response body of **Create Insight report** API.
+Use the `reportId` from the previous step to poll this endpoint for the insight report.
###### Request
-{`GET /v1/insight?reportId=4b108e83-07b6-47a4-84cd-a77d0e9e2b3d`}
+{`GET /v3/insight?reportId={reportId}
+--header 'Accept: application/json'
+--header 'x-client-id: '
+--header 'x-client-secret: '
+--header 'x-product-instance-id: '`}
@@ -262,81 +255,43 @@ Call this API to fetch the Insights report. Pass the `reportId` as a URL paramet
label: "Success",
content: (
<>
- A dictionary, where insight names are keys and insights are values, is returned
+ The response will contain the generated insights. The `status` field for each account indicates whether insights were generated successfully.
{`{
- "status": "Success",
- "body": {
- "name": "Redacted Services",
- "dob": "2006-06-27",
- "email": "redacted@gmail.com",
- "pan": "redacted",
- "ckyc_compliance": false,
- "mobile": 9999912345,
- "bank_branch": "NARKATIAGANJ BH",
- "bank_account_number": "XXXXXXXXXXX1234",
- "bank_account_type": "CURRENT",
- "opening_date": "2019-02-26",
- "closing_balance": 27929.84,
- "end_of_month_balances": {
- "2021": {
- "9": 245676.89,
- "10": 48650.54,
- "11": 145487.41,
- "12": 97725.67
- },
- "2022": {
- "1": 9152.09,
- "2": 5957.19,
- "3": 545.59,
- "4": 1282299.18,
- "5": 134376.04,
- "6": 84468.46,
- "7": 135585.11,
- "8": 3346.11,
- "9": 268766.7,
- "10": 50049.84,
- "11": 27929.84
- }
- },
- "balances_on_10th": {
- "2021": {
- "12": 55387.41
- },
- "2022": {
- "1": 2426.67,
- "2": 9629.59,
- "3": 97487.45,
- "4": 1641.09,
- "5": 52517.54,
- "6": 72084.28,
- "7": 165864.04,
- "8": 63465.11,
- "9": 11226.11,
- "10": 418535.81,
- "11": 27929.84
- }
- },
- "average_end_of_day_balance": 297715.03,
- "maximum_end_of_day_balance": 1818766.7,
- "total_credits": 153,
- "total_credits_value": 44810341.06,
- "total_debits": 473,
- "total_debits_value": 45178088.11,
- "quarterly_salary_average": {
- "2021": {
- "4": 15072
- }
- },
- "cash_deposit_x_total_credit": {
- "2021": {
- "12": 0.0095
- },
- "2022": {
- "3": 0.0018
- }
+ "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
}
- }
}`}