Platform APIs
More PingIdentity APIs

Manage consent records

When a user responds to a consent request, a consent record is created to capture the data. The Consents service implements functions to check for existing consent records, get a specific consent record, and create new or modify existing consent records.

You can get all consent records associated with a specific individual, and that individual can be either the subject of the consent (the person whose data is collected or shared) or the grantor of consent (the person who responded to the consent request).

Checking consent records (getting a list of records) supports specifying either the subject or actor query parameter to focus the search. These parameters identify either the person whose data is being collected or shared (subject) or the person who granted or denied consent (actor). In many cases, the subject and actor are the same individual.

Note: Specifying the subject and actor query parameters are not required by the client. If these parameters are omitted, a subject value is inferred from the authentication context. For example, if the client uses bearer token to authenticate, the token subject is used.

The query parameter can be fine-tuned by adding another consents resource attribute to the query. Here is a sample:

"https://<server>/consent/v1/consents?subject=JohnDoe&definition=share-my-email"

For this request, the response data will show only the consent records for the subject (John Doe) in response to a specific consent definition resource definition (share-my-email).

Filtering result data

The following attributes can be used in a filtering expression for the GET /consents operation:

  • subject

    The individual whose data is being collected or shared through a consent grant.

  • actor

    The individual who granted the consent request.

  • definition

    The consent definition ID.

  • audience

    The entity that requested or received the individual’s response to the consent request.

The following sample shows the GET /consents operation to return the consent records associated with the specified individual.

curl -X GET "https://<server>/consent/v1/consents/?subject=JohnDoe" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data shows all consent records associated with subject John Doe:

{
    "_embedded": {
        "consents": [
            {
                "_links": {
                    "definition": {
                        "href": "https://<server>/consent/v1/definitions/share-my-email"
                    },
                    "localization": {
                        "href": "https://<server>/consent/v1/definitions/share-my-email/localizations/en-US",
                        "hreflang": "en-US"
                    },
                    "self": {
                        "href": "https://<server>/consent/v1/consents/f0c0ac1d-a493-426d-9211-224255145d28"
                    }
                },
                "actor": "JohnDoe",
                "audience": "client1",
                "createdDate": "2018-03-26T18:43:28.616Z",
                "dataText": "Share your email address",
                "definition": {
                    "currentVersion": "1.0",
                    "id": "share-my-email",
                    "locale": "en-US",
                    "version": "1.0"
                },
                "id": "f0c0ac1d-a493-426d-9211-224255145d28",
                "purposeText": "To allow ACME, Inc. to store your email address",
                "status": "accepted",
                "subject": "JohnDoe",
                "updatedDate": "2018-03-26T18:43:28.616Z"
            }
        ]
    },
    "_links": {
        "self": {
            "href": "https://<server>/consent/v1/consents?subject=JohnDoe"
        }
    },
    "count": 1,
    "size": 1
}

You can fine-tune the search by adding another supported query parameter to the request. The GET /consents?param1={value}&param2={value} operation returns consent records that satisfy the filtering expression.

curl -X GET "https://<server>/consent/v1/consents?subject=JohnDoe&audience=salesforce.com" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data lists the consent records associated with John Doe (subject) that apply to a specific audience (salesforce.com).

The Consents API performs basic validation on consent record create and modify operations, with many of the validation rules based on the value of the consent record status attribute.

The following read-only attributes are set by the server and cannot be changed:

  • id
  • subjectDN
  • actorDN
  • createdDate
  • updatedDate

The following attributes are immutable; they cannot be changed after they are set:

  • subject
  • audience
  • definition

For all status values, the definition ID must always be present.

If the status is accepted or denied, the definition must refer to an existing localization (definition.version and definition.locale). However, a consent record can be changed to the revoked or restricted status even if the originally accepted version no longer exists.

If the status is not pending, then the consent record must contain subject, actor, audience, titleText, dataText, and dataPurpose attribute values. These attributes are not required for pending consents because the user has not yet been prompted for consent, and the user ID might not be known.

For create operations, the status attribute value cannot be set to revoked or restricted.

For modify operations, the status attribute value cannot be changed to pending. In addition, the status attribute value can be changed to revoked or restricted from the accepted state only.

You can create consent records to store responses from users. The request body requires values for the subject, actor, audience, and status attributes.

The subject and actor attributes do not have to be specified in the request because they are inferred from the authentication context by default. For unprivileged requesters, this is always the case; these fields are ignored if set by the client. Privileged requesters can set these values.

Note: The actor attribute value is always inferred from the authentication context when an unprivileged client updates a consent record. However, a privileged client can provide an explicit value for the actor attribute. The subject attribute value is immutable and cannot be changed after the create operation.

The value for the status attribute indicates how data represented by the consent record can be processed. The status attribute supports the following options:

Status Description
pending The consent record has been created but is not yet associated with a consent decision. This is a special-purpose state that exists to support Open Banking clients, which use this state to stage account requests prior to their approval.
accepted The actor has granted consent for data to be shared with or processed by the audience. This is the only state that indicates that data may be shared or processed.
denied The actor has declined consent.
revoked The actor has revoked a previously accepted consent. This value cannot be set in a POST request.
restricted An actor has previously accepted consent but has invoked the right to temporarily restrict processing of the data. For example, this status can be used when the user has entered into a dispute with the data processor. This value cannot be set in a POST request.

In addition, the following consent definition resource properties must be provided:

  • id

    The consent definition resource ID associated with this consent record.

  • version

    The version number of the consent definition resource associated with this consent record.

  • locale

    The consent definition resource’s localization locale used when recording this consent record.

The following consent definition resource properties must be provided when the status resource property value is accepted or denied:

  • dataText

    The description of the data to be collected, processed, or shared that is presented to the individual when requesting consent.

  • purposeText

    The description of the reason for data access that is presented to the individual when requesting consent.

  • titleText

    The title of the consent message that is presented to the individual when requesting consent.

Note: You can also define additional properties to store custom data that is relevant to the consent request.

The following sample shows the POST /consents/ operation to create a new consent record.

curl -X POST "https://<server>/consent/v1/consents" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "status": "accepted",
  "subject": "JohnDoe",
  "actor": "JohnDoe",
  "audience": "Apple",
  "definition": {
    "id": "share-my-email", \
    "version": "1.0\",
    "locale": "en-US" },
  "dataText": "You agree to share this data...",
  "purposeText": "This data will be used for..."
  "titleText": "Share Your Data!"
}"

In this sample, the request body specifies values for all the attributes required to create the consent record. The status attribute value is accepted, which then requires values in the request body for the dataText and purposeText attributes.

If successful, the operation returns a 201: Success message and shows the consent record data.

There are two ways to modify an existing consent record. The PUT /consents/{id} operation updates all attribute values for the identified record. In the request body, you must specify values for all required consent record attributes, including values for dataText and purposeText if the status is modified from pending to accepted.

The PATCH /consents/{id} operation performs a partial update operation, changing only the attribute values that you specify in the request body. Again, you must specify values for dataText and purposeText if the status is modified from pending to accepted.

For example, you can use the PATCH /consents/{consentRecordId} operation to update only a single attribute value on an identified consent record.

curl -X PATCH "https://<server>/v1/consents/{consentRecordId}" \
-H "accept: application/hal+json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "status": "revoked"
}"

If successful, the operation returns a 200: Success message and shows the updated consent record data.