User operations

The users endpoint provides operations to create, read, update, and delete users. It includes an import operation that gives privileged applications the ability to create a new user and set the user’s password as part of the user create operation. It also includes endpoints for user verification actions.

Users data model

User schema attribute names follow these case sensitivity rules:

Attribute names are case sensitive. Make sure that the name in your request matches the case defined in the user schema.
Any attribute in a request that does not match an existing user schema attribute is ignored. For example, if the request body contains Nickname instead of nickname or xyzzy when there is no xyzzy user schema attribute, both are ignored.
For safety, the user schema does not allow two attributes to be created in the same environment if the names differ only in case. For example, you cannot create both a Role and a role attribute.

Property Type Required? Mutable? Description

Property	Type	Required?	Mutable?	Description
`account.canAuthenticate`	Boolean	Required	Mutable	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`	Date	N/A	Read-only	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`	Integer	N/A	Read-only	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`	String	Required	Mutable	The account locked state. Options are `LOCKED` and `OK`.
`account.unlockAt`	Date	N/A	Read-only	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`	String	Optional	Mutable	The country name component. When specified, the value must be in ISO 3166-1 "alpha-2" code format. 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`	String	Optional	Mutable	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`	String	Optional	Mutable	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`	String	Optional	Mutable	The state, province, 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`	String	Optional	Mutable	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`).
`bypassMFAEnabledUntil`	Date	Required	Mutable	Used to define a period during which the user can bypass MFA. For details, refer to Allow MFA Bypass for User.
`canBypassMFA`	Boolean	N/A	Read-only	Indicates whether the user currently has permission to bypass MFA.
`createdAt`	Date	N/A	Read-only	The time the resource was created.
`email`	String	Required	Mutable	The user’s email address, which must be provided and valid. For more information about email address formatting, refer to section 3.4 of RFC 2822, Internet Message Format.
`emailVerified`	Boolean	Optional	Mutable	Whether the user’s email is verified, either as part of account verification (refer to `VERIFICATION_REQUIRED` in the `lifecycle.status` property), or as the result of a separate email verification process (refer to Verify Email (Code)).
`enabled`	Boolean	N/A	Read-only	Whether the user is enabled. This attribute is set to 'true' by default when the user is created.
`environment.id`	String	N/A	Read-only	The environment resource’s unique identifier associated with the user.
`externalId`	String	Optional	Mutable	An identifier for the user resource as defined by the provisioning client. 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`).
`groupMemberships.type`	String	Optional	Immutable	Whether the user is a member of a group through direct assignment or indirect filtering: `DIRECT` or `INDIRECT`.
`id`	String	N/A	Read-Only	The user resource’s unique identifier.
`identityProvider.id`	String	Required/Optional	Mutable	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`	String	N/A	Read-Only	Identifies the type of identity provider used to authenticate the user. Possible values are `FACEBOOK`, `GOOGLE`, `LINKEDIN_OIDC`, `LINKEDIN` (Deprecated), `OPENID_CONNECT`, `APPLE`, `AMAZON`, `TWITTER`, `YAHOO`, `PAYPAL`, `MICROSOFT`, `GITHUB`, `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.
`invite`	Object	N/A	Read-only	The invitation resource. Applicable only when a user record represents an invite.
`invite.expiresAt`	String	N/A	Read-only	Date value for when the invite expires.
`lastSignOn.at`	Date	N/A	Read-only	The time of the last successful login of the user through the PingOne flow API.
`lastSignOn.remoteIp`	String	N/A	Read-only	The IP address of the last successful login of the user through the PingOne flow API.
`lifecycle.status`	String	Optional	Mutable	The status of the account lifecycle. Options are `ACCOUNT_OK` and `VERIFICATION_REQUIRED`. This property can only be set when importing a user to set the initial account status. If omitted, the account status defaults to `ACCOUNT_OK`. When the initial status is set to `VERIFICATION_REQUIRED`, an email address is required and a verification email is sent to the email address provided. The verification code must be entered the first time the user tries to authenticate and does not expire when used for this purpose. As a result of using the verification code, the value transitions to `ACCOUNT_OK`. If the verification code is used within 24 hours, `emailVerified` was set to `false`, and the user’s email has not changed, `emailVerified` also transitions to true.
`lifecycle.suppressVerificationCode`	Boolean	Optional	Write-Only	Used when importing a user and the `lifecycle.status` is set to `VERIFICATION_REQUIRED`. If this property is set to `true`, no verification email is sent to the user. If this property is omitted or set to `false`, a verification email is sent to the user automatically.
`locale`	String	Optional	Mutable	The user’s default location. 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`).
`memberOfAdminGroup`	Array	Optional	Read-only	A list of groups with admin roles that include the user. Only returned when the `include=memberOfAdminGroup` query parameter is appended to the request URL.
`memberOfExternalGroups`	Object[]	Optional	Mutable	This is used only for Just In Time (JIT) creation of external groups.
`memberOfExternalGroups.name`	String	Required	Mutable	The name of the external group as it exists in the source.
`memberOfExternalGroups.sourceId`	String	Required	Mutable	The ID of the external group as it exists in the source (generally a UUID).
`memberOfExternalGroups.sourceType`	String	Required	Mutable	The type of the external group as it exists in the source. Currently, this can be only "GATEWAY" or "IDP".
`memberOfGroupIDs`	Array	Optional	Read-only	IDs for the groups the user is a member of. This property is returned for `GET {{apiPath}}/environments/{{envID}}/users/{{userID}}` when the `include=memberOfGroupIDs` query parameter is appended to the request. This property is not returned with a list of users.
`memberOfGroupNames`	Array	Optional	Read-only	Names for the groups the user is a member of. This property is returned for `GET {{apiPath}}/environments/{{envID}}/users/{{userID}}` when the `include=memberOfGroupNames` query parameter is appended to the request. This property is not returned with a list of users.
`mfaEnabled`	Boolean	Optional	Mutable	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`	String	Optional	Mutable	The user’s native phone number. 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`	String	Optional	Mutable	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`	String	Optional	Mutable	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`	String	Optional	Mutable	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`	String	Optional	Mutable	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`	String	Optional	Mutable	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`	String	Optional	Mutable	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`	String	Optional	Mutable	The user’s nickname. 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`).
`Operations`	Array	Optional	Mutable	A JSON array that specifies modifications to users schema attributes in a SCIM `PATCH` request. The `Operations` property is not valid in a regular PATCH request.
`Operations.op`	String	Optional	Mutable	The update operation type. Options are `add`, `replace`, and `remove`. The `Operations` property can have one or more `operations.op` attributes specified in the request body.
`Operations.path`	String	Optional	Mutable	The users schema attribute to be modified.
`Operations.value`	String	Optional	Mutable	The updated value for the users schema attribute that is modified.
`password`	Object	Optional	Immutable	An object that specifies the user’s password. This property is never returned in the response.
`password.forceChange`	Boolean	Optional	Mutable	Whether the user is forced to change the password on the next log in. If not provided, the property is set to `false`.
`password.value`	String	Optional	Immutable	The user’s password value. The string is either in cleartext or pre-encoded format.
`password.external`	Object	Optional	Immutable	Maps the information relevant to the user’s password, and its association to external directories.
`password.external.` `gateway`	Object	Optional	Mutable	Contains the gateway properties. When this is value is specified, the user’s password is managed in an external directory. You can set the user password using Create User (Import) or Update Password (Set).
`password.external.` `gateway.id`	String	Optional	Immutable	The UUID of the linked gateway that references the remote directory.
`password.external.` `gateway.type`	Enumeration	Optional	Mutable	Indicates one of the supported gateway types. For the supported types, refer to `type` in the Gateway base data model.
`password.external.` `gateway.userType`	String	Optional	Mutable	A reference to a `userType` in the list of `userTypes` values for an LDAP gateway.
`password.external.` `gateway.userType.id`	String	Optional	Immutable	The UUID of a user type in the list of `userTypes` for the LDAP gateway.
`password.external.` `gateway.correlationAttributes`	Object	Optional	Mutable	Maps the external LDAP directory attributes to PingOne attributes. PingOne uses the `correlationAttributes` values to read the attributes from the external LDAP directory and map them to the corresponding PingOne attributes.
`photo.href`	String	Optional	Mutable	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`	String	Optional	Immutable	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 {{apiPath}}/environments/{{envID}}/users/{{userID}}/population`.
`preferredLanguage`	String	Optional	Mutable	The user’s preferred written or spoken languages. 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`	String	Optional	Mutable	The user’s primary phone number. 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`	String	Optional	Mutable	The user’s time zone. 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 RFC 6557, also known as the "Olson" time zone database format Olson-TZ for example, "America/Los_Angeles" (regex: `^\w+\/\w+$`).
`title`	String	Optional	Mutable	The user’s title, 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`	String	Optional	Mutable	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`	Date	N/A	Read-only	The time the resource was last updated.
`username`	String	Required	Mutable*	The user name, which must be unique within an environment. This must either be a well-formed email address or another string. The string is case-insensitive, and 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}]$`). Any leading whitespace is ignored. The maximum length is 128 characters. Note: This property is immutable when PingID is part of the environment.
`verifyStatus`	String	Required	Mutable	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`.

account.canAuthenticate

Boolean

Required

Mutable

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

Date

N/A

Read-only

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

Integer

N/A

Read-only

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

String

Required

Mutable

The account locked state. Options are LOCKED and OK.

account.unlockAt

Date

N/A

Read-only

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

String

Optional

Mutable

The country name component. When specified, the value must be in ISO 3166-1 "alpha-2" code format. 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

String

Optional

Mutable

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

String

Optional

Mutable

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

String

Optional

Mutable

The state, province, 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

String

Optional

Mutable

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).

bypassMFAEnabledUntil

Date

Required

Mutable

Used to define a period during which the user can bypass MFA. For details, refer to Allow MFA Bypass for User.

canBypassMFA

Boolean

N/A

Read-only

Indicates whether the user currently has permission to bypass MFA.

createdAt

Date

N/A

Read-only

The time the resource was created.

email

String

Required

Mutable

The user’s email address, which must be provided and valid. For more information about email address formatting, refer to section 3.4 of RFC 2822, Internet Message Format.

emailVerified

Boolean

Optional

Mutable

Whether the user’s email is verified, either as part of account verification (refer to VERIFICATION_REQUIRED in the lifecycle.status property), or as the result of a separate email verification process (refer to Verify Email (Code)).

enabled

Boolean

N/A

Read-only

Whether the user is enabled. This attribute is set to 'true' by default when the user is created.

environment.id

String

N/A

Read-only

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

externalId

String

Optional

Mutable

An identifier for the user resource as defined by the provisioning client. 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).

groupMemberships.type

String

Optional

Immutable

Whether the user is a member of a group through direct assignment or indirect filtering: DIRECT or INDIRECT.

id

String

N/A

Read-Only

The user resource’s unique identifier.

identityProvider.id

String

Required/Optional

Mutable

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

String

N/A

Read-Only

Identifies the type of identity provider used to authenticate the user. Possible values are FACEBOOK, GOOGLE, LINKEDIN_OIDC, LINKEDIN (Deprecated), OPENID_CONNECT, APPLE, AMAZON, TWITTER, YAHOO, PAYPAL, MICROSOFT, GITHUB, 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.

invite

Object

N/A

Read-only

The invitation resource. Applicable only when a user record represents an invite.

invite.expiresAt

String

N/A

Read-only

Date value for when the invite expires.

lastSignOn.at

Date

N/A

Read-only

The time of the last successful login of the user through the PingOne flow API.

lastSignOn.remoteIp

String

N/A

Read-only

The IP address of the last successful login of the user through the PingOne flow API.

lifecycle.status

String

Optional

Mutable

The status of the account lifecycle. Options are ACCOUNT_OK and VERIFICATION_REQUIRED. This property can only be set when importing a user to set the initial account status. If omitted, the account status defaults to ACCOUNT_OK. When the initial status is set to VERIFICATION_REQUIRED, an email address is required and a verification email is sent to the email address provided. The verification code must be entered the first time the user tries to authenticate and does not expire when used for this purpose. As a result of using the verification code, the value transitions to ACCOUNT_OK. If the verification code is used within 24 hours, emailVerified was set to false, and the user’s email has not changed, emailVerified also transitions to true.

lifecycle.suppressVerificationCode

Boolean

Optional

Write-Only

Used when importing a user and the lifecycle.status is set to VERIFICATION_REQUIRED. If this property is set to true, no verification email is sent to the user. If this property is omitted or set to false, a verification email is sent to the user automatically.

locale

String

Optional

Mutable

The user’s default location. 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).

memberOfAdminGroup

Array

Optional

Read-only

A list of groups with admin roles that include the user. Only returned when the include=memberOfAdminGroup query parameter is appended to the request URL.

memberOfExternalGroups

Object[]

Optional

Mutable

This is used only for Just In Time (JIT) creation of external groups.

memberOfExternalGroups.name

String

Required

Mutable

The name of the external group as it exists in the source.

memberOfExternalGroups.sourceId

String

Required

Mutable

The ID of the external group as it exists in the source (generally a UUID).

memberOfExternalGroups.sourceType

String

Required

Mutable

The type of the external group as it exists in the source. Currently, this can be only "GATEWAY" or "IDP".

memberOfGroupIDs

Array

Optional

Read-only

IDs for the groups the user is a member of. This property is returned for GET {{apiPath}}/environments/{{envID}}/users/{{userID}} when the include=memberOfGroupIDs query parameter is appended to the request. This property is not returned with a list of users.

memberOfGroupNames

Array

Optional

Read-only

Names for the groups the user is a member of. This property is returned for GET {{apiPath}}/environments/{{envID}}/users/{{userID}} when the include=memberOfGroupNames query parameter is appended to the request. This property is not returned with a list of users.

mfaEnabled

Boolean

Optional

Mutable

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

String

Optional

Mutable

The user’s native phone number. 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

String

Optional

Mutable

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

String

Optional

Mutable

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

String

Optional

Mutable

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

String

Optional

Mutable

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

String

Optional

Mutable

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

String

Optional

Mutable

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

String

Optional

Mutable

The user’s nickname. 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).

Operations

Array

Optional

Mutable

A JSON array that specifies modifications to users schema attributes in a SCIM PATCH request. The Operations property is not valid in a regular PATCH request.

Operations.op

String

Optional

Mutable

The update operation type. Options are add, replace, and remove. The Operations property can have one or more operations.op attributes specified in the request body.

Operations.path

String

Optional

Mutable

The users schema attribute to be modified.

Operations.value

String

Optional

Mutable

The updated value for the users schema attribute that is modified.

password

Object

Optional

Immutable

An object that specifies the user’s password. This property is never returned in the response.

password.forceChange

Boolean

Optional

Mutable

Whether the user is forced to change the password on the next log in. If not provided, the property is set to false.

password.value

String

Optional

Immutable

The user’s password value. The string is either in cleartext or pre-encoded format.

password.external

Object

Optional

Immutable

Maps the information relevant to the user’s password, and its association to external directories.

password.external.
gateway

Object

Optional

Mutable

Contains the gateway properties. When this is value is specified, the user’s password is managed in an external directory. You can set the user password using Create User (Import) or Update Password (Set).

password.external.
gateway.id

String

Optional

Immutable

The UUID of the linked gateway that references the remote directory.

password.external.
gateway.type

Enumeration

Optional

Mutable

Indicates one of the supported gateway types. For the supported types, refer to type in the Gateway base data model.

password.external.
gateway.userType

String

Optional

Mutable

A reference to a userType in the list of userTypes values for an LDAP gateway.

password.external.
gateway.userType.id

String

Optional

Immutable

The UUID of a user type in the list of userTypes for the LDAP gateway.

password.external.
gateway.correlationAttributes

Object

Optional

Mutable

Maps the external LDAP directory attributes to PingOne attributes. PingOne uses the correlationAttributes values to read the attributes from the external LDAP directory and map them to the corresponding PingOne attributes.

photo.href

String

Optional

Mutable

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

String

Optional

Immutable

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 {{apiPath}}/environments/{{envID}}/users/{{userID}}/population.

preferredLanguage

String

Optional

Mutable

The user’s preferred written or spoken languages. 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

String

Optional

Mutable

The user’s primary phone number. 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

String

Optional

Mutable

The user’s time zone. 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 RFC 6557, also known as the "Olson" time zone database format Olson-TZ for example, "America/Los_Angeles" (regex: ^\w+\/\w+$).

title

String

Optional

Mutable

The user’s title, 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

String

Optional

Mutable

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

Date

N/A

Read-only

The time the resource was last updated.

username

String

Required

Mutable*

The user name, which must be unique within an environment. This must either be a well-formed email address or another string. The string is case-insensitive, and 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}]*$). Any leading whitespace is ignored. The maximum length is 128 characters. *Note: This property is immutable when PingID is part of the environment.

verifyStatus

String

Required

Mutable

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.

Limiting and Filtering data

You can limit the number of results returned on the Read User or Users request with the limit parameter:

https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users?limit=200

Refer to Pagination for more information about use of the limit parameter, as well as other methods of controlling pagination.

You can filter response data by applying a SCIM filtering expression to the Read User or 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 200 members of the population with an ID of 60971d3b-cc5a-4601-9c44-2be541f91bf1:

https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/users?limit=200&filter=population.id eq "60971d3b-cc5a-4601-9c44-2be541f91bf1"

The page size in the /environments/{{envID}}/users endpoint response may be smaller than the requested limit. When determining the number of records returned per page, use the page size in the response rather than the requested limit.

SCIM operators

These SCIM operators can be applied to the following attributes:

eq (equals)

Supported attributes: accountId, address.streetAddress, address.locality, address.region, address.postalCode, address.countryCode, email, enabled, endDate, externalId, locale, mobilePhone, name.formatted, name.given, name.middle, name.family, name.honorificPrefix, name.honorificSuffix, nickname, population.id, photo.href, preferredLanguage, primaryPhone, startDate, timezone, title, type, username, and custom attributes of type STRING
sw (starts with)

Supported attributes: accountId, address.streetAddress, address.locality, address.region, address.postalCode, address.countryCode, email, enabled, externalId, locale, mobilePhone, name.formatted, name.given, name.middle, name.family, name.honorificPrefix, name.honorificSuffix, nickname, photo.href, preferredLanguage, primaryPhone, timezone, title, type, username, and custom attributes of type STRING
ew (ends with)

Supported attributes: name.given, name.family, email (only for the domain specified in the address, starting with and including the symbol "@", such as "@example.com").
and (logical AND)

Logical AND for building compound expressions in which both expressions are true.
or (logical OR)

Logical OR for building compound expressions if either expression is true.
co (contains)

Supported attributes: name.given, name.family.

These SCIM operators are not supported: ne (not equal), 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). The API does not support empty strings in a sw filtering expression. If empty strings are submitted in the request, the response returns a 400 FAILED_REQUEST with an INVALID_FILTER detail error.

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, refer to Schemas. For more information about SCIM syntax and operators, refer to Conventions.

To filter user results for group membership or linked accounts, refer to GET Read User or Users. For more information on groups, refer to Groups. For more information on linked accounts, refer to Linked Accounts.

Expanding user population information

The GET {{apiPath}}/environments/{{envID}}/users and GET {{apiPath}}/environments/{{envID}}/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.

Users events generated

Refer to Audit Reporting Events for the events generated.

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.

PingOne Platform APIs

User operations

Users data model

Limiting and Filtering data

SCIM operators

Expanding user population information

Users events generated

Response codes