PingOne Platform APIs

Languages

There are 239 language codes in the ISO standard language code table. This service defaults to supporting a maximum of 17 languages resources. However, you can add custom languages (requires Environment Admin permissions). Refer to Create Language.

The languages service supports the following input and output data model properties for languages resources.

Languages input data model

Property Type Required Mutable Description

default

Boolean

Required

Mutable

Specifies whether this language is the default for the environment. This property value must be set to false when creating a language resource. It can be set to true only after the language is enabled and after the localization of an agreement resource is complete when agreements are used for the environment.

enabled

Boolean

Required

Mutable

Specifies whether this language is enabled for the environment. This property value must be set to false when creating a language.

environment.id

String

Required

Immutable

The environment resource’s unique identifier associated with the resource.

id

String

Required

Immutable

The resource’s unique identifier.

locale

String

Required

Mutable

An ISO standard language code. For more information about standard language codes, refer to ISO Language Code Table.

name

String

Optional

Mutable

The language name. If omitted, the ISO standard name is used.

Languages output data model

Property Type Required Mutable Description

createdAt

Date

N/A

Read-only

The time the language resource was created.

customerAdded

Boolean

Optional

Mutable

Specifies whether this language was added by a customer administrator.

default

Boolean

Required

Mutable

Specifies whether this language is the default for the environment. This property value must be set to false when creating a language resource. It can be set to true only after the language is enabled and after the localization of an agreement resource is complete when agreements are used for the environment.

enabled

Boolean

Required

Mutable

Specifies whether this language is enabled for the environment. This property value must be set to false when creating a language.

environment.id

String

Required

Immutable

The environment resource’s unique identifier associated with the resource.

id

String

Required

Immutable

The resource’s unique identifier.

locale

String

Required

Mutable

An ISO standard language code. For more information about standard language codes, refer to ISO Language Code Table.

name

String

Optional

Mutable

The language name. If omitted, the ISO standard name is used.

updatedAt

Date

N/A

Read-only

The time the language resource was last updated.

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.

Languages errors

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

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

400

INVALID_REQUEST

None

Message: The service-specific message describing the violated lifecycle rule.

When and details

When: A POST /languages request sets default to true, sets enabled to true, omits locale, or supplies a locale whose environment.id does not match the environment ID in the path; a PUT /languages/{languageID} request changes locale or id, selects default=true while disabling the language, selects default=true for a language that is not enabled, selects default=true before agreement localization is complete when agreements are used for the environment, sets default=false for the current default language, or disables the current default language; or a DELETE /languages/{languageID} request deletes the current default language, a supplied (non-customer-added) language, or a language that is in use by one or more services

Details: None. Representative messages: The language to be created cannot be the default., The language to be created cannot have enabled=true., The locale attribute is required for creation., The environment id in locale does not match the environmentId in the path., The id of a language cannot be changed., The language code cannot be changed., You cannot disable a language and make it the default., You must enable the language before making it the default., The language must be enabled before it is set as the default., The localization of agreement-mgt for the language must be complete before making it the default., The default language cannot be disabled., You cannot reset the default language. You should select a new default language instead., The default language cannot be deleted., The supplied languages cannot be deleted., This language is in use by [<services>] and cannot be deleted.

400

INVALID_REQUEST

None

Message: The environment id <id> in request body does not match the environmentId <environmentID> in path. or The id <id> in request body does not match the id <languageID> in path.

When and details

When: A PUT request’s environment.id or id does not match the environment ID or language ID in the path

Details: None.

400

INVALID_REQUEST

None

Message: For an invalid locale, The language code is not one of the standard language codes; for an invalid name,

Invalid language name. The character set for a language name is alphanumeric characters, space, dot, dash and underscore.

for an unparseable path identifier, The request could not be completed. One or more validation errors were in the request.; otherwise (an unparseable request body) The request could not be completed. The request was malformed or invalid.

When and details

When: A POST or PUT request supplies a locale that is not a standard ISO language code, supplies a name whose characters are outside the allowed set, or 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.

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 /languages request supplies a locale for a language that already exists in the environment

Details: The detail target is locale and the message is the UNIQUENESS_VIOLATION default message, A resource with the specified name already exists.

403

ACCESS_FAILED

None

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

When and details

When: The actor lacks the langmgt:create:language permission (POST), the langmgt:read:language permission (GET operations), the langmgt:update:language permission (PUT), or the langmgt:delete:language permission (DELETE)

Details: None.

404

NOT_FOUND

None

Message: Unable to find language for environmentId=<environmentID> with id=<languageID>

When and details

When: GET /languages/{languageID}, PUT /languages/{languageID}, or DELETE /languages/{languageID} references a language that does not exist in the environment

Details: None.