Skip to content

added tags feature for AA framework #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aditya-67 merged 3 commits into from
Feb 19, 2025
Merged

added tags feature for AA framework #238

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
af22837
added tags feature for AA framework
Feb 19, 2025
4f80e88
removed list for single element in error messages column under data f…
Feb 19, 2025
0d1b3b8
Update consent object
aditya-67 Feb 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 16 additions & 1 deletion content/data/account-aggregator/api-integration/consent-flow.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,10 @@ Call this API to create a consent request. The details of the request will be pr
"to": "2023-01-01T00:00:00Z"
},
"context": [
]
],
"additionalParams": {
"tags": ["Loan_Tracking", "Partner_X"]
}
}`}
</CodeBlockWithCopy>
<Row>
Expand Down Expand Up @@ -97,6 +100,10 @@ Call this API to create a consent request. The details of the request will be pr
"count": "0",
"lastUsed": null
},
"tags": [
"Loan_Tracking",
"Partner_X"
],
"traceId": "1-6433a06a-4b99c3a81b538bc762b5aa08"
}
`}
Expand Down Expand Up @@ -234,6 +241,10 @@ If the consent is approved, the status in the response will be `ACTIVE`. After t
"consentExpiry": "2023-08-02T12:40:41.165Z"
},
"accountsLinked": [],
"tags": [
"Loan_Tracking",
"Partner_X"
],
"traceId": "26b8bc4c-5d33-43a1-a58f-be5d4d0acbd0"
}`}
</CodeBlockWithCopy>
Expand Down Expand Up @@ -289,6 +300,10 @@ If the consent is approved, the status in the response will be `ACTIVE`. After t
"count": "0"
},
"accountsLinked": [],
"tags": [
"Loan_Tracking",
"Partner_X"
],
"traceId": "74d3032a-597e-40e1-859b-67b035e8a0e0"
}`}
</CodeBlockWithCopy>
Expand Down
20 changes: 5 additions & 15 deletions content/data/account-aggregator/api-integration/data-apis.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -595,49 +595,39 @@ Auto-Fetch data feature aims to absorb this complexity from the FIUs. With Auto-
<code>InvalidConsentUse</code>
</td>
<td>
<ul>
<li>Consent fetch frequency exceeded</li>
</ul>
Consent fetch frequency exceeded
</td>
</tr>
<tr>
<td>
<code>InvalidConsentStatus</code>
</td>
<td>
<ul>
<li>Consent for which data fetch has been requested has expired</li>
</ul>
Consent for which data fetch has been requested has expired
</td>
</tr>
<tr>
<td>
<code>SessionExpired</code>
</td>
<td>
<ul>
<li>Session to fetch data for a session ID has expired</li>
</ul>
Session to fetch data for a session ID has expired
</td>
</tr>
<tr>
<td>
<code>ConsentRevoked</code>
</td>
<td>
<ul>
<li>Consent for which data fetch has been requested has been revoked</li>
</ul>
Consent for which data fetch has been requested has been revoked
</td>
</tr>
<tr>
<td>
<code>UpstreamServerDown</code>
</td>
<td>
<ul>
<li>Received 500 from upstream AA</li>
</ul>
Received 500 from upstream AA
</td>
</tr>
<tr>
Expand Down
53 changes: 51 additions & 2 deletions content/data/account-aggregator/consent-object.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,24 @@ The consent object is the core of the AA framework. When an FIU requires data ab

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.

<Callout type type="warning">
<Callout type="warning">
As specified in the table below, some parameters have to be passed mandatorily
when creating a consent.
</Callout>

<br />

<Callout type="tip">
Tagging helps you organize and track consent requests, reports, and analytics
more effectively. With this feature, you can add relevant labels (tags) to
different consent requests and data-fetch reports without creating separate
product instances. Tags make it easier to segment, analyze, and track data for
different use cases, such as monitoring traffic for specific partners or
campaigns.
</Callout>

<br />

### Consent request object

| Property name | Description | Mandatory? |
Expand All @@ -28,14 +39,15 @@ Consent object contains the information about all the different types of data th
| `fetchType` | Enum to specify either `ONETIME` or `PERIODIC` fetch of data. | Yes |
| `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 |
| `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 |
| `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 |
| `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 |
| `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 |
| `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 |
| `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 |
| `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 |
| `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 |
| `redirectUrl` | Redirect your users back to your application once the consent is reviewed. By default, the redirectURL is https://setu.co/. | Yes |
| `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 |
| `additionalParams` | Allows you to specify additional parameters for the consent request. Currently, we have `tags` specified under it. | No |

#### Context property examples

Expand Down Expand Up @@ -83,4 +95,41 @@ Consent object contains the information about all the different types of data th
| `status` | Consent status of the consent request `id`. This will be `PENDING` for a newly created consent. |
| `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. |

<hr class="primary" />

### Understanding Tags in AA Framework

• Tags must first be created at the product instance level before they can be used in any requests.

• 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.

• 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.

• Key limitations and rules:

- Tags are case-insensitive (e.g., "partnerA" = "PartnerA")
- Duplicate tags are not allowed
- Bulk tagging for historical data is not supported
- Number of tags per FIU is configurable
- Invalid characters will trigger errors
- System issues may prevent tag application (with error notifications)

• Best practice: Use clear, consistent, and easily understandable tag names for effective tracking.

• To add tags to a consent request, include them under the `additionalParams` field:

<CodeBlockWithCopy language="json">
{`{
"consentDetail": {
...
},
...,
"additionalParams": {
"tags": ["Loan_Tracking", "Partner_X"]
}
}`}
</CodeBlockWithCopy>

<br />

<WasPageHelpful />