Amazon Fraud Detector is no longer open to new customers as of November 7, 2025. For capabilities similar to Amazon Fraud Detector, explore Amazon SageMaker, AutoGluon, and AWS WAF. # Fraud predictions You can use Amazon Fraud Detector to get fraud predictions for single event in real time or get fraud predictions offline for a set of events. To generate fraud predictions for either a single event or a set of events, you will need to provide Amazon Fraud Detector with the following information: + Fraud prediction logic + Event metadata **Fraud detection logic** Fraud prediction logic uses one or more rules to evaluate data associated with an event and then provides result and a fraud prediction score. You create your fraud prediction logic using the following components: + Event types - Defines structure of the event + Models - Defines algorithm and data requirements for predicting fraud + Variables - Represents a data element associated with the event + Rules - Tells Amazon Fraud Detector how to interpret the variable values during fraud prediction + Outcomes - Results generated from a fraud prediction + Detector version - Contains fraud prediction logic for a particular event For more information about the components used to create fraud detection logic, see [Amazon Fraud Detector concepts](https://docs.aws.amazon.com/frauddetector/latest/ug/frauddetector-ml-concepts.html). Before you start generating fraud predictions, make sure you have created and published the detector version that contains your fraud prediction logic. You can create and publish detector version using the Fraud Detector Console or API. For instructions on using the console, see [Get started (console)](https://docs.aws.amazon.com/frauddetector/latest/ug/get-started.html). For instructions on using the API, see [Create a detector version](https://docs.aws.amazon.com/frauddetector/latest/ug/create-a-detector-version.html). **Event metadata** Event metadata provides details of the event being evaluated. Each event you want to evaluate must include value for each variable in the event type associated with your detector version. In addition, your event metadata must include the following: + EVENT\$1ID – An identifier for the event. For example, if your event is an online transaction the EVENT\$1ID might be the transaction reference number provided to your customer. **Important notes about EVENT\$1ID** + Must be unique for that event + Should represent information that is meaningful to your business + Must satisy the regular expression pattern : `^[0-9a-z_-]+$.` + Must be saved. EVENT\$1ID is the reference for the event and is used to perform operations on the event such as deleting the event. + Appending timestamp to the EVENT\$1ID is not recommended as it might cause issues when later you want to update the event, since you will need to provide the exact same EVENT\$1ID. + ENTITY\$1TYPE – The entity that performs the event, such as a merchant or a customer. + ENTITY\$1ID - An identifier for the entity performing the event. The ENTITY\$1ID must satisfy the following regular expression pattern: `^[0-9a-z_-]+$`. If the ENTITY\$1ID is not available at the time of evaluation, pass the string unknown. + EVENT\$1TIMESTAMP - The timestamp when the event occurred. The timestamp must be in ISO 8601 standard in UTC. # Real time prediction You can evaluate online activities for fraud in real time by calling `GetEventPrediction` API. You provide information about a single event in each request and synchronously receive a model score and an outcome based on the fraud prediction logic associated with the specified detector. ## How real time fraud prediction works The `GetEventPrediction` API uses a specified detector version to evaluate the event metadata provided for the event. During the evaluation, Amazon Fraud Detector first generates model scores for models that are added to the detector version, then passes the results to the rules for evaluation. The rules are executed as specified by the rule execution mode (see [Create a detector version](https://docs.aws.amazon.com/frauddetector/latest/ug/create-a-detector-version.html)). As part of the response, Amazon Fraud Detector provides model scores as well as any outcomes associated to the matched rules. ## Getting real time fraud prediction To get real time fraud predictions, make sure you have created and published a detector that contains your fraud prediction model and rules, or simply a ruleset. You can get fraud prediction for an event in real time by calling the [GetEventPrediction](https://docs.aws.amazon.com/frauddetector/latest/api/API_GetEventPrediction.html) API operation using the AWS Command Line Interface (AWS CLI) or one of the Amazon Fraud Detector SDKs. To use the API, supply information of a single event with each request. As part of the request you must specify `detectorId` that Amazon Fraud Detector will use to evaluate the event. You can optionally specify a `detectorVersionId`. If a `detectorVersionId` is not specified, Amazon Fraud Detector will use the `ACTIVE ` version of the detector. You can optionally send data to invoke an SageMaker AI model by passing the data in the field `externalModelEndpointBlobs`. ### Get a fraud prediction using the AWS SDK for Python (Boto3) To generate a fraud prediction, call the `GetEventPrediction` API. The example below assumes you have completed [Part B: Generate fraud predictions](part-b.md). As part of the response, you will receive a model score as well as any matched rules and corresponding outcomes. You can find additional examples of `GetEventPrediction` requests on the [aws-fraud-detector-samples GitHub repository](https://github.com/aws-samples/aws-fraud-detector-samples). ``` import boto3 fraudDetector = boto3.client('frauddetector') fraudDetector.get_event_prediction( detectorId = 'sample_detector', eventId = '802454d3-f7d8-482d-97e8-c4b6db9a0428', eventTypeName = 'sample_registration', eventTimestamp = '2020-07-13T23:18:21Z', entities = [{'entityType':'sample_customer', 'entityId':'12345'}], eventVariables = { 'email_address' : 'johndoe@exampledomain.com', 'ip_address' : '1.2.3.4' } ) ``` # Batch predictions You can use a *batch predictions* job in Amazon Fraud Detector to get predictions for a set of events that do not require real-time scoring. For example, you could create a batch predictions job to perform an offline proof-of-concept, or to retrospectively evaluate the risk of events on an hourly, daily, or weekly basis. You can create a batch prediction job using the [Amazon Fraud Detector console](https://console.aws.amazon.com/frauddetector), or by calling the [CreateBatchPredictionJob](https://docs.aws.amazon.com/frauddetector/latest/api/API_CreateBatchPredictionJob.html)API operation using the AWS Command Line Interface (AWS CLI) or one of the Amazon Fraud Detector SDKs. **Topics** + [ ## How batch predictions work ](#how-batch-predictions-works) + [ ## Input and output files ](#input-and-output-files) + [ ## Getting batch predictions ](#getting-batch-predictions) + [ ## Guidance on IAM roles ](#guidance-iam-roles) + [ ## Get batch fraud predictions using the AWS SDK for Python (Boto3) ](#get-a-batch-fraud-prediction-using-the-aws-python-sdk) ## How batch predictions work The `CreateBatchPredictionJob` API operation uses a specified detector version to make predictions based on data provided in an input CSV file that is located in an Amazon S3 bucket. The API then returns the resulting CSV file to an S3 bucket. Batch prediction jobs calculate model scores and prediction outcomes in the same way as the `GetEventPrediction` operation. Similar to `GetEventPrediction`, to create a batch predictions job, you first create an event type, optionally train a model, and then create a detector version that evaluates the events in your batch job. The pricing for event risk scores evaluated by batch prediction jobs is the same as the pricing for scores created by the `GetEventPrediction` API. For details, see [Amazon Fraud Detector pricing](https://aws.amazon.com/fraud-detector/pricing/). You can only run one batch prediction job at a time. ## Input and output files The input CSV file should contain headers that match the event type that is associated with the selected detector version. The maximum size of the input data file is 1GB. The number of events will vary by your event size. Amazon Fraud Detector creates the output file in the same bucket as the input file, unless you specify a separate location for the output data. The output file contains the original data from the input file and the following appended columns: + `MODEL_SCORES` — Details the model scores for the event from each model associated with the selected detector version. + `OUTCOMES` — Details the event outcomes as evaluated by the selected detector version and its rules. + `STATUS` — Indicates whether the event was evaluated successfully. If the event was not evaluated successfully, this column shows a reason code for the failure. + ` RULE_RESULTS` — A list of all the rules that matched, based on the rule execution mode. ## Getting batch predictions The following steps assume that you have already created an event type, trained a model using that event type (optional), and created a detector version for that event type. **To get a batch prediction** 1. Sign in to the AWS Management Console and open the Amazon Fraud Detector console at [https://console.aws.amazon.com/frauddetector](https://console.aws.amazon.com/frauddetector). 1. In the left navigation pane of the Amazon Fraud Detector console, choose **Batch Predictions**, and then choose **New batch prediction**. 1. In **Job name**, specify a name for your batch prediction job. If you don’t specify a name, Amazon Fraud Detector randomly generates a job name. 1. In **Detector**, choose the detector for this batch prediction. 1. In **Detector version**, choose the detector version for this batch prediction. You can choose a detector version in any status. If your detector has a detector version in `Active` status, that version is automatically selected, but you can also change this selection if needed. 1. In **IAM role**, choose or create a role that has read and write access to your input and output Amazon S3 buckets. See [Guidance on IAM roles](#guidance-iam-roles) for more information. To get batch predictions, the IAM role that calls the `CreateBatchPredictionJob` operation must have read permissions to your input S3 bucket and write permissions to your output S3 bucket. For more information about bucket permissions, see [User policy examples](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-policies-s3.html) in the *Amazon S3 User Guide*. 1. In **Input data location**, specify the Amazon S3 location of your input data. If you want the output file in a different S3 bucket, select **Separate data location for output** and provide the Amazon S3 location for your output data. 1. (Optional) Create tags for your batch prediction job. 1. Choose **Start**. Amazon Fraud Detector creates the batch prediction job, and the job's status is `In progress`. Batch prediction job processing times vary depending on the number of events and your detector version configuration. To stop a batch prediction job that is in progress, go to the batch prediction job detail page, choose **Actions**, and then choose **Stop batch prediction**. If you stop a batch prediction job, you won't receive any results for the job. When the batch prediction job's status changes to `Complete`, you can retrieve the job's output from the designated output Amazon S3 bucket. The output file's name is in the format `batch prediction job name_file creation timestamp_output.csv`. For example, the output file from a job named `mybatchjob` is `mybatchjob_ 1611170650_output.csv`. To search for specific events evaluated by a batch prediction job, in the left navigation pane of the Amazon Fraud Detector console, choose **Search past predictions**. To delete a batch prediction job that has completed, go to the batch prediction job detail page, choose **Actions** and then choose **Delete batch prediction**. ## Guidance on IAM roles To get batch predictions, the IAM role that calls the [CreateBatchPredictionJob](https://docs.aws.amazon.com/frauddetector/latest/api/API_CreateBatchPredictionJob.html) operation must have read permissions to your input S3 bucket and write permissions to your output S3 bucket. For more information about bucket permissions, see User policy examples in the Amazon S3 User Guide. On the Amazon Fraud Detector console, you have three options for selecting an IAM role for Batch Predictions: 1. Create a role when creating a new Batch Prediction job. 1. Select an existing IAM role that you have previously created in Amazon Fraud Detector console. Make sure to add the `S3:PutObject` permission to the role before you do this step. 1. Enter a custom ARN for a previously created IAM role. If you receive an error related to your IAM role, verify the following: 1. Your Amazon S3 input and output buckets are in the same region as your detector. 1. The IAM role you are using has the `s3:GetObject` permission for your input S3 bucket and the `s3:PutObject` permission for your output S3 bucket. 1. The IAM role you are using has a trust policy for service principal `frauddetector.amazonaws.com`. ## Get batch fraud predictions using the AWS SDK for Python (Boto3) The following example shows a sample request for the [CreateBatchPredictionJob](https://docs.aws.amazon.com/frauddetector/latest/api/API_CreateBatchPredictionJob.html) API. A batch prediction job must include the following existing resources: detector, detector version, and event type name. The following example assumes you have created an event type `sample_registration`, a detector `sample_detector`, and a detector version `1`. ``` import boto3 fraudDetector = boto3.client('frauddetector') fraudDetector.create_batch_prediction_job ( jobId = 'sample_batch', inputPath = 's3://bucket_name/input_file_name.csv', outputPath = 's3://bucket_name/', eventTypeName = 'sample_registration', detectorName = 'sample_detector', detectorVersion = '1', iamRoleArn = 'arn:aws:iam::**:role/service-role/AmazonFraudDetector-DataAccessRole-**' ) ``` # Prediction explanations Prediction explanations provide insight into how each event variable impacted your model’s fraud prediction score, and are automatically generated as part of the fraud prediction. Each fraud prediction comes with a risk score between 1 and 1000. Prediction explanations give you details of the influence of each event variable on the risk scores in terms of magnitude (0-5, 5 being highest) and direction (drove score higher or lower). You can also use prediction explanations for the following tasks: + To identify top risk indicators during manual inverstigations when an event is flagged for review. + To narrow down root causes that lead to false positive predictions (for example, high risk scores for legitimate events). + To analyze fraud patterns across event data and detect bias, if any, in your dataset. **Important** Prediction explanations are automatically generated and available only for models trained on or after *June 30, 2021*. To receive prediction explanations for models trained before *June 30, 2021*, retrain those models. Prediction explanations provide the following set of values for each event variable that was used to train the model. **Relative impact** Provides a visual reference of the variable's impact in terms of magnitude on the fraud prediction scores. The relative impact values consist of a star rating (0-5, 5 being the highest) and direction (increased/decreased) impact of the fraud risk. + Variables that increased fraud risk are indicated by red colored stars. The higher the number of red colored stars, the more the variable drove up the fraud score and increased likelihood of fraud. + Variables that decreased fraud risk are indicated by green colored stars. The higher the number of green colored starts, the more the variable drove down the fraud risk score and decreased likelihood of fraud. + Zero stars for all variables indicate that none of the variables on their own significantly changed the fraud risk. **Raw explanation value** Provides raw, uninterpreted value represented as log-odds of the fraud. These values are usually between -10 to \$110, but range from - infinity to \$1 infinity. + A positive value indicates that the variable drove the risk score up. + A negative value indicates that the variable drove the risk score down. In the Amazon Fraud Detector console, the prediction explanation values are displayed as follows. The colored star ratings and the corresponding raw numerical values make it easy to see the relative influence between variables. ![\[Prediction explanation chart: variables that increased risk and variables that decreased fraud risk with relative impact and raw explanation value for each variable.\]](http://docs.aws.amazon.com/frauddetector/latest/ug/images/PredictionExplanationPane.png) ## Viewing prediction explanations After you generate fraud predictions, you can view prediction explanations in the Amazon Fraud Detector console. To view the prediction explanations using APIs from the AWS SDK, you must first call the `ListEventPrediction` API to obtain the prediction timestamp for the event, and then call the `GetEventPredictionMetadata` API to get the prediction explanations. ### View prediction explanations using Amazon Fraud Detector console **To view the prediction explanations using the console,** 1. Open the AWS Console and sign in to your account. Navigate to Amazon Fraud Detector. 1. In the left navigation pane, choose **Search past predictions**. 1. Use the **Property**, **Operator**, and **Value** filters to select the prediction you want review. 1. In the top **Filter** pane, make sure to select the time period for when the prediction you want to review was generated. 1. The **Results** pane displays a list of all the predictions generated during the specified time period. Click the Event ID of the prediction to view the prediction explanations. 1. Scroll down to the **Prediction explanations** pane. 1. Set the **Show raw prediction explanation value** button **on** to view raw prediction explanation value of all the variables. ### View prediction explanations using the AWS SDK for Python (Boto3) The following examples show sample requests for viewing prediction explanations using `ListEventPredictions` and `GetEventPredictionMetadata` APIs from the AWS SDK. **Example 1: Get a list of most recent predictions using `ListEventPredictions` API** ``` import boto3 fraudDetector = boto3.client('frauddetector') fraudDetector.list_event_predictions( maxResults = 10, predictionTimeRange = { end_time: '2022-01-13T23:18:21Z', start_time: '2022-01-13T20:18:21Z' } ) ``` **Example 2; Get a list of past predictions for event type "registration" using `ListEventPredictions` API** ``` import boto3 fraudDetector = boto3.client('frauddetector') fraudDetector.list_event_predictions( eventType = { value = 'registration' } maxResults = 70, nextToken = "10", predictionTimeRange = { end_time: '2021-07-13T23:18:21Z', start_time: '2021-07-13T20:18:21Z' } ) ``` **Example 3: Get details of a past prediction for a specified event ID, event type, detector ID, and detector version ID that was generated in the specified time period using `GetEventPredictionMetadata` API.** The `predictionTimestamp` specified for this request is obtained by first calling the `ListEventPredictions` API. ``` import boto3 fraudDetector = boto3.client('frauddetector') fraudDetector.get_event_prediction_metadata ( detectorId = 'sample_detector', detectorVersionId = '1', eventId = '802454d3-f7d8-482d-97e8-c4b6db9a0428', eventTypeName = 'sample_registration', predictionTimestamp = '2021-07-13T21:18:21Z' ) ``` ## Understanding how prediction explanations are calculated Amazon Fraud Detector uses [SHAP (SHapeley Additive exPlanations)](https://arxiv.org/abs/1705.07874) to explain individual event predictions by computing the **raw explanation values** of each event variable used for model training. The raw explanation values are computed by the model as part of the classification algorithm when generating predictions. These raw explanation values represent the contribution of each input to the logarithm of the odds of fraud. The raw explanation values (from -infinity to \$1infinity) are converted to a **relative impact value** (-5 to \$15) using a mapping. The relative impact value derived from raw explanation value represents the number of times increase in odds of fraud (positive) or legit (negative), making it easier to understand the prediction explanations.