Risk Evaluations

When you define authentication or other flows for your users, you can include risk evaluations at relevant points in the flow. The risk evaluation that is carried out is based on the risk policy that you specify for the evaluation. The following diagram shows a simplified sample flow that includes risk evaluation.

Note that the flow includes two distinct steps relating to risk evaluation.

The actual risk evaluation step should be added at a point in the flow where you would like to base the next action on the risk level calculated, for example, show an MFA prompt for medium or high-risk, but automatically grant access if the risk is deemed to be low.

After completion of the authentication steps, your flow should include a step to update the risk evaluation system with the results of the flow - was authentication completed successfully.

To ensure protection against fraudulent access attempts, it is essential that your flows include the SUCCESS/FAILED update step to indicate whether the flow was completed successfully or not. Many of the predictors used in risk policies are based on gradual learning of the characteristics of the access attempts made by your users, for example, where were they physically located and what operating system were they using. This learning process can only take place if your flows provide a clear indication which access attempts were made by legitimate users.

Risk evaluation data model

Property Type Required? Mutable? Description

Property	Type	Required?	Mutable?	Description
`createdAt`	Date	N/A	Read-only	The time the resource was created (format ISO-8061).
`details`	Object	Optional	Mutable	Contains additional information about the risk evaluation. Refer to the following [Details data model]{#details-data-model} table.
`environment.id`	String	Required	Immutable	The environment resource’s unique identifier.
`event`	Object	Required	Mutable	Contains the attributes identifying the event. For more information about event attributes, refer to the following [Event data model]{#event-data-model} table.
`id`	String	N/A	Read-only	The risk evaluation’s unique identifier.
`riskPolicySet.id`	String	Optional	Mutable	The risk policy set’s unique identifier. If this property and `riskPolicySet.name` are both specified, the policy set referenced by this property is used. If neither this property nor `riskPolicySet.name` are specified, the environment’s default risk policy set is used.
`riskPolicySet.name`	String	Optional	Mutable	The risk policy set associated with this name. If this property and `riskPolicySet.id` are both specified, the policy set referenced by `riskPolicySet.id` is used. If neither this property nor `riskPolicySet.id` are specified, the environment’s default risk policy set is used.
`riskPolicySet.targeted`	Boolean	Optional	Immutable	Set `riskPolicySet.targeted` to `true` if you want the risk evaluation to process the targeted policies defined in the environment rather than using a specific policy. The targeted policies are processed until a policy is found whose conditions (transaction type, user group, application) are met.
`result`	Object	N/A	Read-only	Contains the risk policy that evaluates as `true`. If there are several risk policies that evaluate as `true`, the highest priority risk policy is returned. If no risk policy evaluates as true, the `defaultResult` of the policy set is returned.
`result.level`	String	N/A	Read-only	The risk evaluation result level. Options are `HIGH`, `MEDIUM`, and `LOW`.
`result.recommendedAction`	String	N/A	Read-only	The recommended course of action based on the evaluation. Currently used only for policies that include a bot detection predictor, an Adversary-in-the-Middle (AitM) predictor, an email reputation predictor, or a traffic anomaly predictor. If `recommendedAction` is included in the response, the possible values are: * ACCOUNT_RECOVERY, meaning that there are indications that the user’s account may have been compromised so you should have them follow your account recovery procedure. * AITM_MITIGATION, meaning that you should take steps to mitigate the damage from an AitM attack. For an AitM attack, the user’s credentials have been intercepted, so in addition to blocking the access request, you should lock the user’s account until the password is changed. * BOT_MITIGATION, meaning that you should take steps to handle a scenario where a bot is involved. * DENY - returned when a risk level of HIGH is calculated for a traffic anomaly predictor. The recommendation is that you deny access because the suspicious activity is likely due to malicious behavior. * TEMP_EMAIL_MITIGATION, meaning that the user has specified a disposable email address, so you should probably block the registration attempt.
`result.type`	String	N/A	Read-only	The risk evaluation result type. Options are `VALUE`, indicating any custom attribute that’s defined.
`updatedAt`	Date	N/A	Read-only	The time the resource was last updated (format ISO-8061).

createdAt

Date

N/A

Read-only

The time the resource was created (format ISO-8061).

details

Object

Optional

Mutable

Contains additional information about the risk evaluation. Refer to the following [Details data model]{#details-data-model} table.

environment.id

String

Required

Immutable

The environment resource’s unique identifier.

event

Object

Required

Mutable

Contains the attributes identifying the event. For more information about event attributes, refer to the following [Event data model]{#event-data-model} table.

id

String

N/A

Read-only

The risk evaluation’s unique identifier.

riskPolicySet.id

String

Optional

Mutable

The risk policy set’s unique identifier. If this property and riskPolicySet.name are both specified, the policy set referenced by this property is used. If neither this property nor riskPolicySet.name are specified, the environment’s default risk policy set is used.

riskPolicySet.name

String

Optional

Mutable

The risk policy set associated with this name. If this property and riskPolicySet.id are both specified, the policy set referenced by riskPolicySet.id is used. If neither this property nor riskPolicySet.id are specified, the environment’s default risk policy set is used.

riskPolicySet.targeted

Boolean

Optional

Immutable

Set riskPolicySet.targeted to true if you want the risk evaluation to process the targeted policies defined in the environment rather than using a specific policy. The targeted policies are processed until a policy is found whose conditions (transaction type, user group, application) are met.

result

Object

N/A

Read-only

Contains the risk policy that evaluates as true. If there are several risk policies that evaluate as true, the highest priority risk policy is returned. If no risk policy evaluates as true, the defaultResult of the policy set is returned.

result.level

String

N/A

Read-only

The risk evaluation result level. Options are HIGH, MEDIUM, and LOW.

result.recommendedAction

String

N/A

Read-only

The recommended course of action based on the evaluation. Currently used only for policies that include a bot detection predictor, an Adversary-in-the-Middle (AitM) predictor, an email reputation predictor, or a traffic anomaly predictor. If recommendedAction is included in the response, the possible values are:

* ACCOUNT_RECOVERY, meaning that there are indications that the user’s account may have been compromised so you should have them follow your account recovery procedure.

* AITM_MITIGATION, meaning that you should take steps to mitigate the damage from an AitM attack. For an AitM attack, the user’s credentials have been intercepted, so in addition to blocking the access request, you should lock the user’s account until the password is changed.

* BOT_MITIGATION, meaning that you should take steps to handle a scenario where a bot is involved.

* DENY - returned when a risk level of HIGH is calculated for a traffic anomaly predictor. The recommendation is that you deny access because the suspicious activity is likely due to malicious behavior.

* TEMP_EMAIL_MITIGATION, meaning that the user has specified a disposable email address, so you should probably block the registration attempt.

result.type

String

N/A

Read-only

The risk evaluation result type. Options are VALUE, indicating any custom attribute that’s defined.

updatedAt

Date

N/A

Read-only

The time the resource was last updated (format ISO-8061).

Event data model

A POST request uses these properties to specify information about events processed for risk evaluation.

The ip, user.id, and user.type properties are required. All other properties are optional. However, the service requires either the targetResource.name or targetResource.id property and the browser.userAgent property to perform user risk behavior modeling.

Property Type Required? Mutable? Description

Property	Type	Required?	Mutable?	Description
`browser.cookie`	String	Optional	Mutable	To improve risk analysis, provide the value of a persistent cookie.
`browser.userAgent`	String	Optional	Mutable	The user agent string for the browser.
`completionStatus`	String	N/A	Read-only	The state of the evaluation transaction. In risk evaluation response, returned with a value of `IN_PROGRESS`.
`device`	Object	Optional	Mutable	Contains information about the device being used.
`device.externalId`	String	Optional	Mutable	If you want to maintain your own device IDs, you can send the device ID to the risk evaluation by using `device.externalId`, and this is the ID that will be used rather than the device ID provided by the Signals SDK. One situation where you may want to use this approach is if your mobile native app incorporates a WebView. In such cases, the mobile Signals SDK and the web Signals SDK will provide different device IDs. By providing your own device ID, you’ll have a consistent device ID that can be used.
`evaluatedFactors.status`	String	Optional	Mutable	The state of the transaction. Options are `FAILED`, `IN_PROGRESS`, and `SUCCESS`.
`evaluatedFactors.type`	String	Optional	Mutable	The transaction type.
`flow.type`	String	Optional	Mutable	The type of flow for which the risk evaluation is being carried out. Can take any of the following values: * `REGISTRATION` - initial registration of an account * `AUTHENTICATION` - standard authentication for login or actions such as password change * `ACCESS` - verification of whether user can access the relevant application, using tools such as PingAccess * `AUTHORIZATION` - verification of whether user is authorized to perform a specific action such as a profile change, using tools such as PingOne Authorize * `TRANSACTION` - authentication carried out in the context of a purchase or other monetary transaction The default value is `AUTHENTICATION`.
`flow.subtype`	String	Optional	Mutable	If you want to provide additional detail about the context of the flow, you can specify a subtype in addition to `type`. The values that can be used for `subtype` are: * For AUTHENTICATION - ACCOUNT_RECOVERY, ACTIVE_SESSION, KERBEROS, NEO_CREDENTIALS, PASSKEY, PASSWORDLESS, USER_CERTIFICATION, USER_PASSWORD, USERNAME_RECOVERY * For AUTHORIZATION - ADD_ADDRESS, ADD_MFA, ADD_PAYEE, ADD_PHONE_NUMBER, ADD_USER, CHANGE_PASSWORD, DELETE_MFA, DELETE_PAYEE, UPDATE_ADDRESS, UPDATE_PHONE_NUMBER
`ip`	String	Required	Mutable	The originating IP address of the authentication flow.
`origin`	String	Optional	Mutable	The calling service.
`sdk`	Object	Optional	Immutable	Object used to provide the data from the Signals (Protect) SDK.
`sdk.signals.data`	String	Optional	Immutable	The data collected by the Signals (Protect) SDK.
`session.id`	String	Optional	Mutable	The unique session ID associated with the event.
`sharingType`	String	Optional	Mutable	The device sharing type. Options are `UNSPECIFIED`, `SHARED`, and `PRIVATE`.
`targetResource.id`	String	Optional	Mutable	The ID of the target application.
`targetResource.name`	String	Optional	Mutable	The name of the target application.
`user.groups`	String[]	Optional	Mutable	The names of the groups in which the user is a member.
`user.groups.name`	String	Optional	Mutable	The name of the group associated with the user (maximum size: 1024 characters).
`user.id`	String	Required/Optional	Mutable	The ID of the user associated with the event (maximum size: 1024 characters). Required when `user.type` is set to `EXTERNAL`. When `user.type` is set to `PING_ONE`, you must provide either `user.id` or `user.name`.
`user.name`	String	Required/Optional	Mutable	The name of the user associated with the event (maximum size: 1024 characters). When `user.type` is set to `PING_ONE`, you must provide either `user.id` or `user.name`.
`user.type`	String	Required	Mutable	The type of user associated with the event. The possible values are `PING_ONE` and `EXTERNAL`.

browser.cookie

String

Optional

Mutable

To improve risk analysis, provide the value of a persistent cookie.

browser.userAgent

String

Optional

Mutable

The user agent string for the browser.

completionStatus

String

N/A

Read-only

The state of the evaluation transaction. In risk evaluation response, returned with a value of IN_PROGRESS.

device

Object

Optional

Mutable

Contains information about the device being used.

device.externalId

String

Optional

Mutable

If you want to maintain your own device IDs, you can send the device ID to the risk evaluation by using device.externalId, and this is the ID that will be used rather than the device ID provided by the Signals SDK. One situation where you may want to use this approach is if your mobile native app incorporates a WebView. In such cases, the mobile Signals SDK and the web Signals SDK will provide different device IDs. By providing your own device ID, you’ll have a consistent device ID that can be used.

evaluatedFactors.status

String

Optional

Mutable

The state of the transaction. Options are FAILED, IN_PROGRESS, and SUCCESS.

evaluatedFactors.type

String

Optional

Mutable

The transaction type.

flow.type

String

Optional

Mutable

The type of flow for which the risk evaluation is being carried out. Can take any of the following values:

* REGISTRATION - initial registration of an account

* AUTHENTICATION - standard authentication for login or actions such as password change

* ACCESS - verification of whether user can access the relevant application, using tools such as PingAccess

* AUTHORIZATION - verification of whether user is authorized to perform a specific action such as a profile change, using tools such as PingOne Authorize

* TRANSACTION - authentication carried out in the context of a purchase or other monetary transaction

The default value is AUTHENTICATION.

flow.subtype

String

Optional

Mutable

If you want to provide additional detail about the context of the flow, you can specify a subtype in addition to type. The values that can be used for subtype are:

* For AUTHENTICATION - ACCOUNT_RECOVERY, ACTIVE_SESSION, KERBEROS, NEO_CREDENTIALS, PASSKEY, PASSWORDLESS, USER_CERTIFICATION, USER_PASSWORD, USERNAME_RECOVERY

* For AUTHORIZATION - ADD_ADDRESS, ADD_MFA, ADD_PAYEE, ADD_PHONE_NUMBER, ADD_USER, CHANGE_PASSWORD, DELETE_MFA, DELETE_PAYEE, UPDATE_ADDRESS, UPDATE_PHONE_NUMBER

ip

String

Required

Mutable

The originating IP address of the authentication flow.

origin

String

Optional

Mutable

The calling service.

sdk

Object

Optional

Immutable

Object used to provide the data from the Signals (Protect) SDK.

sdk.signals.data

String

Optional

Immutable

The data collected by the Signals (Protect) SDK.

session.id

String

Optional

Mutable

The unique session ID associated with the event.

sharingType

String

Optional

Mutable

The device sharing type. Options are UNSPECIFIED, SHARED, and PRIVATE.

targetResource.id

String

Optional

Mutable

The ID of the target application.

targetResource.name

String

Optional

Mutable

The name of the target application.

user.groups

String[]

Optional

Mutable

The names of the groups in which the user is a member.

user.groups.name

String

Optional

Mutable

The name of the group associated with the user (maximum size: 1024 characters).

user.id

String

Required/Optional

Mutable

The ID of the user associated with the event (maximum size: 1024 characters). Required when user.type is set to EXTERNAL. When user.type is set to PING_ONE, you must provide either user.id or user.name.

user.name

String

Required/Optional

Mutable

The name of the user associated with the event (maximum size: 1024 characters). When user.type is set to PING_ONE, you must provide either user.id or user.name.

user.type

String

Required

Mutable

The type of user associated with the event. The possible values are PING_ONE and EXTERNAL.

Details data model

A POST request returns the following attributes in the details property for the specified event.

Property Type Required? Mutable? Description

Property	Type	Required?	Mutable?	Description
`anonymousNetworkDetected`	Boolean	N/A	Read-only	Indicates whether the current authentication originated from an anonymous network (for example, proxy or VPN).
`city`	String	N/A	Read-only	The city related to the current transaction from the IP address.
`country`	String	N/A	Read-only	The country related to the current transaction from the IP address.
`detected`	Object	N/A	Read-only	Relevant only for Bot Detection predictors and Suspicious Device predictors. Contains the information on the rule that led to the `level` reported.
`detected.rule.id`	Integer	N/A	Read-only	Relevant only for Bot Detection predictors and Suspicious Device predictors. ID number of the rule that led to the `level` reported.
`device`	Object	N/A	Read-only	Contains information about the device being used.
`device.agent`	Object	N/A	Read-only	For risk evaluations that include the PingID Device Trust predictor, contains the data from the trust agent.
`device.agent.customScript.exitCode`	Integer	N/A	Read-only	If a local script was specified when installing the Workforce Trust agent on individual computers, will contain the exit code for the script.
`device.agent.customScript.output`	String	N/A	Read-only	If a local script was specified when installing the Workforce Trust agent on individual computers, will contain the output of the script.
`device.agent.id`	String	N/A	Read-only	The ID generated by the agent to identify the user’s computer.
`device.agent.loggedInUser.domainName`	String	N/A	Read-only	The domain name for the logged-in user.
`device.agent.loggedInUser.name`	String	N/A	Read-only	The name of the logged-in user.
`device.agent.loggedInUser.objectSid`	String	N/A	Read-only	The SID (security identifier) for the logged-in user.
`device.agent.macAddress`	Array	N/A	Read-only	The MAC addresses of the user’s computer.
`device.agent.name`	String	N/A	Read-only	The name of the user’s computer.
`device.agent.os.name`	String	N/A	Read-only	The operating system on the user’s computer.
`device.agent.os.version`	String	N/A	Read-only	The version of the operating system on the user’s computer.
`device.agent.version`	String	N/A	Read-only	The version of the trust agent.
`device.estimatedDistance`	Double	N/A	Read-only	The distance between the current location of the device and the location of the device when the last risk evaluation was carried out. Distance is given in meters.
`device.externalId`	String	N/A	Read-only	The externally-maintained device ID that was provided in the risk evaluation request, if such an ID was included. For more details, refer to the Event data model.
`device.externalLastSeen`	Date	N/A	Read-only	If an externally-maintained device ID was provided in the risk evaluation request, `externalLastSeen` is the date and time that device was last seen. Returned only if the risk policy used for the evaluation includes the New Device predictor.
`device.id`	String	N/A	Read-only	The device ID provided by the Signals (Protect) SDK.
`device.lastSeen`	Date	N/A	Read-only	The date and time the device was last seen. Returned only if the risk policy used for the evaluation includes the New Device predictor.
`estimatedDistance`	Double	N/A	Read-only	The distance between the user’s current location and the user location when a risk evaluation was last updated with the completion status SUCCESS. Distance is given in meters.
`estimatedSpeed`	Integer	N/A	Read-only	The speed the user would have had to travel at to reach their current location, based on the distance from the location when a risk evaluation for the user was last updated with the completion status SUCCESS and the time elapsed since that update event. Speed is given in kilometers per hour.
`impossibleTravel`	Boolean	N/A	Read-only	Indicates whether the distance between the location of the user in their previous successful authentication and current authentication infers that the user had to travel at a speed greater than 1000 kilometers per hour. This condition is marked as fulfilled, only if: * Location data is available for the current and previous IP address of the user. * This is not the first transaction that the user has performed. * The user’s previous successful transaction was performed less than 24 hours ago. * The user moved a distance of at least 100 kilometers. Thus, even if the user moved very fast, but moved only a distance of 90 kilometers, the condition is not fulfilled. * The user moved at a speed greater than 1000 kilometers per hour. .
`ipAddressReputation.domain.asn`	Integer	N/A	Read-only	The autonomous system number.
`ipAddressReputation.domain.isp`	String	N/A	Read-only	The ISP that registered the domain.
`ipAddressReputation.domain.organization`	String	N/A	Read-only	The organization that owns the domain.
`ipAddressReputation.domain.sld`	String	N/A	Read-only	The second-level domain.
`ipAddressReputation.domain.tld`	String	N/A	Read-only	The top-level domain.
`ipAddressReputation.level`	String	N/A	Read-only	The risk level of the evaluated IP address. Options are `LOW`, `MEDIUM`, and `HIGH`. If the score is less than 55, the level is `LOW`; if the score is greater than 77, the level is `HIGH`; if the score is between 55 and 77, the level is `MEDIUM`. Note that these guidelines could change based on data analytics and product consideration. If the `ipAddressReputation.score` is unknown, `NULL` is returned.
`ipAddressReputation.score`	Integer	N/A	Read-only	Represents the calculated score of the IP address involved in the transaction. Scores range between 0 and 100. A score of 0 indicates a non-risky IP address; a score of 100 indicates a high-risk IP address. If the IP address reputation score is not available for the specific IP address, `NULL` is returned.
`previousSuccessfulTransaction.anonymousNetworkDetected`	Boolean	N/A	Read-only	Indicates whether an anonymous network was detected. Information is available twenty-four hours after the last successful transaction.
`previousSuccessfulTransaction.city`	String	N/A	Read-only	The city of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.
`previousSuccessfulTransaction.country`	String	N/A	Read-only	The country of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.
`previousSuccessfulTransaction.ip`	String	N/A	Read-only	The IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.
`previousSuccessfulTransaction.state`	String	N/A	Read-only	The state of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.
`previousSuccessfulTransaction.timestamp`	String	N/A	Read-only	The timestamp of the transaction. Information is available twenty-four hours after the last successful transaction.
`state`	String	N/A	Read-only	The state or province related to the current transaction from the IP address.
`{{predictorCompactName}}.level`	String	N/A	Read-only	The risk score calculated for the predictor-related transactions associated with the accessing device, and for the current authentication attempt. Options are `LOW`, `MEDIUM`, and `HIGH`.
`{{predictorCompactName}}.reason`	String	N/A	Read-only	The reason (or reasons) provided for the risk score classification (for example, the operating system or browser type used by the device, and country in which the accessing device is located). Each reason is classified as Unusual, to indicate how much it deviates from normal user behavior, and its effect in calculating the overall predictor risk score. Note that these messages may change in the future. If you want to take action based on a certain scenario, the action should be based on the value of `detected.rule.id`, which is constant.
`{{predictorCompactName}}.status`	String	N/A	Read-only	Additional information about the predictor evaluation outcome. Example responses are `NOT_AVAILABLE`, `IN_TRAINING_PERIOD`, or `FAILED_TO_COMPUTE`.
`{{predictorCompactName}}.type`	String	N/A	Read-only	The type of the predictor.

anonymousNetworkDetected

Boolean

N/A

Read-only

Indicates whether the current authentication originated from an anonymous network (for example, proxy or VPN).

city

String

N/A

Read-only

The city related to the current transaction from the IP address.

country

String

N/A

Read-only

The country related to the current transaction from the IP address.

detected

Object

N/A

Read-only

Relevant only for Bot Detection predictors and Suspicious Device predictors. Contains the information on the rule that led to the level reported.

detected.rule.id

Integer

N/A

Read-only

Relevant only for Bot Detection predictors and Suspicious Device predictors. ID number of the rule that led to the level reported.

device

Object

N/A

Read-only

Contains information about the device being used.

device.agent

Object

N/A

Read-only

For risk evaluations that include the PingID Device Trust predictor, contains the data from the trust agent.

device.agent.customScript.exitCode

Integer

N/A

Read-only

If a local script was specified when installing the Workforce Trust agent on individual computers, will contain the exit code for the script.

device.agent.customScript.output

String

N/A

Read-only

If a local script was specified when installing the Workforce Trust agent on individual computers, will contain the output of the script.

device.agent.id

String

N/A

Read-only

The ID generated by the agent to identify the user’s computer.

device.agent.loggedInUser.domainName

String

N/A

Read-only

The domain name for the logged-in user.

device.agent.loggedInUser.name

String

N/A

Read-only

The name of the logged-in user.

device.agent.loggedInUser.objectSid

String

N/A

Read-only

The SID (security identifier) for the logged-in user.

device.agent.macAddress

Array

N/A

Read-only

The MAC addresses of the user’s computer.

device.agent.name

String

N/A

Read-only

The name of the user’s computer.

device.agent.os.name

String

N/A

Read-only

The operating system on the user’s computer.

device.agent.os.version

String

N/A

Read-only

The version of the operating system on the user’s computer.

device.agent.version

String

N/A

Read-only

The version of the trust agent.

device.estimatedDistance

Double

N/A

Read-only

The distance between the current location of the device and the location of the device when the last risk evaluation was carried out. Distance is given in meters.

device.externalId

String

N/A

Read-only

The externally-maintained device ID that was provided in the risk evaluation request, if such an ID was included. For more details, refer to the Event data model.

device.externalLastSeen

Date

N/A

Read-only

If an externally-maintained device ID was provided in the risk evaluation request, externalLastSeen is the date and time that device was last seen. Returned only if the risk policy used for the evaluation includes the New Device predictor.

device.id

String

N/A

Read-only

The device ID provided by the Signals (Protect) SDK.

device.lastSeen

Date

N/A

Read-only

The date and time the device was last seen. Returned only if the risk policy used for the evaluation includes the New Device predictor.

estimatedDistance

Double

N/A

Read-only

The distance between the user’s current location and the user location when a risk evaluation was last updated with the completion status SUCCESS. Distance is given in meters.

estimatedSpeed

Integer

N/A

Read-only

The speed the user would have had to travel at to reach their current location, based on the distance from the location when a risk evaluation for the user was last updated with the completion status SUCCESS and the time elapsed since that update event. Speed is given in kilometers per hour.

impossibleTravel

Boolean

N/A

Read-only

Indicates whether the distance between the location of the user in their previous successful authentication and current authentication infers that the user had to travel at a speed greater than 1000 kilometers per hour. This condition is marked as fulfilled, only if:

* Location data is available for the current and previous IP address of the user.

* This is not the first transaction that the user has performed.

* The user’s previous successful transaction was performed less than 24 hours ago.

* The user moved a distance of at least 100 kilometers. Thus, even if the user moved very fast, but moved only a distance of 90 kilometers, the condition is not fulfilled.

* The user moved at a speed greater than 1000 kilometers per hour.

ipAddressReputation.domain.asn

Integer

N/A

Read-only

The autonomous system number.

ipAddressReputation.domain.isp

String

N/A

Read-only

The ISP that registered the domain.

ipAddressReputation.domain.organization

String

N/A

Read-only

The organization that owns the domain.

ipAddressReputation.domain.sld

String

N/A

Read-only

The second-level domain.

ipAddressReputation.domain.tld

String

N/A

Read-only

The top-level domain.

ipAddressReputation.level

String

N/A

Read-only

The risk level of the evaluated IP address. Options are LOW, MEDIUM, and HIGH. If the score is less than 55, the level is LOW; if the score is greater than 77, the level is HIGH; if the score is between 55 and 77, the level is MEDIUM. Note that these guidelines could change based on data analytics and product consideration. If the ipAddressReputation.score is unknown, NULL is returned.

ipAddressReputation.score

Integer

N/A

Read-only

Represents the calculated score of the IP address involved in the transaction. Scores range between 0 and 100. A score of 0 indicates a non-risky IP address; a score of 100 indicates a high-risk IP address. If the IP address reputation score is not available for the specific IP address, NULL is returned.

previousSuccessfulTransaction.anonymousNetworkDetected

Boolean

N/A

Read-only

Indicates whether an anonymous network was detected. Information is available twenty-four hours after the last successful transaction.

previousSuccessfulTransaction.city

String

N/A

Read-only

The city of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.

previousSuccessfulTransaction.country

String

N/A

Read-only

The country of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.

previousSuccessfulTransaction.ip

String

N/A

Read-only

The IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.

previousSuccessfulTransaction.state

String

N/A

Read-only

The state of the IP address involved in the transaction. Information is available twenty-four hours after the last successful transaction.

previousSuccessfulTransaction.timestamp

String

N/A

Read-only

The timestamp of the transaction. Information is available twenty-four hours after the last successful transaction.

state

String

N/A

Read-only

The state or province related to the current transaction from the IP address.

{{predictorCompactName}}.level

String

N/A

Read-only

The risk score calculated for the predictor-related transactions associated with the accessing device, and for the current authentication attempt. Options are LOW, MEDIUM, and HIGH.

{{predictorCompactName}}.reason

String

N/A

Read-only

The reason (or reasons) provided for the risk score classification (for example, the operating system or browser type used by the device, and country in which the accessing device is located). Each reason is classified as Unusual, to indicate how much it deviates from normal user behavior, and its effect in calculating the overall predictor risk score. Note that these messages may change in the future. If you want to take action based on a certain scenario, the action should be based on the value of detected.rule.id, which is constant.

{{predictorCompactName}}.status

String

N/A

Read-only

Additional information about the predictor evaluation outcome. Example responses are NOT_AVAILABLE, IN_TRAINING_PERIOD, or FAILED_TO_COMPUTE.

{{predictorCompactName}}.type

String

N/A

Read-only

The type of the predictor.

Update Risk Evaluation data model

Property Type Required? Mutable? Description

Property	Type	Required?	Mutable?	Description
`completionStatus`	String	Required	Immutable	If the flow was completed successfully, set to `SUCCESS`. If not, set to `FAILED`. The value of this property can be changed only if its current state is `IN_PROGRESS`.

completionStatus

String

Required

Immutable

If the flow was completed successfully, set to SUCCESS. If not, set to FAILED. The value of this property can be changed only if its current state is IN_PROGRESS.

Risk evaluations events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Code	Message
200	Successful operation.
201	Successfully created.
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.

Providing feedback for risk evaluations{#providing-feedback-for-risk-evaluations}

Use the riskFeedback endpoint to provide feedback on the accuracy of specific risk evaluations that were carried out. The request for providing feedback takes a list of feedback items, each consisting of the risk evaluation ID, a feedback category, and a reason for including it in that category (optional). In each such request, you can include feedback for up to 100 risk evaluations.

Risk evaluation feedback data model

Property Type Required? Mutable? Description

Property	Type	Required?	Mutable?	Description
`evaluationFeedbackItems`	Array	Required	Immutable	The collection of feedback items.
`evaluationFeedbackItems[].feedbackCategory`	String	Required	Immutable	One of the following categories of feedback: FALSE_HIGH_RISK, FRIENDLY_BOT, NEW_ACCOUNT_FRAUD, COMPROMISED_ACCOUNT, AUTOMATED_ATTACK.
`evaluationFeedbackItems[].reason`	String	Optional	Immutable	The reason that the specific feedback category was specified. The possible values depend upon the category chosen. * False high risk: OFFICE_NETWORK, COMPANY_VPN, WRONG_LOCATION, ORG_NETWORK, SUCCESSFUL_MFA, OTHER * Friendly bot: KNOWN_CRAWLER, KNOWN_AGGREGATOR, INTERNAL_AUTOMATION, OTHER * New account fraud: SUSPICIOUS_EMAIL_ADDRESS, USERNAME_GUESSING, OTHER * Compromised account: USER_CLAIMS_IT_IS_NOT_THEM, UNSUCCESSFUL_MFA, OTHER * Automated attack: CREDENTIAL_STUFFING, PASSWORD_SPRAY, OTHER
`evaluationFeedbackItems[].riskEvaluation.createdAt`	Date	Optional	Immutable	The date and time the risk evaluation was carried out. Use ISO-8061 format, for example, `2024-05-01T13:44:33.417Z`. This parameter is optional, but providing a value for it makes the feedback process more efficient.
`evaluationFeedbackItems[].riskEvaluation.id`	String	Required	Immutable	The ID of the risk evaluation.

evaluationFeedbackItems

Array

Required

Immutable

The collection of feedback items.

evaluationFeedbackItems[].feedbackCategory

String

Required

Immutable

One of the following categories of feedback: FALSE_HIGH_RISK, FRIENDLY_BOT, NEW_ACCOUNT_FRAUD, COMPROMISED_ACCOUNT, AUTOMATED_ATTACK.

evaluationFeedbackItems[].reason

String

Optional

Immutable

The reason that the specific feedback category was specified. The possible values depend upon the category chosen.

* False high risk: OFFICE_NETWORK, COMPANY_VPN, WRONG_LOCATION, ORG_NETWORK, SUCCESSFUL_MFA, OTHER

* Friendly bot: KNOWN_CRAWLER, KNOWN_AGGREGATOR, INTERNAL_AUTOMATION, OTHER

* New account fraud: SUSPICIOUS_EMAIL_ADDRESS, USERNAME_GUESSING, OTHER

* Compromised account: USER_CLAIMS_IT_IS_NOT_THEM, UNSUCCESSFUL_MFA, OTHER

* Automated attack: CREDENTIAL_STUFFING, PASSWORD_SPRAY, OTHER

evaluationFeedbackItems[].riskEvaluation.createdAt

Date

Optional

Immutable

The date and time the risk evaluation was carried out. Use ISO-8061 format, for example, 2024-05-01T13:44:33.417Z. This parameter is optional, but providing a value for it makes the feedback process more efficient.

evaluationFeedbackItems[].riskEvaluation.id

String

Required

Immutable

The ID of the risk evaluation.

Below is the sample body for a request that provides feedback on three risk evaluations. Full sample request can be found here.

{
  "evaluationFeedbackItems":[
    {
      "riskEvaluation": {
            "id": "15f1d245-33b3-4dba-849d-4df4b64b2d42"
       },
      "feedbackCategory": "FRIENDLY_BOT",
      "reason": "INTERNAL_AUTOMATION"
    },
    {
      "riskEvaluation": {
            "id": "d1b638b4-638e-4c56-8fc6-872691c1bab1"
       },
      "feedbackCategory": "FALSE_HIGH_RISK",
      "reason": "COMPANY_VPN"
    },
    {
      "riskEvaluation": {
            "id": "35f1d245-33b3-4dba-849d-4df4b64b2d45"
       },
      "feedbackCategory": "FALSE_HIGH_RISK"
    }
   ]
}

PingOne Platform APIs

Risk Evaluations

Risk evaluation data model

Event data model

Details data model

Update Risk Evaluation data model

Risk evaluations events generated

Response codes

Providing feedback for risk evaluations{#providing-feedback-for-risk-evaluations}

Risk evaluation feedback data model