---
title: Consent API Activity
description: The Consent API may be used as the data backend for an Open Banking account requests API. For more information about Open Banking, refer to Open Banking.
component: pingdirectory
page_id: pingdirectory:consent:consent-api-activity
canonical_url: https://developer.pingidentity.com/pingdirectory/consent/consent-api-activity.html
section_ids:
  introduction: Introduction
  workflow-order-of-operations: Workflow order of operations
  create-the-account-request: Create the account request
  create-a-consent-record: Create a consent record
  check-the-account-request-state: Check the account request state
  prompt-to-get-the-customers-consent: Prompt to get the Customer's consent
  update-the-consent-record: Update the consent record
---

# Consent API Activity

## Introduction

The Consent API may be used as the data backend for an Open Banking account requests API. For more information about Open Banking, refer to [Open Banking](https://www.openbanking.org.uk/).

In this activity, a third-party payment processor (Company A) makes an account request to an account servicing provider (Company B) on behalf of the account holder (Customer). Company A needs permission to access specific account data. To move forward with the transaction, a consent request must be sent to the Customer, and a consent record must be created to capture the consent response.

This scenario illustrates some common open banking operations supported by the Consent API, including:

* Creating a consent record.

* Checking the state of an existing consent record.

* Retrieving localized consent prompt text.

* Updating a consent record.

The actors in this scenario are:

* **The Customer**

  This is the account holder who must provide consent so that the third party can access account data.

* **Third-Party Provider** (Company A)

  This is the third-party client that requires access to the customer's account data.

* **Account Servicing Payment Servicing Provider** (Company B)

  This is the service that processes the customer's accounts and consents. This service consists of:

  * A data governance server, which provides the Open Banking account requests API.

  * A PingFederate server, which handles OpenID Connect authentication and OAuth2 authorization in conjunction with a Consent Capture Web Application.

  * A directory server, which provides the Consent Service and the Consent Capture Web Application.

## Workflow order of operations

To request the Customer's consent, the following tasks must be completed successfully:

1. [Create the account request](#create-the-account-request): A makes a `POST` request to the `/account-requests` service on the data governance server at Company B. This `POST` specifies the list of permissions that Company A needs to be granted through the consent request.

2. [Create a consent record](#create-a-consent-record): B makes a `POST` request to `/consents` on its directory server to create a consent record with the consent `status` value set to `pending`.

3. [Check the account request state](#check-the-account-request-state): Using the consent record id generated in step 2, Company A can now make a GET request to Company B's consent capture app to check the account request state to see if the Customer has accepted or denied consent.

4. [Prompt to get the Customer's consent](#prompt-to-get-the-customers-consent): If the consent state is `pending`, the consent capture app prompts the Customer to grant authorization. The app makes a `GET` request to the `/definitions/<consentDefinitionName>/localizations` service for the specified consent definition.

5. [Update the consent record](#update-the-consent-record): The Customer grants or denies authorization, and the consent capture app makes a `PATCH` request to `/consents` to update the consent record based on the Customer's response.

[]()

## Create the account request

Company A needs the following common open banking permissions from the Customer:

* ReadAccountsDetail

* ReadBalances

* ReadBeneficiariesDetail

* ReadDirectDebits

* ReadProducts

Company A knows that Company B has a standard consent definition called *OpenBankingAccountsConsent* that can be used to capture consent from the Customer for these permissions.

The `POST /account-requests` operation initiates the consent request. The request body specifies these permissions. In the Authorization request header field, the `accessToken` value is your full base64url-encoded JSON web token generated by the authentication service.

```none
curl -X POST "https://api.companyb.com/v1/account-requests" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken" \
-d "{
  "data": {
    "permissions": [
    "ReadAccountsDetail",
    "ReadBalances",
    "ReadBeneficiariesDetail",
    "ReadDirectDebits",
    "ReadProducts"
    ]
  }
}"
```

The response data shows the requested permissions as well as the `AccountRequestId` and the `status` of the account request.

## Create a consent record

Company B creates a consent record to capture and store the Customer's response to the consent request on its directory server. The request body must provide values for the `status`, `subject`, `actor`, and `audience` properties. In this case, the `status` property value is set to `pending`. In addition, the request can define additional properties to store custom data relevant to the consent request, such as the permissions requested by Company A.

The `POST /consents/` operation creates a new consent record.

```none
curl -X POST "https://api.companyb.com/consent/v1/consents" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken" \
-d "{
  "status": "pending",
  "subject": "Customer",
  "actor": "Customer",
  "audience": "CompanyA",
  "definition": {
    "id": "OpenBankingAccountsConsent", \
    "version": "1.0\",
    "locale": "en-US" },
  "data": {
    "Permissions": [
      "ReadAccountsDetail", \
      "ReadBalances", \
      "ReadBeneficiariesDetail", \
      "ReadDirectDebits", \
      "ReadProducts"
    ]
  }
}"
```

If successful, the operation returns a `201: Success` message and shows the consent record data. The consent record `id` and other properties shown in the consent record data can be converted into an open banking response sent to Company A for further action. The consent record data looks like this:

```json
{
  "_links": {},
  "_embedded": {},
  "status": "pending",
  "subject": "Customer",
  "actor": "Customer",
  "audience": "CompanyA",
  "definition": {
    "id": "OpenBankingAccountsConsent",
    "version": "1.0",
    "locale": "en-US"
  },
  "id": "4308ac1d-a493-426d-9211-224255145d28",
  "dataText": "Allow access to your financial accounts.",
  "purposeText": "This data is required to complete your transaction.",
  "data": {
    "Permissions": [
      "ReadAccountsDetail", \
      "ReadBalances", \
      "ReadBeneficiariesDetail", \
      "ReadDirectDebits", \
      "ReadProducts"
      ]
    },
  "consentContext": {}
}
```

[]()

## Check the account request state

Company A checks the consent status of the Customer's account. It makes a `GET` request to the `/account-requests/{{accountrequestid}}` service on the data governance server at Company B using the `AccountRequestId` property value returned in [Create the account request](#consent-create-the-account-request). Company B checks the consent status by making a `GET` request to the `/consents/{{consentRecordId}}` service on its directory server.

The `GET /consents/{{consentRecordId}}` operation finds the consent record data for the `consentRecordId` returned in [Create a consent record](#post-create-a-consent).

```none
curl -X GET "https://api.companyb.com/consent/v1/consents/5caa81af-ec05-41ff-a709-c7378007a99c" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken"
```

In this case, the resulting consent record data shows the `status` property as `pending`, which tells company A that it needs to move forward by prompting the Customer to grant authorization.

```none
{
  ...
  "status": "pending",
  "subject": "Customer",
  "actor": "Customer",
  "audience": "CompanyA",
  ...
}
```

[]()

## Prompt to get the Customer's consent

Company B gets the consent definition's localized text to display a consent prompt to the Customer. The consent capture app makes a `GET` request to the `/definitions/{{definitionid}}/localizations+` service on the directory server.

The `GET definitions/OpenBankingAccountsConsent/localizations` operation gets the consent record data for the `OpenBankingAccountsConsent` consent definition.

```none
curl -X GET "https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent/localizations" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken"
```

The response data shows the current consent definition localizations. For this consent definition, there are two localizations resources: `en-US` and `fr-CA`.

```json
{
  "count": 2,
  "size": 2,
  "_links":{
    "self":{
      "href":"https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent/localizations"
    }
  },
  "_embedded":{
    "localizations":[
      {
        "_links":{
          "parent":{
            "href":"https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent"
          },
          "self":{
            "href":"https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent/localizations/en-US"
          }
        },
        "id":"en-US",
        "locale":"en-US",
        "version":"1.1",
        "dataText":"Allow access to your financial accounts.",
        "purposeText":"This data is required to complete your transaction."
      },
      {
        "_links":{
          "parent":{
            "href":"https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent"
          },
          "self":{
            "href":"https://api.companyb.com/consent/v1/definitions/OpenBankingAccountsConsent/localizations/fr-CA"
          }
        },
        "id":"fr-CA",
        "locale":"fr-CA",
        "version":"1.2",
        "dataText":"Autoriser l'accès à vos comptes financiers.",
        "purposeText":"Ces données sont nécessaires pour compléter votre transaction."
      }
    ]
  }
}
```

## Update the consent record

After the Customer responds to the consent prompt, the authorization or denial of consent is added to the consent record. The consent capture app makes a `PATCH` request to the `/consents/{{consentRecordId}}` service to update the Customer's consent record. The updated record stores the information collected by the consent capture app from the Customer's response to the consent prompt.

The `PATCH /consents/{{consentRecordId}}` operation updates an existing consent record, modifying the record to reflect only the new property values specified in the request body. The `consentRecordId` value obtained in [Create a consent record](#post-create-a-consent) is added to the request URL to identify the Customer's consent record.

```none
curl -X PATCH "https://api.companyb.com/consent/v1/consents/5caa81af-ec05-41ff-a709-c7378007a99c" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken" \
-d "{
  "status": "accepted"
  }
}"
```

In this sample, the Customer is prompted to ALLOW/DENY authorization to Company A for all data-sharing permissions. The request body specifies a modification to only the `status` property value to reflect the Customer's response. The updated consent record looks like this:

```json
{
  "_links": {},
  "_embedded": {},
  "status": "accepted",
  "subject": "Customer",
  "actor": "Customer",
  "audience": "CompanyA",
  "definition": {
    "id": "OpenBankingAccountsConsent",
    "version": "1.0",
    "locale": "en-US"
  },
  "id": "32adc1d-a493-426d-9211-224255145d28",
  "dataText": "Allow access to your financial accounts.",
  "purposeText": "This data is required to complete your transaction.",
  "data": {
    "Permissions": [
      "ReadAccountsDetail", \
      "ReadBalances", \
      "ReadBeneficiariesDetail", \
      "ReadDirectDebits", \
      "ReadProducts"
      ]
    },
  "consentContext": {}
}
```

If the Customer chooses to terminate the relationship with Company A, the Customer can revoke consent. In this case, to honor the Customer's revocation request, Company A makes a `DELETE` request to the `/account-requests/{{accountrequestid}}` service on Company B's data governance server. To complete the operation, Company B makes a `PATCH` request to the `/consent/v1/consents/{{consentRecordId}}` service on the directory server, specifying the change in `status` for the account.

```none
curl -X PATCH "https://api.companyb.com/consent/v1/consents/5caa81af-ec05-41ff-a709-c7378007a99c" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer accessToken" \
-d "{
  "status": "revoked"
  }
}"
```