--- title: Risk Evaluations description: 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. component: pingone-api page_id: pingone-api:protect:risk-evaluations canonical_url: https://developer.pingidentity.com/pingone-api/protect/risk-evaluations.html section_ids: assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service risk-evaluation-data-model: Risk evaluation data model event-data-model: Event data model details-data-model: Details data model update-risk-evaluation-data-model: Update Risk Evaluation data model risk-evaluations-events-generated: Risk evaluations events generated response-codes: Response codes providing-feedback-for-risk-evaluations: Providing feedback for risk evaluations risk-evaluation-feedback-data-model: Risk evaluation feedback data model --- # 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. ![Sample flow with risk evaluation](../_images/risk_flow_example.png) 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. ## Assigning admin roles and permissions to this service Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to [PingOne Permissions by Service](../platform/reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](../platform/reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](../platform/roles/predefined-roles.html#automatic-role-assignment). * [Group Role Assignments](../platform/group-role-assignments/group-role-assignments.html). * [User Role Assignments](../platform/users/user-role-assignments.html). Refer to [Roles Management](../platform/roles.html) for more information. ## Risk evaluation data model | 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). | ## Event data model These properties 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 | | ------------------------- | --------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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 | Whether the flow completed successfully. For the various flow types, `SUCCESS` and `FAILED` represents the following:- `AUTHENTICATION` * `SUCCESS`: authentication completed and a session or token is issued. * `FAILED`: authentication did not complete (invalid credentials, step-up failed, user cancelled or abandoned) - `ACCOUNT_RECOVERY` / `PASSWORD_RESET` * `SUCCESS`: account recovery or password reset successful (user verified or reset completed) * `FAILED`: recovery did not complete (verification failed or user abandoned) - `REGISTRATION` * `SUCCESS`: account created * `FAILED`: account creation failed or abandoned - `TRANSACTION` * `SUCCESS`: transaction approved or committed * `FAILED`: transaction declined, failed, or abandoned - `AUTHORIZATION` * `SUCCESS`: action permitted and performed * `FAILED`: action denied or not completed | | `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 transactionThe 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:- `AUTHENTICATION` - `ACCOUNT_RECOVERY`, `ACTIVE_SESSION`, `KERBEROS`, `NEO_CREDENTIALS`, `PASSKEY`, `PASSWORDLESS`, `USER_CERTIFICATION`, `USER_PASSWORD`, `USERNAME_RECOVERY` - `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 | Whether a device is likely used by a single individual, or shared among multiple users.Used to adjust risk interpretation and risk policy decisions. If not specified, risk engines may over-penalize normal behavior on shared devices, or under-estimate risk on private devices.Options include `UNSPECIFIED`, `SHARED`, and `PRIVATE`. | | `targetResource.id` | String | Optional | Mutable | The unique identifier representing the application, service, or resource the user is attempting to access or act upon.This identifier is used for policy targeting, analytics, and consistent risk evaluation. For PingOne integrations, this value corresponds to the PingOne application ID. For non-PingOne integrations, define this value and ensure it is unique within your environment. | | `targetResource.name` | String | Optional | Mutable | The name describing the target application or resource.This name is intended for display, logging, and explainability purposes. The name does not need to be unique, and may change over time without affecting policy behavior. | | `user.groups` | String\[] | Optional | Mutable | The list of groups the user belongs to, representing organizational, role-based, or business-level classifications associated with the user.Groups can be used as contextual signals for authorization, policy evaluation, risk assessment, and fraud detection. They allow decisions to be tailored based on the user's role, privileges, or segment within an organization. | | `user.groups.name` | String | Optional | Mutable | The name of a group associated with the user. Group names may represent roles, departments, access levels, or other organizational classifications. | | `user.id` | String | Optional | Mutable | A unique, persistent identifier for the user that remains constant across events and time. This ID enables identity correlation, historical analysis, and consistent risk evaluation.For `EXTERNAL` users, provide `user.id` and `user.name`. For `PING_ONE` users, provide `user.id` is available, and include `user.name` if it's meaningful (for example, email address). For AITM, include user.name when it represents the login identifier. | | `user.name` | String | Optional | Mutable | A human-readable identifier for the user, typically the username or login identifier (for example, an email address). | | `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 | | -------------------------------------------------------- | ------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 | | ------------------ | ------ | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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](/pingone/platform/v1/api/#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 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 | | ---------------------------------------------------- | ------ | --------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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](risk-evaluations/send_risk_evaluation_feedback.html). ```json { "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" } ] } ```