PingOne Platform APIs

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

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:

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

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