1. Introduction

LFIs must implement a Consent Management Interface (CMI) prescribed by standards to provide a User with information on their consents.

The Consent Manager API is used to retrieve consent-related data with which to populate the CMI. This guide explains how to use the API to retrieve User consent details, apply filtering and pagination, retrieve consent history, and map UI elements to API fields.

2. Retrieving User Consents

To retrieve all consents associated with a User (termed PSU in the Consent Manager) use the get /psu/{userId}/consents operation, where userId is the LFI unique identifier for the User.

To use this operation the User identifier must be patched on the consent using patch /consent/{consentId}.

The response will return an array of consent objects containing information about each consent.

The table below shows how the response properties map to a given property in the CMI for Data Sharing.

	Label	Operation	Property (JSONPath)	Guidelines

	Label	Operation	Property (JSONPath)	Guidelines
1	TPP * Trading Name	`get /psu/{userId}/consents`	`$.data[*].tpp.tppName`
2	Last data shared	`get /psu/{userId}/consents`	`$.data.consentUsage.lastDataShared`
3	Connection Expires	`get /psu/{userId}/consents`	`$.data[*].request.consent.ExpirationDateTime`
4	Status	`get /psu/{userId}/consents`	`$.data[*].status`
5	Consent ID	`get /psu/{userId}/consents`	`$.data.id`
6	IBAN	`get /psu/{userId}/consents`	`$.data[*].accountIds`	The surrogate account identifiers patched onto the consent are returned. These must be replaced by the real IBAN by the LFI due restrictions on PII in the API Hub.
7	Data they get	`get /psu/{userId}/consents`	`$.data[*].request.consent.Permissions`	Permissions must be provided using the standardised data cluster language provided in the Customer Data standards. The `Permissions` property provides the values for LFIs to map the permission code to the correct language.
8	First Connected	`get /psu/{userId}/consents` OR `get /consent-groups/{consentGroupId}/consents`	`$.data[*].consentBody.Data.CreationDateTime`	If the consent is part of a consent group, this must be the `CreationDateTime` of the first consent in the consent group. The property `BaseConsentId` provides the value of the `consentGroupId` parameter. If a consent is not part of a consent group as `BaseConsentId` is not set this will be `CreationDateTime` of the consent.
9	Last Updated	`/psu/{userId}/consents` OR `get /consent-groups/{consentGroupId}/consents`	`$.data[*].consentBody.Data.CreationDateTime`	If the consent is part of a consent group, this must be the `CreationDateTime` of the latest consent in the consent group. If a consent is not part of a consent group as `BaseConsentId` is not set this will be `CreationDateTime` of the consent.

The table below shows how the response properties map to a given property in the CMI for Service Initiation.

	Label	Operation	Property (JSONPath)	Guidelines

	Label	Operation	Property (JSONPath)	Guidelines
1	TPP * Trading Name	`get /psu/{userId}/consents`	`$.data[*].tpp.tppName`
2	Total paid/Total paid to date	`get /payment-log?consentId={consentId}`	`$.data[*].requestBody.Instruction.Amount.Amount`	Sum that values indicated by the JSONPath that returned by this operation.
3	Permission Cancelled/Expired/Consumed	`get /psu/{userId}/consents`	`$.data.updatedAt`	The statuses are all terminal states and the last update date will reflect when the consent was moved into that state.
4	Last payment made	`get /psu/{userId}/consents`	`$.data.consentUsage.lastServiceInitiationAttempt`
5	Payment to	`get /psu/{userId}/consents` OR `get /payment-log?consentId={consentId}`	`$.data.request.consent.PersonalIdentifiableInformation` OR `$.data.requestBody.Data.PersonalIdentifiableInformation`	Use the value of `Creditor.Name` from either the consent or the payment initiation request, depending on the payment type.
6	IBAN	`get /psu/{userId}/consents` OR `get /payment-log?consentId={consentId}`	`$.data.request.consent.PersonalIdentifiableInformation` OR `$.data.requestBody.Data.PersonalIdentifiableInformation`	Use the value of `CreditorAccount.Identification` from either the consent or the payment initiation request, depending on the payment type.
7	Reference	`get /payment-log?consentId={consentId}`	`$.data.requestBody.Data.CreditorReference`
8	Payment Purpose	`get /payment-log?consentId={consentId}`	`$.data.requestBody.Data.PaymentPurposeCode`	The payment request provides the Aani purpose code, which must be transposed to the correct purpose code description based on Aani reference information.
9	From Account	`get /psu/{userId}/consents`	`$.data[].accountIds` OR `$.data[].request.consent.PersonalIdentifiableInformation`	The surrogate account identifiers patched onto the consent are returned. These must be replaced by the real IBAN by the LFI due restrictions on PII in the API Hub OR The debtor IBAN has been provided on the consent by the TPP, so the value of `DebtorAccount.Identification` can be used to provide the IBAN.
10	Payment Rules	`get /psu/{userId}/consents`	`$.data[*].request.consent.ControlParameters`	The properties show need to be based on the values found in control parameters, which differ based on the payment type. Please refer to the API description for available properties.
11	You started this permission	`get /psu/{userId}/consents`	`$.data[*].consentBody.Data.CreationDateTime`	If the consent is part of a consent group, this must be the `CreationDateTime` of the first consent in the consent group. The property `BaseConsentId` provides the value of the `consentGroupId` parameter. If a consent is not part of a consent group as `BaseConsentId` is not set this will be `CreationDateTime` of the consent.
12	You cancelled this permission	`get /psu/{userId}/consents`	`$.data.updatedAt`

3. Connection History

To provide Connection History information to the User use the get /consent-groups/{consentGroupId}/consents operation. This returns all consents in a consent group, which are linked by the value of BaseConsentId.

The following guidance is provided on Connection History and the use of BaseConsentId:

Connection History is driven by “revisions” to consents orchestrated by TPPs, where an existing consent is replaced by a new consent.
When a TPP and User agree a new set of permissions or a change to data access a new consent can be created and the existing consent moved to an appropriate state (note that the existing consent could also have expired).
In order to link the existing consent with the new consent the TPP will set BaseConsentId on the new consent to the value of ConsentId of the original consent.
All subsequently created consents that share the same history will use the same BaseConsentId value i.e. the first consent agreed between the TPP and the User.
Retrieving these consents is achieved by using get /consent-groups/{consentGroupId}/consents where consentGroupId is the value of BaseConsentId.
The get /consents/{consentId}/audit operation does not provide the means to retrieve Connection History as it relates to changes to a single consent, not changes to multiple consents by BaseConsentId.

The table below shows how the response properties map to a given property in the CMI for Data Sharing.

	Label	Operation	Property (JSONPath)	Guidelines

	Label	Operation	Property (JSONPath)	Guidelines
1	TPP Trading Name	`get /consent-groups/{consentGroupId}/consents`	`$.data[*].tpp.tppName`
2	Consent ID	`get /consent-groups/{consentGroupId}/consents`	`$.data.id`
3	IBAN	`get /consent-groups/{consentGroupId}/consents`	`$.data[*].accountIds`	The surrogate account identifiers patched onto the consent are returned. These must be replaced by the real IBAN by the LFI due restrictions on PII in the API Hub.
4	Data they get	`get /consent-groups/{consentGroupId}/consents`	`$.data[*].request.consent.Permissions`	Permissions must be provided using the standardised data cluster language provided in the Customer Data standards. The `Permissions` property provides the values for LFIs to map the permission code to the correct language.
5	<Connection date show as label>	`get /consent-groups/{consentGroupId}/consents`	`$.data[*].consentBody.Data.CreationDateTime`

4. Payment History

To provide Payment History information to the User use the get /payment-log?consentId={consentId} operation. This returns a summary of all payments for a given consent.

The table below shows how the response properties map to a given property in the Payment History view.

Label	Operation	Property (JSONPath)	Guidelines

Label	Operation	Property (JSONPath)	Guidelines
TPP * Trading Name	`get /payment-log?consentId={consentId}`	`$.data[*].tpp.tppName`
Total paid/Total paid to date	`get /payment-log?consentId={consentId}`	`$.data[*].requestBody.Data.Instruction.Amount.Amount`	Sum that values indicated by the JSONPath that returned by this operation.
<Payment Date>	`get /payment-log?consentId={consentId}`	`$.data[*].paymentResponse.creationDateTime`
<Payment Reference>	`get /payment-log?consentId={consentId}`	`$.data[*].requestBody.Data.CreditorReference`
<Amount>	`get /payment-log?consentId={consentId}`	`$.data[*].requestBody.Data.Instruction.Amount.Amount`

5. Status Code Language

The Consent Manager API provides consent statuses as codes.

The table below maps a given code from a Consent Manager API status code to a CMI status code is mandated.

	Consent Manager Status Code	CMI Status Code

	Consent Manager Status Code	CMI Status Code
1	Rejected (where Rejected consents are returned, as the User identifier has been patched to the consent)	Rejected
2	AwaitingAuthorisation	Awaiting
3	Authorised	Active
4	Suspended	Suspended
5	Revoked	Cancelled
6	Consumed	Consumed
7	Expired	Expired

If a code does not appear in this list it should be normalised based on the following rules:

Codes should be split on word boundary.
Case should be maintained.
If the status requires truncation for display purposes the whole of the leftmost word should be returned.

API Hub Documentation v6

LFI Consent Management Interface Guide

Analytics

1. Introduction

2. Retrieving User Consents

3. Connection History

4. Payment History

5. Status Code Language

Related content