PingOne Platform APIs

Agreement Revisions Resources

Agreement revisions define the specific version text (the agreement content) to manage the lifecycle of the agreement to which users provide consent.

A revision resource allows you to update the content for an agreement language. (A language can have up to 100 associated revisions.) The revision must have a value specified for the effectiveDate property, and when showing content to a user for an agreement language, the content associated with a revision with an effective date closest to the current date is shown. The revision can be configured to force the user to consent again to the agreement.

The revisions service implements functions to create, read, and delete agreement revision resources. Agreement revision resources cannot be updated. If an agreement revision needs to be updated, a new agreement revision should be created. In addition, agreement revision resources that have become effective cannot be deleted, which ensures that consent data is preserved.

You need the Environment Admin role to perform operations on agreement revisions resources.

Revision data model

Property Type Required Mutable Description

agreement

String

Required

Read-Only

The UUID for the agreement resource for this revision.

contentType

String

Required

Immutable

The content type of text. Options are text/html and text/plain, as defined by rfc-6838 and Media Types/text. This attribute is supported in POST requests only.

effectiveAt

Date

Required

Mutable

The start date that the revision is presented to users. This property value can be modified only if the current value is a date that has not already passed. The effective date must be unique for each language agreement, and the property value can be the present date or a future date only.

id

String

Required

Read-Only

The revision ID.

language

String

Required

Mutable

A UUID that specifies the language resource associated with this revision.

notValidAfter

Date

Optional

Read-Only

Specifies whether the revision is still valid in the context of all revisions for a language. This property is calculated dynamically at read time, taking into consideration the agreement language, the language enabled property, and the agreement enabled property. When a new revision is added, the notValidAfter property values for all other previous revisions might be impacted. For example, if a new revision becomes effective and it forces reconsent, then all older revisions are no longer valid.

requiresReconsent

Boolean

Required

Mutable

Whether the user is required to provide consent to the language revision after it becomes effective.

text

String

Required

Immutable

Text or HTML for the revision. HTML support includes:

* tags - italicize, bold, links, headers, paragraph, line breaks

* link (a) tags - allow href, style, target attributes

* block tags (p, b, h) - allow style and align attributes

This attribute is supported in POST requests only. For more information, refer to contentType.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

Agreement revision errors

In addition to the general error codes, agreement revision 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 : [<property> <message>]

When and details

When: A POST or PUT /agreements/{agreementID}/languages/{languageID}/revisions request omits the required effectiveAt or requireReconsent property, or a POST request omits the required text property

Details: Describes the failing property, such as must not be null for an omitted effectiveAt, requireReconsent, or text property, for example Validation Error : [effectiveAt must not be null]

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A POST /agreements/{agreementID}/languages/{languageID}/revisions request supplies a contentType value other than text/html or text/plain

Details: must be one of [text/html, text/plain], for example Validation Error : [contentType must be one of [text/html, text/plain]]

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: A POST /agreements/{agreementID}/languages/{languageID}/revisions request supplies revision text that is empty or exceeds 150 KB

Details: must not be empty or maximum size is 150KB

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: A POST /agreements/{agreementID}/languages/{languageID}/revisions request with a contentType of text/html supplies HTML that the revision content rules reject, such as unsupported tags or attributes, or a link that does not use https:// or mailto://

Details: Describes the rejected HTML, such as unsupported HTML or All HTML links must use https:// or mailto:// protocols

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: A POST or PUT /agreements/{agreementID}/languages/{languageID}/revisions request supplies an effectiveAt date more than 5 seconds in the past, or an effectiveAt date that another revision of the same language already uses

Details: The revision can not take effect in the past. or Another revision has the same effectiveAt date.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A POST /agreements/{agreementID}/languages/{languageID}/revisions request would exceed the maximum number of revisions for the language

Details: The maximum of <maximum> revisions per language has been reached.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A PUT /agreements/{agreementID}/languages/{languageID}/revisions/{ID} request changes the effectiveAt date of a revision that has already taken effect

Details:

The revision is already effective and can not be updated. If this is the current revision and you need to override it try creating a new revision and forcing reconsent.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

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

When and details

When: A DELETE /agreements/{agreementID}/languages/{languageID}/revisions/{ID} request deletes a revision that has taken effect

Details: A currently effective revision cannot be deleted.

400

INVALID_REQUEST

None

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

When and details

When: A path identifier cannot be parsed as a UUID

Details: None.

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: The request body cannot be deserialized as JSON

Details: Invalid value for attribute., with the target set to the field path for a field conversion error. Otherwise no detail is returned.

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:agreement permission (GET operations), the agreements:update:agreement permission (POST and PUT), or the agreements:delete:agreement permission (DELETE)

Details: None.

404

NOT_FOUND

None

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

When and details

When: GET, PUT, or DELETE /agreements/{agreementID}/languages/{languageID}/revisions/{ID} references a revision, language, or agreement that does not exist

Details: None.