A user resource is a unique identity within PingOne that interacts with the applications and services in the environment to which the user is assigned. The users service implements directory functions to create, read, update, delete, and search for user resources. Users are associated with an environment and a population.

You need the Identity Data Admin role to perform operations on users resources.

Users data model

Property Description
account.canAuthenticate A boolean that specifies the whether the user can authenticate. If the value is set to false, the account is locked or the user is disabled, and unless specified otherwise in administrative configuration, the user will be unable to authenticate.
account.lockedAt The time the specified user account was locked. This property might be absent if the account is unlocked or if the account was locked out automatically by failed password attempts.
account.secondsUntilUnlock An integer that specifies the number of seconds until the user’s account is unlocked. This property is absent if the account is unlocked, or if it will not automatically unlock (and must be unlocked by an administrator).
account.status A string that specifies the account locked state. Options are LOCKED and OK.
account.unlockAt The time the specified user account will be unlocked. This property is absent if the account is unlocked, or if it will not automatically unlock (and must be unlocked by an administrator).
address.countryCode A string that specifies the country name component. When specified, the value must be in ISO 3166-1 “alpha-2” code format [ISO3166]. For example, the country codes for the United States and Sweden are “US” and “SE”, respectively. Valid characters consist of two upper-case letters (regex: [A-Z]{2}).
address.locality A string that specifies the city or locality component of the address. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
address.postalCode A string that specifies the zip code or postal code component of the address. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 40 characters (min/max=1/40).
address.region A string that specifies the state or region component of the address. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
address.streetAddress A string that specifies the full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute may contain newlines (regex: ^[\p{L}\p{M}\p{N}\p{Zs}\p{P}\n\r]*$). It can have a length of no more than 256 characters (min/max=1/256).
createdAt The time the resource was created.
email A string that specifies the user’s email address, which must be provided and valid. For more information about email address formatting, see section 3.4 of RFC 2822, Internet Message Format.
enabled A read-only boolean attribute that specifies whether the user is enabled. This attribute is set to ‘true’ by default when the user is created.
environment.id A string that specifies the environment resource’s unique identifier associated with the user.
externalId A string that specifies an identifier for the user resource as defined by the provisioning client. This is optional. This may be explicitly set to null when updating a user to unset it. The externalId attribute simplifies the correlation of the user in PingOne with the user’s account in another system of record. The platform does not use this attribute directly in any way, but it is used by Ping Identity’s Data Sync product. It can have a length of no more than 1024 characters (min/max=1/1024).
id A string that specifies the user resource’s unique identifier.
identityProvider.id A mutable string that identifies the external identity provider used to authenticate the user. If not provided, PingOne is the identity provider. This attribute is required if the identity provider is authoritative for just-in-time user provisioning.
identityProvider.type A read-only string that identifies the type of identity provider used to authenticate the user. Possible values are FACEBOOK, GOOGLE, LINKEDIN, APPLE, TWITTER, AMAZON, YAHOO, MICROSOFT, PAYPAL, GITHUB, OPENID_CONNECT, SAML, and PING_ONE. The default value of PING_ONE is set when a value for identityProvider.id is not provided. The PING_ONE value is the default for all pre-existing users. There is currently no search filter support for this attribute.
lastSignOn.at The time of the last successful login of the user through the PingOne flow API.
lastSignOn.remoteIp The IP address of the last successful login of the user through the PingOne flow API.
lifecycle.status A string that specifies information about the account lifecycle. Options for status are ACCOUNT_OK and VERIFICATION_REQUIRED. This property value is only allowed to be set when importing a user to set the initial account status. If the initial status is set to VERIFICATION_REQUIRED and an email address is provided, a verification email is sent.
locale A string that specifies the user’s default location, which is optional. This may be explicitly set to null when updating a user to unset it. This is used for purposes of localizing such items as currency, date time format, or numerical representations. If provided, it must be a valid language tag as defined in RFC 5646. The following are example tags: fr, en-US, es-419, az-Arab, man-Nkoo-GN. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
memberOfGroupIDs A read-only array of IDs for the groups the user is a member of. This property is returned for GET /environments/{envID}/users/{userID} when include=memberOfGroupIDs is appended to the request. This property is not returned with a list of users.
memberOfGroupNames A read-only array of names for the groups the user is a member of. This property is returned for GET /environments/{envID}/users/{userID} when include=memberOfGroupNames is appended to the request. This property is not returned with a list of users.
mfaEnabled A boolean attribute that specifies whether multi-factor authentication is enabled. This attribute is set to false by default when the user is created. You can set mfaEnabled to true with POST CREATE User, POST CREATE User (Import), or PUT UPDATE User MFA Enabled. You cannot update mfaEnabled with PUT UPDATE User or PATCH UPDATE User.
mobilePhone A string that specifies the user’s native phone number, which is optional. This might also match the primaryPhone attribute. This may be explicitly set to null when updating a user to unset it. Valid phone numbers must have at least one number and a maximum character length of 32.
name.family A string that specifies the family name of the user, or Last in most Western languages (for example, ‘Jensen’ given the full name ‘Ms. Barbara J Jensen, III’). This may be explicitly set to null when updating a name to unset it. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen (regex: ^[\p{L}\p{M}\p{N}' .-]*$). It can have a length of no more than 256 characters (min/max=1/256).
name.formatted A string that specifies the fully formatted name of the user (for example ‘Ms. Barbara J Jensen, III’). This can be explicitly set to null when updating a name to unset it. Valid characters consist of any Unicode letter, mark (for example, accent, umlaut), space, dot, apostrophe, or hyphen (regex: ^[\p{L}\p{M}\p{N}' .-]*$). It can have a length of no more than 256 characters (min/max=1/256).
name.given A string that specifies the given name of the user, or First in most Western languages (for example, ‘Barbara’ given the full name ‘Ms. Barbara J Jensen, III’). This may be explicitly set to null when updating a name to unset it. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
name.honorificPrefix A string that specifies the honorific prefix(es) of the user, or title in most Western languages (for example, ‘Ms.’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it.
name.honorificSuffix A string that specifies the honorific suffix(es) of the user, or suffix in most Western languages (for example, ‘III’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it.
name.middle A string that specifies the the middle name(s) of the user (for exmple, ‘Jane’ given the full name ‘Ms. Barbara Jane Jensen, III’). This can be explicitly set to null when updating a name to unset it. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
nickname A string that specifies the user’s nickname, which is optional. This can be explicitly set to null when updating a user to unset it. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
password An object that specifies the user’s password. This property is never returned in the response.
password.value A string that specifies the user’s password value. The string is either in cleartext or pre-encoded format.
password.forceChange A boolean that specifies whether the user is forced to change the password on the next log in. If not provided, the property is set to false.
photo.href A string that specifies the URI that is a uniform resource locator (as defined in Section 1.1.3 of RFC 3986) that points to a resource location representing the user’s image. This can be removed from a user by setting the photo attribute to null. If provided, the resource must be a file (for example, a GIF, JPEG, or PNG image file) rather than a web page containing an image. It must be a valid URL that starts with the HTTP or HTTPS scheme.
population.id A string that specifies the identifier of the population resource associated with the user. This property cannot be updated using PUT {{apiPath}}/environments/{{envID}}/users/{{userID}}. However, it can be updated using PUT /environments/{{envID}}/users/{{userID}}/population.
preferredLanguage A string that specifies the user’s preferred written or spoken languages, which are optional. This may be explicitly set to null when updating a user to unset it. If provided, the format of the value must be a valid language range and the same as the HTTP Accept-Language header field (not including Accept-Language:) and is specified in Section 5.3.5 of RFC 7231. For example: en-US, en-gb;q=0.8, en;q=0.7.
primaryPhone A string that specifies the user’s primary phone number, which is optional. This might also match the mobilePhone attribute. This may be explicitly set to null when updating a user to unset it. Valid phone numbers must have at least one number and a maximum character length of 32.
timezone A string that specifies the user’s time zone, which is optional. This can be explicitly set to null when updating a user to unset it. If provided, it must conform with the IANA Time Zone database format [RFC6557], also known as the “Olson” time zone database format [Olson-TZ] for example, “America/Los_Angeles” (regex: ^\w+\/\w+$).
title A string that specifies the user’s title, which is optional, such as “Vice President”. This can be explicitly set to null when updating a user to unset it. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
type A string that specifies the user’s type, which is optional. This can be explicitly set to null when updating a user to unset it. This attribute is organization-specific and has no special meaning within the PingOne platform. It could have values of “Contractor”, “Employee”, “Intern”, “Temp”, “External”, and “Unknown”. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 256 characters (min/max=1/256).
updatedAt The time the resource was last updated.
username A string that specifies the user name, which must be provided and must be unique within an environment. The username must either be a well-formed email address or a string. The string can contain any letters, numbers, combining characters, math and currency symbols, dingbats and drawing characters, and invisible whitespace (regex: ^[\p{L}\p{M}\p{Zs}\p{S}\p{N}\p{P}]*$). It can have a length of no more than 128 characters (min/max=1/128).
verifyStatus Indicates whether ID verification can be done for the user. This value can be: NOT_INITIATED (the initial value), ENABLED, or DISABLED. If the user verification status is DISABLED, a new verification status cannot be created for that user until the status is changed to ENABLED.

User credentials data model

Property Description
applicationInstanceId The UUID for the user’s application instance registered with the Id Routing service. This enables the application to send messages to the service.
claimReference A serialized JSON string used to create a ClaimReference object, which is needed to revoke the issued user credential.
credentialId The UUID (primary key) of the user credential.
credentialTypeId The UUID of the credential type being issued.
environmentId The UUID of the environment associated with the user credentials.
expiryDate The date when this user credential expires. If this value is null, the user credential never expires.
userId The UUID of the user.
userMetadata A JSON string containing a map of the fields in the user credentials.

Limiting and Filtering data

You can limit the number of results returned on the READ All Users request with the limit parameter:

https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users?limit=1000

You can filter response data by applying a SCIM filtering expression to the READ All Users request. For large collections, a filtering expression appended to the query returns a targeted, more useful data set. For example, this URL-encoded SCIM filter returns up to 1000 members of the population with an ID of 60971d3b-cc5a-4601-9c44-2be541f91bf1:

https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/users?limit=1000 and filter=population.id eq "60971d3b-cc5a-4601-9c44-2be541f91bf1"

These SCIM operators can be applied to the following attributes:

These SCIM operators are not supported: ne (not equal), co (contains), ew (ends with), pr (present, is a non-empty or non-null value), gt (greater than), ge (greater than or equal to), lt (less than), le (less than or equal to), not (logical NOT).

You can also use custom user schema string attributes in a filtering expression to fine-tune the user response data. For more information about custom attributes, see Schemas. For more information about SCIM syntax and operators, see Conventions.

Expanding user population information

The GET /environments/{environmentId}/users and GET /environments/{environmentId}/users/{userId} endpoints allow an expand query parameter on the population embedded resource. A query that expands population returns information about a user’s associated population as an _embedded resource.

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.
404 The requested resource was not found.