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 has been deprecated. Use the v2 data model in the body of your requests. When sending feedback on multiple risk evaluations, use the structure described in the bulk mode data model.
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.
| Property | Type | Required | Mutable | Description |
|---|---|---|---|---|
|
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. |
|
Object |
Optional |
Immutable |
A single-level JSON object that can be used to provide supplementary information using attribute names. For example:
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. |
|
String |
Optional |
Immutable |
Level of confidence in the
|
|
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. |
|
Date |
N/A |
Read-only |
The time the resource was created. |
|
String |
N/A |
Read-only |
The ID of the PingOne environment. |
|
String |
Optional |
Immutable |
The type of flow for which the risk evaluation was carried out. Can be one of the following values:
|
|
String |
Optional |
Immutable |
If fraud was detected, you can use |
|
String |
N/A |
Read-only |
The unique ID assigned to the feedback submitted. |
|
Date |
Required |
Immutable |
Use |
|
Date |
Required/Optional |
Immutable |
Use |
|
String |
Optional |
Immutable |
Free text explanation of the reasoning behind the |
|
Object |
Required |
Immutable |
Contains the information that will be used to identify the risk evaluation. |
|
String |
Required |
Immutable |
The type of information provided to identify the risk evaluation. Can be one of the following values:
|
|
String |
Required/Optional |
Immutable |
Used to provide the relevant value for the type of information specified with |
|
String |
Optional |
Immutable |
The real-world event that led to the risk evaluation being analyzed. Can be one of the following values:
|
|
Date |
N/A |
Read-only |
The time the resource was last updated. |
|
String |
Required |
Immutable |
The actual situation when the risk evaluation was carried out. Can be one of the following values:
|
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), however each such item is sent inside the items array, for example, items[].verdict.
| Property | Type | Required | Mutable | Description |
|---|---|---|---|---|
|
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. |
|
String |
N/A |
Read-only |
Points to the feedback item that resulted in an error, for example, |
|
Integer |
Optional |
Immutable |
When submitting multiple feedback items in a single request, include |
|
Array |
Required |
Immutable |
When submitting multiple risk evaluation feedback items in a single request, the |
|
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. |
|
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. |
|
String |
N/A |
Read-only |
For feedback items that resulted in an error, |
|
String |
N/A |
Read-only |
For feedback items that resulted in an error, |
|
String |
N/A |
Read-only |
For feedback items that resulted in an error, |
|
String |
N/A |
Read-only |
The status returned for each of the feedback items submitted, such as SUCCESS or INVALID_DATA. |
|
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. |
|
Integer |
N/A |
Read-only |
The total number of feedback items submitted. |
|
Integer |
N/A |
Read-only |
The number of feedback items that resulted in errors. |
|
Integer |
N/A |
Read-only |
The number of feedback items that were submitted successfully. |
|
Integer |
N/A |
Read-only |
The number of feedback items that were skipped because the number of errors specified with |
Risk evaluation feedback data model - v1 (deprecated)
| Property | Type | Required | Mutable | Description |
|---|---|---|---|---|
|
Array |
Required |
Immutable |
The collection of feedback items. |
|
String |
Required |
Immutable |
One of the following categories of feedback: |
|
String |
Optional |
Immutable |
The reason that the specific feedback category was specified. The possible values depend upon the category chosen.
|
|
Date |
Optional |
Immutable |
The date and time the risk evaluation was carried out. Use ISO-8061 format, for example, |
|
String |
Required |
Immutable |
The ID of the risk evaluation. |
Sample request body - individual feedback item (using v2)
{
"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.
Sample request body - multiple items (using v2)
{
"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.