Skip to content

Commit 320b5f4

Browse files
riyasuntwalriyasuntwaladitya-67
authored
added tags feature for AA framework (#238)
* added tags feature for AA framework * removed list for single element in error messages column under data fetch API * Update consent object --------- Co-authored-by: riyasuntwal <riyasuntwal@Setus-MacBook-Pro.local> Co-authored-by: Aditya Gannavarapu <adityagannavarapu.67@gmail.com>
1 parent 04bb8b9 commit 320b5f4

File tree

3 files changed

+72
-18
lines changed

3 files changed

+72
-18
lines changed

‎content/data/account-aggregator/api-integration/consent-flow.mdx

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,10 @@ Call this API to create a consent request. The details of the request will be pr
3838
"to": "2023-01-01T00:00:00Z"
3939
},
4040
"context": [
41-
]
41+
],
42+
"additionalParams": {
43+
"tags": ["Loan_Tracking", "Partner_X"]
44+
}
4245
}`}
4346
</CodeBlockWithCopy>
4447
<Row>
@@ -97,6 +100,10 @@ Call this API to create a consent request. The details of the request will be pr
97100
"count": "0",
98101
"lastUsed": null
99102
},
103+
"tags": [
104+
"Loan_Tracking",
105+
"Partner_X"
106+
],
100107
"traceId": "1-6433a06a-4b99c3a81b538bc762b5aa08"
101108
}
102109
`}
@@ -234,6 +241,10 @@ If the consent is approved, the status in the response will be `ACTIVE`. After t
234241
"consentExpiry": "2023-08-02T12:40:41.165Z"
235242
},
236243
"accountsLinked": [],
244+
"tags": [
245+
"Loan_Tracking",
246+
"Partner_X"
247+
],
237248
"traceId": "26b8bc4c-5d33-43a1-a58f-be5d4d0acbd0"
238249
}`}
239250
</CodeBlockWithCopy>
@@ -289,6 +300,10 @@ If the consent is approved, the status in the response will be `ACTIVE`. After t
289300
"count": "0"
290301
},
291302
"accountsLinked": [],
303+
"tags": [
304+
"Loan_Tracking",
305+
"Partner_X"
306+
],
292307
"traceId": "74d3032a-597e-40e1-859b-67b035e8a0e0"
293308
}`}
294309
</CodeBlockWithCopy>

‎content/data/account-aggregator/api-integration/data-apis.mdx

Lines changed: 5 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -595,49 +595,39 @@ Auto-Fetch data feature aims to absorb this complexity from the FIUs. With Auto-
595595
<code>InvalidConsentUse</code>
596596
</td>
597597
<td>
598-
<ul>
599-
<li>Consent fetch frequency exceeded</li>
600-
</ul>
598+
Consent fetch frequency exceeded
601599
</td>
602600
</tr>
603601
<tr>
604602
<td>
605603
<code>InvalidConsentStatus</code>
606604
</td>
607605
<td>
608-
<ul>
609-
<li>Consent for which data fetch has been requested has expired</li>
610-
</ul>
606+
Consent for which data fetch has been requested has expired
611607
</td>
612608
</tr>
613609
<tr>
614610
<td>
615611
<code>SessionExpired</code>
616612
</td>
617613
<td>
618-
<ul>
619-
<li>Session to fetch data for a session ID has expired</li>
620-
</ul>
614+
Session to fetch data for a session ID has expired
621615
</td>
622616
</tr>
623617
<tr>
624618
<td>
625619
<code>ConsentRevoked</code>
626620
</td>
627621
<td>
628-
<ul>
629-
<li>Consent for which data fetch has been requested has been revoked</li>
630-
</ul>
622+
Consent for which data fetch has been requested has been revoked
631623
</td>
632624
</tr>
633625
<tr>
634626
<td>
635627
<code>UpstreamServerDown</code>
636628
</td>
637629
<td>
638-
<ul>
639-
<li>Received 500 from upstream AA</li>
640-
</ul>
630+
Received 500 from upstream AA
641631
</td>
642632
</tr>
643633
<tr>

‎content/data/account-aggregator/consent-object.mdx

Lines changed: 51 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,24 @@ The consent object is the core of the AA framework. When an FIU requires data ab
1111

1212
Consent object contains the information about all the different types of data the FIU needs, the purpose of the data, and how the FIU plans to use the data and so on.
1313

14-
<Callout type type="warning">
14+
<Callout type="warning">
1515
As specified in the table below, some parameters have to be passed mandatorily
1616
when creating a consent.
1717
</Callout>
1818

1919
<br />
2020

21+
<Callout type="tip">
22+
Tagging helps you organize and track consent requests, reports, and analytics
23+
more effectively. With this feature, you can add relevant labels (tags) to
24+
different consent requests and data-fetch reports without creating separate
25+
product instances. Tags make it easier to segment, analyze, and track data for
26+
different use cases, such as monitoring traffic for specific partners or
27+
campaigns.
28+
</Callout>
29+
30+
<br />
31+
2132
### Consent request object
2233

2334
| Property name | Description | Mandatory? |
@@ -28,14 +39,15 @@ Consent object contains the information about all the different types of data th
2839
| `fetchType` | Enum to specify either `ONETIME` or `PERIODIC` fetch of data. | Yes |
2940
| `consentTypes` | Specifies the type of data being requested for, from your user—<br/><li>`PROFILE`—Personal details such as mobile number, date of birth, PAN etc.</li><li>`SUMMARY`—Information like mutual fund summary for total amount invested, current value, number of MFs and more.</li><li>`TRANSACTIONS`—List of records against some financial data—e.g., a bank statement.</li> | Yes |
3041
| `fiTypes` | Specifies the type of financial information being requested for. Possible enums—`DEPOSIT`, `MUTUAL_FUNDS`, `INSURANCE_POLICIES`, `TERM_DEPOSIT`, `RECURRING_DEPOSIT`, `SIP`, `GOVT_SECURITIES`, `EQUITIES`, `BONDS`, `DEBENTURES`, `ETF`, and more. Click <a href="/data/account-aggregator/fi-data-types" target="_blank">here</a> to learn more about the data types. | Yes |
31-
| `vua` | Virtual user address (VUA) that identifies your customer when they login to the Account Aggregator.<br/>It can be either mobile number or mobile number with handle (**{customer_mobile_number}@onemoney**)<br/><li>If mobile@handle is used, consent will be created for the specified AA</li><li>If mobile is used, a best performing AA is selected for consent creation</li> | Yes |
42+
| `vua` | Virtual user address (VUA) that identifies your customer when they login to the Account Aggregator.<br/>It can be either mobile number or mobile number with handle (**{customer_mobile_number}@onemoney**)<br/><li>If mobile@handle is used, consent will be created for the specified AA</li><li>If mobile is used, a best performing AA is selected for consent creation</li> | Yes |
3243
| `purpose` | This is used to indicate the purpose of requesting for data. As per the AA spec, the following codes are supported—<br/><li>`101`—Wealth management service</li><li>`102`—Customer spending patterns, budget or other reportings</li><li>`103`—Aggregated statement</li><li>`104`—Explicit consent to monitor the accounts</li><li>`105`—Explicit one-time consent for accessing data from the accounts</li> | Yes |
3344
| `dataRange` | This is used to specify the `from` and `to` date-time range for querying financial information. It is mandatory only when the `consentTypes` array includes `TRANSACTIONS`. | Mandatory |
3445
| `dataLife` | This is the time period for which you are allowed to process the data. Choose between `MONTH`, `YEAR`, `DAY`, `INF` as the `unit` and define a numeric `value` alongside. <br /> For more details on the difference between Data life and Data Storage, please see [Sahamati guidelines](https://sahamati.org.in/aa-community-guidelines-v1/storage-of-data/) (see SD001 in the table) | Yes |
3546
| `frequency` has 2 components—`unit` and `value` | `unit` can be `HOURLY`, `DAILY`, `MONTHLY`, `YEARLY`. `value` has to be greater than 0.<br/>Additionally the maximum frequency value is defined is `1` request per HOUR. So, no more than `24` requests are allowed per DAY | Yes |
3647
| `dataFilter` | Allows you to specify conditions for filtering the data being fetched. For example, fetch transactions where the `TRANSACTIONAMOUNT` is greater than or equal to INR 20,000. You can use the `type`, `operator` like `>, <, <=, >=` and `value` like `5000` keys to set the filters. | No |
3748
| `redirectUrl` | Redirect your users back to your application once the consent is reviewed. By default, the redirectURL is https://setu.co/. | Yes |
3849
| `context` | Allows you to specify an FIP OR Account type (Current, Savings, Insurance, etc) as a key value pair for you to be able to customise the accounts fetched on the consent flow. We support the context filters `accounttype` which takes the Key as `accounttype` where values can be `CURRENT` or `SAVINGS` and `fipid` with the `FIP ID` as the value(s). | No |
50+
| `additionalParams` | Allows you to specify additional parameters for the consent request. Currently, we have `tags` specified under it. | No |
3951

4052
#### Context property examples
4153

@@ -83,4 +95,41 @@ Consent object contains the information about all the different types of data th
8395
| `status` | Consent status of the consent request `id`. This will be `PENDING` for a newly created consent. |
8496
| `Usage` | This field specifies `lastUsed` and `count` which corresponds to data fetches against the consent id. It is also available in Get Consent Status response. |
8597

98+
<hr class="primary" />
99+
100+
### Understanding Tags in AA Framework
101+
102+
• Tags must first be created at the product instance level before they can be used in any requests.
103+
104+
• Tags can be created and managed while setting up or updating a product instance. They are unique identifiers (max 100 characters) that can be linked to multiple product instances.
105+
106+
• Tags are visible in consent and data-fetch reports, and serve as filters in analytics dashboards. Use them to track user journeys, monitor failures, analyze behavior, measure campaign performance, and generate custom insights.
107+
108+
• Key limitations and rules:
109+
110+
- Tags are case-insensitive (e.g., "partnerA" = "PartnerA")
111+
- Duplicate tags are not allowed
112+
- Bulk tagging for historical data is not supported
113+
- Number of tags per FIU is configurable
114+
- Invalid characters will trigger errors
115+
- System issues may prevent tag application (with error notifications)
116+
117+
• Best practice: Use clear, consistent, and easily understandable tag names for effective tracking.
118+
119+
• To add tags to a consent request, include them under the `additionalParams` field:
120+
121+
<CodeBlockWithCopy language="json">
122+
{`{
123+
"consentDetail": {
124+
...
125+
},
126+
...,
127+
"additionalParams": {
128+
"tags": ["Loan_Tracking", "Partner_X"]
129+
}
130+
}`}
131+
</CodeBlockWithCopy>
132+
133+
<br />
134+
86135
<WasPageHelpful />

0 commit comments

Comments
 (0)