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.

Checking consent records (getting a list of records) requires 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. 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.id=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.id (share-my-email).

Filtering result data

The following attributes can be used in a filtering expression for the GET /consents/check 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.

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 colleted or shared) or the grantor of consent (the person who responded 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).

You can create consent records to store responses from users. The request body must provide values for the status, subject, actor, and audience attributes. 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.

  • dataText

    The description of the data to be collected, processed, or shared that is presented to the individual when requesting consent. This attribute is required when the status attribute value is accepted or denied.

  • purposeText

    The description of the reason for data access that is presented to the individual when requesting consent. This attribute is required when the status attribute value is accepted or denied.

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..."
}"

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 essential consent record attributes. The PATCH /consents/{id} operation performs a partial update operation, changing only the attribute values that you specify in the request body.

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.