---
title: Risk evaluation feedback
description: Send feedback on PingOne Protect risk evaluations
component: pingone-api
page_id: pingone-api:protect:risk-evaluation-feedback/index
canonical_url: https://developer.pingidentity.com/pingone-api/protect/risk-evaluation-feedback/index.html
llms_txt: https://developer.pingidentity.com/pingone-api/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2026-11-05
section_ids:
  required-headers-for-requests: Required headers for requests
  risk-evaluation-feedback-data-model-v2: Risk evaluation feedback data model - v2
  risk-evaluation-feedback-data-model-v2-bulk-mode: Risk evaluation feedback data model - v2 - bulk mode
  risk-evaluation-feedback-data-model-v1-deprecated: Risk evaluation feedback data model - v1 (deprecated)
  sample-request-body-individual-feedback-item-using-v2: Sample request body - individual feedback item (using v2)
  sample-request-body-multiple-items-using-v2: Sample request body - multiple items (using v2)
---

# Risk evaluation feedback

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 single or multiple feedback objects, each consisting of:

* Information to help identify the risk evaluation, such as the risk evaluation ID

* An indication of what the evaluation should have been, for example, legitimate attempt or fraud

* Optional supplementary information, such as the confidence level of the assessment

You can send a request that includes a single feedback item or multiple feedback items (bulk mode). Examples of the request body to use for individual feedback items and multiple feedback items can be found at the end of this section.

In order to make it easier to submit feedback items, the [original data model](#risk-evaluation-feedback-data-model-v1-deprecated) has been deprecated. Use the [v2 data model](#risk-evaluation-feedback-data-model-v2) in the body of your requests. When sending feedback on multiple risk evaluations, use the structure described in the [bulk mode data model](#risk-evaluation-feedback-data-model-v2-bulk-mode).

When submitting a bulk request, you can include up to 20 feedback items in each request.

## Required headers for requests

With the introduction of risk evaluation feedback v2, the following required headers were added.

For sending feedback for a single risk evaluation, use this Content-Type header for your request:

`Content-Type: application/vnd.pingidentity.risk.feedback.v2+json`

For sending feedback for multiple risk evaluations (bulk mode), use this Content-Type header for your request:

`Content-Type: application/vnd.pingidentity.risk.feedback.bulk.v2+json`

## Risk evaluation feedback data model - v2

This table lists the objects and fields to use when submitting feedback for a risk evaluation. When submitting feedback for multiple risk evaluations (bulk mode), you use the same fields but the data for each risk evaluation is sent inside the `items` array, as described in [Risk evaluation feedback data model - v2 - bulk mode](#risk-evaluation-feedback-data-model-v2-bulk-mode).

| Property         | Type   | Required          | Mutable   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------- | ------ | ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `analyst`        | String | Optional          | Immutable | Identification of the analyst or system that provided the information for the feedback item such as name or email address. The value can be a maximum of 50 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `attributes`     | Object | Optional          | Immutable | A single-level JSON object that can be used to provide supplementary information using attribute names. For example:```json
"attributes": {
        "userPhoneNumber": "+1.5125551111"
}
```The object can contain a maximum of 20 keys. Keys can be a maximum length of 100 characters, and the corresponding values can be a maximum of 300 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `confidence`     | String | Optional          | Immutable | Level of confidence in the `verdict` that was submitted for the risk evaluation feedback. Can be any of the following values:- HIGH

- MEDIUM

- LOW                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `confirmedAt`    | String | Optional          | Immutable | Date and time when the fraud was confirmed, such as the date the chargeback was received or date when it was reviewed by an analyst. Format should be an RFC 3339 UTC timestamp (YYYY-MM-DDThh:mm:ss.SSSZ), such as 2026-06-29T10:30:00.000Z.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `createdAt`      | Date   | N/A               | Read-only | The time the resource was created.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `environment.id` | String | N/A               | Read-only | The ID of the PingOne environment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `flowType`       | String | Optional          | Immutable | The type of flow for which the risk evaluation was carried out. Can be one of the following values:- ACCESS

- AUTHENTICATION

- AUTHORIZATION

- REGISTRATION

- TRANSACTION                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `fraudType`      | String | Optional          | Immutable | If fraud was detected, you can use `fraudType` to describe the specific type of fraud, such as "new account fraud", "account takeover", or "credential stuffing". The value can be a maximum of 50 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `id`             | String | N/A               | Read-only | The unique ID assigned to the feedback submitted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `occurredFrom`   | Date   | Required          | Immutable | Use `occurredFrom` to specify the date and time when the risk evaluation was carried out. If you set `subject.type` to TIME_RANGE, use `occurredFrom` in conjunction with `occurredTo` to specify the time range in which the risk evaluation was carried out. Format should be an RFC 3339 UTC timestamp (YYYY-MM-DDThh:mm:ss.SSSZ), such as 2026-06-29T10:30:00.000Z.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `occurredTo`     | Date   | Required/Optional | Immutable | Use `occurredTo` in conjunction with `occurredFrom` to specify the time range in which the risk evaluation was carried out. Required when `subject.type` is set to TIME_RANGE. Format should be an RFC 3339 UTC timestamp (YYYY-MM-DDThh:mm:ss.SSSZ), such as 2026-06-29T10:45:00.000Z. The range can be a maximum of three days.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `reason`         | String | Optional          | Immutable | Free text explanation of the reasoning behind the `verdict` that was reported. Can be a maximum of 200 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `subject`        | Object | Required          | Immutable | Contains the information that will be used to identify the risk evaluation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `subject.type`   | String | Required          | Immutable | The type of information provided to identify the risk evaluation. Can be one of the following values:- RISK_EVALUATION_ID - the PingOne ID of the relevant risk evaluation

- EXTERNAL_TRANSACTION_ID - The PingOne API endpoints allow you to include an identifier generated by an application or system external to PingOne in your API requests by providing the ID in the `X-Ping-External-Transaction-Id` header, as described in [External transaction and session IDs](../../platform/reference/external-transaction-and-session-ids.html). If you take advantage of this feature and provide external IDs when creating risk evaluations, you can later provide this ID in a feedback request to identify the relevant risk evaluation. Set `subject.type` to EXTERNAL_TRANSACTION_ID, and then provide the external ID with `subject.value`.

- PINGONE_USER_ID - the user's PingOne ID

- EXTERNAL_USER_ID - unique identifier assigned to a user by an application or system external to PingOne

- IP_ADDRESS - the IP address used for the risk evaluation

- TIME_RANGE - time range during which the risk evaluation occurred |
| `subject.value`  | String | Required/Optional | Immutable | Used to provide the relevant value for the type of information specified with `subject.type`, such as the risk evaluation ID or the IP address used for the risk evaluation. Required except for cases where `subject.type` is set to TIME_RANGE. For time ranges, use `occurredFrom` and `occurredTo` to specify the range.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `trigger`        | String | Optional          | Immutable | The real-world event that led to the risk evaluation being analyzed. Can be one of the following values:- CHARGEBACK

- MANUAL_REVIEW

- CUSTOMER_COMPLAINT

- THIRD_PARTY_SIGNAL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `updatedAt`      | Date   | N/A               | Read-only | The time the resource was last updated.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `verdict`        | String | Required          | Immutable | The actual situation when the risk evaluation was carried out. Can be one of the following values:- FRAUD

- SUSPECTED_FRAUD

- LEGITIMATE                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

## Risk evaluation feedback data model - v2 - bulk mode

When submitting feedback for multiple risk evaluations, the structure of the data for each risk evaluation is similar to that when submitting feedback for a single evaluation (as described in [Risk evaluation feedback data model - v2](#risk-evaluation-feedback-data-model-v2)), however each such item is sent inside the `items` array, for example, `items[].verdict`.

| Property                   | Type    | Required | Mutable   | Description                                                                                                                                                                                                                                                                                                   |
| -------------------------- | ------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `errors`                   | Array   | N/A      | Read-only | Included in responses to requests that include multiple risk evaluation feedback items. Lists the feedback items that resulted in errors when processing the individual feedback items.                                                                                                                       |
| `errors[].$ref`            | String  | N/A      | Read-only | Points to the feedback item that resulted in an error, for example, `#/responses/1`. An explanation of what the problem actual was is returned in `responses[].body.message`.                                                                                                                                 |
| `failOnErrors`             | Integer | Optional | Immutable | When submitting multiple feedback items in a single request, include `failOnErrors` if you want processing to stop if a certain number of errors occur. For example, if you set this parameter to 2, PingOne will stop after a second error is encountered and will not process the remaining feedback items. |
| `items`                    | Array   | Required | Immutable | When submitting multiple risk evaluation feedback items in a single request, the `items` array contains each of the individual feedback objects. The `items` array can contain up to 20 feedback items.                                                                                                       |
| `responses`                | Array   | N/A      | Read-only | Included in responses to requests that include multiple risk evaluation feedback items. Contains information about each of the feedback items submitted.                                                                                                                                                      |
| `responses[].body`         | Object  | N/A      | Read-only | Contains information about each of the feedback items submitted. For items that resulted in an error, contains detailed information about what the problem was.                                                                                                                                               |
| `responses[].body.code`    | String  | N/A      | Read-only | For feedback items that resulted in an error, `code` contains an indication of what the problem was, for example, INVALID_DATA. The value may or may not be identical to the value of `responses[].status`.                                                                                                   |
| `responses[].body.details` | String  | N/A      | Read-only | For feedback items that resulted in an error, `details` contains additional details of what the problem was, beyond the text contained in `responses[].body.message`.                                                                                                                                         |
| `responses[].body.message` | String  | N/A      | Read-only | For feedback items that resulted in an error, `message` contains an explanation of what the problem was.                                                                                                                                                                                                      |
| `responses[].status`       | String  | N/A      | Read-only | The status returned for each of the feedback items submitted, such as SUCCESS or INVALID_DATA.                                                                                                                                                                                                                |
| `summary`                  | Object  | N/A      | Read-only | Included in responses to requests that include multiple risk evaluation feedback items. Contains a summary of the results, in terms of success and errors.                                                                                                                                                    |
| `summary.requested`        | Integer | N/A      | Read-only | The total number of feedback items submitted.                                                                                                                                                                                                                                                                 |
| `summary.errors`           | Integer | N/A      | Read-only | The number of feedback items that resulted in errors.                                                                                                                                                                                                                                                         |
| `summary.successful`       | Integer | N/A      | Read-only | The number of feedback items that were submitted successfully.                                                                                                                                                                                                                                                |
| `summary.skipped`          | Integer | N/A      | Read-only | The number of feedback items that were skipped because the number of errors specified with `failOnErrors` was reached.                                                                                                                                                                                        |

## Risk evaluation feedback data model - v1 (deprecated)

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

## Sample request body - individual feedback item (using v2)

```json
{
    "subject": {
        "type": "RISK_EVALUATION_ID",
        "value": "d1b638b4-638e-4c56-8fc6-872691c1bab1"
    },
    "verdict": "FRAUD",
    "trigger": "CHARGEBACK",
    "flowType": "TRANSACTION",
    "fraudType" : "account takeover",
    "occurredFrom": "2026-05-14T10:30:00.000Z",
    "confirmedAt": "2026-05-15T10:30:00.000Z",
    "reason": "An end user reported unauthorized pay transaction",
    "analyst": "analyst_1234@example.com",
    "confidence": "HIGH",
    "attributes": {
        "userPhoneNumber": "+1.5125551111"
    }
}
```

Full sample request for an individual feedback item can be found [here](send_risk_evaluation_feedback_v2_single.html).

## Sample request body - multiple items (using v2)

```json
{
    "failOnErrors": 1,
    "items": [
        {
            "subject": {
                "type": "RISK_EVALUATION_ID",
                "value": "d1b638b4-638e-4c56-8fc6-872691c1bab1"
            },
            "verdict": "FRAUD",
            "trigger": "CHARGEBACK",
            "flowType": "TRANSACTION",
            "fraudType" : "account takeover",
            "confirmedAt": "2026-05-15T10:30:00.000Z",
            "reason": "An end user reported unauthorized pay transaction",
            "analyst": "analyst_1234@example.com",
            "confidence": "HIGH",
            "attributes": {
                "userPhoneNumber": "+1.5125551111"
            }
        },
        {
            "subject": {
                "type": "RISK_EVALUATION_ID",
                "value": "d1b638b4-638e-4c56-8fc6-872691c1bab7"
            },
            "verdict": "LEGITIMATE",
            "trigger": "CUSTOMER_COMPLAINT",
            "flowType": "AUTHENTICATION",
            "confirmedAt": "2026-07-22T10:30:00.000Z",
            "reason": "Authentication failed for a legitimate user",
            "analyst": "analyst_1234@example.com",
            "confidence": "HIGH",
            "attributes": {
                "userPhoneNumber": "+1.5125551111"
            }
        }
    ]
}
```

Full sample request for multiple feedback items can be found [here](send_risk_evaluation_feedback_v2.html).
