Agreements define the details of an agreement to which end users provide consent. An agreement consists of these PingOne resources:

Agreement configuration

An agreement cannot be enabled unless it supports the default environment language. The agreement resource can have its enabled property set to true only if there is “agreement content to show” for the default environment language. If the enabled property on the agreement resource is false, the agreement cannot be presented to end users.

The condition of having “agreement content to show” requires that at least the environment’s default language is configured as an agreement language resource. The agreement language resource that supports the environment’s default language must be enabled. The agreement language resource can have its enabled property set to true only if there is “localized content to show” configured on its associated agreement revisions resource. If the enabled property on the agreement language resource is false, the agreement language cannot be presented to end users. Remember, you must enable the agreement language resource that represents the environment’s default language to enable the agreement. Additional agreement languages can also be configured and associated with the agreement.

The agreement revision resource associated with an agreement language resource must have text content (and it can have optional buttons and checkboxes) configured on the resource to meet the “localized content to show” condition to enable the language. For the agreement revision to be active, the agreement revision’s effectiveDate property must not be set to a future date. However, the effectiveDate value can be set to a future date, but the revision is inactive until the specified date.

How agreement content is presented to users

Agreement languages are defined by either the language code (for example, en) or the combination of language code and country code (for example, en-GB). For identifying languages, the API follows the tags for identifying languages described in RFC_4646. For selecting a language code to use in an agreement, the API follows the matching of language tags described in RFC_4647.

When an agreement is active, languages are presented to the user in the following order:

  1. User preference: The end user receives agreement content in the language that matches the user’s preferredLanguage property value.

  2. Browser preference: If the user’s preferredLanguage is not configured (or enabled) as one of the supported agreement language resources for this agreement, the end user receives agreement content in the language associated with the browser’s configured locale.

  3. Environment default language: If the browser’s configured language is not one of the enabled agreement language resources for this agreement, then the agreement content is presented to the end user in the environment’s default language.

The following table shows an example of how the platform presents agreement languages to users, depending on the environment default language, the configured agreement languages, and the user’s language preferences.

Environment default language Configured agreement languages User preference languages (ordered) Language presented to user
es en, es en-US, es en
es en-GB, es en-US es
es en, en-GB, es en-US, es, en-GB en

Agreement consent history

A user’s consents to agreements do not expire by default, but they can be configured to designate a re-consent action based on a specified length of time or the active date of an agreement revision. An environment supports up to 100 agreement resources.

Only the user’s latest consent information is kept in the API. Agreement consent history is visible through audit reporting events. For more information about audit reporting, see Audit Activities.

For example, to search for the consent history for a specific user to an agreement using the audit activities API, the query filter looks like this:

recordedat ge "2020-12-11T22:13:41.838Z" and recordedat le "2021-06-09T21:13:41.838Z" and resources.type eq "user" and resources.id eq "<user-id>" and (action.type eq "AGREEMENT_CONSENT.ACCEPTED")

To search for consent history for an agreement (showing consents for all users), the query filter looks like this:

recordedat ge "2020-12-11T22:11:54.484Z" and recordedat le "2021-06-09T21:11:54.484Z" and resources.id eq "<agreement-id>" and (action.type eq "AGREEMENT_CONSENT.ACCEPTED")

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

The audit reporting events applicable to agreement consent history are:

Service Event
agreements AGREEMENT.CREATED
agreements AGREEMENT.UPDATED
agreements AGREEMENT_LANGUAGE.CREATED
agreements AGREEMENT_LANGUAGE.UPDATED
agreements AGREEMENT_LANGUAGE_REVISION.CREATED
agreements AGREEMENT_LANGUAGE_REVISION.DELETED
users AGREEMENT_CONSENT.ACCEPTED
users AGREEMENT_CONSENT.REVOKED
users AGREEMENT_CONSENT.DECLINED
agreements AGREEMENT_CONSENT.ACCEPTED
agreements AGREEMENT_CONSENT.REVOKED
agreements AGREEMENT_CONSENT.DECLINED
agreements LOCALIZATION_STATUS.UPDATED