Agreements Resources

The agreements API defines the top level configuration for all the languages resources associated with the agreement. It implements functions to create, read, update, and delete agreement resources.

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

Agreements data model

Property Type Required Mutable Description

Property	Type	Required	Mutable	Description
`consentCountsUpdatedAt`	Date	N/A	Read-Only	The time the consent count metric was last updated. This value is typically updated once every 24 hours.
`description`	String	Optional	Mutable	The description of the agreement.
`enabled`	Boolean	Required	Mutable	The current enabled state of the agreement. The agreement must support the default language to be enabled. It cannot be disabled if it is referenced by a sign-on action. When an agreement is disabled, it is not used anywhere that it is configured across PingOne.
`environment.id`	String	N/A	Read-Only	A string that specifies the environment associated with the agreement.
`expiredUserConsents`	Integer	Required	Read-Only	The number of users who have consented to the agreement, but their consent has expired. This value is last calculated at the `consentCountsUpdatedAt` time.
`id`	String	N/A	Read-Only	The agreement ID.
`name`	String	Required	Mutable	The name of the agreement resource.
`reconsentPeriodDays`	Float	Optional	Mutable	The number of days until a consent to this agreement expires.
`totalUserConsents`	Integer	Required	Read-Only	The total number of users who have consented to the agreement. This value is last calculated at the `consentCountsUpdatedAt` time.

consentCountsUpdatedAt

Date

N/A

Read-Only

The time the consent count metric was last updated. This value is typically updated once every 24 hours.

description

String

Optional

Mutable

The description of the agreement.

enabled

Boolean

Required

Mutable

The current enabled state of the agreement. The agreement must support the default language to be enabled. It cannot be disabled if it is referenced by a sign-on action. When an agreement is disabled, it is not used anywhere that it is configured across PingOne.

environment.id

String

N/A

Read-Only

A string that specifies the environment associated with the agreement.

expiredUserConsents

Integer

Required

Read-Only

The number of users who have consented to the agreement, but their consent has expired. This value is last calculated at the consentCountsUpdatedAt time.

id

String

N/A

Read-Only

The agreement ID.

name

String

Required

Mutable

The name of the agreement resource.

reconsentPeriodDays

Float

Optional

Mutable

The number of days until a consent to this agreement expires.

totalUserConsents

Integer

Required

Read-Only

The total number of users who have consented to the agreement. This value is last calculated at the consentCountsUpdatedAt time.

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 errors

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

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

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` request omits the required `name` or `enabled` property Details: `must not be null` on `name` or `enabled` (detail `EMPTY_VALUE`), for example `Validation Error : [name must not be null]`
400	`INVALID_DATA`	`INVALID_VALUE`	Message: `Validation Error : [<property> <message>]` When and details When: A `POST` or `PUT /agreements` request supplies a `name` that does not match the object name rules, or a `description` that does not match the description character rules Details: `must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens` for an invalid `name`, or must contain only Unicode letters, marks, numbers, spaces, or punctuation (except $, +, <, =, >, ^, `, \|, ~) for an invalid `description`, for example: Validation Error : [name must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens]
400	`INVALID_DATA`	`OUT_OF_RANGE`	Message: `Validation Error : [<property> <message>]` When and details When: A `POST` or `PUT /agreements` request supplies a `name` or `description` that exceeds its maximum length, or a `reconsentPeriodDays` value of `0` or less Details: `size must be between 1 and 256` for a too-long `name`, `size must be between 1 and 1024` for a too-long `description`, or `must be greater than 0` for `reconsentPeriodDays` (detail `INVALID_VALUE` for the `reconsentPeriodDays` violation), for example `Validation Error : [reconsentPeriodDays must be greater than 0]`
400	`INVALID_DATA`	`UNIQUENESS_VIOLATION`	Message: `The request could not be completed. One or more validation errors were in the request.` When and details When: A `POST /agreements` request creates an agreement with a name that duplicates another agreement in the environment, or a `PUT /agreements/{ID}` request renames the agreement to one that does Details: `A resource with the specified name already exists.`
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` request would exceed the maximum number of agreements for the environment (default 100) Details: `The maximum of <maximum> agreements 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 `POST /agreements` request sets `enabled` to `true`. An agreement is enabled only after it supports the environment’s default language Details: `Must be false. The agreement can be enabled upon configuring support for the environment’s default language.`
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/{ID}` request sets `enabled` to `true` when the agreement does not have an enabled language matching the environment’s default language Details: `The agreement can not be enabled without supporting the default language configured for the environment.`
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/{ID}` request deletes an agreement that is enabled Details: `Can not delete an enabled agreement.`
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/{ID}` request deletes an agreement that end users have consented to, including expired consents Details: `Can not delete an agreement that has been consented to by end users.`
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, or the request body cannot be deserialized Details: For a JSON field conversion error, the target is the field path. 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:create:agreement` permission (`POST`), the `agreements:update:agreement` permission (`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/{ID}` references an agreement that does not exist in the environment Details: None.

400

INVALID_DATA

EMPTY_VALUE

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

When and details

When: A POST or PUT /agreements request omits the required name or enabled property

Details: must not be null on name or enabled (detail EMPTY_VALUE), for example Validation Error : [name must not be null]

400

INVALID_DATA

INVALID_VALUE

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

When and details

When: A POST or PUT /agreements request supplies a name that does not match the object name rules, or a description that does not match the description character rules

Details: must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens for an invalid name, or must contain only Unicode letters, marks, numbers, spaces, or punctuation (except $, +, <, =, >, ^, `, |, ~) for an invalid description, for example:

Validation Error : [name must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, underscores, or hyphens]

400

INVALID_DATA

OUT_OF_RANGE

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

When and details

When: A POST or PUT /agreements request supplies a name or description that exceeds its maximum length, or a reconsentPeriodDays value of 0 or less

Details: size must be between 1 and 256 for a too-long name, size must be between 1 and 1024 for a too-long description, or must be greater than 0 for reconsentPeriodDays (detail INVALID_VALUE for the reconsentPeriodDays violation), for example Validation Error : [reconsentPeriodDays must be greater than 0]

400

INVALID_DATA

UNIQUENESS_VIOLATION

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

When and details

When: A POST /agreements request creates an agreement with a name that duplicates another agreement in the environment, or a PUT /agreements/{ID} request renames the agreement to one that does

Details: A resource with the specified name already exists.

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 request would exceed the maximum number of agreements for the environment (default 100)

Details: The maximum of <maximum> agreements 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 POST /agreements request sets enabled to true. An agreement is enabled only after it supports the environment’s default language

Details: Must be false. The agreement can be enabled upon configuring support for the environment’s default language.

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/{ID} request sets enabled to true when the agreement does not have an enabled language matching the environment’s default language

Details: The agreement can not be enabled without supporting the default language configured for the environment.

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/{ID} request deletes an agreement that is enabled

Details: Can not delete an enabled agreement.

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/{ID} request deletes an agreement that end users have consented to, including expired consents

Details: Can not delete an agreement that has been consented to by end users.

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, or the request body cannot be deserialized

Details: For a JSON field conversion error, the target is the field path. 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:create:agreement permission (POST), the agreements:update:agreement permission (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/{ID} references an agreement that does not exist in the environment

Details: None.

PingOne Platform APIs

Agreements Resources

Agreements data model

Response codes

Agreement errors