PingOne Platform APIs

User Agreement Consents

A user agreement consent resource is a record of a user consenting to a terms of service agreement for a specific language and revision. Only the latest consent record is available through a GET request, which shows only the current agreement consent state for (1) all the user’s agreement consents, or (2) the current agreement consent state for one specific agreement.

This service provides operations to read and update user agreement consent resources.

You need the Environment Admin role to perform operations on user consent resources.

The properties described here identify the agreement consents associated with a specified user and current state of the agreement consent (represented by the lastConsent properties).

Property Type Required Mutable Description

agreement

Object

Required

Mutable

Specifies the agreement resource for this agreement consent.

agreement.id

String

Required

Mutable

Specifies the UUID of the agreement resource for this agreement consent.

language

Object

Required

Mutable

Specifies the language resource associated with this agreement consent.

language.id

String

Required

Mutable

Specifies the language resource UUID associated with this agreement consent. If the status is ACCEPTED, then this is the language associated with the consent. For any other status value, this represents the language to which the user must consent.

lastConsent.at

DateTime

N/A

Read-only

Specifies the date and time at which the user consented to the agreement.

lastConsent.expiresAt

DateTime

N/A

Read-only

Specifies the date and time at which the user consent to the agreement expires.

lastConsent.language

Object

N/A

Read-only

Specifies the language resource associated with the user’s last agreement consent.

lastConsent.language.id

String

N/A

Read-only

Specifies the language resource UUID associated with the user’s last agreement consent.

lastConsent.revision

Object

N/A

Read-only

Specifies the revision resource associated with the user’s last agreement consent.

lastConsent.revision.id

String

N/A

Read-only

Specifies the revision resource UUID associated with the user’s last agreement consent.

revision

Object

Required

Mutable

Specifies the revision resource associated with this agreement consent.

revision.id

String

Required

Mutable

Specifies the revision resource UUID associated with this agreement consent.

status

String

N/A

Read-only

Specifies whether the consent is valid or not, depending on the agreement, language, and revision configuration. Options are PENDING, ACCEPTED, REVOKED, EXPIRED, and AGREEMENT_DISABLED. This property value is computed dynamically when the resource is returned.

user

Object

Required

Mutable

Specifies the user associated with this agreement consent.

user.id

String

Required

Mutable

Specifies the UUID of the user associated with this agreement consent.

The properties described here are used with the PingOne audit reporting service to search for a user’s consent history for specific agreements. For more information about the audit events to use to query a user’s consent history, refer to Agreement Management.

Property Type Required Mutable Description

consentedAt

DateTime

Optional

Mutable

Specifies the date and time at which the user consented to the agreement.

agreement

Object

Required

Mutable

Specifies the agreement resource for this agreement consent.

agreement.id

String

Required

Mutable

Specifies the UUID of the agreement resource for this agreement consent.

language

Object

Required

Mutable

Specifies the language resource associated with this agreement consent.

language.id

String

Required

Mutable

Specifies the language resource UUID associated with this agreement consent.

revision

Object

Required

Mutable

Specifies the revision resource associated with this agreement consent.

revision.id

String

Required

Mutable

Specifies the revision resource UUID associated with this agreement consent.

status

String

N/A

Read-only

Specifies whether the consent is valid or not, depending on the agreement, language, and revision configuration. Options are ACTIVE, INVALID, and EXPIRED. This property value is computed dynamically when the resource is returned.

user

Object

Required

Mutable

Specifies the user associated with this agreement consent.

user.id

String

Required

Mutable

Specifies the UUID of the user associated with this agreement consent.

Response codes

Code Message

200

Successful operation.

400

The request could not be completed.

401

You do not have access to this resource.

404

The requested resource was not found.

In addition to the general error codes, user agreement consent operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE

Message: Validation Error : [<field> <message>]

When and details

When: A POST /users/{ID}/agreementConsents/{agreementID} request body omits language or revision

Details: Describes the failing property, such as must not be null for an omitted language or revision relationship, or must have an id for a relationship without an id value, for example Validation Error : [language must not be null].

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: An accept request references a language that does not exist or is disabled, a revision that does not exist or is not effective or is expired, or a consentedAt date in the future

Details: The language does not exist, The language is disabled, The revision does not exist, The revision is not effective or is expired, or The consent date cannot be a future date

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: An accept request targets an agreement that is disabled

Details: The agreement can not be consented to because it is disabled.

400

REQUEST_FAILED

INVALID_FILTER

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A GET /users/{ID}/agreementConsents request uses an unsupported filter value

Details: The filter failure message.

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: The directory service cannot validate the user on the list operation, or the list operation is not authorized and the user’s population cannot be resolved

Details: Failed to validate the user. or User doesn’t exist.

403

ACCESS_FAILED

INSUFFICIENT_PERMISSIONS

Message: The request could not be completed. You do not have access to this resource.

When and details

When: The list operation is not authorized for the user’s environment, population, or group scope

Details: You do not have permissions to access this resource.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the agreements:read:userConsent permission (GET operations), the agreements:create:userConsent permission (accept), or the agreements:delete:userConsent permission (revoke)

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: The agreement ID in the request URL does not exist in the environment, or a revoke request finds no consent for the user and agreement

Details: None.

500

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: The environment has no default language configured, or no preferred language and revision can be determined when building the consent state

Details: None.