# Retrieve Rating-based Alerts
source: https://developer.mastercard.com/riskrecon-api/documentation/use-cases/risk-mgmt-issue-rmdfn/alerting/rate-based-alerting/index.md

## Overview {#overview}

Rating-based alerts provide the score change summaries for all the vendors you have access to, whose overall score level or security domain level rating scores have changed. Rating-based alerts are based on your alert settings or policies and are user specific.

### Filter parameters {#filter-parameters}

RiskRecon recommends using filtering capabilities to limit the amount of data that comes back in the response by using [pagination parameters](https://developer.mastercard.com/riskrecon-api/documentation/use-cases/index.md#pagination-metadata) and the following query parameters in the API request:

* **Start date** and **End date**: You can search for alerting issues for a particular date range within a period of one month.
* **Alert types** : You can use the `alert_types` array parameter to search for alerts as per their score type, such as rating_improved, low_threshold, high_threshold, and rating_dropped.

### Configure to rating-based alerts {#configure-to-rating-based-alerts}

To retrieve rating-based alerts, you must configure the rating-based alert policy from the **Alert Settings** tab in the **Alerts** section of the **RiskRecon web portal** by setting the following thresholds:

* **Overall Rating Policy** - This subscribes the user to receive alerts when the overall RiskRecon rating changes for a TOE.

* **Security Domain Policy** - This subscribes the user to receive alerts when the security domain ratings change for a TOE. The user can also configure granular alerting for each of the 9 security domains that RiskRecon measures.

Here is a pictorial representation of the filter parameters and rating-based alerts configuration.

![](https://static.developer.mastercard.com/content/riskrecon-api/uploads/rating_alerts_settings.png)

### Retrieve rating-based alerts {#retrieve-rating-based-alerts}

Once you have configured your rating-based alert policies, you can use the `GET Alerting Rating Changes` endpoint to fetch any rating or score changes from new scans of your portfolio. The rating-based alerts retrieved by this endpoint are as per your alert settings.

The following are the steps necessary to retrieve rating-based alerts:

1. [Set rating-based alert policies](https://developer.mastercard.com/riskrecon-api/documentation/use-cases/risk-mgmt-issue-rmdfn/alerting/rate-based-alerting/index.md#set-rating-based-alert-policies)
2. [Retrieve rating-based alerts](https://developer.mastercard.com/riskrecon-api/documentation/use-cases/risk-mgmt-issue-rmdfn/alerting/rate-based-alerting/index.md#retrieve-rating-based-alerts)

## Set rating-based alert policy {#set-rating-based-alert-policy}

### Sequence Diagram {#sequence-diagram}

The following sequence diagram shows how to set a rating-based alert policy:
Diagram set-rate-based-alerts1

### Execution Steps {#execution-steps}

The following steps describe how to set a rating-based alert policy:

1. The user navigates to the **Alerts** page to set the portal rating-based alert policy from the **Rating Based Alerting** section in the **Alert Settings** tab.
2. The web portal processes the overall rating and security domain rating alert policies.
3. RiskRecon saves the overall rating policy and security domain rating alert policies.

## Retrieve rating-based alerts {#retrieve-rating-based-alerts-1}

### Sequence Diagram {#sequence-diagram-1}

The following diagram shows how to retrieve rating-based alerts:
Diagram receive-rating-alerts

### Execution Steps {#execution-steps-1}

The following steps describe a sample integration flow to retrieve rating-based alerts:

1. The user sends the `GET` request to RiskRecon to receive the rating-based alerts.
2. RiskRecon provides the rating-based score summary changes to the user.

## Sample Request and Response {#sample-request-and-response}

For a sample response for this use case, visit [Get rating-based alert](https://developer.mastercard.com/riskrecon-api/documentation/testing/alerting-samples/rcv-rtng-alrts-smpl/index.md).

## Use Case Examples {#use-case-examples}

The use cases in this section discuss how you can use the `GET Alerting Rating Changes` endpoint to retrieve the latest overall and security domain rating changes as new analyses are published within your portfolio. All these use cases use the `alert_types` attribute in the parameter. This attribute can be used to filter rating alerts based on the different rating alert settings configured in the portal.

* [Retrieve vendors with change in score in Application Security](https://developer.mastercard.com/riskrecon-api/documentation/use-cases/risk-mgmt-issue-rmdfn/alerting/rate-based-alerting/index.md#retrieve-vendors-with-a-decrease-in-score-in-application-security)
* [Retrieve vendors with a decrease in overall score](https://developer.mastercard.com/riskrecon-api/documentation/use-cases/risk-mgmt-issue-rmdfn/alerting/rate-based-alerting/index.md#retrieve-vendors-with-a-decrease-in-overall-score)
* [Retrieve vendors with a Web Encryption score that fell below the High or Low Threshold mark](https://developer.mastercard.com/riskrecon-api/documentation/use-cases/risk-mgmt-issue-rmdfn/alerting/rate-based-alerting/index.md#retrieve-vendors-with-a-web-encryption-score-that-fell-below-the-high-or-low-threshold-mark)

### Retrieve vendors with a decrease in score in Application Security {#retrieve-vendors-with-a-decrease-in-score-in-application-security}

The use cases here discusses how the rating alerts can be used to notify the customer about the increase or decrease in the application security score of a vendor.

### Retrieve vendors with a decrease in overall score {#retrieve-vendors-with-a-decrease-in-overall-score}

The use cases here discusses how the rating alerts can be used to notify the customer about the fall of the overall score of the vendors in their portfolio.

### Retrieve vendors with a Web Encryption score that fell below the High or Low Threshold mark {#retrieve-vendors-with-a-web-encryption-score-that-fell-below-the-high-or-low-threshold-mark}

The use cases here discusses how the rating alerts API can be used to notify the customer about the fall of the Web Encryption score below the low or high threshold mark. For example, a fall in the web encryption score could indicate increase in web encryption issues like expired certificates, invalid certificate subjects, or use of insecure encryption protocols.

## Endpoint {#endpoint}


API Reference: `GET /v1/alerting/rating_changes`