PingOne Platform APIs

Agreement Languages Resources

Agreement languages define the configuration for the locale and for the configuration that applies to all revision resources associated with the language.

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.

The end user’s language selection for the consent agreement is determined by these attributes in the following priority: (1) the user’s preferred locale, (2) the browser locale, or (3) the default language for the environment.

The agreement languages service implements functions to create, read, update, and delete agreement language resources.

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

Agreement languages data model

Property Type Required Mutable Description

agreement

String

Required

Read-Only

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

currentRevision

String

Optional

Read-Only

A UUID that specifies the current revision associated with this language resource. The current revision is the one shown to users for new consents in the language.

displayName

String

Required

Mutable

Used as the title of the agreement for the language presented to the user.

enabled

Date

Required/Optional

Mutable

Maps directly with a language being enabled or displayed for the environment within the platform. When running Create Language, enabled value will be false whether or not this property is included. If the language is disabled at the environment level, this property if always false.

id

String

Required

Read-Only

UUID that specifies the language ID.

locale

String

Required

Mutable

The tag for identifying the language resource associated with this agreement consent (for example, en-US). For more information about language tags, refer to Tags for Identifying Languages.

userExperience.acceptCheckboxText

String

Optional

Mutable

The text next to the "accept" checkbox in the end user interface. Accepted character are unicode letters, combining marks, numeric characters, whitespace, and punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$).

userExperience.continueButtonText

String

Optional

Mutable

The text of the "continue" button in the end user interface. Accepted character are unicode letters, combining marks, numeric characters, whitespace, and punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$).

userExperience.declineButtonText

String

Optional

Mutable

The text of the "decline" button in the end user interface. Accepted character are unicode letters, combining marks, numeric characters, whitespace, and punctuation characters (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}]+$).

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 language errors

In addition to the general error codes, agreement language 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 or OUT_OF_RANGE or INVALID_VALUE

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

When and details

When: A POST or PUT /agreements/{agreementID}/languages request omits the required displayName or locale property, or supplies a displayName that is empty, blank, over 256 characters, or does not match the display name character rules

Details: must not be null for an omitted displayName or locale, size must be between 1 and 256 for an empty or over-long displayName, must not be empty or blank for a blank displayName, or:

must contain only Unicode letters, marks, numbers, spaces, forward slashes, dots, apostrophes, brackets, underscores, or hyphens

for a displayName that does not match the display name character rules, for example Validation Error : [displayName 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: A POST or PUT /agreements/{agreementID}/languages request supplies a userExperience object with no acceptCheckboxText, continueButtonText, or declineButtonText value

Details: must not be an empty object with target userExperience

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/{agreementID}/languages request creates a language with a locale that another language of the same agreement already uses (case‑insensitive)

Details: A resource with the specified name already exists. with target locale

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/{ID} request deletes a language that has an effective revision

Details: Agreement language with effective revision can not be deleted. with no target

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 PUT /agreements/{agreementID}/languages/{ID} request sets enabled to true when the language has no effective revision to show users

Details: The language must have a revision to show users in order to be enabled. Please create a revision for the language that is configured to take effect immediately. with target enabled

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/{ID} request sets enabled to true when the language is not enabled for the environment, or is not configured for the environment at all

Details: the language is not enabled for the environment or the language is not configured for the environment, each with target enabled

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/{ID} request sets enabled to false for the language that supports the environment’s default language while the agreement is enabled

Details:

The agreement language that supports default environment language can not be disabled. To disable agreement language 1) disable an agreement or 2) configure default environment language to another.

with target enabled.

400

INVALID_REQUEST

None

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

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: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/{ID} references an agreement language that does not exist, or an agreement that does not exist

Details: None.