Handling Multiple Use Cases

If you are implementing multiple use cases that have different purpose statements, this guide will help you set up consents for different purpose statements (use cases) & retrieve data based on the purpose statement.

Step 1: Identify purpose statement in Create Intent API

You can set up different consent journeys for multiple use cases by specifying the purposeStatement and permissionsList in the Create Intent API request body. This method ensures each use case has its own consent journey, allowing you to manage data access separately.

How it works

When a customer wants to use a specific service (a use case) in your application, then you need to specify the following values in the Create Intent API request body:

• purposeStatement: This field specifies the reason for the data request, for example ACCOUNT_AGGREGATION
• permissionsList: This array defines the specific data the application needs access to. The list of permissions must align with the specified purposeStatement.
• product & entryPoint: These optional fields help with analytics by identifying the product or service and from where the customer started the journey.

By creating a separate consent for each use case, you can ensure that the customer's consent is configured correctly, and your application retrieves data only for the use case they've approved.

Example scenario

Let's imagine a customer using a financial app that offers two different services:

1. A service for aggregating all bank accounts in one place (use case: ACCOUNT_AGGREGATION)
2. A service for a credit limit increase (use case: CREDIT_ASSESSMENT)

When the customer first accesses the account aggregation service, the app creates an intent with purposeStatement: ACCOUNT_AGGREGATION and the corresponding permissionsList. The customer is then prompted to give consent for this specific purpose.

Example request body of the Create Intent endpoint:

{
	"user": {
		"customerUserId": "38737982364",
		"firstName": "John",
		"lastName": "Snow",
		"email": "[email protected]"
	},
	"providerType": "Retail",
	"consent": {
		"providerId": "BLUE",
		"flowType": "TPP_MANAGED",
		"tppDetails": {
			"tradingName": "TPP tradingName",
			"legalName": "TPP legalName",
			"identifier": {
				"type": "Other",
				"value": "TPP CR Number"
			},
			"purposeStatement": "ACCOUNT_AGGREGATION",
			"product": "BANK_ACCOUNTS_AGGREGATION",
			"entryPoint": "CONSENT_MANAGEMENT"
		},
		"permissionsList": [
			"ReadAccountsBasic",
			"ReadAccountsDetail",
			"ReadBalances",
			"ReadTransactionsBasic",
			"ReadTransactionsDetail",
			"ReadTransactionsCredits",
			"ReadTransactionsDebits",
			"ReadBeneficiariesBasic",
			"ReadBeneficiariesDetail",
			"ReadScheduledPaymentsBasic",
			"ReadScheduledPaymentsDetail",
			"ReadDirectDebits",
			"ReadStandingOrdersBasic",
			"ReadStandingOrdersDetail"
		]
	},
	"language": "EN",
	"redirectUrl": "http://myredirectURL.me"
}

Later, if the same customer decides to apply for a credit limit increase through the same app, the app will create a new and separate intent. This second request will have purposeStatement: CREDIT_ASSESSMENT and a different permissionsList. The customer must then provide new consent for this distinct purpose.

Example request body of the Create Intent endpoint:

{
	"user": {
		"customerUserId": "38737982364",
		"firstName": "John",
		"lastName": "Snow",
		"email": "[email protected]"
	},
	"providerType": "Retail",
	"consent": {
		"providerId": "BLUE",
		"flowType": "TPP_MANAGED",
		"tppDetails": {
			"tradingName": "TPP tradingName",
			"legalName": "TPP legalName",
			"identifier": {
				"type": "Other",
				"value": "TPP CR Number"
			},
			"purposeStatement": "CREDIT_ASSESSMENT",
			"product": "CREDIT_LIMIT_INCREASE",
			"entryPoint": "CREDIT_CARD_JOURNEY"
		},
		"permissionsList": [
			"ReadAccountsBasic",
			"ReadAccountsDetail",
			"ReadBalances",
			"ReadTransactionsBasic",
			"ReadTransactionsDetail",
			"ReadTransactionsCredits",
      "ReadTransactionsDebits",
			"ReadScheduledPaymentsBasic",
			"ReadScheduledPaymentsDetail",
			"ReadDirectDebits",
			"ReadStandingOrdersBasic",
			"ReadStandingOrdersDetail"
		]
	},
	"language": "EN",
	"redirectUrl": "http://myredirectURL.me"
}

This method ensures that even though the customer is using the same app, the data access is tied directly to the specific service they are using.

Permissions allowed for each purpose statement

Products for each purpose statement

• Purpose statement (ACCOUNT_AGGREGATION): available product value (BANK_ACCOUNTS_AGGREGATION).
• Purpose statement (PFM): available product value (CASH_FLOW_ANALYSIS, BUDGETING_AND_SAVINGS).
• Purpose statement (ELECTRONIC_VERIFICATION): available product value (KYC).
• Purpose statement (E_STATEMENT): available product value (BANK_STATEMENT, CREDIT_CARD_STATEMENT).
• Purpose statement (CREDIT_ASSESSMENT): available product value (CREDIT_LIMIT_INCREASE, ISSUE_CREDIT_CARD, CREDIT_CARD_BALANCE_TRANSFER).
• Purpose statement (TAX_FILING): available product value (INDIVIDUAL_INCOME_TAX, BUSINESS_TAX).
• Purpose statement (ENTERPRISE_FINANCIAL_MANAGEMENT): available product value (CASH_FLOW_ANALYSIS).

Entry points values

• HOME_SCREEN
• ACCOUNTS_LIST
• PFM_SCREEN
• OPEN_NEW_ACCOUNT
• CREDIT_CARD_JOURNEY
• CONSENT_MANAGEMENT
• NOTIFICATION

📘

If you have product or entry point that is not in the defined list, please reach out to sustmer support in order to add it ([email protected]).

Step 2: Retrieving data by purpose statement

When you need to retrieve data using Get Accounts endpoint, you can ensure you only get data relevant to a specific use case by using the purposeStatement query parameter.

For example, to retrieve accounts linked to the ACCOUNT_AGGREGATION use case, you would use Get Accounts endpoint and pass in the query parameterpurposeStatement=ACCOUNT_AGGREGATION'

Example request:

curl --request GET \
     --url 'https://api.sau.sandbox.tarabutgateway.io/accountInformation/v2/accounts?purposeStatement=ACCOUNT_AGGREGATION' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json'

In this way, you will be able to retrieve only the account that matches your use case.

Note: if did not pass the value purposeStatement in the query parameter, you will get all the accounts that have been linked by the customer across all purposeStatement.

❗️

If you don't include the purposeStatement query parameter, the API will return all accounts that have been linked by the customer, regardless of the use case.

We recomend always use purposeStatement query parameter to retrieve only the data that matches the use case.

This method allows your application to retrieve and use data strictly for the purpose the customer has consented to.

Step 3: Consent management by purpose statement (optional)

You can manage your customer's consents by purpose statement using the Get All Consents endpoint. The response from this endpoint provides a list of all consents your customer has, each with its purposeStatement and product values.

This allows you to see which use cases a customer has consented to, helping you to show the right purpose statement in the consent management dashboard.

Example response of the Get All Consents endpoint:

[
	{
		"id": "dea58319-8ad8-4c7c-9f88-3d0511c05550",
		"status": "ACTIVE",
		"expiryDate": "2026-08-24T08:58:31Z",
		"startDate": "2025-08-24T11:58:31.440Z",
		"purposeStatement": "ACCOUNT_AGGREGATION",
		"product": "BANK_ACCOUNTS_AGGREGATION",
		"providerId": "BLUE"
	},
	{
		"id": "8446bb01-6494-404a-ab3a-0f51a8085554",
		"status": "ACTIVE",
		"expiryDate": "2026-08-26T12:12:35Z",
		"startDate": "2025-08-26T15:12:37.206Z",
		"purposeStatement": "CREDIT_ASSESSMENT",
		"product": "CREDIT_LIMIT_INCREASE",
		"providerId": "BLUE"
	}
]

This response shows that the customer has two separate, active consents for two different use cases.